also looking at this
feat(stx): generate component declarations
#3105
19 files
+894
-37
Review threads live on the whole diff, not on one commit, so none are shown here - a thread's line means something in the branch's final form, and painting it into an intermediate step would put it on code it is not about.
| @@ -52,7 +52,7 @@ import { generate, processSource } from '@stacksjs/dtsx' | ||
| 52 | 52 | const options: DtsGenerationOptions = { |
| 53 | 53 | cwd: './', // default: process.cwd() |
| 54 | 54 | root: './src', // default: './src' |
| 55 | entrypoints: ['**/*.ts'], // default: ['**/*.ts'] | |
| 55 | entrypoints: ['**/*.{ts,tsx,mts,cts,vue,stx}'], // default | |
| 56 | 56 | outdir: './dist', // default: './dist' |
| 57 | 57 | clean: true, // default: false |
| 58 | 58 | verbose: true, // default: false |
| @@ -80,6 +80,31 @@ console.log(dtsContent) | ||
| 80 | 80 | // export declare function greet(name: string): string; |
| 81 | 81 | ``` |
| 82 | 82 | |
| 83 | ### STX Components | |
| 84 | ||
| 85 | `.stx` files are declaration entrypoints alongside TypeScript and Vue files. | |
| 86 | dtsx reads Vue-style `<script server|client>` blocks and Blade-style `@ts` | |
| 87 | blocks, then emits an `@stacksjs/stx` `DefineComponent` declaration. Props are | |
| 88 | derived from typed macros, runtime prop schemas, explicit `props as Props` | |
| 89 | assertions, and legacy `$props.name` access: | |
| 90 | ||
| 91 | ```stx | |
| 92 | <script server lang="ts"> | |
| 93 | interface CardProps { | |
| 94 | title: string | |
| 95 | count?: number | |
| 96 | } | |
| 97 | ||
| 98 | const props = withDefaults(defineProps<CardProps>(), { count: 0 }) | |
| 99 | </script> | |
| 100 | ||
| 101 | <article>{{ props.title }}</article> | |
| 102 | ``` | |
| 103 | ||
| 104 | This emits `Card.d.ts` with `{ title: string; count?: number }` as its `$props` | |
| 105 | contract. The same transform feeds the semantic inference path and the | |
| 106 | annotation-first `isolatedDeclarations` path. | |
| 107 | ||
| 83 | 108 | Library usage can also be configured using a `dts.config.ts` _(or `dts.config.js`)_ file, automatically loaded when running `./dtsx` _(or `bunx dtsx`)_ and when calling `generate()` unless custom options are provided. |
| 84 | 109 | |
| 85 | 110 | ```ts |
| @@ -185,7 +210,7 @@ cat src/utils.ts | dtsx stdin > dist/utils.d.ts | ||
| 185 | 210 | |
| 186 | 211 | - `--cwd <path>`: Set the current working directory _(default: current directory)_ |
| 187 | 212 | - `--root <path>`: Specify the root directory of the project _(default: './src')_ |
| 188 | - `--entrypoints <files>`: Define entry point files _(comma-separated, default: '**/*.ts')_ | |
| 213 | - `--entrypoints <files>`: Define entry point files _(comma-separated, default: `**/*.{ts,tsx,mts,cts,vue,stx}`)_ | |
| 189 | 214 | - `--outdir <path>`: Set the output directory for generated .d.ts files _(default: './dist')_ |
| 190 | 215 | - `--keep-comments`: Keep comments in generated .d.ts files _(default: true)_ |
| 191 | 216 | - `--clean`: Clean output directory before generation _(default: false)_ |
| @@ -25,7 +25,7 @@ import { generate } from '@stacksjs/dtsx' | ||
| 25 | 25 | const config: DtsGenerationConfig = { |
| 26 | 26 | cwd: './', // default: process.cwd() |
| 27 | 27 | root: './src', // default: './src' |
| 28 | entrypoints: ['**/*.ts'], // default: ['**/*.ts'] | |
| 28 | entrypoints: ['**/*.{ts,tsx,mts,cts,vue,stx}'], // default | |
| 29 | 29 | outdir: './dist', // default: './dist' |
| 30 | 30 | keepComments: true, // default: true |
| 31 | 31 | clean: true, // default: true |
| @@ -134,7 +134,7 @@ dtsx generate --output-structure flat | ||
| 134 | 134 | |--------|------|---------|-------------| |
| 135 | 135 | | `--cwd <path>` | `string` | current directory | Set the current working directory | |
| 136 | 136 | | `--root <path>` | `string` | `'./src'` | Specify the root directory of the project | |
| 137 | | `--entrypoints <files>` | `string` | `'**/*.ts'` | Define entry point files (comma-separated) | | |
| 137 | | `--entrypoints <files>` | `string` | `'**/*.{ts,tsx,mts,cts,vue,stx}'` | Define entry point files (comma-separated) | | |
| 138 | 138 | | `--outdir <path>` | `string` | `'./dist'` | Set the output directory for generated .d.ts files | |
| 139 | 139 | | `--keep-comments [value]` | `boolean` | `true` | Keep comments in generated .d.ts files | |
| 140 | 140 | | `--clean` | `boolean` | `true` | Clean output directory before generation | |
| @@ -64,7 +64,7 @@ import { generate } from '@stacksjs/dtsx' | ||
| 64 | 64 | const options: DtsGenerationOptions = { |
| 65 | 65 | cwd: './', // default: process.cwd() |
| 66 | 66 | root: './src', // default: './src' |
| 67 | entrypoints: ['**/*.ts'], // default: ['**/*.ts'] | |
| 67 | entrypoints: ['**/*.{ts,tsx,mts,cts,vue,stx}'], // default | |
| 68 | 68 | outdir: './dist', // default: './dist' |
| 69 | 69 | clean: true, // default: false |
| 70 | 70 | verbose: true, // default: false |
| @@ -74,6 +74,13 @@ const options: DtsGenerationOptions = { | ||
| 74 | 74 | await generate(options) |
| 75 | 75 | ``` |
| 76 | 76 | |
| 77 | ### STX Components | |
| 78 | ||
| 79 | `.stx` entrypoints support Vue-style script blocks, Blade-style `@ts` blocks, | |
| 80 | typed and runtime `defineProps`, `props as Props`, and legacy `$props.name` | |
| 81 | contracts. dtsx emits the default component as | |
| 82 | `DefineComponent<Props>` from `@stacksjs/stx` in semantic and isolated modes. | |
| 83 | ||
| 77 | 84 | ### Configuration File |
| 78 | 85 | |
| 79 | 86 | Library usage can also be configured using a `dts.config.ts` _(or `dts.config.js`)_ file which is automatically loaded when running the `./dtsx` _(or `bunx dtsx`)_ command. It is also loaded when the `generate` function is called, unless custom options are provided. |
| @@ -269,7 +276,7 @@ echo "export function foo(): string { return 'bar' }" | dtsx stdin | ||
| 269 | 276 | #### Generate Options |
| 270 | 277 | |
| 271 | 278 | - `--root <path>`: Specify the root directory of the project _(default: './src')_ |
| 272 | - `--entrypoints <files>`: Define entry point files _(comma-separated, default: '**/*.ts')_ | |
| 279 | - `--entrypoints <files>`: Define entry point files _(comma-separated, default: `**/*.{ts,tsx,mts,cts,vue,stx}`)_ | |
| 273 | 280 | - `--outdir <path>`: Set the output directory for generated .d.ts files _(default: './dist')_ |
| 274 | 281 | - `--keep-comments`: Keep comments in generated .d.ts files _(default: true)_ |
| 275 | 282 | - `--clean`: Clean output directory before generation _(default: false)_ |