Skip to content
Skills Library
Programming · Building & coding

npm-patterns

/npm-patterns

Package management discipline for any JavaScript/TypeScript project: dependency declaration, semver, scripts conventions, lockfile hygiene, package-manager detection (npm/yarn/pnpm). Stack-agnostic — referenced by every JS/TS framework plugin in the marketplace. Use this skill to: - Add a dependency correctly (right field, right semver range). - Pick the project's package manager from lockfile. - Define `scripts` entries that match conventions. - Avoid lockfile mistakes (manual edits, wrong commits). Do NOT use this skill for: - Code-level conventions (see the active framework plugin's convent

Repository
claude-sdlc ↗
Licence
MIT
Last repository change
26.10.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
1
Scripts
0
HTML comments
0
URLs in SKILL.md
1
Deprecation

No signals detected. Repository changed on 26.10.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

Package management discipline for any JavaScript/TypeScript project: dependency declaration, semver, scripts conventions, lockfile hygiene, package-manager detection (npm/yarn/pnpm). Stack-agnostic — referenced by every JS/TS framework plugin in the marketplace. Use this skill to: - Add a dependency correctly (right field, right semver range). - Pick the project's package manager from lockfile. - Define `scripts` entries that match conventions. - Avoid lockfile mistakes (manual edits, wrong commits). Do NOT use this skill for: - Code-level conventions (see the active framework plugin's convent

Original author description

Package management discipline for any JavaScript/TypeScript project: dependency declaration, semver, scripts conventions, lockfile hygiene, package-manager detection (npm/yarn/pnpm). Stack-agnostic — referenced by every JS/TS framework plugin in the marketplace. Use this skill to: - Add a dependency correctly (right field, right semver range). - Pick the project's package manager from lockfile. - Define `scripts` entries that match conventions. - Avoid lockfile mistakes (manual edits, wrong commits). Do NOT use this skill for: - Code-level conventions (see the active framework plugin's convent

How it works

  1. Detect the package manager
  2. Dependency fields
  3. Semver discipline
  4. scripts conventions
  5. Lockfile policy
  6. engines field
  7. package.json type field
  8. Workspaces (monorepos)
  9. Dependency hygiene
  10. Anti-patterns
