Out of scope: application deployment (not a library) and framework-owned build pipelines
belong to the framework expert's own skills.
TypeScript Packaging
Ship a TypeScript library with a correct exports map, on the right registry.
Agent Workflow (MANDATORY)
Before ANY implementation, spawn 3 agents in parallel, one Agent call each with a name:
- 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 and require↔CJS - Never point require at ESM
- One subpath per module - Consistent specifier; set
"type": "module" explicitly
- Validate with attw -
arethetypeswrong before 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
types in 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-types on JSR as a habit (degrades docs + npm compat)
1---2name: ts-packaging3description: Use when publishing a TypeScript library — exports map, JSR vs npm, dual ESM/CJS, type validation, provenance. Not for application deployment.4versions:5 node: "26"6 attw: "0.18.4"7user-invocable: true8references: references/exports-map.md, references/jsr-publishing.md, references/npm-publishing.md, references/validation.md, references/templates/package-json-dual.md, references/templates/jsr-json.md, references/templates/publish-workflow.md9related-skills: solid-generic, ts-testing10metadata:11 source: https://skillmd.com/skills/fusengine/ts-packaging12---1314<objective>15This skill covers shipping a TypeScript library correctly: designing the exports map and its16conditions ordering (types first, default last), choosing JSR (ESM-only, publishes TS source17directly, fixes 'slow types') versus npm (built .js + .d.ts, optionally dual ESM/CJS for18CommonJS consumers), validating resolved types with arethetypeswrong (attw) before every19publish, and enabling provenance on public releases via CI with id-token: write.2021Out of scope: application deployment (not a library) and framework-owned build pipelines22belong to the framework expert's own skills.23</objective>2425# TypeScript Packaging2627Ship a TypeScript library with a correct exports map, on the right registry.2829## Agent Workflow (MANDATORY)3031Before ANY implementation, spawn 3 agents in parallel, one `Agent` call each with a `name`:32331. **fuse-ai-pilot:explore-codebase** - Inspect package.json, build output, targets342. **fuse-ai-pilot:research-expert** - Verify latest JSR / npm / Node exports docs via Context7/Exa353. **mcp__context7__query-docs** - Check conditions ordering, attw usage3637After implementation, run **fuse-ai-pilot:sniper** for validation.3839---4041## Overview4243| Registry | Format | Publishes | Best for |44|----------|--------|-----------|----------|45| JSR | ESM only | TS **source** directly | Deno/Node/Bun libs, doc-rich APIs |46| npm | ESM (or dual ESM/CJS) | Built `.js` + `.d.ts` | Broadest public reach, CJS consumers |4748Rule of thumb: internal or Bun/Deno/ESM-only consumer → **ESM-pure**;49broad public library still serving CommonJS → **dual ESM/CJS**.5051---5253## Critical Rules54551. **`"types"` first, `"default"` last** - Conditions match in object order562. **Match `import`↔ESM and `require`↔CJS** - Never point `require` at ESM573. **One subpath per module** - Consistent specifier; set `"type": "module"` explicitly584. **Validate with attw** - `arethetypeswrong` before every publish595. **Provenance on public releases** - Publish from CI with `id-token: write`6061---6263## Decision Guide6465```66Publishing a TS library?67├── Consumers on Deno/Bun/Node ESM, want source + docs → JSR (ESM only)68│ └── Fix "slow types" (explicit return/prop/const types)69└── Public npm audience70 ├── ESM-only consumers → ESM-pure package.json71 └── Some consumers still on CJS → dual ESM/CJS exports72```7374→ See `references/exports-map.md` for the conditions model7576---7778## Reference Guide7980### Concepts8182| Topic | Reference | Load when |83|-------|-----------|-----------|84| Exports map & conditions | `references/exports-map.md` | Writing the `exports` field |85| JSR publishing | `references/jsr-publishing.md` | Publishing TS source to JSR |86| npm publishing | `references/npm-publishing.md` | Publishing to npm (dual/ESM) |87| Type validation | `references/validation.md` | Checking types resolve correctly |8889### Templates9091| Template | Use Case |92|----------|----------|93| `references/templates/package-json-dual.md` | Dual ESM/CJS + ESM-pure package.json |94| `references/templates/jsr-json.md` | jsr.json with multi-entry exports |95| `references/templates/publish-workflow.md` | GitHub Actions release with provenance |9697---9899## Quick Start100101### Modern exports (ESM-pure)102103```json104{105 "type": "module",106 "exports": {107 ".": { "types": "./dist/index.d.ts", "default": "./dist/index.js" }108 }109}110```111112### Validate before publish113114```bash115npx @arethetypeswrong/cli --pack116```117118→ See `references/validation.md`119120---121122## Best Practices123124### DO125- Set `"type"` explicitly, even for CJS packages126- Provide `types` in every conditional branch127- Publish from CI so provenance is automatic128129### DON'T130- Ship dual CJS when every consumer is ESM (dead weight)131- Order `"default"` before `"types"` (breaks type resolution)132- Use `--allow-slow-types` on JSR as a habit (degrades docs + npm compat)