Onboarding Basics

Q: pnpm or npm for onboarding?

Use whatever CONTRIBUTING.md says. Do not let new hires pick their own manager on day one.

10 examples for day-one setup: Node LTS, package manager, Docker, local Postgres/Redis - so a new teammate runs the API before lunch.

Prerequisites

Clone the team repo and confirm the stack contract before installing dependencies.

git clone git@github.com:your-org/your-api.git
cd your-api
node -v   # expect v24.18.0
cat package.json | grep '"engines"'

Target stack for this section:

{
  "engines": { "node": "24.18.0", "npm": ">=10.0.0" },
  "packageManager": "npm@10.8.0"
}

Tooling: Node.js 24.18.0 (Active LTS), TypeScript 5.6+, Fastify 5 or Nest 11 per service ADR.

Basic Examples

1. Node 24 LTS with fnm or nvm

# fnm example
fnm install 24.18.0
fnm use 24.18.0
node -v   # v24.18.0
npm -v    # 10.x

# .nvmrc
24.18.0

Fix Node version before npm ci - wrong Node causes native module ABI errors
engines in package.json should match .nvmrc

Related: Installing & Version Management

2. Install Dependencies with npm ci

npm ci

Use npm ci, not npm install, on fresh clone to match CI exactly
If the team uses pnpm, run corepack enable && pnpm install --frozen-lockfile instead
One lockfile policy per repo - see Package Managers Basics

3. Environment Variables

cp .env.example .env

# .env.example (committed)
NODE_ENV=development
PORT=3000
DATABASE_URL=postgres://app:app@localhost:5432/app_dev
REDIS_URL=redis://localhost:6379
LOG_LEVEL=debug

Never commit .env with real secrets
Production secrets come from platform inject, not files

Related: Configuration Basics

4. Docker Compose for Postgres and Redis

# docker-compose.yml
services:
  postgres:
    image: postgres:16
    environment:
      POSTGRES_USER: app
      POSTGRES_PASSWORD: app
      POSTGRES_DB: app_dev
    ports: ["5432:5432"]
  redis:
    image: redis:7-alpine
    ports: ["6379:6379"]

docker compose up -d
npm run db:migrate

Local data stores match production topology (SQL + Redis) even if prod is managed RDS/ElastiCache
Document docker compose down -v wipes data - warn new hires

5. Start the API and Verify Health

npm run dev
curl -sf http://localhost:3000/health | jq .
curl -sf http://localhost:3000/ready | jq .

Green path: both return 200 before assigning feature work
If ready fails, check DATABASE_URL and Postgres container logs

Related: CLI Basics for Node

6. Run the Test Suite

npm test
npm run typecheck
npm run lint

Same three commands CI runs - learn them day one
Fix failures locally before opening first PR

7. CONTRIBUTING.md Checklist

Every repo should document:

## Quick start
1. fnm use / nvm use
2. npm ci
3. cp .env.example .env
4. docker compose up -d && npm run db:migrate
5. npm run dev
6. npm test

Buddy points new hire to CONTRIBUTING.md in first 30 minutes
Confusion on day one becomes a doc PR by day five

Intermediate Examples

8. Monorepo Bootstrap

cd your-monorepo
npm ci                    # root installs workspaces
npm run build --workspaces --if-present
cd services/orders-api
npm run dev

Root package.json defines workspaces
New hire works in one service first, not entire monorepo day one

Related: Workspaces & Monorepos

9. IDE and Debugger Setup

// .vscode/launch.json (excerpt)
{
  "type": "node",
  "request": "launch",
  "name": "Debug API",
  "runtimeArgs": ["--import", "tsx"],
  "args": ["src/server.ts"]
}

Commit shared VS Code/Cursor launch config
Breakpoint debugging beats console.log for learning async flow

10. Day-One Buddy Assignment

## New hire: Alex - start 2026-07-09
Buddy: Jordan (backend, 2 years)
Day 1: Machine setup + health green + codebase tour Tier 1
Day 2: Tiny doc PR (fix README path)
Day 3-5: First feature PR with pairing

Named buddy - not "ask in Slack"
See Team & Onboarding Best Practices

FAQs

pnpm or npm for onboarding?

Use whatever CONTRIBUTING.md says. Do not let new hires pick their own manager on day one.

Skip Docker if cloud dev environment exists?

If the org provides GitHub Codespaces or remote dev with Postgres/Redis, document that path equally in CONTRIBUTING.md.

Frontend → Node Path - week-one learning curve
Skills Matrix - leveling expectations
Team & Onboarding Best Practices - 25-item summary

Node.js Learn Guides - Official learning path.
NodeSchool - Free interactive workshoppers.
freeCodeCamp – Backend Development & APIs - Free certification path with Node/Express projects.
Get Programming with Node.js - Introductory programming with Node.js.
Node.js the Right Way - Server-side JavaScript fundamentals.

