typescript-publish-types

Your role is to make every public entry point of a package resolve to a declaration file from the packed tarball, without breaking the existing build.

The job is not done when package.json has a types field. It is done when a fresh consumer, installing the tarball you would actually publish, gets types for every entry point they can import.

Order Of Work

Each step has a check that must pass before you move on. Do the preflight first: most wasted work in this task is a late discovery of the runtime, the package manager, or a lifecycle script.

1. Preflight
2. Inventory every public entry point
3. Emit declarations
4. Route every entry point to its declaration
5. Make sure the declarations are in the tarball
6. Verify as a consumer
7. Prove you didn't break the build

0. Preflight

One pass, before you edit anything. Write the answers down; every later command depends on them. Run it from the repo root; it prints only what it finds, and exits 0 whether or not a lockfile exists — do not paper over the absent cases with 2>/dev/null or || true.

pwd; node -v; npm -v
for f in package-lock.json yarn.lock pnpm-lock.yaml bun.lock; do
  if [ -e "$f" ]; then echo "lockfile: $f"; fi
done
node -e 'const p = require("./package.json");
console.log("name:", p.name, "| type:", p.type ?? "commonjs", "| engines.node:", p.engines?.node ?? "unset");
console.log("workspaces:", JSON.stringify(p.workspaces ?? null));
for (const [k, v] of Object.entries(p.scripts ?? {})) console.log("script", k + ":", v)'

No lockfile: line means there is no lockfile: decide the package manager deliberately rather than defaulting. workspaces tells you whether this is a monorepo without listing the tree; for pnpm, read pnpm-workspace.yaml instead.

Record:

• Absolute paths of the repo root and of the package you are fixing. They differ in a monorepo, and packing the wrong one produces a thousand-line manifest of the wrong package.
• Package manager, from the lockfile — not from habit. Use that one manager for everything.
• Node: declared versus actual. Compare node -v against engines.node, .nvmrc, and any CI config. A test suite that fails under Node 18 when the package declares Node 24 is an environment mismatch, not a regression in your change. Find this out now, not after a day of bisecting.
• Which tools already exist: typescript, the bundler, publint, @arethetypeswrong/cli in devDependencies or node_modules. If node_modules is missing, install now with the repo's own manager and lockfile. Do not re-discover a missing tool once per step.
• Lifecycle scripts: prepare, prepack, prebuild, pretest, build, test, and any watch:*. These determine what your commands actually run. A prebuild: npm install means every build reinstalls; a pretest that deletes the build output means a build followed by npm test threw the build away.
• Monorepo prerequisites: which sibling packages must be built first, and the exact command.

Then:

• Give every command its own directory: npm --prefix <abs-pkg-dir> run build, or (cd <abs-pkg-dir> && ...). Never rely on a previous command having left the terminal somewhere.
• Use git status at the repo root, not inside the package, so you see stray artifacts elsewhere.

1. Inventory Every Public Entry Point

This is the step that is most often done wrong. Fixing exports["."] and stopping is the single most common failure. Write the list down before you edit anything.

Read the package's package.json and enumerate:

• main, module, browser, types/typings
• every key in exports — ".", "./browser", "./api", "./cli", wildcards like "./*". "./package.json" needs no types; everything else does.
• every condition inside each exports key — import, require, node, browser, default. A require condition that resolves to CJS needs its own CJS declaration.
• typesVersions, if present
• if there is no exports map at all, the deep paths consumers already import. Every published file is reachable today. Adding an exports map makes all of them unreachable except the ones you list — a breaking change you did not intend. Either keep the existing shape, or enumerate the deep paths (grep -rn "from '<pkg>/" --include='*.ts' --include='*.js' across the repo, plus the README and tests) and export them too.

exports also has a legacy array form, which is easy to skim past:

"exports": {
  ".": [{ "import": "./build/lib/index.js" }, "./build/lib/index.js"],
  "./browser": ["./browser.js"]      // <- still a public entry point, still needs types
}

Enumerate it mechanically rather than by eye:

node -e 'const e=require("./package.json").exports; console.log(JSON.stringify(e,null,2))'

Every path in that output is something a consumer can import. All of them need a declaration route.

2. Emit Declarations

Find how the package builds, then enable declaration output there. Adding "types" to package.json without emitting a .d.ts produces a package that is worse than untyped — it points at a file that does not exist.

