Team Onboarding Checklist

For .NET engineers who know: The full Microsoft stack and are now joining a team using the JS/TS stack covered in this curriculum You’ll learn: The concrete, ordered steps to go from zero to productive — accounts to create, tools to install, repos to run, and the 30/60/90-day plan to fully ramp Time: 10-15 min read (then use the checklist as a working document)

The .NET Way (What You Already Know)

Onboarding to a .NET shop typically involves: getting a Windows machine joined to the domain, installing Visual Studio, connecting to Azure DevOps, cloning the solution, configuring connection strings in appsettings.Development.json, and asking someone to explain the solution architecture. The IDE does most of the heavy lifting — it finds the projects, resolves NuGet packages, and gives you a working F5 experience within an hour.

The toolchain is integrated. One installer (Visual Studio) handles the compiler, debugger, NuGet, and project system. Azure DevOps handles source control, CI, and work items. Azure handles hosting. The number of external accounts and CLI tools you need is low.

The JS/TS stack is different. You interact with more services, more CLI tools, and more configuration files. The trade-off is that the tools are lighter, faster, and composable — but the onboarding footprint is larger.

This article is your complete checklist. Print it, save it as a GitHub issue, or open it in a second window and work through it top to bottom.

The Onboarding Model

Onboarding happens in four stages:

Accounts — create accounts and get access to the systems your team uses
Local environment — install the tools needed to run the codebase
First run — clone repos, get the apps running locally, make a change
First contributions — fix a bug, add a feature, deploy to preview

Stages 1 and 2 can be done before your first day if you have access to the account creation steps. Stage 3 is typically day one. Stage 4 starts day two and takes through the end of week one.

Stage 1: Accounts

Create these accounts in order. Some require approval from an existing team member — flag those immediately so approval is not a blocker.

Version Control and Code Quality

GitHub account — github.com. Create a personal account if you do not have one. Your employer does not own your GitHub account. Use your work email as a secondary email for commit attribution if required.
- Ask team lead to add you to the organization and the relevant team.
- Enable two-factor authentication. This is required for all organizations we work with.
SonarCloud — sonarcloud.io. Log in with your GitHub account. SonarCloud uses GitHub OAuth.
- Ask team lead to add you to the organization.
- Verify you can see the project dashboards after being added.
Snyk — app.snyk.io. Log in with your GitHub account.
- Ask team lead to add you to the organization.
- Snyk scans dependencies for known vulnerabilities; you will see its PR checks immediately.
Semgrep — semgrep.dev. Log in with GitHub.
- Ask team lead to add you to the organization.
- Semgrep performs static analysis and security pattern matching; its findings appear in PRs.

Hosting and Infrastructure

Render — render.com. Create an account and log in with GitHub.
- Ask team lead to add you to the team.
- Verify you can see the services dashboard after being added.
- Render is our hosting platform. You will deploy here and read logs here.

Observability

Sentry — sentry.io. Create an account.
- Ask team lead to add you to the organization.
- Verify you can see the project issues after being added.
- Sentry is where you go when something breaks in production.

Authentication (Application)

Clerk — clerk.com. Create an account.
- Ask team lead to add you to the organization.
- Clerk manages user authentication for the applications you will build. You need dashboard access to configure auth settings and view user data in development.

AI Coding Assistant

Claude Code — Install via npm (covered in Stage 2). You need an Anthropic account to use Claude Code.
- Go to console.anthropic.com and create an account.
- Get an API key from the API Keys section. Store it in your password manager; you will not see it again.
- Alternatively, ask the team lead if there is a shared workspace API key for the team.

Stage 2: Local Environment

Work through this section in order. Each tool is a prerequisite for the next.

Terminal

On macOS, use Terminal.app or install iTerm2. On Linux, use your distribution’s default terminal. On Windows, use WSL2 with Ubuntu — the JS/TS toolchain is designed for Unix. Running natively on Windows without WSL2 works but produces inconsistent behavior with file watchers, line endings, and shell scripts.

# Verify your shell
echo $SHELL
# Should be /bin/zsh (macOS) or /bin/bash (Linux)