Original SKILL.md headings · 150 lines, 1,021 words
SKILL.md preview
---
name: npm-patterns
description: |
  Package management discipline for any JavaScript/TypeScript project: dependency declaration, semver, scripts conventions, lockfile hygiene, package-manager detection (npm/yarn/pnpm). Stack-agnostic — referenced by every JS/TS framework plugin in the marketplace.

  Use this skill to:
  - Add a dependency correctly (right field, right semver range).
  - Pick the project's package manager from lockfile.
  - Define `scripts` entries that match conventions.
  - Avoid lockfile mistakes (manual edits, wrong commits).

  Do NOT use this skill for:
  - Code-level conventions (see the active framework plugin's conventions skill).
  - Framework-specific package patterns (NestJS modules, Angular schematics, Expo SDK choice etc.).
user-invocable: false
paths: ["package.json", "package-lock.json", "pnpm-lock.yaml", "yarn.lock", ".npmrc"]
---

# npm / yarn / pnpm Patterns (stack-agnostic)

This skill consolidates package management idioms applicable to any JS/TS project — backend, frontend, mobile, library. Apply when modifying `package.json`, adding dependencies, or defining scripts.

## Detect the package manager

Look at the lockfile in the project root:

| Lockfile present | Use |
|---|---|
| `package-lock.json` | npm |
| `yarn.lock` | yarn |
| `pnpm-lock.yaml` | pnpm |
| `bun.lockb` / `bun.lock` | bun (rare; mostly drop-in for npm) |
| (none) | npm — but flag in DECISIONS that no lockfile is committed |

Also check `package.json` `"packageManager"` field (e.g. `"packageManager": "pnpm@8.6.0"`) — when present, it overrides lockfile inference.

Map common commands:

| Action | npm | yarn | pnpm |
|---|---|---|---|
| Install all | `npm install` | `yarn install` | `pnpm install` |
| Add runtime dep | `npm install pkg` | `yarn add pkg` | `pnpm add pkg` |
| Add dev dep | `npm install -D pkg` | `yarn add -D pkg` | `pnpm add -D pkg` |
| Run script | `npm run x` | `yarn x` | `pnpm x` |
| Update lockfile | `npm install` | `yarn install` | `pnpm install` |

Always run the install command after editing `package.json` — never edit the lockfile by hand.

## Dependency fields

| Field | Use for |
|---|---|
| `dependencies` | Runtime — what the production app needs to run (express, react, pinia, axios). |
| `devDependencies` | Dev tooling — bundlers, test runners, linters, type definitions, dev servers. |
| `peerDependencies` | Library authors only — declares what host app must provide (e.g., `react` for a React component library). |
| `optionalDependencies` | Rare — install failure should not break install (native binaries with fallbacks). |
| `bundledDependencies` | Rare — packaged inside `npm pack` tarball. |

Rule of thumb: if the code is bundled into the production output for runtime use, it's a dependency. If it only runs during `npm test` / `npm run build` / lint, it's a devDependency.

Frontend nuance: bundlers (Vite/Webpack/esbuild) often tree-shake unused exports — but the package still belongs in `dependencies` if any production-rendered code imports it.

## Semver discipline

| Range | Meaning | When to use |
|---|---|---|
| `^1.2.3` | >=1.2.3 <2.0.0 (no breaking changes) | Default — most deps |
| `~1.2.3` | >=1.2.3 <1.3.0 (only patch) | Conservative — production-critical |
| `1.2.3` | Exact | When you've debugged a specific version (rare) |
| `>=1.2.3` | Any version >=1.2.3 | Almost never — too loose |
| `*` or `latest` | Anything | NEVER. Reproducible builds matter. |
| `git+https://...` | Git ref | Only as last resort; pin to commit SHA. |

Default: `^x.y.z`. Lockfile pins exact versions for reproducibility — that's what makes `^` safe.

## `scripts` conventions

Common script names (be consistent — these are de-facto standard):

| Script | Purpose |
|---|---|
| `start` | Production entry: `node dist/index.js` (Node) or static server (frontend) |
| `dev` | Dev entry: `nodemon` / `tsx watch` / `vite` / `next dev` / `ng serve` |
| `build` | Compile/bundle: `tsc`, `vite build`, `next build`, `ng build`, `esbuild`, `webpack` |
| `test` | Test runner: `jest`, `vitest`, `mocha`, `ng test` |
| `test:watch` | Watch-mode tests |
| `test:coverage` | Coverage report |
| `test:e2e` | E2E tests (Playwright/Cypress/Detox) |
| `lint` | `eslint .` |
| `lint:fix` | `eslint . --fix` |
| `format` | `prettier --write .` |
| `format:check` | `prettier --check .` |
| `typecheck` | `tsc --noEmit` (or `vue-tsc --noEmit` for Vue) |
| `clean` | Remove `dist/`, `coverage/`, `.next/`, `out/` |
| `prepare` | Auto-runs after `install` (husky setup, etc.) |

Don't invent new names without a reason. CI configs and other tools assume these.

## Lockfile policy

- **Always commit** the lockfile to git.
- **Never edit** by hand. Always regenerate via the package manager.
- **Match the package manager**: don't commit `yarn.lock` and `package-lock.json` simultaneously.
- **Resolve conflicts** by accepting one side, then running `<pm> install` to regenerate.
- For library packages published to npm, lockfile is committed but not published (it's in `.npmignore` by default).

## `engines` field

Pin Node version when it matters (e.g., uses `node:test` requires ≥18, or your bundler requires ≥20):

```json
{
  "engines": {
    "node": ">=18.0.0"
  }
}
```

Add `engines.npm` only if you need a specific npm major version.

## `package.json` `type` field

- `"type": "module"` — files default to ESM. Use `import`/`export`. CJS files must use `.cjs` extension.
- Absent or `"type": "commonjs"` — files default to CJS. Use `require`/`module.exports`. ESM files must use `.mjs` extension.

Don't change this unless the BA spec explicitly asks; switching modes mid-project is invasive (especially for backend Node projects).

Frontend bundler-driven projects (Vite/Webpack/Next/Angular CLI) typically use `"type": "module"` regardless — bundler handles output.

## Workspaces (monorepos)

For monorepos:

```json
// Root package.json
{
  "name": "my-monorepo",
  "private": true,
  "workspaces": ["apps/*", "packages/*"]
}
```

- pnpm: uses `pnpm-workspace.yaml` instead.
- yarn: same `workspaces` field; berry vs classic differ in detail.
- Monorepo runners (Nx, Turborepo, Lerna): override default install/build/test orchestration. Match what's installed.

Per-app `package.json` files declare app-specific deps; root-only deps go in root.

## Dependency hygiene

- Run `npm audit` (or equivalent) when adding deps; fix Critical/High before committing.
- Avoid `--force` resolution unless you know what you're overriding and document it.
- Don't add deps for trivial utilities you can write in 5 lines (e.g., is-odd, padleft) — supply chain risk.
- Watch for typo-squatting: `lodash` vs `lodahs`, `chalk` vs `chal-k`.
- For frontend: bundle size matters — measure before adding heavy deps (use `bundlephobia.com` as a quick gauge).

## Anti-patterns

- ❌ `npm install --force` without justification.
- ❌ Editing `package-lock.json` / `yarn.lock` / `pnpm-lock.yaml` by hand.
- ❌ Using `*` or `latest` as a version range.
- ❌ Adding the same package to both `dependencies` and `devDependencies`.
- ❌ Committing `node_modules/`.
- ❌ Mixing package managers (lockfile from one, install via another).
- ❌ Adding `engines.node` without testing on the lower bound.
- ❌ For frontend: putting build-time tools in `dependencies` (bloats `npm ci` for production-only installs).

Versions

The database has no other skills named npm-patterns.

Database snapshot: 13.11.2026 · package version aa8c02c209f4 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100bun-package-manager
    Bun package manager commands (install, add, remove, update), workspaces, lockfiles, npm/yarn/pnpm migration. Use for dependency management with Bun.
  • 95package-management
    Use when choosing or configuring JavaScript/TypeScript package managers, managing dependencies, setting up workspaces, or publishing packages. Covers npm, yarn, pnpm, and bun. USE FOR: package manager selection, npm/yarn/pnpm/bun configuration, monorepo workspaces, dependency…
  • 100bun-package-manager
    Use when managing dependencies with Bun's package manager. Covers installing packages, workspaces, lockfiles, and migrating from npm/yarn/pnpm to Bun.
  • 100npm-publish
    Use when publishing or releasing a new version of an npm/pnpm/yarn/bun package to the registry. Covers package-manager detection, semver bump selection, tagging, pushing, scoped-package access, authentication, and one-time passwords (OTP).
  • 100npm-semver
    Semver and version-field discipline for published npm packages, plus a reminder to propagate a bump into consuming repos. TRIGGER when: editing the source of a published npm package, or preparing to publish one. DO NOT TRIGGER when: the package.json has "private": true, or the…
  • 100migrate-to-deno
    Use when moving a Node.js, npm, Yarn, pnpm, or Bun project to Deno, or when adopting Deno incrementally in an existing JavaScript or TypeScript codebase. Covers using Deno as a drop-in package manager, running existing package.json scripts, CommonJS versus ESM, node_modules…

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.