JavaScript/Node.js Conventions

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

Dispatch

$ARGUMENTS	Action
Active (auto-invoked when working on JS/TS files)	Apply all conventions below
Empty	Display convention summary
check	Verify package manager compliance only

References

File	Purpose
references/edge-cases.md	Repo-specific exceptions and edge cases

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

Purpose	Tool
Package manager	pnpm
Bundler	vite or esbuild
Linting	eslint
Formatting	prettier
Testing	vitest or framework-native runner
Type checking	tsc --noEmit

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