Stack versions: This page was written for Node.js 24.18.0 (Active LTS), npm 10+, TypeScript 5.6+, Express 5, Fastify 5, and NestJS 11.

Prerequisites

Clone the team repo and confirm the stack contract before installing dependencies.

git clone git@github.com:your-org/your-api.git
cd your-api
node -v   # expect v24.18.0
cat package.json | grep '"engines"'

Target stack for this section:

{
  "engines": { "node": "24.18.0", "npm": ">=10.0.0" },
  "packageManager": "npm@10.8.0"
}

Tooling: Node.js 24.18.0 (Active LTS), TypeScript 5.6+, Fastify 5 or Nest 11 per service ADR.

Basic Examples

1. Node 24 LTS with fnm or nvm

# fnm example
fnm install 24.18.0
fnm use 24.18.0
node -v   # v24.18.0
npm -v    # 10.x

# .nvmrc
24.18.0

Fix Node version before npm ci - wrong Node causes native module ABI errors
engines in package.json should match .nvmrc

Related: Installing & Version Management

2. Install Dependencies with npm ci

npm ci

Use npm ci, not npm install, on fresh clone to match CI exactly
If the team uses pnpm, run corepack enable && pnpm install --frozen-lockfile instead
One lockfile policy per repo - see Package Managers Basics

3. Environment Variables

cp .env.example .env

# .env.example (committed)
NODE_ENV=development
PORT=3000
DATABASE_URL=postgres://app:app@localhost:5432/app_dev
REDIS_URL=redis://localhost:6379
LOG_LEVEL=debug

Never commit .env with real secrets
Production secrets come from platform inject, not files

Related: Configuration Basics

4. Docker Compose for Postgres and Redis

# docker-compose.yml
services:
  postgres:
    image: postgres:16
    environment:
      POSTGRES_USER: app
      POSTGRES_PASSWORD: app
      POSTGRES_DB: app_dev
    ports: ["5432:5432"]
  redis:
    image: redis:7-alpine
    ports: ["6379:6379"]

docker compose up -d
npm run db:migrate

Local data stores match production topology (SQL + Redis) even if prod is managed RDS/ElastiCache
Document docker compose down -v wipes data - warn new hires

5. Start the API and Verify Health

npm run dev
curl -sf http://localhost:3000/health | jq .
curl -sf http://localhost:3000/ready | jq .

Green path: both return 200 before assigning feature work
If ready fails, check DATABASE_URL and Postgres container logs

Related: CLI Basics for Node

6. Run the Test Suite

npm test
npm run typecheck
npm run lint

Same three commands CI runs - learn them day one
Fix failures locally before opening first PR

7. CONTRIBUTING.md Checklist

Every repo should document:

## Quick start
1. fnm use / nvm use
2. npm ci
3. cp .env.example .env
4. docker compose up -d && npm run db:migrate
5. npm run dev
6. npm test

Buddy points new hire to CONTRIBUTING.md in first 30 minutes
Confusion on day one becomes a doc PR by day five

Intermediate Examples

8. Monorepo Bootstrap

cd your-monorepo
npm ci                    # root installs workspaces
npm run build --workspaces --if-present
cd services/orders-api
npm run dev

Root package.json defines workspaces
New hire works in one service first, not entire monorepo day one

Related: Workspaces & Monorepos

9. IDE and Debugger Setup

// .vscode/launch.json (excerpt)
{
  "type": "node",
  "request": "launch",
  "name": "Debug API",
  "runtimeArgs": ["--import", "tsx"],
  "args": ["src/server.ts"]
}

Commit shared VS Code/Cursor launch config
Breakpoint debugging beats console.log for learning async flow

10. Day-One Buddy Assignment

## New hire: Alex - start 2026-07-09
Buddy: Jordan (backend, 2 years)
Day 1: Machine setup + health green + codebase tour Tier 1
Day 2: Tiny doc PR (fix README path)
Day 3-5: First feature PR with pairing

Named buddy - not "ask in Slack"
See Team & Onboarding Best Practices

FAQs

pnpm or npm for onboarding?

Use whatever CONTRIBUTING.md says. Do not let new hires pick their own manager on day one.

Skip Docker if cloud dev environment exists?

If the org provides GitHub Codespaces or remote dev with Postgres/Redis, document that path equally in CONTRIBUTING.md.

Frontend → Node Path - week-one learning curve
Skills Matrix - leveling expectations
Team & Onboarding Best Practices - 25-item summary

Node.js Learn Guides - Official learning path.
NodeSchool - Free interactive workshoppers.
freeCodeCamp – Backend Development & APIs - Free certification path with Node/Express projects.
Get Programming with Node.js - Introductory programming with Node.js.
Node.js the Right Way - Server-side JavaScript fundamentals.

Stack versions: This page was written for Node.js 24.18.0 (Active LTS), npm 10+, TypeScript 5.6+, Express 5, Fastify 5, and NestJS 11.

Onboarding Basics

Search Documentation

Onboarding Basics