Build system	How to emit declarations
tsc	"declaration": true in the tsconfig that produces the shipped output (watch noEmit, and project references/composite)
tsup	dts: true in tsup.config.ts
vite	vite-plugin-dts
rollup	rollup-plugin-dts, as a second bundle whose input is the entry .ts
esbuild	esbuild does not emit declarations — run tsc --emitDeclarationOnly alongside it
api-extractor	@microsoft/api-extractor to roll many .d.ts into one

Rules that cost whole runs when ignored:

• Extend the existing build; do not invent a parallel one. A standalone tsc config in a repo whose bundler resolves workspace aliases emits a nested multi-package tree that routes nowhere. If the repo bundles, use that bundler's declaration emitter.

• Configure a declaration plugin from the version that is actually installed, not from memory. Option names move between majors — vite-plugin-dts renamed rollupTypes to bundleTypes, and bundling needs an API Extractor peer dependency. Read the resolved copy before you configure it:

  node -p 'require("vite-plugin-dts/package.json").version'
  sed -n '1,120p' node_modules/vite-plugin-dts/README.md
  

  Then make all the dependency changes at once, through the package manager, in one install.

• tsc does not copy hand-written .d.ts inputs to the output directory. If your source tree contains declarations or module augmentations that the public API references, copy them into the output or bundle them in. Do not weaken the types to make the reference disappear.

• Generate declarations for published sources only. Tests, fixtures, and benchmarks in the output are noise, and they drag their own dependencies into the declaration graph.

• If the tsconfig sets "noEmit": true for type checking, do not flip it — emit from the build config, or add a separate tsconfig.build.json.

• If you add a build dependency, update the lockfile too, or a clean npm ci / --frozen-lockfile install fails for everyone.

• Confirm the output exists on disk before continuing:

  find <outDir> -name '*.d.*ts' | head
  

3. Route Every Entry Point To Its Declaration

Set a types condition for each entry point you inventoried. types goes inside the format branch, immediately before that branch's default — not once at the top of the entry:

{
  "name": "my-pkg",
  "type": "module",
  "main": "./dist/index.cjs",
  "types": "./dist/index.d.cts", // Node10 fallback only; see below
  "exports": {
    ".": {
      "import": {
        "types": "./dist/index.d.mts",
        "default": "./dist/index.mjs",
      },
      "require": {
        "types": "./dist/index.d.cts",
        "default": "./dist/index.cjs",
      },
    },
    "./browser": {
      // subpaths need the same shape
      "import": {
        "types": "./dist/browser.d.mts",
        "default": "./dist/browser.mjs",
      },
      "require": {
        "types": "./dist/browser.d.cts",
        "default": "./dist/browser.cjs",
      },
    },
    "./package.json": "./package.json",
  },
  "typesVersions": { "*": { "browser": ["./dist/browser.d.cts"] } },
}

A package that ships one format needs one branch per entry, { "types": ..., "default": ... }. Choose the declaration extension from the JavaScript entry point's extension, even for a single-format package.

Rules:

• Within any object of conditions, default must always be last. Conditions match in order, so an earlier default wins over later conditions, including types.
• Every publicly accessible JavaScript file entry point needs a declaration file with the corresponding extension: .js -> .d.ts, .mjs -> .d.mts, .cjs -> .d.cts. Route each entry point to its matching declaration. This applies to every format branch, even when the declaration contents are identical; matching contents do not make different extensions interchangeable.
• Legacy (Node10) resolution ignores exports entirely. It reads top-level types, and for subpaths it reads typesVersions — as above, pointing at the CJS declaration, since Node10 consumers are CJS. Restructuring exports will never fix a Node10 subpath failure.

4. Make Sure The Declarations Are In The Tarball

Declarations that are generated but filtered out of the tarball are the second most common failure, and nothing in the source tree reveals it. Check all four filters:

• files in package.json — including negations, e.g. "!*.d.ts", "!*.d.cts". Packages that once had broken types often still carry these exclusions; they will silently drop your new output.

