Skip to content

Commit 64df2de

Browse files
docs(site): explain the bin exception to convention claims
main (#413) made a bin entry stop claiming a direct src/scripts/<name> module, so the same file ships as the npm bin and the artifact script. The Scripts page now states that rule and the AB4737/AB4738 export requirements in both locales.
1 parent bf6de9c commit 64df2de

2 files changed

Lines changed: 15 additions & 0 deletions

File tree

‎website/docs/en/guide/authoring/scripts-assets.mdx‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -47,6 +47,14 @@ Nested modules under `src/scripts/` are a hard error (`AB4808`) — the output n
4747
unambiguous. Opt out by prefixing a path segment with `_`, or by claiming the file with an
4848
explicit `scripts` entry.
4949

50+
Every explicit config entry that references a module — `scripts`, `hooks`, `mcp`, `lib` — claims
51+
it out of convention, with one exception: a `bin` entry does **not** claim a direct
52+
`src/scripts/<name>.ts` child. The bin compiles to `dist/bin/<name>.js`, disjoint from every
53+
artifact, and both envelopes run the same `main`, so the module ships as the npm bin *and* the
54+
artifact `scripts/<name>.mjs`. Such a module must export `main` or be self-executing: a
55+
`default`-only plain script is `AB4738`, and a rendered `.tsx` script must export both its default
56+
component and `main` (`AB4737`). For a bin-only module, prefix a path segment with `_`.
57+
5058
### Rendered scripts
5159

5260
`src/scripts/<name>.tsx` is a rendered script. Its async default component receives `argv` and

‎website/docs/zh/guide/authoring/scripts-assets.mdx‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -43,6 +43,13 @@ export default defineConfig({
4343
`src/scripts/` 下的嵌套模块是硬错误(`AB4808`)——输出名必须无歧义。给某一段路径加 `_` 前缀,或用
4444
显式 `scripts` 条目认领该文件,即可退出。
4545

46+
每个引用了某模块的显式配置条目——`scripts`、`hooks`、`mcp`、`lib`——都会把它从约定中认领走,只有一个
47+
例外:`bin` 条目**不会**认领 `src/scripts/<name>.ts` 这样的直接子模块。bin 编译到 `dist/bin/<name>.js`,
48+
与所有 artifact 互不重叠,而且两种外壳运行同一个 `main`,所以该模块会同时作为 npm bin *和* artifact 中的
49+
`scripts/<name>.mjs` 发布。这样的模块必须导出 `main` 或自执行:只导出 `default` 的普通脚本是 `AB4738`,
50+
渲染式 `.tsx` 脚本则必须同时导出默认组件和 `main`(`AB4737`)。若只想作为 bin 发布,给某一段路径加 `_`
51+
前缀即可。
52+
4653
### 渲染式脚本
4754

4855
`src/scripts/<name>.tsx` 是渲染式脚本。它的 async 默认组件接收 `argv` 与 `signal`,并按完整的 CLI

0 commit comments

Comments
 (0)