Ts packaging
Skill fusengine/agents/plugins/typescript-expert/skills/ts-packaging
Use when publishing a TypeScript library — exports map, JSR vs npm, dual ESM/CJS, type validation, provenance. Covers modern package.json, jsr.json, and release CI. Do NOT use for application deployment (not a library) or framework build pipelines (use the framework expert's skills).From its SKILL.md
npx -y skills add fusengine/agents --skill ts-packagingAssembled from the repository path, not quoted from the project. Check it against their README if it does not work.
SKILL.md
3.8 KB, 851 tokens by cl100k_base, as published. Nobody here has run it
TypeScript Packaging
Ship a TypeScript library with a correct exports map, on the right registry.
Agent Workflow (MANDATORY)
Before ANY implementation, use TeamCreate to spawn 3 agents:
- fuse-ai-pilot:explore-codebase - Inspect package.json, build output, targets
- fuse-ai-pilot:research-expert - Verify latest JSR / npm / Node exports docs via Context7/Exa
- mcp__context7__query-docs - Check conditions ordering, attw usage
After implementation, run fuse-ai-pilot:sniper for validation.
Overview
| Registry | Format | Publishes | Best for |
|---|---|---|---|
| JSR | ESM only | TS source directly | Deno/Node/Bun libs, doc-rich APIs |
| npm | ESM (or dual ESM/CJS) | Built .js + .d.ts | Broadest public reach, CJS consumers |
Rule of thumb: internal or Bun/Deno/ESM-only consumer → ESM-pure; broad public library still serving CommonJS → dual ESM/CJS.
Critical Rules
"types"first,"default"last - Conditions match in object order- Match
import↔ESM andrequire↔CJS - Never pointrequireat ESM - One subpath per module - Consistent specifier; set
"type": "module"explicitly - Validate with attw -
arethetypeswrongbefore every publish - Provenance on public releases - Publish from CI with
id-token: write
Decision Guide
Publishing a TS library?
├── Consumers on Deno/Bun/Node ESM, want source + docs → JSR (ESM only)
│ └── Fix "slow types" (explicit return/prop/const types)
└── Public npm audience
├── ESM-only consumers → ESM-pure package.json
└── Some consumers still on CJS → dual ESM/CJS exports
→ See references/exports-map.md for the conditions model
Reference Guide
Concepts
| Topic | Reference | Load when |
|---|---|---|
| Exports map & conditions | references/exports-map.md | Writing the exports field |
| JSR publishing | references/jsr-publishing.md | Publishing TS source to JSR |
| npm publishing | references/npm-publishing.md | Publishing to npm (dual/ESM) |
| Type validation | references/validation.md | Checking types resolve correctly |
Templates
| Template | Use Case |
|---|---|
references/templates/package-json-dual.md | Dual ESM/CJS + ESM-pure package.json |
references/templates/jsr-json.md | jsr.json with multi-entry exports |
references/templates/publish-workflow.md | GitHub Actions release with provenance |
Quick Start
Modern exports (ESM-pure)
{
"type": "module",
"exports": {
".": { "types": "./dist/index.d.ts", "default": "./dist/index.js" }
}
}
Validate before publish
npx @arethetypeswrong/cli --pack
→ See references/validation.md
Best Practices
DO
- Set
"type"explicitly, even for CJS packages - Provide
typesin every conditional branch - Publish from CI so provenance is automatic
DON'T
- Ship dual CJS when every consumer is ESM (dead weight)
- Order
"default"before"types"(breaks type resolution) - Use
--allow-slow-typeson JSR as a habit (degrades docs + npm compat)
What ships with it: 8 files
15.3 KB alongside SKILL.md
references/
- exports-map.md2.5 KB
- jsr-publishing.md2.6 KB
- npm-publishing.md2.3 KB
- templates/jsr-json.md1.6 KB
- templates/package-json-dual.md2.3 KB
- templates/publish-workflow.md2.0 KB
- validation.md1.9 KB
- .gitkeep0 B