Git

Git is almost certainly already installed. Verify and configure it.

# Verify
git --version
# Should be 2.40+

# Configure your identity (use the same email as your GitHub account)
git config --global user.name "Your Name"
git config --global user.email "you@example.com"

# Set default branch name to main
git config --global init.defaultBranch main

# Set VS Code as the default git editor
git config --global core.editor "code --wait"

Configure SSH for GitHub. This avoids HTTPS credential prompts.

# Generate a key (if you do not have one)
ssh-keygen -t ed25519 -C "you@example.com"

# Add to SSH agent
eval "$(ssh-agent -s)"
ssh-add ~/.ssh/id_ed25519

# Copy the public key
cat ~/.ssh/id_ed25519.pub

Add the public key to your GitHub account: Settings → SSH and GPG keys → New SSH key.

# Verify it works
ssh -T git@github.com
# Should respond: Hi username! You've successfully authenticated...

Node.js

We use fnm (Fast Node Manager) to manage Node.js versions. Do not install Node.js directly from nodejs.org — it installs a system-wide version that cannot be swapped per project.

# Install fnm
curl -fsSL https://fnm.vercel.app/install | bash

# Reload your shell profile
source ~/.zshrc  # or ~/.bashrc

# Install the Node.js version we use (check .nvmrc in the repo, or use LTS)
fnm install 22
fnm use 22
fnm default 22

# Verify
node --version  # v22.x.x
npm --version   # 10.x.x

pnpm

pnpm is our package manager. Do not use npm or yarn on team projects — they produce different lockfiles and will cause merge conflicts.

# Install pnpm via the standalone installer (recommended)
curl -fsSL https://get.pnpm.io/install.sh | sh -

# Or via npm
npm install -g pnpm

# Verify
pnpm --version  # 9.x.x

Docker

Docker runs our local PostgreSQL database and other services. Install Docker Desktop from docker.com/products/docker-desktop.

# Verify
docker --version       # Docker 27.x.x or similar
docker compose version # Docker Compose version v2.x.x

VS Code

Download VS Code from code.visualstudio.com. After installing, open VS Code and install the required extensions.

Required extensions:

# Install from the command line (run after VS Code is installed and `code` is in PATH)
code --install-extension dbaeumer.vscode-eslint
code --install-extension esbenp.prettier-vscode
code --install-extension bradlc.vscode-tailwindcss
code --install-extension Prisma.prisma
code --install-extension ms-vscode.vscode-typescript-next
code --install-extension Vue.volar
code --install-extension ms-playwright.playwright
code --install-extension github.copilot  # if team uses Copilot alongside Claude

Recommended VS Code settings — add these to your settings.json (Cmd+Shift+P → “Open User Settings JSON”):

{
  "editor.defaultFormatter": "esbenp.prettier-vscode",
  "editor.formatOnSave": true,
  "editor.codeActionsOnSave": {
    "source.fixAll.eslint": "explicit"
  },
  "typescript.preferences.importModuleSpecifier": "relative",
  "typescript.updateImportsOnFileMove.enabled": "always",
  "eslint.validate": ["javascript", "typescript", "typescriptreact", "vue"],
  "files.insertFinalNewline": true,
  "files.trimTrailingWhitespace": true
}

GitHub CLI

The GitHub CLI (gh) is used extensively for PRs, issues, and CI status. We work GitHub-first; most workflows happen via gh rather than the web interface.

# Install on macOS
brew install gh

# Install on Linux
# Follow instructions at: https://github.com/cli/cli/blob/trunk/docs/install_linux.md

# Authenticate
gh auth login
# Choose: GitHub.com → HTTPS or SSH → Log in with a web browser
# Follow the prompts

# Verify
gh auth status

Claude Code

# Install Claude Code globally
npm install -g @anthropic-ai/claude-code

# Run the setup (it will prompt for your API key)
claude

# Or set the API key directly
export ANTHROPIC_API_KEY=sk-ant-...
# Add this line to your ~/.zshrc or ~/.bashrc to persist it

Verify Claude Code works:

# In any project directory
claude --help

Stage 3: Repos and First Run

