JavaScript/Node.js Conventions

Apply these conventions when working on JavaScript or Node.js files or projects.

Dispatch

References

Package Management

• Use pnpm for all Node.js package management
• Do not use npm or yarn unless the project explicitly requires them
• Commands: pnpm install, pnpm add <pkg>, pnpm run <script>, pnpm exec <cmd>
• Always commit pnpm-lock.yaml -- never .gitignore it
• Run pnpm install --frozen-lockfile in CI environments

Monorepo Conventions

• Use pnpm workspaces for multi-package repositories
• Define workspaces in pnpm-workspace.yaml at the repo root
• Use pnpm -r or pnpm --filter <pkg> for targeted operations
• Hoist shared dependencies to the root where possible

Lockfile Handling

• Commit lockfiles to version control
• Use --frozen-lockfile in CI to prevent drift
• When migrating from npm/yarn, delete the old lockfile and run pnpm import or pnpm install

Tooling Preferences

Critical Rules

1. Always use pnpm unless an existing lockfile or CI config mandates otherwise
2. Never mix package managers in the same project (no npm install alongside pnpm)
3. Commit pnpm-lock.yaml to version control in every project
4. Run pnpm install --frozen-lockfile in CI -- never allow lockfile mutation
5. Check references/edge-cases.md before breaking any convention
6. Use pnpm exec instead of npx for running local binaries

Canonical terms (use these exactly):

• pnpm -- the required package manager (not npm, not yarn)
• lockfile -- pnpm-lock.yaml specifically
• workspace -- pnpm workspace for monorepo packages
• frozen-lockfile -- CI mode that prevents lockfile changes