An open source design system that's fully customizable and agent ready
TypeScript
docs(cli): every integration runs integration check --strict in its build (#7708)
Joey7462c4156985
diff --git a/.changeset/integration-check-required-in-guides.md b/.changeset/integration-check-required-in-guides.mdnew file mode 100644index 0000000000..2404bdf3ef--- /dev/null+++ b/.changeset/integration-check-required-in-guides.md@@ -0,0 +1,7 @@+---+'@astryxdesign/cli': patch+---++[docs] The integration guides make `integration check --strict` a required step in every integration's build: the quick start installs `typescript@6` (the checks need its JavaScript compiler API, which TypeScript 7 does not ship) and adds "Check it in every build (required)", the Build an integration overview says so, and the checks guide's section reads "Run every check in every build (required)".++@josephfarinadiff --git a/packages/cli/assets/docs/tree/checks.doc.mjs b/packages/cli/assets/docs/tree/checks.doc.mjsindex 1c083195e0..fef38d55c9 100644--- a/packages/cli/assets/docs/tree/checks.doc.mjs+++ b/packages/cli/assets/docs/tree/checks.doc.mjs@@ -74,11 +74,11 @@ export const docs = {},{id: 'run-every-check-in-ci',- title: 'Run every check in CI',+ title: 'Run every check in every build (required)',content: [{type: 'prose',- text: "Run `integration check --strict` in your package's own build, so every build keeps your docs, types, and links in sync, and run `integration verify` before you publish. Install devDependencies first, because the components check needs Core, and `tsc --noEmit` needs `typescript` and a `tsconfig.json`. In package.json:",+ text: 'Every integration runs `integration check --strict` in its own build, so every build keeps your docs, types, and links in sync; this is required, not optional. Run `integration verify` before you publish. Install devDependencies first, because the components check needs Core, and `tsc --noEmit` needs `typescript` and a `tsconfig.json`. In package.json:',},{type: 'code',diff --git a/packages/cli/assets/docs/tree/integrations.doc.mjs b/packages/cli/assets/docs/tree/integrations.doc.mjsindex 4906a4863b..6ec96b6be0 100644--- a/packages/cli/assets/docs/tree/integrations.doc.mjs+++ b/packages/cli/assets/docs/tree/integrations.doc.mjs@@ -36,5 +36,9 @@ export const docs = {type: 'prose',text: 'An integration can also replace a built-in template or doc. To start, install `@astryxdesign/cli` and open {@link generic:quick-start}.',},+ {+ type: 'prose',+ text: "Every integration runs `astryx integration check --strict` in its own build: it is required, not optional, so a doc, prop, or link that stops matching the code fails your build instead of your users' apps. See {@link generic:checks}.",+ },],};diff --git a/packages/cli/assets/docs/tree/quick-start.doc.mjs b/packages/cli/assets/docs/tree/quick-start.doc.mjsindex 445803d3cc..718e43ab2c 100644--- a/packages/cli/assets/docs/tree/quick-start.doc.mjs+++ b/packages/cli/assets/docs/tree/quick-start.doc.mjs@@ -34,12 +34,12 @@ export const docs = {},{type: 'prose',- text: 'An integration starts as a normal npm package. Make a folder for it, create a package.json inside that folder, give the package a name, then install the Astryx CLI and Core for development.',+ text: 'An integration starts as a normal npm package. Make a folder for it, create a package.json inside that folder, give the package a name, then install the Astryx CLI, Core, and TypeScript for development.',},{type: 'code',lang: 'bash',- code: "mkdir acme-widgets && cd acme-widgets\nnpm init -y\nnpm pkg set name=@acme/astryx-widgets\nnpm pkg set 'exports={}' --json\nnpm install -D @astryxdesign/cli @astryxdesign/core",+ code: "mkdir acme-widgets && cd acme-widgets\nnpm init -y\nnpm pkg set name=@acme/astryx-widgets\nnpm pkg set 'exports={}' --json\nnpm install -D @astryxdesign/cli @astryxdesign/core typescript@6",},{type: 'list',@@ -48,6 +48,7 @@ export const docs = {'Start with `"exports": {}`: each component and template you add then writes the public import that `integration verify` resolves.','Run the CLI as `npx astryx`, which runs the `@astryxdesign/cli` you installed as a devDependency.','Component commands read Core, so they need `@astryxdesign/core` installed.',+ "The checks compare your docs with your code through TypeScript's JavaScript compiler API, so they need `typescript` 5.0 through 6 installed. TypeScript 7 does not ship that API, and with it the checks skip those comparisons.",],},{@@ -86,6 +87,33 @@ export const docs = {type: 'prose',text: 'You now have an integration package with one exported component.',},+ {+ type: 'heading',+ level: 3,+ text: 'Check it in every build (required)',+ },+ {+ type: 'prose',+ text: 'Every integration runs `integration check --strict` in its own build, so a doc, prop, template, or link that stops matching the code fails your build instead of reaching the apps that install your package. Set it up now, as the `typecheck` script, and run it.',+ },+ {+ type: 'code',+ lang: 'bash',+ code: 'npm pkg set scripts.typecheck="astryx integration check --strict"\nnpm run typecheck',+ },+ {+ type: 'code',+ lang: 'text',+ code: '[ok] 0 errors, 0 warnings, 0 skipped. Every check passed.',+ },+ {+ type: 'list',+ style: 'unordered',+ items: [+ 'Run `typecheck` in CI and before every publish. When you add a `tsconfig.json`, put `tsc --noEmit && ` in front of the check so the same script checks your types.',+ 'What each check covers, and what `--strict` adds: {@link generic:checks}.',+ ],+ },{type: 'heading',level: 3,@@ -177,8 +205,8 @@ export const docs = {],['`devDependencies`',- '`@astryxdesign/cli` and `@astryxdesign/core`',- 'Lets you run the CLI and build components while working on the integration.',+ '`@astryxdesign/cli`, `@astryxdesign/core`, and `typescript`',+ 'Lets you run the CLI, build components, and run the checks while working on the integration.',],],},