node

name	node
description	Node.js and TypeScript conventions for this repo: package management, build tooling, type safety, and testing patterns.
user-invocable	false
allowed-tools	["Bash(npm *)","Bash(pnpm *)","Bash(yarn *)","Bash(npx *)","Bash(node *)"]

Node.js / TypeScript Project Guide

This repo uses Node.js. Apply these conventions.

Package Management

• Use the package manager declared in package.json (packageManager field or lock file presence).
• Never mix npm, yarn, and pnpm in the same repo — pick one and stick with it.
• Pin exact versions for production dependencies in critical services; use ^ ranges for dev tooling.
• npm ci (not npm install) in CI — it respects the lockfile exactly.

TypeScript

• strict: true in tsconfig.json — no implicit any.
• Prefer interface for object shapes that will be extended; type for unions and aliases.
• Avoid as casts except at serialization boundaries — they silence the type checker.
• unknown instead of any for values from external sources; narrow before use.

Build Tooling

• Vite: vite build for production; vite dev for development.
• esbuild/tsup: for library builds; configure entry, format, and dts explicitly.
• Never import from dist/ in source files — fix the path alias instead.

Module Conventions

• Use ES modules ("type": "module" in package.json) for new projects.
• Named exports are preferred over default exports for better refactoring support.
• Barrel files (index.ts) for public APIs; avoid deep re-exporting.

Testing

• Vitest for unit tests (matches Vite config); Jest for legacy projects.
• Test files alongside source: foo.ts → foo.test.ts.
• Use vi.mock() / jest.mock() at module level — not inside test bodies.
• Integration tests must not share global state; reset before each test.