feat: ship a skill facade in the npm package (#1122)

Author: sxzzbot

.gitignore

@@ -11,6 +11,7 @@ temp
 .DS_Store
 .eslintcache
 tsdown-*.tgz
+.skills-backup
 
 docs/.vitepress/dist
 docs/.vitepress/cache

npm-skills/tsdown/SKILL.md

@@ -0,0 +1,36 @@
+---
+name: tsdown
+description: Bundle TypeScript and JavaScript libraries with blazing-fast speed powered by Rolldown. Use when building libraries, generating type declarations, bundling for multiple formats, or migrating from tsup.
+---
+
+# tsdown
+
+This package ships only a pointer to the full tsdown skill, which lives on GitHub to keep the npm package small.
+
+## Step 1: Find the installed version
+
+Read the `version` field of `node_modules/tsdown/package.json`.
+
+## Step 2: Read the full skill for that version
+
+Fetch the skill that matches the installed version, replacing `<version>` with it:
+
+```
+https://raw.githubusercontent.com/rolldown/tsdown/v<version>/skills/tsdown/SKILL.md
+```
+
+Read it completely before writing tsdown config or code. Its links to `references/*.md` are relative to that URL, so fetch them from:
+
+```
+https://raw.githubusercontent.com/rolldown/tsdown/v<version>/skills/tsdown/references/<file>.md
+```
+
+If the tag does not exist (e.g. a prerelease or local build), use `main` instead of `v<version>`.
+
+To browse the skill: https://github.com/rolldown/tsdown/tree/main/skills/tsdown
+
+## More
+
+- Documentation: https://tsdown.dev
+- Documentation for LLMs: https://tsdown.dev/llms.txt
+- Migrating from tsup: https://github.com/rolldown/tsdown/tree/main/skills/tsdown-migrate

package.json

@@ -48,7 +48,8 @@
   "files": [
     "client.d.ts",
     "dist",
-    "esm-shims.js"
+    "esm-shims.js",
+    "skills"
   ],
   "publishConfig": {
     "access": "public",
@@ -86,6 +87,8 @@
     "schema:generate": "node ./scripts/generate-schema.ts",
     "schema:check": "node ./scripts/generate-schema.ts -c",
     "release": "node ./scripts/release.ts",
+    "prepack": "node ./scripts/skills-facade.ts prepack",
+    "postpack": "node ./scripts/skills-facade.ts postpack",
     "docs:dev": "pnpm -C docs run dev",
     "docs:build": "pnpm -C docs run build",
     "docs:preview": "pnpm -C docs run preview",

scripts/skills-facade.ts

@@ -0,0 +1,28 @@
+// The full skills under `skills/` are too large to ship in the npm package,
+// but pnpm only discovers package skills under `skills/`. While packing, swap
+// in the lightweight facades from `npm-skills/`, which link to GitHub.
+import { rename } from 'node:fs/promises'
+import process from 'node:process'
+import { fsCopy, fsExists, fsRemove } from '../src/utils/fs.ts'
+
+const SKILLS = 'skills'
+const FACADES = 'npm-skills'
+const BACKUP = '.skills-backup'
+
+async function restore() {
+  if (!(await fsExists(BACKUP))) return
+  await fsRemove(SKILLS)
+  await rename(BACKUP, SKILLS)
+}
+
+const mode = process.argv[2]
+if (mode === 'prepack') {
+  // Recover from a previous pack that did not reach postpack
+  await restore()
+  await rename(SKILLS, BACKUP)
+  await fsCopy(FACADES, SKILLS)
+} else if (mode === 'postpack') {
+  await restore()
+} else {
+  throw new Error(`Unknown mode: ${mode}`)
+}