# NPM Package

> Practical, human-friendly guidance for building, testing, securing, versioning, and publishing npm packages. Use this skill for libraries, CLIs, SDKs, component packages, or when the user mentions package.json, publishing, semver, build tools, or audits.

- Skill: `rafidstudio/npm-package` (Agent Skill, multi-file: 25 files)
- Install (CLI): `npx skillmds@latest add rafidstudio/npm-package`
- Raw SKILL.md: https://api.skillmd.com/api/skills/rafidstudio/npm-package/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Web & Frontend
- Author: rafidstudio (https://skillmd.com/u/rafidstudio)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/rafidstudio/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.