Node, nvm & Tooling
.nvmrc
A .nvmrc file at the repo root pins the Node version. Anyone running nvm use gets the correct version automatically. CI reads this file too.
# .nvmrc (both backend/ and frontend/ root)
20Version Pinning Policy
Phase 1: pin all
@medusajs/*packages to exact versions (no^or~). Medusa minor releases sometimes contain breaking changes. Update deliberately, test in staging first.
| Package | Version policy | Reason |
|---|---|---|
@medusajs/medusa | Exact: 2.13.3 | Breaking changes in minor releases |
@medusajs/js-sdk | Exact: pin to match medusa | Must stay in sync |
next | Exact: 14.x.x | App Router API changes between minors |
stripe | Exact: pin | API version tied to webhook version |
TypeScript | Exact: 5.x | Type inference can change between patches |
devDependencies | ^ range OK | Only affects local dev |
Claude Code Plugin (Medusa-specific)
Once the backend is initialised, install the official Medusa Claude Code plugin. This gives Claude Code knowledge of DML data models, workflows, module isolation, and API route patterns specific to Medusa v2.
# Inside the project directory in Claude Code
/plugin marketplace add medusajs/medusa-claude-plugins
/plugin install medusa-dev@medusaEssential Tooling Stack
| Tool | Purpose | Config file |
|---|---|---|
| nvm | Node version management | .nvmrc |
| ESLint | Linting | .eslintrc.json |
| Prettier | Formatting | .prettierrc |
| TypeScript | Type checking | tsconfig.json |
| Husky | Git hooks | .husky/ |
| lint-staged | Run checks on staged files | .lintstagedrc.json |
| Zod | Runtime validation on all custom endpoints | src/api/*/validators.ts |
Pre-Commit Hook Pipeline
# .husky/pre-commit
npx lint-staged// .lintstagedrc.json
{
"*.{ts,tsx}": ["eslint --fix", "prettier --write", "tsc --noEmit"],
"*.{js,json,md}": ["prettier --write"]
}