node-typescript

---
name: "node-typescript"
description: "Configures TypeScript for Node libraries and apps - explicit strict tsconfig, module and moduleResolution choices, verbatimModuleSyntax, isolatedDeclarations, declaration emit for publishing, tsc type-check gates, incremental strictification. Use when the user asks to set up TypeScript, tighten tsconfig, or fix declaration output. Not for lint rules, bundling, or package exports resolution."
license: "MIT"
---

# node-typescript

Produces TypeScript configurations that are **explicit, strict, and correct for
how the code is consumed**. The failures this skill fixes: models copy tsconfigs
whose implicit defaults changed between TypeScript majors, pick `bundler`
resolution for unbundled Node packages (broken for consumers), and flip strict
mode on a large codebase in one unreviewable big bang.

## When NOT to use

- Lint/format rules → `node-lint`.
- Bundling and `exports` maps / consumer type *resolution* → `node-packaging`
  (this skill owns declaration *emission*; the packaging skill owns how
  consumers resolve it).
- Test runner TS support → `node-testing`.

## Workflow

1. **Explicit-config principle first.** Never rely on generated or version
   defaults — TypeScript majors have changed them. Every option that matters is
   written out, per the blocks in `references/tsconfig-playbook.md`.
2. **Choose by consumption model**, not fashion:
   - Published/unbundled Node package → `module`/`moduleResolution` in the
     `nodenext` family; `verbatimModuleSyntax`; `declaration` +
     `declarationMap`; `isolatedDeclarations` where the API surface allows
     (parallel, tool-agnostic declaration emit).
   - Bundled app code → `bundler` resolution with `noEmit` (the bundler emits).
3. **Gate it**: `tsc --noEmit` (or `-b` for project references) as a script and
   a CI job (wiring → `node-ci`).
4. **Strictification of an existing codebase** is a ratchet, not a flip: measure
   the error surface first, enable flags incrementally (per-flag or
   per-directory), and keep CI green with a no-new-errors rule. Playbook has the
   sequence.
5. **Verify**: clean `tsc --noEmit`; for published packages, confirm declarations
   emit and hand consumer-resolution verification to `node-packaging`'s gates.

## Output spec

An explicit tsconfig with every load-bearing option stated; type-check script +
CI gate; for libraries: declarations emitting with maps; a written rationale for
module/resolution choices; strictification plan with measurable checkpoints when
applicable.

## Gotchas

- `bundler` resolution on a package consumed by Node directly will typecheck
  locally and break consumers — the consumption model decides, always.
- `verbatimModuleSyntax` makes `import type` mandatory for type-only imports and
  constrains CJS-emit default exports — enable it *with* the codemod pass.
- `isolatedDeclarations` demands explicit return types on exported API — great
  for libraries, noisy for apps; don't cargo-cult it into app configs.
- The Go-based compiler (tsgo/TS 7) is coming but changes no recommendation
  here: standard explicit tsconfigs stay compatible. No timeline promises.
- Version-gate: re-verify default/flag behavior against the official TSConfig
  reference when the TS major changes.

## Files

- `references/tsconfig-playbook.md` — explicit config blocks (library/app),
  nodenext-vs-bundler decision, strictification ratchet, verification commands.