NPM Package

npm Package Builder

Packages have many consumers and environments; early choices (module format, exports, deps, types) shape future compatibility. Start by understanding who will use the package, then pick the shape, then write code.

Phase 0 — Intake (do this before scaffolding)

Don't scaffold until the key decisions are clear. Ask the user a short, batched set of questions (or offer sensible defaults they can accept).

See references/intake-questions.md for the full question bank. Minimum questions to resolve:

• Package name and scope (public vs private)
• TypeScript or JavaScript
• Target runtimes (Node, browser, isomorphic, CLI, framework)
• Module format (ESM-only or dual ESM+CJS)
• Runtime dependency policy (zero-dep goal or not)
• Test framework preference (Vitest/Jest/node:test)
• Node version floor (e.g. >=20)
• Release flow (manual publish / Changesets / semantic-release)

If the user asks you to pick defaults, recommend a pragmatic stack and list choices so they can veto. If an existing package needs review, run scripts/preflight.py first and use references/checklist.md to triage issues.

Phase 1 — Shape the package

After intake, pick the skeleton and read the most relevant reference:

• references/project-setup.md — package.json fields, exports, files, sideEffects, engines, dep classification.
• references/backend-packages.md — Node libraries and CLI patterns.
• references/frontend-packages.md — component libraries, peer deps, tree-shaking.
• references/build-and-bundling.md — tsup/rollup/unbuild decisions.

Guideline: Node-targeted libraries usually shouldn't bundle dependencies; browser-facing packages should be tree-shakeable and avoid bundling peer deps.

Phase 2 — Correctness: types, tests, smoke tests

Read references/testing.md and aim for three practical checks:

1. Unit tests covering the public API.
2. Type tests for TypeScript packages (expectTypeOf / tsd).
3. Install smoke test: npm pack the package, install into a temporary project, and import via both require() and import to validate exports and published files (scripts/smoke_test.sh).

Run scripts/preflight.py helpers to catch common packaging mistakes.

Phase 3 — Security and supply chain

Security is mandatory for published packages. Key checks:

• Run npm audit and interpret results (separate dev-only issues from runtime risks).
• Keep lockfiles, prefer npm ci in CI, avoid risky postinstall scripts, and limit transitive deps where possible.
• Review npm pack --dry-run to ensure only intended files ship; run secret scanning before publish.
• Prefer OIDC-based CI publishing and ephemeral tokens over long-lived repo secrets; enable 2FA on the npm account.
• Harden code at public boundaries and provide SECURITY.md and a clear patch/release plan.

If asked to assess security, run the tooling and report findings with severity and concrete fixes, separating package code issues from dependency issues.

Phase 4 — Release

Treat semver as a contract. Prepare consumer-focused changelogs and use npm publish --dry-run to inspect the tarball before publishing. Use prerelease tags (--tag next) for non-GA releases and prefer deprecation over unpublishing.

Automate releases from CI if the project owner approves the workflow and permissions; otherwise keep publishing manual. Always run the final gate: references/checklist.md + scripts/preflight.py.

Templates and scripts

assets/templates contains starter configs (package.json, tsconfig.json, tsup.config.ts, vitest.config.ts, eslint.config.js, .npmignore, .gitignore, README.template.md, SECURITY.template.md) and optional github-workflows examples. Copy and adapt; do not enable or run workflows that require repository or account permissions without explicit user approval.

scripts/preflight.py, scripts/smoke_test.sh, and scripts/security_scan.sh are provided to validate package.json, published tarball, and basic security checks — prefer running these locally or with the owner's consent.

Working style for this skill

• Ask first, scaffold second: short, targeted questions avoid wasted work.

• Explain trade-offs, then recommend a single pragmatic option.

• Verify facts before stating them (versions, advisories, metrics).

• Match the user's language for explanations; keep code and config in English.

• Adapt depth to the user's experience level.

• Permission note: do not modify or run CI/workflow configs that require repository or account permissions without explicit user consent.