<!-- skill: npm Ecosystem | version: 1.0.0 | description: Master package.json, semver, workspaces, publish and security audits | category: Web -->

## Instructions
- Treat `package.json` as contract: correct `name/version`, `type`, `exports`, `files`, `engines`, `scripts`; keep metadata (`description/license/repository`) accurate.
- Follow semver strictly: PATCH fixes, MINOR features, MAJOR breaks; express ranges as `^` (minor-safe) by default, `~` for-zero-major caution, exact pins for CLIs.
- Always commit lockfiles (`package-lock.json`); use `npm ci` in CI/deploy, `npm install` only for intentional upgrades; never hand-edit lockfiles.
- Separate deps: `dependencies` (runtime), `devDependencies` (build/test), `peerDependencies` (plugins/libs), `optionalDependencies` (platform extras).
- Prefer `npx` for one-shot tools (`npx prettier .`, `npx create-vite`), local `node_modules/.bin` via `npm run` scripts for repeatable tasks.
- Workspaces for monorepos: root `workspaces: ["apps/*","packages/*"]`, per-package names, `npm -w <pkg> run <script>`, shared devDeps hoisted to root.
- Publishing: set `files` whitelist, dual ESM/CJS via `exports` + `tsup`, include `README/CHANGELOG/LICENSE`, version with `npm version minor`.
- Enable provenance + 2FA: `npm publish --provenance` from CI OIDC, `npm access` scoping (`@scope/pkg`), deprecate (don't delete) bad versions.
- Audit routinely: `npm audit` + `npm audit fix` (review majors manually), `npm outdated`, replace abandoned deps, check licenses with `npx license-checker`.
- Consider pnpm/bun where apt: pnpm for disk-efficient monorepos (`pnpm-workspace.yaml`), bun for fast scripts; document the chosen manager + lockfile.
- Script hygiene: `dev/start/build/test/lint/typecheck` standard names, `prepublishOnly` runs build+test, cross-platform via `cross-env`/`shx` if needed.
- Cache safely: `npm cache verify` for corruption, honor `.npmrc` (`save-exact`, registry, `engine-strict=true`), pin Node via `.nvmrc` + `engines`.

## Examples
- Library publish: `exports` map (`.` + `./package.json`), `files: ["dist"]`, `tsup` dual build, `--provenance` publish from GitHub Actions.
- Monorepo: root + `apps/web` + `packages/ui` workspaces, shared eslint config, `npm -w apps/web run dev` per-app scripts.
- Audit fix: `npm audit` flags critical lodash path, `npm update lodash`, major bump reviewed via `npm diff`, lockfile recommitted, CI green.

## Workflows
1. Init: `npm init -y`, set name/version/type/engines/exports, add `.nvmrc` + `.npmrc` (`engine-strict=true`).
2. Install deliberately: `npm i <runtime>` vs `npm i -D <tooling>`; verify `package.json` section + lockfile diff after each add.
3. Script it: add dev/build/test/lint scripts; confirm clean-clone flow works: `npm ci && npm test && npm run build`.
4. Audit monthly: `npm outdated` → `npm update` minors → `npm audit fix` → manual review of majors/breaks.
5. Publish: bump (`npm version`), build (`prepublishOnly`), dry-run (`npm publish --dry-run`), then `npm publish --provenance`.

## Templates
```json
{
  "name": "@acme/utils",
  "version": "1.2.0",
  "type": "module",
  "description": "Shared utils",
  "main": "./dist/index.cjs",
  "module": "./dist/index.js",
  "types": "./dist/index.d.ts",
  "exports": { ".": { "import": "./dist/index.js", "require": "./dist/index.cjs", "types": "./dist/index.d.ts" } },
  "files": ["dist", "README.md", "LICENSE"],
  "engines": { "node": ">=20" },
  "scripts": {
    "dev": "vite", "build": "tsup src/index.ts --format esm,cjs --dts",
    "test": "node --test", "lint": "eslint .", "prepublishOnly": "npm test && npm run build"
  },
  "publishConfig": { "access": "public", "provenance": true }
}
```
```ini
# .npmrc
engine-strict=true
save-exact=false
audit-level=moderate
```

## Tools
- SARAH `shell_run`: `npm ci` for clean installs, `npm outdated`/`npm audit` for health, `npm publish --dry-run` before real publish.
- SARAH `file_write`: edit `package.json` scripts/exports directly; never touch `package-lock.json` or `node_modules` by hand.
- SARAH preview: after `npm run build`, list `dist/` matches `files` whitelist; verify packed output with `npm pack --dry-run`.

## Advanced
- `exports` mastery: subpath patterns (`./features/*`), `imports` (`#*`) aliases for internals, `browser`/`node` conditions for dual runtimes.
- Version surgery: `npm version patch -m "release %s"`, `npm deprecate pkg@1.0.0 "use 1.0.1"`, `npm dist-tag add pkg@2.0.0 beta`.
- Troubleshooting: phantom dep → missing declaration in package.json (works locally via hoisting, breaks in CI); `EBADENGINE` → `.nvmrc`/engine mismatch; lockfile churn → mixed npm/pnpm usage — standardize on one.
- Workspaces tips: `npm exec -ws -- <cmd>` runs across all, `npm query ":attr(...)"` inspects graph; keep cross-package imports via workspace protocol.
- Pro tip: `npm pkg get dependencies` / `npm pkg set scripts.x="y"` edits package.json from shell without JSON mangling; `npx -y` + pinned versions for CI one-shots.

## Documentation
- npm docs: https://docs.npmjs.com
- semver spec: https://semver.org
- pnpm workspaces: https://pnpm.io/workspaces