• .npmignore — a bare *.ts line excludes .d.ts. Fix by re-including rather than deleting:

  *.ts
  !**/*.d.ts
  

• .gitignore — npm falls back to it when there is no .npmignore

• the build's clean/rimraf step, which may wipe declarations after emitting them

Then make one scratch workspace and produce one real tarball in it, with lifecycle scripts enabled:

mktemp -d                                     # note the path it prints; use it literally below
(cd <abs-pkg-dir> && npm pack --pack-destination <workspace>)

Use the printed path verbatim in every later command. A shell variable does not survive between commands any more reliably than the working directory does, and a fixed path like /tmp/pkgcheck fails the first time because nothing created it.

Assert the inventoried paths against the tarball instead of reading the whole manifest — a full file list of a large package buries the answer and costs a re-read:

tar -tzf <workspace>/<name>-<version>.tgz | grep -E '\.d\.(m|c)?ts$'

Every declaration you routed in step 3 must appear, by exact path. Do not accept "the path is under a directory that is already allowlisted" as proof.

Keep the workspace: steps 5 and 6 reuse this tarball and write their reports beside it. Delete it (rm -rf <workspace>) when you finish, whether or not the task succeeded, and re-pack only when the sources, build config, package.json, or dependencies change — note that --dry-run is fine for reading a manifest but produces no artifact to install.

If packing fails because a prepare/prepack hook needs tools that aren't installed, install dependencies and pack again. Never pass --ignore-scripts and present the result as release evidence: the hook is part of what publishing runs.

5. Verify As A Consumer

Metadata can be well-formed and still not resolve. Run the tools built for this, against the tarball you already produced:

npx --yes publint run <tarball>
npx --yes @arethetypeswrong/cli --format table <tarball>

attw is the check that catches a subpath export with no types, a require condition with no CJS declaration, and ESM declarations masquerading as CJS. It reports per entry point, which is exactly the blind spot in step 1. If you run only one verification tool, run this one.

An attw failure in a mode the package supports is a failure. Finding a declaration file is not the same as that file having the right module semantics: a successful path-only probe does not overrule export = missing from a CJS entry, or an ESM declaration served to require. Fix it, or report it as an unresolved failure in your summary. Never drop it silently.

When a checker misbehaves

Sort the output into four kinds before reacting:

Symptom	What it means	What to do
Errors naming your entry points, conditions, or files	Real package diagnostics	Fix the package
An internal stack trace, e.g. Cannot read properties of undefined (reading 'filename')	The checker crashed	Retry once with a genuinely different input (explicit tarball instead of --pack), then use the packed-consumer check
publint and npm pack disagree about what is published	The checker inspected a different artifact or pack manager	Inspect the real archive from the repo's own manager (yarn pack, pnpm pack) and compare. Do not add metadata to make the message go away
A publint "suggestion", or a warning about a mode the package does not support	Optional	Leave it. Do not add "type": "commonjs", change default, or restructure exports to silence advice — the warning usually survives and the change breaks something real

Cycling through attw option permutations after the same internal error is not a discriminating retry. One new hypothesis per attempt; when you run out, switch to the packed-consumer check.

Capture the report to a file and read the file rather than re-running the tool, and be careful with && chains: if the checker exits nonzero the formatter never runs, and the report is already there.

npx --yes @arethetypeswrong/cli --format json <tarball> > <workspace>/attw.json; echo "attw exit=$?"
node -e 'const p = require("<workspace>/attw.json").problems;
for (const [kind, list] of Object.entries(p)) for (const x of list)
  console.log(kind, x.entrypoint ?? x.fileName ?? "", x.resolutionKind ?? x.resolutionOption ?? "")'

problems is an object keyed by problem kind, empty when the package is clean. Report the real exit status. Suppressing it with || true hides the failure from the shell, not from your consumers.

Offline, or when the checkers are broken

Use consumer-check.md: a tested script that installs the packed tarball into a throwaway consumer and type-checks an import of each entry point it is given, in every mode that entry publishes. It derives entries from the tarball's own exports map, so pass your step-1 deep imports and any concrete wildcard subpaths as arguments — a package with no exports map has no enumerable subpaths, and it will otherwise probe only the root and pass while the deep paths are untyped.

Do not call ts.resolveModuleName(spec, '/tmp/consumer.ts', ...) from the repo. Nothing installs the package into /tmp, so it reports UNRESOLVED for a perfectly good package, and a resolution lookup alone cannot see a broken import inside a declaration.

If the repo has a type test (test/typescript, *.test-d.ts, tsd, a test:typescript script), run it too.

6. Prove You Didn't Break The Build

Turning on declaration emission changes what the compiler checks. It surfaces errors the build never had — "has or is using name X from external module but cannot be named", inferred types referencing private symbols, and deprecation errors from tooling that calls tsc internally. These are real regressions, and they are easy to miss because the types goal appears met.

Run the checks your change can invalidate, once each:

What you changed	What that invalidates
Source, build config, or tsconfig	build, pack, consumer checks, tests
package.json routes or typesVersions only	routing/resolution and pack checks — not the runtime suites, not the install
Dependencies, the lockfile, or install-affecting config	the clean/frozen install, build and tests, and pack plus consumer checks, since a dependency change can change the declarations you emit

A successful check stays valid until something it depends on changes. Re-running an unchanged runtime suite after a metadata-only edit buys nothing. Equally, do not let lifecycle scripts run work twice: if pretest compiles, npm run build && npm test compiles twice and throws the first build away. Read the scripts from the preflight and chain accordingly.

Before you report success, each of these guarantees must hold, backed by evidence produced after the last change that invalidated it:

• A clean, frozen install — npm ci / pnpm install --frozen-lockfile / yarn --immutable — proving the manifest and lockfile you are shipping install from scratch. It must postdate your final dependency or lockfile edit. A clean install done before that edit proves nothing about what you are shipping; redo it, or say plainly that it predates the change. If you changed no dependencies at all, an earlier clean install still counts — name it.
• Build and test evidence for the current sources and config. If your last edit was routes-or-typesVersions-only, the green build and suites you already have are still valid: reuse them and say which run they came from. Do not repeat them "to be safe" — that is exactly the repetition this list exists to prevent.
• Pack and consumer evidence for the current artifact, from step 4 and step 5.

Run any install you do need from a clean state, not the warm node_modules your own ad-hoc installs produced. A build that only works in your session is a broken build.

If the build pipeline changed, check the watch:* scripts too — they usually duplicate the build command you just rewrote, and they break silently.

Do not dismiss a failing check as "pre-existing". Either confirm it against an unmodified baseline — a second checkout or git worktree add, never by stashing or resetting the working tree — or report it as failing and unexplained.

Forbidden Fixes

Declaration emission is a correctness check. Do not silence it.

• Do not add ignoreDeprecations. It is a short-lived compatibility window, not a fix. If a build tool's own internals trip a deprecation, upgrade or configure that tool.
• Do not downgrade TypeScript to dodge a declaration-tool problem. Fix or replace the tool.
• Do not add // @ts-ignore, // @ts-expect-error, or // @ts-nocheck to make declaration emission succeed.
• Do not widen exported types to any to avoid a "cannot be named" error. Export the referenced type instead — if it appears in a public signature, it is already part of your public API.
• Do not turn on skipLibCheck to hide errors in the declarations you just generated. Those errors are what your consumers will see.
• Do not delete a files/.npmignore exclusion wholesale when a narrower re-inclusion works, and do not delete a type test that fails.
• Do not hand-write a .d.ts that duplicates generated output. It will drift.
• Do not edit package.json metadata solely to quiet a checker you have not explained.

Environment

These cost whole runs when they aren't anticipated:

• The checkout may have no node_modules. tsc: not found, vite: not found, and a failing prepare hook usually mean this, not a broken config. Install once, in the preflight. Shipping unverified because a tool was missing is not acceptable.
• Anything interactive hangs until the run dies. Use npx --yes, npm init -y (plain npm init --silent still prompts for a name), and package-manager flags that never prompt. Prefer writing a two-line package.json to running an initializer at all.
• Work in a temporary directory and delete it on failure as well as success — trap 'rm -rf "$WORK"' EXIT. A .tgz or a scratch consumer left in the tree ends up in the diff.
• rg may not be installed. Fall back to grep -rn / find rather than retrying it.
• Bash history expansion eats ! inside double quotes. Verification one-liners like node -e "... if (!paths.includes(x)) ..." fail with event not found. Use single quotes around the script, or write it to a file.
• Extra arguments do not always reach the underlying tool. npm test -- --runInBand can arrive as jest "--" "--runInBand", which Jest reads as a test-name pattern and then reports that no tests matched. Read the script and pass arguments the way it forwards them.
• Keep JSON indentation consistent with the file. Re-read the file after patching package.json; a mis-indented insertion is a pointless extra review cycle.

Summarize

Keep it short and verifiable. Report:

• Each public entry point and the declaration file it now resolves to, per module mode — the table from attw or the packed-consumer check, not a full tarball listing
• How declarations are emitted (which config/tool changed)
• The exact packed paths you asserted in step 4
• Build, test, and clean-install results, with the commands that produced them

Then, in the same summary and without softening:

• Every check you could not complete, and why — a crashed checker, an offline tool, a suite you did not run. An unfinished check is not a pass.
• Every failure you are leaving behind, including attw diagnostics in supported modes.
• Anything that only worked with help: a stubbed binary, a shim on PATH, a hand-set environment variable. Say so; it makes the result narrower than "the build passes".
• Any failure you call pre-existing, with the baseline comparison that establishes it.
• The output of a repo-wide git status, so stray tarballs, caches, or edits in other packages are visible rather than shipped.