Node.js, pnpm and TypeScript

Many exercises and answer projects are small TypeScript programs: MCP servers, Agent SDK scripts and evaluation harnesses. This page sets up the toolchain they assume: Node.js 22.18 or newer (the current LTS is better), pnpm, and a project layout where node runs TypeScript directly, with no build step.

Before you start

• Works on macOS, Linux and Windows. On Windows, use PowerShell.
• If you already have Node, run node --version. Anything from v22.18.0 up can run .ts files with no flags. The current LTS (v26 at the time of writing) is the best choice, and eve needs v24 or newer.

1. Install Node.js with fnm

fnm is a fast Node version manager. It lets you switch versions per project.

macOS

brew install fnm

Linux

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

Windows

winget install Schniz.fnm

Next, set up your shell so fnm can put the right node on your PATH. Add the line for your shell to its profile and open a new terminal.

# ~/.zshrc (macOS default) or ~/.bashrc
eval "$(fnm env --use-on-cd --shell zsh)"   # use --shell bash in ~/.bashrc

# PowerShell profile: run `notepad $profile` to edit it
fnm env --use-on-cd --shell powershell | Out-String | Invoke-Expression

Then install the current LTS line (v26 at the time of writing; fnm install --lts also works) and make it the default:

fnm install 26
fnm default 26
node --version

If you don't want a version manager, use the installer from nodejs.org/en/download instead.

2. Install pnpm

pnpm 12 is a standalone binary. On macOS and Linux:

curl -fsSL https://get.pnpm.io/install.sh | sh -

On Windows, pnpm recommends the npm route, because Windows Defender sometimes blocks the standalone executable:

npm install -g pnpm@latest

Open a new terminal and check the version with pnpm --version.

3. Create the project layout exercises assume

Answer projects follow this shape. Create it once to see it work:

mkdir ts-check && cd ts-check
mkdir src test
pnpm init
pnpm add -D typescript @types/node

Edit package.json so it has these fields:

{
  "name": "ts-check",
  "private": true,
  "type": "module",
  "engines": { "node": ">=22.18" },
  "scripts": {
    "start": "node --env-file-if-exists=.env src/main.ts",
    "test": "node --test",
    "typecheck": "tsc --noEmit"
  }
}

Keep the devDependencies block that pnpm add wrote; only the fields shown change.

Add the tsconfig.json that the Node docs recommend for type stripping, plus strict:

{
  "compilerOptions": {
    "target": "esnext",
    "module": "nodenext",
    "noEmit": true,
    "strict": true,
    "rewriteRelativeImportExtensions": true,
    "erasableSyntaxOnly": true,
    "verbatimModuleSyntax": true,
    "skipLibCheck": true,
    "types": ["node"]
  },
  "include": ["src", "test"]
}

Then three small files:

export function greet(name: string): string {
  return `Hello, ${name}!`;
}

import { greet } from "./greet.ts";
 
console.log(greet(process.env.NAME ?? "world"));

import { test } from "node:test";
import assert from "node:assert/strict";
import { greet } from "../src/greet.ts";
 
test("greets by name", () => {
  assert.equal(greet("Ada"), "Hello, Ada!");
});

What each piece does:

• node src/main.ts runs TypeScript by stripping the types. Node doesn't type-check, so pnpm typecheck runs tsc for that.
• Imports keep the .ts extension (./greet.ts). Node requires it, and rewriteRelativeImportExtensions keeps tsc happy.
• erasableSyntaxOnly makes tsc reject syntax Node can't strip: enum, parameter properties, namespaces with runtime code. Use union types and plain classes instead.
• node --test finds *.test.ts files on its own, so you don't need a test framework.
• --env-file-if-exists=.env loads settings such as your OpenRouter key (ANTHROPIC_AUTH_TOKEN or OPENAI_API_KEY) from a .env file when there is one. Add .env to .gitignore.

Check it works

pnpm install && pnpm start && pnpm test && pnpm typecheck

Expected output, trimmed:

Hello, world!
ℹ tests 1
ℹ pass 1
ℹ fail 0

pnpm typecheck prints nothing when it passes.

Troubleshooting

Unknown file extension ".ts". Your Node is older than 22.18. Run node --version. If fnm installed a newer one, the shell setup line is missing from your profile, or you haven't opened a new terminal since adding it.

Cannot find module './greet'. Add the extension: import { greet } from "./greet.ts".

An error about unsupported TypeScript syntax, often pointing at an enum. Type stripping can't handle that syntax. Rewrite it as erasable TypeScript, or run the file with tsx.

pnpm: command not found after installing. Open a new terminal; the installer edits your shell profile. On Windows, check that npm's global folder is on PATH (npm prefix -g).

Going further

• Python with uv for the Python exercises
• MCP servers in Claude Code, which registers a TypeScript server you write