Clone the Repositories

Ask your team lead which repositories you need. A typical setup:

# Create a development directory
mkdir ~/dev && cd ~/dev

# Clone the main application repo (example — use actual repo URL)
git clone git@github.com:your-org/main-app.git
cd main-app

# Install dependencies
pnpm install

# Copy the example environment file and fill in your values
cp .env.example .env

The .env file contains local secrets and configuration. Your team lead will share the development values. Common required variables:

# .env (never commit this file)
DATABASE_URL=postgresql://postgres:postgres@localhost:5432/appdb
CLERK_SECRET_KEY=sk_test_...
CLERK_PUBLISHABLE_KEY=pk_test_...
SENTRY_DSN=https://...@sentry.io/...

Start the Local Database

# Start PostgreSQL via Docker Compose
docker compose up -d postgres

# Run database migrations
pnpm db:migrate

# Optional: seed with development data
pnpm db:seed

# Open Prisma Studio to browse the database
pnpm db:studio

Prisma Studio opens at http://localhost:5555. It is the equivalent of SQL Server Management Studio for your local database.

Start the Application

# Start the development server(s)
pnpm dev

In a monorepo, pnpm dev at the root typically starts all services via Turborepo. In a single-package project, it starts one process.

Expected result: the application is available at http://localhost:3000 (or the port specified in .env), hot reload is working (change a file and the browser updates), and no errors appear in the terminal.

If something does not work:

Check the README — the Getting Started section should cover common issues
Check that all required environment variables are set in .env
Check that Docker is running and the database container is healthy: docker compose ps
Ask in the team Slack channel — do not spend more than 30 minutes blocked on setup

Run the Tests

# Run unit tests
pnpm test

# Run tests in watch mode (while developing)
pnpm test --watch

# Run end-to-end tests
pnpm test:e2e

All tests should pass on a clean checkout. If they do not, that is a bug in the project, not a problem with your setup. Report it.

Make Your First Change

Before writing any real code, make a trivial change to verify the full cycle works:

Create a new branch: git checkout -b chore/onboarding-hello-world
Add a comment to any file: // onboarding check - remove me
Run the linter: pnpm lint
Run the tests: pnpm test
Commit: git commit -m "chore: onboarding test commit"
Push: git push -u origin chore/onboarding-hello-world
Open a draft PR: gh pr create --draft --title "chore: onboarding test" --body "Testing my setup"
Observe the CI checks run in the PR
Close the PR without merging: gh pr close

If CI passes, your environment is correctly configured end-to-end.

Stage 4: First Contributions

Finding Your First Task

Ask your team lead for a “good first issue” — a low-stakes bug fix or small improvement that:

Does not require deep domain knowledge
Has a clear acceptance criterion
Touches a real part of the codebase (not a toy example)
Will be reviewed promptly

In GitHub Issues, look for the good-first-issue label.

The Task Workflow

# 1. Assign the issue to yourself
gh issue edit ISSUE_NUMBER --add-assignee @me

# 2. Create a branch from main
git checkout main && git pull
git checkout -b fix/brief-description-of-issue

# 3. Write the fix
# ... edit files ...

# 4. Run lint and tests
pnpm lint && pnpm test

# 5. Commit
git add specific-file.ts another-file.ts
git commit -m "fix: brief description of what was fixed

Fixes #ISSUE_NUMBER"

# 6. Push and open a PR
git push -u origin fix/brief-description-of-issue
gh pr create --title "fix: brief description" --body "
## Summary
- What changed and why

## Testing
- How you verified the fix

Fixes #ISSUE_NUMBER
"

Your First Deployment

Render deploys automatically from the main branch. To deploy your change:

Get your PR approved and merged to main
Render picks up the push automatically and starts a new deployment
Watch the deployment in the Render dashboard
Check the Render logs to confirm startup was clean
Verify your change is visible in the production or staging environment

If Render has preview environments configured (common for frontend changes), your PR will have a preview URL — a live deployment of your branch. Share it in the PR for easier review.

People to Meet

In your first week, schedule 30-minute 1:1s with:

Team lead — project context, priorities, communication norms
The engineer who last touched the main service — architecture walkthrough, known issues, ongoing work
The engineer responsible for infrastructure/DevOps — how deployments work, how to read logs, who to call when production breaks
A frontend engineer (if you are primarily backend) — how the client consumes the API, what the pain points are
A backend engineer (if you are primarily frontend) — how the API is structured, where the business logic lives

These are not status meetings. Come with specific questions about the codebase. “Walk me through how a new user signs up, end-to-end” is a better question than “can you explain the architecture?”

30/60/90-Day Plan

Days 1–30: Orient

Complete all four stages of this checklist
Fix at least two issues from the backlog
Review at least five PRs from teammates
Read all existing ADRs in docs/decisions/
Run through the full test suite locally and in CI
Deploy at least one change to production
Complete any outstanding articles from this curriculum that are relevant to your current work

Success criteria: You can open the codebase, find where a given feature is implemented, make a change, test it, and get it deployed. You do not need to ask for help with any of those steps.

Days 31–60: Contribute

Own at least one feature from issue creation to production deployment
Write an ADR for any significant technical decision you make or are involved in
Contribute to or update at least one runbook
Identify and fix one test coverage gap
Propose one improvement to the team’s process or tooling (PR, ADR, or discussion)

Success criteria: You are shipping features independently. You know which architectural decisions are settled and which are open to discussion. You have opinions about the codebase that are informed by the code, not just the curriculum.

Days 61–90: Lead

Be the primary reviewer on at least three PRs
Lead a small technical initiative (refactor, new tooling, infrastructure improvement)
Conduct a knowledge transfer session on something you’ve learned
Update this onboarding checklist with anything that was missing or wrong
Mentor the next engineer who joins after you

Success criteria: You are a full contributor. You are adding to the team’s institutional knowledge, not just drawing on it.

Gotchas for .NET Engineers

Gotcha 1: pnpm install must be run before every tool that reads node_modules. In .NET, dotnet build restores NuGet packages automatically. In Node.js, pnpm dev or pnpm test does not automatically install packages if package.json has changed. If you pull new commits and see Cannot find module '...' errors, run pnpm install first. Make it a habit: git pull && pnpm install && pnpm dev.

Gotcha 2: Environment variables are not inherited from your terminal session in the dev server. In .NET, environment variables set in launchSettings.json are scoped to the debug session. In Node.js projects, environment variables come from the .env file (via dotenv or the framework’s config module). Changing a variable in your terminal session (export FOO=bar) usually does not affect the running dev server — update .env and restart the dev server instead.

Gotcha 3: The lockfile is a team contract; do not upgrade dependencies unilaterally. pnpm-lock.yaml is committed to the repository and defines exact versions for the entire team. If you run pnpm add or pnpm update without discussing it, you change the lockfile for everyone. Dependency updates should go through a PR with CI verification, not be done incidentally while working on a feature. Never run pnpm install --no-frozen-lockfile on a team project without understanding why the lockfile is out of sync.

Gotcha 4: VS Code extensions must be installed per machine, not per repository. In .NET, ReSharper or StyleCop settings travel with the solution or .editorconfig. VS Code extensions are user-level, not workspace-level. If you do not have the ESLint extension installed, linting errors will not appear in the editor — but they will still fail CI. Install all required extensions on day one. If the project has a .vscode/extensions.json file, VS Code will prompt you to install recommended extensions automatically.

Gotcha 5: Node.js processes do not restart automatically on .env changes. IIS can pick up web.config changes without a restart. .NET apps with Azure App Configuration can reload settings at runtime. Node.js reads process.env once at startup. If you change .env, restart the dev server. This is obvious but easy to forget when you have had the server running for hours.

Hands-On Exercise

This article is itself the exercise. Work through the checklist from top to bottom and check off each item as you complete it.

When you reach the end, do one additional task: identify something that was confusing, missing, or incorrect in this checklist, open a GitHub issue describing it, and fix it in a PR. This is how the onboarding experience improves — every person who goes through it makes it slightly better for the next person.

Quick Reference

Daily Commands

# Start your day
git pull && pnpm install && pnpm dev

# Before committing
pnpm lint && pnpm test

# Create a PR
gh pr create --title "..." --body "..."

# Check CI status
gh pr checks

# View production logs
render logs --service SERVICE_ID --tail

# Check Sentry for recent errors
# (open sentry.io in browser — no CLI)

Branch Naming Conventions

feat/short-description       # new feature
fix/short-description        # bug fix
chore/short-description      # maintenance, dependency updates
docs/short-description       # documentation changes
refactor/short-description   # code changes with no behavior change

First-Week Checklist Summary

Stage	Item	Done?
Accounts	GitHub (with 2FA)	[ ]
Accounts	SonarCloud	[ ]
Accounts	Snyk	[ ]
Accounts	Semgrep	[ ]
Accounts	Render	[ ]
Accounts	Sentry	[ ]
Accounts	Clerk	[ ]
Accounts	Anthropic (Claude Code)	[ ]
Environment	Git configured	[ ]
Environment	fnm + Node.js 22	[ ]
Environment	pnpm 9	[ ]
Environment	Docker Desktop	[ ]
Environment	VS Code + extensions	[ ]
Environment	GitHub CLI	[ ]
Environment	Claude Code	[ ]
First run	Repos cloned	[ ]
First run	`.env` configured	[ ]
First run	Database running and migrated	[ ]
First run	Application starts	[ ]
First run	All tests pass	[ ]
First run	Test PR cycle completed	[ ]
First tasks	First issue assigned	[ ]
First tasks	First PR opened	[ ]
First tasks	First change deployed	[ ]

GitHub Issue Template

Copy this template when creating the onboarding issue for a new engineer. Assign it to them on their first day.

---
name: Engineer Onboarding
about: Onboarding checklist for new engineers joining the team
title: 'Onboarding: [Engineer Name]'
labels: onboarding
assignees: ''
---

## Welcome

This issue tracks your onboarding progress. Work through each section in order.
Check off items as you complete them. If anything is unclear or wrong, leave a
comment — and fix it in a PR when you have the bandwidth.

## Stage 1: Accounts

- [ ] GitHub account created and 2FA enabled
- [ ] Added to GitHub organization by team lead
- [ ] SonarCloud account created and added to organization
- [ ] Snyk account created and added to organization
- [ ] Semgrep account created and added to organization
- [ ] Render account created and added to team
- [ ] Sentry account created and added to organization
- [ ] Clerk dashboard access granted
- [ ] Anthropic account created and API key saved to password manager

## Stage 2: Local Environment

- [ ] Git configured with name, email, and SSH key for GitHub
- [ ] fnm installed and Node.js 22 active
- [ ] pnpm installed (v9+)
- [ ] Docker Desktop installed and running
- [ ] VS Code installed with all required extensions
- [ ] GitHub CLI installed and authenticated
- [ ] Claude Code installed and authenticated

## Stage 3: First Run

- [ ] Main application repo cloned
- [ ] `pnpm install` succeeded
- [ ] `.env` file configured with development values (get from team lead)
- [ ] Database container running (`docker compose up -d postgres`)
- [ ] Migrations applied (`pnpm db:migrate`)
- [ ] Application runs locally (`pnpm dev`)
- [ ] All tests pass (`pnpm test`)
- [ ] Test PR cycle completed (create draft PR, observe CI, close PR)

## Stage 4: First Contributions

- [ ] First issue assigned and in progress
- [ ] First PR opened and reviewed
- [ ] First change merged and deployed
- [ ] 1:1 completed with team lead
- [ ] 1:1 completed with infrastructure/DevOps engineer
- [ ] 1:1 completed with at least one other team member

## 30-Day Goal

- [ ] Two issues fixed independently
- [ ] Five PRs reviewed
- [ ] ADRs and runbooks read
- [ ] One improvement to this onboarding checklist submitted as a PR

---

**Questions?** Leave a comment here or message the team in Slack.
**Blocked?** Tag the team lead in a comment — do not stay blocked for more than 30 minutes on setup issues.

Keyboard shortcuts

TypeScript for .NET Engineers