TypeScript for .NET Engineers

A comprehensive guide for senior .NET engineers transitioning to the modern TypeScript/Node.js ecosystem.

Who This Book Is For

This book is designed for senior .NET engineers — people with deep Microsoft experience (C#, ASP.NET, SQL Server, Azure DevOps, Visual Studio) — who are transitioning into a modern open-source stack built on TypeScript, Node.js, React/Vue, PostgreSQL, and GitHub-centric workflows.

This is not a beginner curriculum. It assumes strong engineering fundamentals and focuses on mapping existing knowledge to new tools, closing specific gaps, and building fluency in the ecosystem conventions that differ from the Microsoft world.

You should read this book if you are:

• A senior engineer with 5+ years of .NET/Microsoft stack experience
• Comfortable with strongly-typed languages, ORMs, middleware pipelines, and enterprise patterns
• Now working on (or transitioning to) projects using: Next.js, NestJS, React, Vue 3, PostgreSQL, GitHub, CLI-first tooling

Our Stack

Every concept in this book is grounded in a specific, opinionated toolchain. We don’t survey the ecosystem — we teach our stack and explain why we chose it.

How This Book Is Organized

The book is organized into 9 parts with 78 chapters, plus 4 appendices:

1. Foundation & Mental Models — Mapping .NET concepts to the JS/TS world
2. TypeScript Deep Dive — The type system that replaces C#
3. Frontend Frameworks — React, Vue 3, Next.js, Nuxt
4. Backend with NestJS — The ASP.NET Core of Node.js
5. Polyglot Architectures — When .NET or Python is the right backend
6. Data Layer — PostgreSQL, ORMs, migrations
7. DevOps & Toolchain — GitHub, CI/CD, Render, Docker
8. Security & Quality — Sentry, SonarCloud, Snyk, Semgrep
9. Workflow & Productivity — Claude Code, CLI workflows, team conventions

Recommended reading order: Work through Parts I–III in the first two weeks, then continue through the remaining parts as you begin project work. Each chapter is self-contained but builds on concepts from earlier chapters.

Design Principles

• Respect your intelligence — you are a senior engineer, not a bootcamp student
• Always bridge from .NET — every concept is grounded in what you already know
• Show real code — examples from actual projects, not toy demos
• CLI-first — we work in terminals, not GUIs
• Opinionated — we chose this stack for reasons; we’ll explain them

Expected Outcome

After completing this book, you should be able to:

• Stand up a full Next.js or NestJS project from scratch
• Write idiomatic TypeScript with proper type safety across all layers
• Work confidently with PostgreSQL and a TypeScript ORM
• Use GitHub, Render, Sentry, and the security tools without hand-holding
• Use Claude Code as a daily productivity tool
• Architect polyglot systems — knowing when to keep .NET, when to add Python, and how to maintain type safety across language boundaries
• Ship your first PR within the first week of project work

The Landscape: .NET World vs. JS/TS Ecosystem

For .NET engineers who know: The Microsoft stack — C#, ASP.NET Core, EF Core, Azure DevOps, Azure hosting You’ll learn: How the JS/TS ecosystem maps to your .NET mental model, and which specific tools this curriculum teaches and why Time: 12 min read

The .NET Way (What You Already Know)

Microsoft built a vertically integrated stack. When you start a new ASP.NET Core project, you get a curated, co-designed set of tools: C# as the language, the CLR as the runtime, ASP.NET Core as the web framework, Entity Framework Core as the ORM, and NuGet as the package manager. Visual Studio (or Rider) handles the IDE. Azure DevOps handles CI/CD. Azure handles hosting. These components are designed to work together, tested together, and documented together. Microsoft owns the whole thing.

The practical consequence of this integration is that most architectural decisions are made for you. When you need an HTTP client, you reach for HttpClient. When you need auth, you configure ASP.NET Identity or integrate Azure AD. When you need a background job, you implement IHostedService. The framework answers these questions before you ask them.

This is genuinely good. Enterprise software benefits from opinionated, coherent stacks. The consistency lowers onboarding costs, simplifies debugging, and produces predictable results.

The JS/TS world does not work this way.

The JS/TS Way

In the JavaScript and TypeScript ecosystem, every layer of the stack is a separate decision made by the team. The language (TypeScript) is maintained by Microsoft but separately from any runtime. The runtime (Node.js) is maintained by the OpenJS Foundation. The web frameworks (Next.js, NestJS, Nuxt) are maintained by separate companies or open-source collectives. The ORM is your choice from a field of viable options. The hosting platform, the CI/CD pipeline, the observability tools — all independent products with independent release cycles, independent documentation, and independent communities.

The first time a .NET engineer encounters the JS ecosystem, the typical reaction is something between confusion and alarm. npm install on a new project downloads hundreds of packages. The same problem (form validation, state management, HTTP fetching) has five popular solutions. Answers on Stack Overflow reference library versions from three major releases ago. Articles that appear authoritative recommend approaches the community quietly deprecated two years later.

This is not incompetence. It is the natural consequence of an ecosystem built in public, by thousands of contributors, without a single coordinating entity. The flexibility is real and valuable — but it comes with a cognitive tax.

This curriculum solves that by making the decisions for you. We have chosen a specific, coherent stack. You will learn that stack. We will explain why we chose each tool, and we will map every concept to something you already know from .NET.

The Stack We’ve Chosen

Here is every tool in our stack, grouped by function:

You will notice that some .NET equivalents are the same tools used differently (Playwright, SonarCloud, Semgrep all support both ecosystems). Others have clear analogs. A few have no good equivalent — we will call those out explicitly in the relevant articles.

Full Ecosystem Map

The following table maps every major layer of the .NET stack to its JS/TS equivalent, including both the specific tools we use and the broader field of alternatives you will encounter in existing codebases.

Runtime and Language

Project Structure and Build

Packages and Dependencies

Web Framework

Frontend Frameworks

Data Layer

Testing

DevOps and Tooling

Key Differences

The table above shows structural equivalence. These are the philosophical differences that will change how you work:

Fragmentation is the default. In .NET, you get one HTTP client, one DI container, one ORM. In the JS ecosystem, there are five competing solutions for every problem. We have made choices; you do not need to re-evaluate them. But when you read external code, you will encounter the alternatives.

There is no assembly. In .NET, a project compiles to an assembly (.dll or .exe) — a discrete, versioned artifact. In the JS/TS world, TypeScript compiles to JavaScript files that are then bundled. The output is not a versioned artifact; it is a directory of files optimized for execution or delivery. There is no GAC. There is no strong naming.

Types are erased at runtime. TypeScript’s type system is a compile-time tool. At runtime, you have JavaScript. If you receive JSON from an API and type it as User, TypeScript believes you — but the runtime has no way to verify the claim. This is fundamentally different from C#, where a User object IS a User object, enforced by the CLR. This distinction drives almost all of the patterns in Article 2.3 (Zod and end-to-end type safety).

Single-threaded execution. Node.js runs your code on a single thread. Concurrency is achieved through the event loop, not thread pools. This has implications for how you write async code, how you handle CPU-intensive work, and how you think about scaling. Article 1.2 covers this in depth.

Ecosystem velocity is higher. The Node.js ecosystem moves faster than the .NET ecosystem. Major versions, breaking changes, and paradigm shifts happen more frequently. This is a trade-off, not a flaw — but it requires active attention to stay current. This curriculum uses the 2026 versions of all tools.

No integrated IDE. Visual Studio is a full IDE — debugger, designer, profiler, test runner, NuGet browser, all integrated. VS Code is a text editor with extensions. The debugging story is more manual, the tooling is more fragmented, and the workflow is more terminal-centric. Article 8.2 covers the CLI-first workflow.

Gotchas for .NET Engineers

node_modules is not the NuGet cache. In NuGet, packages are stored once in ~/.nuget/packages and referenced by all projects. In npm, every project gets its own node_modules folder with its own copies of every dependency. This is why a new Node.js project can download 500MB of packages and why node_modules is proverbially heavy. pnpm addresses this with hard links to a central store, which is one reason we use it. You will never commit node_modules. You will add it to .gitignore before your first commit.

Semver ranges are not lockfiles. In NuGet, a <PackageReference Version="6.0.1"> installs exactly version 6.0.1. In npm, "express": "^4.18.0" means “version 4.18.0 or any compatible minor/patch release.” Without a lockfile (pnpm-lock.yaml), two engineers running pnpm install on the same package.json can get different versions. Always commit the lockfile. Always use pnpm install --frozen-lockfile in CI.

TypeScript’s strict mode is not optional. TypeScript has a strict compiler flag that enables a set of checks including strict null checking, no implicit any, and others. When strict is off, TypeScript is approximately as type-safe as writing comments — it will accept almost anything. All our projects start with "strict": true in tsconfig.json. If you encounter a TypeScript codebase where strict is off, treat it with the same suspicion you would treat a C# codebase with #pragma warning disable at the top of every file.

async/await looks the same but is not. TypeScript async/await and C# async/await use the same keywords and similar syntax. The semantics are different in ways that will produce subtle bugs if you assume they are equivalent. The most important difference: in C#, await can resume on any thread pool thread; in Node.js, everything runs on the same thread. There is no ConfigureAwait(false). There is no Task.Run for offloading to a thread pool. Article 1.7 covers this in detail.

Hands-On Exercise

This is an orientation article — there is no code to write yet. The exercise is to set up your mental model.

Take any feature in a .NET project you know well — a typical CRUD API endpoint with validation, auth, and database access. Write down the ASP.NET components involved: the controller, the service, the repository or EF context, the DTO, the validation attributes, the auth filter.

Then, using the ecosystem map above, write the equivalent list for our JS/TS stack. Which NestJS component replaces the controller? Which replaces the EF context? Where does Zod fit in?

Keep this list. By the end of Track 4, every item on it will have a concrete, working implementation you have written yourself.

If you want to go further: spend 15 minutes exploring the NestJS documentation and the Next.js documentation. Do not try to learn anything yet — just notice how the documentation is structured, what concepts appear in the navigation, and how they compare to ASP.NET Core’s documentation structure.

Quick Reference

The Toolchain at a Glance

Key Conceptual Shifts

Where to Go Next in This Curriculum

• Article 1.2 — Node.js runtime: the single-threaded event loop explained for CLR engineers
• Article 1.3 — pnpm and package.json: NuGet to npm migration guide
• Article 1.7 — async/await: same syntax, different execution model
• Article 2.1 — TypeScript’s type system compared to C#’s
• Article 4.1 — NestJS architecture: the ASP.NET Core Rosetta Stone

Further Reading

• TypeScript Documentation — Start with the “TypeScript for Java/C# Programmers” handbook entry
• Node.js Documentation — The “Guides” section covers the event loop
• NestJS Documentation — The “Introduction” and “First Steps” chapters map well to ASP.NET Core mental models
• pnpm Documentation — The “Motivation” page explains why pnpm exists and why node_modules is the way it is

Runtime Fundamentals: CLR vs. Node.js

For .NET engineers who know: The CLR, thread pools, JIT compilation, and async/await in C# You’ll learn: How Node.js achieves high concurrency with a single thread, and why TypeScript’s async/await is syntactically familiar but mechanically different from C#’s Time: 15-20 minutes

The most dangerous misconception a .NET engineer brings to Node.js is this: “async/await looks the same, so it works the same.” It does not. Understanding why is not academic — it directly affects how you write correct, performant TypeScript code and explains behaviors that will otherwise baffle you in production.

The .NET Way (What You Already Know)

The CLR is a multi-threaded runtime. When a request arrives at an ASP.NET Core application, Kestrel picks it up and assigns it to a thread from the thread pool. That thread executes your middleware pipeline, controller action, and any synchronous work. When it hits an await, the CLR’s SynchronizationContext or TaskScheduler releases the thread back to the pool so it can serve another request while the awaited I/O operation completes. When the I/O finishes, a thread (possibly a different one) is pulled from the pool to resume execution.

// ASP.NET Core — this runs on a thread pool thread.
// When it hits await, the thread is returned to the pool.
// A (possibly different) thread resumes when the DB call completes.
[HttpGet("{id}")]
public async Task<UserDto> GetUser(int id)
{
    // Thread is released here while DB is doing I/O
    var user = await _dbContext.Users.FindAsync(id);

    // A thread pool thread resumes here — might not be the same thread
    return _mapper.Map<UserDto>(user);
}

The CLR’s model is fundamentally preemptive multi-threading: the OS scheduler can interrupt any thread at any time and switch to another. Your code runs in parallel across multiple cores. ConfigureAwait(false) exists because the default behavior captures the SynchronizationContext to resume on the original “context” (important in ASP.NET Framework or UI apps) — in ASP.NET Core you typically add it everywhere to avoid pointless context switches.

The thread pool dynamically sizes itself based on demand. The runtime can also handle CPU-bound work by running tasks on pool threads in parallel. This is the model you’ve internalized over years of .NET development.

Node.js works nothing like this.

The Node.js Way

Single Thread, Event Loop

Node.js runs your JavaScript/TypeScript code on a single thread. There is no thread pool for your application code. There is no concept of “releasing a thread to the pool.” At any given moment, exactly one piece of your code is executing.

This is not a limitation to work around — it is the architecture. And it handles high concurrency through a different mechanism: the event loop.

The event loop is an infinite loop that continuously checks for work to do. Node.js delegates I/O operations (network calls, file reads, database queries) to the operating system or to libuv (its cross-platform async I/O library). The OS handles the actual waiting. When the I/O completes, the OS notifies libuv, libuv queues a callback on the event loop, and the event loop executes that callback when the current synchronous work is done.

graph TD
    EL["Event Loop"]
    T["timers\nsetTimeout / setInterval"]
    P["pending callbacks"]
    PO["poll (I/O events)"]
    CH["check (setImmediate)"]
    JS["Your JS code\n(single thread)"]
    LIB["libuv thread pool\n(file I/O, DNS, crypto)"]
    OS["OS async I/O\n(network sockets, epoll/kqueue)"]

    T --> P --> PO --> CH --> T
    EL --- T
    EL --- JS
    EL --- LIB
    LIB --- OS

The event loop has distinct phases, each with its own queue of callbacks to execute:

1. Timers — callbacks from setTimeout and setInterval whose delay has elapsed
2. Pending callbacks — I/O callbacks deferred to the next loop iteration
3. Idle, prepare — internal use only
4. Poll — retrieve new I/O events; execute I/O callbacks (the main phase)
5. Check — setImmediate callbacks execute here
6. Close callbacks — cleanup callbacks (e.g., socket.on('close', ...))

Between each phase, Node.js drains two additional queues before moving on:

• process.nextTick queue — runs after the current operation completes, before returning to the event loop. Higher priority than Promises.
• Promise microtask queue — resolved Promise callbacks (.then(), await continuations)

Both of these run to completion between event loop phases. This matters when reasoning about execution order.

What await Actually Does in Node.js

In TypeScript/Node.js, await does not release a thread. There are no threads to release. What it does is yield control back to the event loop until the awaited Promise resolves.

// Node.js/TypeScript — there is only one thread.
// When we hit await, we yield to the event loop.
// The event loop can process other pending callbacks while the DB query runs.
// When the query completes (via libuv callback), our code resumes.

async function getUser(id: number): Promise<UserDto> {
    // Control yields to the event loop here.
    // Other requests can be handled while the DB query is in-flight.
    const user = await db.query('SELECT * FROM users WHERE id = $1', [id]);

    // We resume here on the same thread — always.
    return mapToDto(user.rows[0]);
}

The single thread is never blocked (assuming the code is written correctly). The event loop keeps spinning, picking up I/O completion callbacks and executing them in turn.

Side-by-Side: Handling 1,000 Concurrent Requests

To make this concrete, here is how ASP.NET Core and a Node.js HTTP server handle the same scenario: 1,000 simultaneous requests each requiring a 100ms database query.

ASP.NET Core (CLR)

sequenceDiagram
    participant R as Request
    participant T1 as Thread-1
    participant Pool as Thread Pool
    participant DB as Database
    participant T42 as Thread-42

    R->>T1: thread pool assigns Thread-1
    T1->>T1: executes middleware
    T1->>DB: await db.QueryAsync()
    T1->>Pool: released to pool
    Note over DB: 100ms passes
    DB->>Pool: DB returns
    Pool->>T42: resumes request
    T42->>R: sends response

The thread pool might have 50-200 threads active. Each await releases a thread but involves OS-level thread context switches. Memory overhead per thread: ~1MB stack.

Node.js

sequenceDiagram
    participant R as Request
    participant EL as Event Loop (Thread-1)
    participant LIB as libuv / OS
    participant DB as Database

    R->>EL: event loop processes it on Thread-1 (only thread)
    EL->>EL: code executes synchronously until first await
    EL->>LIB: await db.query() — libuv sends query to OS
    EL->>EL: picks up next pending request callback
    Note over LIB,DB: 100ms passes
    DB->>LIB: OS signals I/O completion
    LIB->>EL: event loop queues our callback
    EL->>R: executes our callback, sends response

No thread pool. No context switches between threads. Concurrent requests are handled by interleaving execution — each request makes progress whenever its I/O completes, with zero overhead from thread scheduling.

The result: for I/O-bound workloads, Node.js can handle tens of thousands of concurrent connections using a fraction of the memory a thread-per-request model would require.

A Full Request Lifecycle Comparison

Here is a complete picture of how a typical “fetch a user and return JSON” request flows through each system.

ASP.NET Core pipeline:

graph TD
    A["Kestrel"] --> B["Thread Pool: assign thread"]
    B --> C["Middleware 1: logging"]
    C --> D["Middleware 2: auth"]
    D --> E["Routing"]
    E --> F["Controller action invoked"]
    F --> G["await db.Users.FindAsync(id)\n← thread released to pool"]
    G --> H["DB returns\n← thread resumed (possibly different thread)"]
    H --> I["Map to DTO"]
    I --> J["JSON serialization"]
    J --> K["Response written"]
    K --> L["Thread returned to pool"]

Node.js + Express/NestJS pipeline:

graph TD
    A["libuv: TCP connection accepted"] --> B["Event loop: execute request handler"]
    B --> C["Middleware 1: logging (sync)"]
    C --> D["Middleware 2: auth (sync, or await JWT verify)"]
    D --> E["Route matched"]
    E --> F["Controller function called"]
    F --> G["await db.query()\n← yield to event loop"]
    G --> H["Other requests handled during DB wait"]
    H --> I["DB completes: callback queued"]
    I --> J["Event loop: resume our handler"]
    J --> K["Map result to response shape"]
    K --> L["res.json(data)\n← libuv writes to TCP socket"]
    L --> M["Event loop moves to next callback"]

The Node.js model has no thread assignment overhead, no stack allocation per request, and no context switch cost between requests. The trade-off is that everything in the critical path must be non-blocking — something that is easy to get wrong.

Key Differences

Gotchas for .NET Engineers

1. CPU-Bound Code Blocks Every Concurrent Request

In .NET, running a CPU-intensive calculation blocks one thread. The thread pool picks up the slack with other threads. In Node.js, a CPU-bound operation on the main thread blocks the entire event loop — no other request gets served until it finishes.

// This blocks every other request while it runs.
// In .NET, this would only block the one thread handling this request.
app.get('/fibonacci', (req, res) => {
    const result = fibonacci(45); // 3-4 seconds of CPU time
    res.json({ result }); // Every other request waits here
});

function fibonacci(n: number): number {
    if (n <= 1) return n;
    return fibonacci(n - 1) + fibonacci(n - 2);
}

The fix for genuine CPU-bound work is Node.js Worker Threads, which run JavaScript in a separate thread with its own V8 instance and event loop:

import { Worker, isMainThread, parentPort, workerData } from 'worker_threads';

// main-thread.ts
function runFibonacciInWorker(n: number): Promise<number> {
    return new Promise((resolve, reject) => {
        const worker = new Worker('./fibonacci-worker.js', { workerData: { n } });
        worker.on('message', resolve);
        worker.on('error', reject);
    });
}

// fibonacci-worker.ts — runs in its own thread, won't block the event loop
if (!isMainThread) {
    const { n } = workerData as { n: number };
    const result = fibonacci(n);
    parentPort?.postMessage(result);
}

Worker threads communicate via message passing (like Web Workers in the browser). They do not share memory by default. This is intentionally different from .NET’s shared-memory threading model — it eliminates most race conditions at the cost of serialization overhead. For most web API work, you will not need worker threads. If you are doing report generation, PDF rendering, image processing, or any computation that takes more than 10-20ms, you do.

2. async Functions That Contain Synchronous Blocking Code Are Still Blocking

Marking a function async in TypeScript does not make it non-blocking. It only means it returns a Promise and can use await. If the function body contains no await expressions, it runs synchronously and blocks the event loop for its entire duration.

// This is fully synchronous despite being async.
// Calling await on it still blocks the event loop for the duration of the loop.
async function processLargeArray(items: string[]): Promise<string[]> {
    // No await — this runs synchronously, blocking other requests
    return items.map(item => expensiveTransform(item));
}

// If expensiveTransform is slow, you need to either:
// 1. Move this to a Worker Thread
// 2. Break it into batches with setImmediate() between batches to yield the event loop
async function processLargeArrayYielding(items: string[]): Promise<string[]> {
    const results: string[] = [];
    for (const item of items) {
        results.push(expensiveTransform(item));
        // Yield to the event loop every 100 items
        if (results.length % 100 === 0) {
            await new Promise(resolve => setImmediate(resolve));
        }
    }
    return results;
}

3. There Is No ConfigureAwait(false), and You Do Not Need It

In C#, ConfigureAwait(false) is best practice in library code to avoid deadlocks caused by capturing the SynchronizationContext. .NET engineers sometimes reach for it out of habit when writing TypeScript.

In Node.js, there is no SynchronizationContext. There is only one thread. await always resumes on the event loop. There is no deadlock risk from sync-over-async because there is nothing to deadlock against. Do not look for an equivalent. Do not worry about it.

What you should worry about in its place: not forgetting await. In C#, forgetting await is often caught by the compiler or immediately visible because Task<T> is not assignable to T. In TypeScript, Promise<User> is assignable to… basically anything if you are not careful with your types, and the Promise will resolve silently in the background. Enable @typescript-eslint/no-floating-promises in your ESLint configuration. It will catch this class of bug at lint time.

// TypeScript won't always catch this without the lint rule
async function updateUser(id: number, data: UpdateUserDto): Promise<void> {
    // Missing await — the update runs, but we don't wait for it.
    // The function returns before the DB write completes.
    // The caller has no idea anything went wrong.
    db.update(users).set(data).where(eq(users.id, id)); // no await
}

4. Promise.all Concurrency Is Different from Task.WhenAll Parallelism

Task.WhenAll in C# runs tasks truly in parallel on multiple threads. Promise.all in Node.js runs Promises concurrently on a single thread — the I/O operations overlap, but the JavaScript code between await points still executes sequentially.

For I/O-bound work (API calls, DB queries), the practical result is similar — both approaches finish when the slowest operation finishes. For CPU-bound work, Promise.all provides no benefit because only one piece of code runs at a time.

// These two approaches have identical performance for I/O-bound operations.
// Neither is "parallel" in the CPU sense — both are concurrent I/O.

// Sequential — total time: 300ms + 200ms + 100ms = 600ms
const user = await fetchUser(id);
const orders = await fetchOrders(id);
const preferences = await fetchPreferences(id);

// Concurrent — total time: max(300ms, 200ms, 100ms) = 300ms
const [user, orders, preferences] = await Promise.all([
    fetchUser(id),
    fetchOrders(id),
    fetchPreferences(id),
]);

Use Promise.all (or Promise.allSettled) any time you have independent async operations that do not depend on each other’s results. This is the equivalent of Task.WhenAll and has the same performance benefit for I/O-bound work.

5. The Memory Model Is Not What You Expect

Node.js has a default heap limit of roughly 1.5GB on 64-bit systems. You can raise it with --max-old-space-size=4096 (to 4GB), but you cannot exceed physical RAM. Unlike the CLR, which has decades of optimization for large heaps and server workloads, V8’s GC is optimized for shorter-lived objects and smaller heaps.

For most web APIs, this is not a problem. Where it becomes one: in-memory caching of large datasets, streaming large file uploads into memory, and processing large JSON payloads without streaming. Know the limit exists, monitor your heap usage in production via Sentry or process.memoryUsage(), and prefer streaming approaches for large data.

Hands-On Exercise

This exercise demonstrates the event loop’s behavior concretely. Run it and verify you can predict the output before you do.

Create a file event-loop-demo.ts:

import { createServer } from 'http';
import { setTimeout as sleep } from 'timers/promises';

// Simulate two types of work:
// 1. I/O-bound: a DB query that takes 100ms
// 2. CPU-bound: a loop that takes 100ms

function cpuBound100ms(): void {
    const start = Date.now();
    while (Date.now() - start < 100) {
        // Busy-wait — burns CPU, blocks event loop
    }
}

async function ioBound100ms(): Promise<void> {
    // Yields to event loop for 100ms, does not block it
    await sleep(100);
}

let requestCount = 0;

const server = createServer(async (req, res) => {
    const id = ++requestCount;
    const start = Date.now();
    console.log(`[${id}] Request started at ${start}`);

    if (req.url === '/cpu') {
        cpuBound100ms(); // Blocks the event loop
    } else {
        await ioBound100ms(); // Yields to the event loop
    }

    const duration = Date.now() - start;
    console.log(`[${id}] Request done in ${duration}ms`);
    res.end(JSON.stringify({ id, duration }));
});

server.listen(3000, () => {
    console.log('Server running on port 3000');
});

Run it with:

npx ts-node event-loop-demo.ts

Then in a second terminal, send two concurrent requests to /io:

curl http://localhost:3000/io & curl http://localhost:3000/io &
wait

Both should complete in ~100ms total because they overlap. Now try with /cpu:

curl http://localhost:3000/cpu & curl http://localhost:3000/cpu &
wait

The second request will take ~200ms — it had to wait for the first CPU-bound request to finish before the event loop could pick it up. This is the event loop blocking in practice.

Next, extend the exercise:

1. Move the CPU-bound work to a Worker Thread and verify that both concurrent requests now complete in ~100ms.
2. Add console.log calls around process.nextTick and Promise.resolve().then() to observe microtask queue ordering.

Reference solution structure (fill in the Worker Thread implementation):

import { Worker } from 'worker_threads';
import { fileURLToPath } from 'url';
import { dirname, join } from 'path';

function runCpuBoundInWorker(): Promise<void> {
    return new Promise((resolve, reject) => {
        const worker = new Worker(
            join(dirname(fileURLToPath(import.meta.url)), 'cpu-worker.ts'),
            // ts-node/esm handles the TypeScript — in production, compile first
        );
        worker.once('message', resolve);
        worker.once('error', reject);
    });
}

Quick Reference

Further Reading

• The Node.js Event Loop, Timers, and process.nextTick — Official Node.js documentation. The definitive reference for event loop phases.
• Worker Threads — Node.js Documentation — Full API reference and examples for CPU-bound parallelism.
• Don’t Block the Event Loop (or the Worker Pool) — Official Node.js guide on what operations block the event loop and how to avoid them.
• V8 Blog — Memory Management — How V8’s garbage collector works, for engineers who want to understand the memory model deeply.

Package Management: NuGet vs. npm/pnpm

For .NET engineers who know: NuGet, MSBuild, dotnet add package, packages.lock.json, and the NuGet cache at %USERPROFILE%\.nuget\packages You’ll learn: How npm and pnpm package management maps to NuGet, where it diverges, and why those differences cause real problems if you don’t understand them Time: 15-20 minutes

The .NET Way (What You Already Know)

NuGet is the package manager for the .NET ecosystem. You reference packages in your .csproj file, restore them with dotnet restore, and the runtime uses the package graph to resolve dependencies. The key properties of this system:

• Centralized registry: NuGet.org is the default and dominant package source. Private feeds (Azure Artifacts, GitHub Packages) are opt-in.
• Version pinning by default: When you dotnet add package Newtonsoft.Json, you get an exact version in your .csproj. No ranges unless you write them manually.
• Global cache: All packages are stored once in ~/.nuget/packages and shared across every project on your machine. Two projects using Newtonsoft.Json 13.0.3 share the same on-disk files.
• MSBuild integration: Package restore is part of the build pipeline. dotnet build runs restore implicitly.
• Lockfile is optional: packages.lock.json exists but most projects don’t use it. Reproducibility is ensured by version pinning in .csproj.
• Transitive dependency resolution: NuGet resolves the full dependency graph and selects the lowest applicable version that satisfies all constraints — a “nearest wins” strategy when conflicts arise.

<!-- .csproj — explicit, versioned, readable -->
<ItemGroup>
  <PackageReference Include="Microsoft.EntityFrameworkCore" Version="8.0.0" />
  <PackageReference Include="Newtonsoft.Json" Version="13.0.3" />
  <PackageReference Include="Serilog.AspNetCore" Version="8.0.0" />
</ItemGroup>

This is the mental model you’re bringing to npm. Some of it maps cleanly. A significant portion does not.

The npm/pnpm Way

package.json vs. .csproj

The package.json file is the npm equivalent of .csproj — it declares your package identity, dependencies, and scripts. The structural difference is that .csproj is XML with a tight MSBuild contract, while package.json is a freeform JSON document with only a few reserved keys.

// package.json — the JS equivalent of .csproj
{
  "name": "my-api",
  "version": "1.0.0",
  "private": true,
  "dependencies": {
    "express": "^4.18.2",
    "zod": "^3.22.4"
  },
  "devDependencies": {
    "typescript": "^5.3.3",
    "@types/express": "^4.17.21",
    "vitest": "^1.2.0"
  },
  "scripts": {
    "build": "tsc",
    "dev": "ts-node-dev src/main.ts",
    "test": "vitest run",
    "lint": "eslint src"
  }
}

The dependencies / devDependencies split is the first conceptual shift: devDependencies contains packages only needed during development and build (compilers, test runners, linters). They are not installed in production environments when you run npm install --production or pnpm install --prod. In .NET there is no equivalent concept at the package reference level — build tools are either part of the SDK or handled by MSBuild targets.

Semver Ranges: The ^ and ~ Problem

This is the most operationally significant difference from NuGet.

In .csproj, Version="13.0.3" means exactly 13.0.3. In package.json, version strings are ranges by default:

When you run npm install or pnpm install, the package manager resolves each range to a specific version based on what’s currently published on the registry. Run it again six months later and you may get different versions — not because you changed anything, but because new patch releases were published within the allowed range.

This is why lockfiles exist and must be committed.

Lockfiles: Your Reproducibility Guarantee

In .NET, version pinning in .csproj provides reproducibility. In npm/pnpm, version ranges in package.json mean the lockfile is the reproducibility mechanism.

The lockfile records the exact resolved version of every dependency and transitive dependency. It must be committed to source control. It must be used in CI. Without it, two engineers cloning the same repo may install different package versions.

In CI, always use the locked install command:

# CI pipelines — install exactly what the lockfile specifies
pnpm install --frozen-lockfile    # fails if lockfile is out of date
npm ci                             # npm equivalent

Never use npm install or pnpm install without --frozen-lockfile in CI — these commands update the lockfile if ranges are satisfied by newer versions, defeating the purpose of locking.

node_modules vs. the NuGet Cache

The NuGet cache stores packages once at ~/.nuget/packages and all projects share them. npm installs packages directly into a node_modules folder inside each project. This has significant consequences:

The node_modules size problem: A freshly bootstrapped Next.js project can have 300MB+ in node_modules. If you work on five projects, that’s potentially 1.5GB of packages — most of them duplicates. This is not a hypothetical. It is a daily reality. The node_modules folder is famously joked about as the heaviest object in the universe for a reason.

You never commit node_modules. Every .gitignore for a Node.js project must include node_modules/. This is not optional. Committing node_modules is one of the few genuinely catastrophic mistakes a .NET engineer new to the JS ecosystem can make — it adds hundreds of megabytes to the repository and breaks everything downstream.

Why pnpm solves this: pnpm uses a content-addressed global store (similar to NuGet’s cache) and creates symlinks in node_modules rather than copying files. A package used by five projects is stored once on disk. This is the primary reason we use pnpm instead of npm.

graph TD
    subgraph NuGet["NuGet (all projects share one cache)"]
        NC["~/.nuget/packages/newtonsoft.json/13.0.3/\n← stored once"]
    end

    subgraph npm["npm (each project has its own copy)"]
        NA["project-a/node_modules/lodash/\n← full copy"]
        NB["project-b/node_modules/lodash/\n← another full copy"]
        NC2["project-c/node_modules/lodash/\n← another full copy"]
    end

    subgraph pnpm["pnpm (symlinks to one global store)"]
        PS["~/.local/share/pnpm/store/v3/lodash/4.17.21/\n← stored once"]
        PA["project-a/node_modules/lodash"]
        PB["project-b/node_modules/lodash"]
        PC["project-c/node_modules/lodash"]
        PA -->|symlink| PS
        PB -->|symlink| PS
        PC -->|symlink| PS
    end

Installing and Managing Packages

The CLI commands map cleanly once you understand the structure:

# Adding a package
dotnet add package Newtonsoft.Json --version 13.0.3
pnpm add zod                          # adds to dependencies, installs latest
pnpm add -D typescript                # adds to devDependencies (-D)
pnpm add zod@3.22.4                   # exact version

# Removing a package
dotnet remove package Newtonsoft.Json
pnpm remove zod

# Restoring/installing all packages
dotnet restore
pnpm install

# Listing installed packages
dotnet list package
pnpm list

# Updating packages
dotnet add package Newtonsoft.Json   # re-add to get latest compatible
pnpm update zod                       # updates within semver range
pnpm update zod --latest              # updates to latest, ignores range

Scripts in package.json vs. MSBuild Targets

MSBuild provides a task system with BeforeBuild, AfterBuild, custom Target elements, and rich dependency modeling. The scripts section in package.json is a simpler equivalent: named shell commands that can be invoked with pnpm run <name>.

<!-- .csproj MSBuild target -->
<Target Name="GenerateApiClient" BeforeTargets="Build">
  <Exec Command="nswag run nswag.json" />
</Target>

// package.json scripts
{
  "scripts": {
    "build": "tsc --project tsconfig.json",
    "build:full": "pnpm run generate && pnpm run build",
    "generate": "openapi-typescript api.yaml -o src/api-types.ts",
    "dev": "ts-node-dev --respawn src/main.ts",
    "test": "vitest run",
    "test:watch": "vitest",
    "test:coverage": "vitest run --coverage",
    "lint": "eslint src --ext .ts",
    "lint:fix": "eslint src --ext .ts --fix",
    "typecheck": "tsc --noEmit"
  }
}

Scripts run with pnpm run <name>, or for common ones like build, test, dev, and start, you can omit run:

pnpm build          # runs the "build" script
pnpm dev            # runs the "dev" script
pnpm run lint:fix   # "run" is required for names with colons/custom names

There is no direct equivalent to MSBuild’s dependency graph between targets. If you need script A to run before script B, you either chain them explicitly ("build:full": "pnpm run generate && pnpm run build") or use a tool like Turborepo (covered in Article 6.5).

You can also run scripts from packages directly without adding them to scripts:

pnpm exec tsc --version        # run a locally installed binary
pnpm dlx create-next-app@latest  # run without installing (like dotnet tool run)

Global vs. Local Installs

In .NET, global tools are installed with dotnet tool install -g and available everywhere. In npm/pnpm, global installs exist but are discouraged:

# Global install (works, but avoid if possible)
pnpm add -g typescript
tsc --version    # now available globally

# Local install (preferred)
pnpm add -D typescript
pnpm exec tsc --version    # run via pnpm exec
# or add to package.json scripts and run via pnpm run

The reason to prefer local installs: reproducibility. If TypeScript is installed globally at version 5.2 on your machine but a colleague has 5.0, you will get different compilation behavior. Local installs pin the version in package.json and the lockfile, guaranteeing every developer and CI pipeline uses the same version.

The one exception is project scaffolding tools you run once (create-next-app, nest new). For those, use pnpm dlx (equivalent to npx) to run them transiently without installing:

pnpm dlx create-next-app@latest my-app
pnpm dlx @nestjs/cli@latest new my-api

Auditing Dependencies for Vulnerabilities

npm and pnpm have built-in audit commands that check your dependency tree against a vulnerability database:

pnpm audit                    # show all vulnerabilities
pnpm audit --audit-level high # fail only for high/critical
pnpm audit --fix              # attempt to fix by upgrading within ranges

The output maps severity levels (critical, high, moderate, low, info) to CVE identifiers and the affected package. A typical audit finding:

┌─────────────────────────────────────────────┐
│                    moderate                   │
│   Prototype Pollution in lodash               │
│   Package: lodash                             │
│   Patched in: >=4.17.21                       │
│   Dependency of: my-lib > some-package        │
│   Path: my-lib > some-package > lodash        │
│   More info: https://npmjs.com/advisories/... │
└─────────────────────────────────────────────┘

The Path field is important — it shows that the vulnerable lodash is a transitive dependency (your dependency some-package depends on it, not your code directly). Fixing it may require waiting for some-package to publish an updated version, or overriding the transitive dependency version using pnpm’s overrides field:

// package.json — override a transitive dependency version
{
  "pnpm": {
    "overrides": {
      "lodash": ">=4.17.21"
    }
  }
}

This is the equivalent of the <PackageReference> version floor override in NuGet. It forces pnpm to use at least 4.17.21 regardless of what transitive dependencies request.

For team-wide continuous scanning, we integrate Snyk (covered in Article 7.3) into the CI pipeline. The built-in pnpm audit is useful for immediate checks; Snyk provides richer reporting and automated fix PRs.

Key Differences

Gotchas for .NET Engineers

1. Phantom Dependencies Will Burn You — Use pnpm’s Strict Mode

In .NET, if you want to use a library, you must add a <PackageReference> to your .csproj. The compiler will not let you use code from a package you haven’t explicitly declared.

npm’s flat node_modules structure breaks this contract. When package A depends on lodash, npm hoists lodash to the top-level node_modules folder. Your code can now import lodash and it will work — even though lodash is not in your package.json. This is a phantom dependency: you’re using a package you never declared.

The problem: when package A later drops its lodash dependency or pins a different version, your code silently breaks at runtime with a module-not-found error or, worse, a subtle behavior change.

pnpm prevents this by design. Its node_modules structure uses symlinks and only makes explicitly declared packages importable. Attempting to import a phantom dependency throws an error immediately, at development time. This is a primary reason we use pnpm.

# With npm (phantom dependency works silently)
npm install some-package   # some-package depends on lodash
# now "import lodash" works in your code — dangerous

# With pnpm (phantom dependency caught immediately)
pnpm add some-package      # some-package depends on lodash
# "import lodash" throws: Cannot find module 'lodash'
# Correct fix: pnpm add lodash (make it explicit)

If you inherit a project that was using npm and migrate to pnpm, the phantom dependency audit can reveal dozens of packages your code relies on but never declared.

2. Peer Dependency Warnings Are Not Optional — Address Them

When you install a package in .NET, NuGet resolves the dependency graph and silently picks compatible versions. In npm/pnpm, some packages declare peer dependencies: packages they require you to have installed separately, at a specific version range, in your own project.

A common example is a React component library that lists react as a peer dependency rather than a direct dependency, because it should use your version of React, not install its own.

 WARN  Issues with peer dependencies found
└─┬ @tanstack/react-query 5.18.1
  └── ✕ unmet peer react@^18.0.0: found 17.0.2

This warning means: @tanstack/react-query@5.18.1 requires React 18, but your project has React 17. In .NET, NuGet would refuse to install or show a binding redirect. In npm, the installation succeeds with a warning — and you get subtle runtime failures or simply broken behavior.

Peer dependency warnings must be resolved, not ignored. The fix is either to upgrade the peer (upgrade React to 18) or to find a version of the package that supports your current peer version.

3. The node_modules Folder Is Not the Global Cache — Delete It Freely

NuGet’s global cache at ~/.nuget/packages is precious — clearing it forces re-downloading everything. node_modules is not the cache; it is a local installation folder that can always be recreated from the lockfile.

The correct mental model: node_modules is a build artifact, like your bin/ and obj/ folders. You can and should delete it when things behave strangely:

# The Node.js equivalent of "clean solution"
rm -rf node_modules
pnpm install

# In a monorepo — delete all node_modules recursively
find . -name "node_modules" -type d -prune -exec rm -rf '{}' +
pnpm install

This is standard practice. Engineers run it several times a week when debugging dependency issues. Unlike deleting the NuGet cache, it does not trigger a network re-download if pnpm’s global store already has the packages.

4. The ^ Range Bites You in Lockfile-Free Environments

If you ever run pnpm install without a lockfile present — which happens when you clone a fresh repo before someone committed the lockfile, or when a lockfile is incorrectly gitignored — you will install whatever the latest versions within each range are at that moment. Two engineers cloning the same repo on different days can end up with different transitive dependency versions.

The lockfile must be committed. If pnpm-lock.yaml is in your .gitignore, remove it immediately. Check your .gitignore template — some generic Node.js templates include lockfiles in .gitignore by mistake.

# Verify your lockfile is tracked
git ls-files pnpm-lock.yaml   # should output the filename if tracked
git ls-files package-lock.json

If the lockfile exists but shows constant churn in git diff with no actual dependency changes, the cause is usually different engineers using different package manager versions. Standardize the pnpm version in package.json:

{
  "packageManager": "pnpm@8.15.1"
}

5. npm Scripts Have No Dependency Graph — Order Is Your Responsibility

MSBuild targets can declare BeforeTargets, AfterTargets, and DependsOnTargets, and the build system executes them in the correct order. package.json scripts have none of this. They are independent shell commands. Ordering is enforced only by explicit chaining:

{
  "scripts": {
    "prebuild": "pnpm run generate",  // "pre" prefix runs before "build"
    "build": "tsc",
    "postbuild": "pnpm run copy-assets"  // "post" prefix runs after "build"
  }
}

The pre<name> and post<name> convention exists for simple sequencing, but it becomes unwieldy for complex pipelines. For monorepos with inter-package dependencies, use Turborepo (Article 6.5), which provides the dependency graph that package.json scripts lack.

Hands-On Exercise

This exercise sets up a minimal TypeScript project from scratch using pnpm and exercises the core package management concepts covered in this article.

Prerequisites: pnpm installed (npm install -g pnpm or via brew install pnpm), Node.js 20+.

Step 1: Create the project

mkdir pkg-exercise && cd pkg-exercise
pnpm init

This creates a minimal package.json. Open it and observe the structure.

Step 2: Add dependencies with intentional version variation

pnpm add zod                    # adds with ^ range (e.g., "^3.22.4")
pnpm add -D typescript          # dev dependency
pnpm add -D @types/node

Inspect package.json — note the ^ prefixes. Inspect pnpm-lock.yaml — note the exact resolved versions.

Step 3: Understand the lockfile

# Simulate a fresh clone
rm -rf node_modules
pnpm install --frozen-lockfile   # installs exact versions from lockfile

Now modify the zod version range in package.json to "zod": "^3.0.0" without running pnpm install. Then run:

pnpm install --frozen-lockfile   # this should fail

The --frozen-lockfile flag fails because your package.json range no longer matches the lockfile. This is how CI catches drift. Revert the change.

Step 4: Audit the dependency tree

pnpm list                         # show installed packages
pnpm list --depth 3               # show transitive dependencies
pnpm audit                        # check for vulnerabilities

Step 5: Add a script and run it

Add to package.json:

{
  "scripts": {
    "typecheck": "tsc --noEmit",
    "build": "tsc"
  }
}

Create a tsconfig.json:

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "NodeNext",
    "moduleResolution": "NodeNext",
    "strict": true,
    "outDir": "dist"
  },
  "include": ["src"]
}

Create src/index.ts:

import { z } from "zod";

const UserSchema = z.object({
  name: z.string(),
  email: z.string().email(),
});

type User = z.infer<typeof UserSchema>;

const user: User = UserSchema.parse({ name: "Alice", email: "alice@example.com" });
console.log(user);

Run it:

pnpm typecheck    # type-checks without emitting files
pnpm build        # compiles to dist/
node dist/index.js

Step 6: Observe pnpm’s strict dependency isolation

Create a second file src/attempt-phantom.ts:

// This would work with npm (if zod's deps included something useful)
// With pnpm, you can only import what you explicitly installed
import { z } from "zod";  // works — declared in package.json

// If you tried to import something not in package.json:
// import _ from "lodash";  // would fail: Cannot find module 'lodash'
// Fix: pnpm add lodash

This reinforces that pnpm enforces explicit dependency declarations — the same contract NuGet enforces in .NET.

Quick Reference

Command Mapping

package.json Structure Reference

{
  "name": "my-project",
  "version": "1.0.0",
  "private": true,
  "packageManager": "pnpm@8.15.1",

  "dependencies": {
    "zod": "^3.22.4"
  },

  "devDependencies": {
    "typescript": "^5.3.3",
    "@types/node": "^20.11.0",
    "vitest": "^1.2.0"
  },

  "scripts": {
    "build": "tsc",
    "dev": "ts-node-dev src/main.ts",
    "test": "vitest run",
    "test:watch": "vitest",
    "typecheck": "tsc --noEmit",
    "lint": "eslint src"
  },

  "pnpm": {
    "overrides": {
      "some-vulnerable-dep": ">=4.17.21"
    }
  }
}

Version Range Quick Reference

Critical .gitignore Entries

# Always ignore — recreated by pnpm install
node_modules/

# Never ignore — required for reproducibility
# (make sure these lines are NOT in your .gitignore)
# pnpm-lock.yaml
# package-lock.json
# yarn.lock

Common Diagnostic Commands

pnpm why <package>         # why is this package installed? (like NuGet dependency graph)
pnpm list --depth 10       # full dependency tree
pnpm store path            # location of pnpm's global store
pnpm store prune           # clean up unused packages from global store
pnpm dedupe                # optimize lockfile by deduplicating dependencies

Further Reading

• pnpm Documentation — Start with the Motivation page to understand why pnpm exists and how it differs from npm
• npm Semantic Versioning Calculator — Interactive tool for understanding what a given version range resolves to
• package.json Field Reference (npm docs) — Authoritative reference for all package.json fields
• PNPM Workspaces — Relevant when you reach Article 1.4 (Monorepos & Workspaces), which builds directly on the concepts here

Project Structure: Solutions & Projects vs. Monorepos & Workspaces

For .NET engineers who know: .sln files, .csproj files, Project References, and MSBuild’s role in assembling multi-project solutions. You’ll learn: How the JS/TS ecosystem maps Solution → Monorepo, Project → Package, Assembly → npm package, and how to navigate an unfamiliar JS/TS codebase from the file system up. Time: 10-15 minutes

The .NET Way (What You Already Know)

In .NET, physical organization and logical organization are both handled by a pair of files: the Solution (.sln) and the Project (.csproj). The solution is the container — it lists which projects belong together and in what order to build them. Each project compiles to a single assembly (.dll or .exe), has its own dependencies defined in the .csproj, and can reference other projects in the same solution via <ProjectReference>.

A typical multi-project solution looks like this:

MyApp.sln
├── src/
│   ├── MyApp.Api/
│   │   ├── MyApp.Api.csproj       # references MyApp.Core
│   │   └── Controllers/
│   ├── MyApp.Core/
│   │   ├── MyApp.Core.csproj      # no internal references
│   │   ├── Domain/
│   │   └── Services/
│   └── MyApp.Infrastructure/
│       ├── MyApp.Infrastructure.csproj  # references MyApp.Core
│       └── Data/
└── tests/
    └── MyApp.Tests/
        ├── MyApp.Tests.csproj     # references MyApp.Api, MyApp.Core
        └── ...

The .csproj is doing two things at once: it defines how the project compiles (target framework, nullable settings, warnings-as-errors), and it defines what the project depends on (NuGet packages and project references). The SDK-style .csproj makes this reasonably concise.

The .sln ties everything together. Visual Studio reads it to know which projects to load. dotnet build MyApp.sln builds all of them in dependency order. dotnet test MyApp.sln finds all test projects automatically.

This model has two important properties that you should keep in mind as you read the rest of this article: strong isolation (each project is its own assembly, its own namespace root, its own compilation unit) and explicit dependency graph (project references are declared, not implied).

The JS/TS Way

Single-App Projects

Before covering monorepos, it is worth knowing what a standalone JS/TS project looks like, because you will encounter these at least as often as monorepos.

The root-level package.json is the entry point for understanding any JS/TS project — it is the rough equivalent of reading a .csproj file, except it also contains the build scripts, the test runner invocation, and sometimes the project’s entire configuration surface.

A standalone Next.js application:

my-next-app/
├── package.json          # dependencies, scripts, name/version
├── package-lock.json     # lockfile (or pnpm-lock.yaml if using pnpm)
├── tsconfig.json         # TypeScript compiler configuration
├── next.config.ts        # Next.js framework configuration
├── .env.example          # documented environment variable template
├── .env.local            # actual secrets (never committed)
├── src/
│   ├── app/              # App Router: file-system-based routing
│   │   ├── layout.tsx    # root layout (like _Layout.cshtml)
│   │   ├── page.tsx      # root page (/)
│   │   ├── globals.css
│   │   └── dashboard/
│   │       └── page.tsx  # /dashboard route
│   ├── components/       # shared React components
│   ├── lib/              # utility functions, type definitions
│   └── types/            # global TypeScript type declarations
└── public/               # static assets (no build processing)

A standalone NestJS API:

my-nest-api/
├── package.json
├── tsconfig.json
├── tsconfig.build.json   # extends tsconfig.json, excludes tests
├── nest-cli.json         # NestJS build tooling configuration
├── .env.example
├── src/
│   ├── main.ts           # application bootstrap (like Program.cs)
│   ├── app.module.ts     # root module (like Startup.cs / IServiceCollection)
│   ├── app.controller.ts
│   ├── app.service.ts
│   └── users/            # feature module (like a domain project)
│       ├── users.module.ts
│       ├── users.controller.ts
│       ├── users.service.ts
│       ├── dto/
│       │   ├── create-user.dto.ts
│       │   └── update-user.dto.ts
│       └── entities/
│           └── user.entity.ts
└── test/
    ├── app.e2e-spec.ts
    └── jest-e2e.json

Note the NestJS layout: the users/ directory is a self-contained feature slice — module, controller, service, DTOs, and entities all in one folder. This is a NestJS convention, not a file-system-enforced rule. It resembles organizing by domain in ASP.NET Core (vertical slice architecture), but there is no compiler telling you about it.

Monorepos

When your project grows to include multiple apps or shared libraries, a monorepo packages them together under a single repository root. This is the direct equivalent of a .sln containing multiple .csproj files.

The structure for a monorepo containing a Next.js frontend, a NestJS API, and a shared types package:

my-project/                         # .sln equivalent (the root)
├── package.json                    # root package.json (workspace definition)
├── pnpm-workspace.yaml             # tells pnpm which folders are packages
├── pnpm-lock.yaml                  # single lockfile for the entire monorepo
├── turbo.json                      # Turborepo build orchestration config
├── tsconfig.base.json              # base TypeScript config, extended by all packages
├── .env.example
├── apps/
│   ├── web/                        # Next.js frontend
│   │   ├── package.json            # name: "@myproject/web"
│   │   ├── tsconfig.json           # extends ../../tsconfig.base.json
│   │   ├── next.config.ts
│   │   └── src/
│   └── api/                        # NestJS backend
│       ├── package.json            # name: "@myproject/api"
│       ├── tsconfig.json
│       ├── nest-cli.json
│       └── src/
└── packages/
    ├── types/                      # shared TypeScript types
    │   ├── package.json            # name: "@myproject/types"
    │   ├── tsconfig.json
    │   └── src/
    │       └── index.ts
    └── utils/                      # shared utility functions
        ├── package.json            # name: "@myproject/utils"
        ├── tsconfig.json
        └── src/
            └── index.ts

The root package.json in a pnpm workspace looks like this:

{
  "name": "my-project",
  "private": true,
  "scripts": {
    "dev": "turbo run dev",
    "build": "turbo run build",
    "test": "turbo run test",
    "lint": "turbo run lint"
  },
  "devDependencies": {
    "turbo": "^2.0.0",
    "typescript": "^5.4.0"
  }
}

And pnpm-workspace.yaml:

packages:
  - "apps/*"
  - "packages/*"

This file is roughly equivalent to the project list inside a .sln file. It tells pnpm: these directories are the packages that make up this workspace. Every directory listed here must have its own package.json.

Workspace Dependencies (Project References)

When @myproject/web needs types from @myproject/types, you declare that dependency in apps/web/package.json using the workspace: protocol:

{
  "name": "@myproject/web",
  "dependencies": {
    "@myproject/types": "workspace:*"
  }
}

// .NET equivalent in MyApp.Api.csproj:
// <ProjectReference Include="../MyApp.Core/MyApp.Core.csproj" />

The workspace:* syntax tells pnpm: use the local version of this package, not the one from the npm registry. At build time, pnpm symlinks the packages together. No separate publish step is required for internal packages during development.

tsconfig.json: The .csproj for Compilation

tsconfig.json is the TypeScript compiler configuration file. It controls what TypeScript compiles, how, and what rules apply. For .NET engineers, the mental model is: .csproj’s <PropertyGroup> section, but for the TypeScript compiler rather than the C# compiler.

A representative tsconfig.json for a NestJS API:

{
  "compilerOptions": {
    "module": "commonjs",
    "target": "ES2022",
    "lib": ["ES2022"],
    "strict": true,
    "esModuleInterop": true,
    "experimentalDecorators": true,
    "emitDecoratorMetadata": true,
    "outDir": "./dist",
    "rootDir": "./src",
    "paths": {
      "@/*": ["./src/*"]
    }
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules", "dist", "test"]
}

Mapped to .csproj equivalents:

In a monorepo, you typically have a tsconfig.base.json at the root that defines shared settings, then each package’s tsconfig.json extends it and adds package-specific overrides:

// packages/types/tsconfig.json
{
  "extends": "../../tsconfig.base.json",
  "compilerOptions": {
    "outDir": "dist",
    "rootDir": "src",
    "declaration": true,
    "declarationMap": true
  },
  "include": ["src"]
}

The "declaration": true option generates .d.ts type definition files alongside the compiled JavaScript. This is how TypeScript packages expose their types to consumers — the rough equivalent of having a public API surface that other assemblies can reference.

Build Orchestration with Turborepo

Turborepo (often shortened to “turbo”) is the build orchestrator for JS/TS monorepos. The closest .NET analogy is MSBuild’s dependency graph resolution: turbo understands which packages depend on which, and it builds them in the right order while parallelizing everything it safely can.

The turbo.json configuration:

{
  "$schema": "https://turbo.build/schema.json",
  "tasks": {
    "build": {
      "dependsOn": ["^build"],
      "outputs": ["dist/**", ".next/**"]
    },
    "dev": {
      "cache": false,
      "persistent": true
    },
    "test": {
      "dependsOn": ["build"]
    },
    "lint": {}
  }
}

The "^build" syntax means “run the build task in all dependencies first.” So if @myproject/web depends on @myproject/types, running turbo build in the root will build types before building web. This is the behavior you get for free from MSBuild with <ProjectReference> — turbo makes it explicit.

Turbo also provides build caching: if nothing in a package has changed since the last build, turbo skips that package’s build entirely and restores outputs from cache. This is similar to incremental compilation in MSBuild, but turbo’s caching is more aggressive and can be distributed across CI runners.

Key Differences

One difference that often surprises .NET engineers: there is no concept of internal visibility in TypeScript at the package level. You can mark members private or protected on classes, but you cannot prevent another package in your monorepo from importing a module that you intend to be “internal” — unless you carefully configure the exports field in package.json to limit which paths are publicly resolvable.

Gotchas for .NET Engineers

1. node_modules exists in multiple places in a monorepo, and this is intentional.

In a pnpm workspace, each package has its own node_modules directory containing symlinks to the actual package files stored in a central content-addressable store. You will also see a node_modules at the root. Do not try to rationalize this based on your NuGet mental model — NuGet has a single global cache and project-local references; pnpm has a similar global store but surfaces local node_modules per package to satisfy Node.js’s module resolution algorithm. The key rule: never manually modify node_modules. Run pnpm install at the repo root and let pnpm manage the structure.

2. There is no single entry point for “build all projects in the right order” unless you configure it.

In .NET, dotnet build MySolution.sln automatically resolves the dependency graph and builds in order. In a JS/TS monorepo, this is not automatic. Without Turborepo (or a similar orchestrator like Nx), running pnpm build in the root will attempt to build all packages in parallel or alphabetical order — which will fail if @myproject/web depends on the built output of @myproject/types. You need Turborepo’s "dependsOn": ["^build"] configuration to get the correct ordering. Many monorepos that look broken to newcomers are broken for exactly this reason: someone ran a build command outside of turbo.

3. tsconfig.json paths aliases require a separate runtime resolution step.

The paths option in tsconfig.json — commonly used to define import aliases like @/ to map to src/ — is a TypeScript compiler feature only. It tells the TypeScript language server and tsc how to resolve imports, but it does not affect the output JavaScript. If you use import { something } from '@/lib/utils' and your runtime is Node.js, the path alias will not be resolved at runtime unless you configure an additional tool to handle it. For NestJS, this means adding path alias configuration to nest-cli.json or using tsconfig-paths at startup. For Next.js, the framework handles this automatically. For a shared package compiled with tsc, you need tsc-alias or similar. This is a common source of “works in the editor, fails at runtime” bugs.

4. The absence of a .sln-equivalent means project discovery is by convention, not registration.

In .NET, a project must be explicitly added to the solution to be part of the build. In a pnpm workspace, any directory matching the glob patterns in pnpm-workspace.yaml is automatically treated as a workspace package. This means a new packages/my-new-lib/ directory with a package.json is immediately part of the workspace on the next pnpm install. There is no registration step. This is convenient but also means orphaned or experimental packages sitting in the right directory are silently included.

5. package.json "main", "module", and "exports" fields control what is actually public.

When one package in your monorepo imports from another, Node.js resolves what gets imported based on the "exports" field in the target package’s package.json. If you set "exports": { ".": "./dist/index.js" }, then only what is exported from dist/index.js is importable — all other paths in the package are opaque to the consumer. Omit exports, and Node.js allows importing any path inside the package. This is the closest you get to .NET’s internal keyword for package-level boundaries.

Hands-On Exercise

The goal is to orient yourself in an unfamiliar monorepo — the same skill you use when joining a team with an existing .sln.

Clone any public monorepo (or use the one you are working in) and complete this walkthrough:

Step 1: Find and read the workspace definition.

cat pnpm-workspace.yaml
# or, if using npm workspaces:
cat package.json | grep -A 10 '"workspaces"'

This tells you how many packages exist and where they live.

Step 2: List all packages and their names.

# Lists every package.json in the workspace, excluding node_modules
find . -name "package.json" \
  -not -path "*/node_modules/*" \
  -not -path "*/.next/*" \
  -not -path "*/dist/*" \
  | sort

For each package.json found, read the "name" field. This is your project’s assembly list.

Step 3: Map the dependency graph.

For each package, check what workspace packages it depends on:

# In the web app's directory:
cat apps/web/package.json | grep "workspace:"

Draw or mentally map the dependency graph. This is the equivalent of reading <ProjectReference> entries.

Step 4: Find the entry points.

For each package, locate:

• The "main" or "exports" field in package.json — this is the public API
• The "scripts" field — this tells you how to run, build, and test the package

cat apps/api/package.json | grep -A 10 '"scripts"'

Step 5: Read the tsconfig.json files.

Start with the root tsconfig.base.json if it exists, then read each package’s tsconfig.json to understand its compilation targets, path aliases, and any special settings.

Step 6: Read turbo.json.

Understand the task dependency chain. Answer: what runs before what? What is cached? What always reruns?

After completing these six steps, you should be able to answer: how many packages are in this monorepo, what does each produce, what depends on what, and how do you build and run the whole system.

Quick Reference

Further Reading

• pnpm Workspaces — Official Documentation — The definitive reference for workspace configuration, the workspace: protocol, and filtering.
• Turborepo Core Concepts — Explains task pipelines, caching, and the dependency graph that replaces MSBuild’s implicit ordering.
• TypeScript Project References — The TypeScript compiler’s native multi-project support. Less common in the monorepo ecosystem than Turborepo, but worth knowing, especially for library authors.
• tsconfig.json Reference — Complete reference for every compilerOptions field. Bookmark this; you will use it when debugging type errors that seem to disappear or appear based on which directory you run tsc from.

Build Systems: MSBuild vs. the JS Build Toolchain

For .NET engineers who know: dotnet build, MSBuild, .csproj settings, and the C# compilation pipeline You’ll learn: What actually happens when you build a TypeScript project — the full chain from tsc through bundlers — and which tsconfig.json settings map to what you already configure in .csproj Time: 15-20 min read

The .NET Way (What You Already Know)

When you run dotnet build, MSBuild orchestrates a pipeline that is largely invisible because Microsoft owns the entire chain. The C# compiler (csc or Roslyn) takes your source files, resolves project references from .csproj, compiles to IL (Intermediate Language), and writes a .dll to bin/. The runtime (CLR/CoreCLR) JIT-compiles that IL to native code at execution time. You configure this pipeline through .csproj properties: <TargetFramework>, <Nullable>, <ImplicitUsings>, <LangVersion>, <Optimize>. If you need to see what’s actually happening, dotnet build -v detailed will show you the full MSBuild task graph, but most engineers never need to look.

The key characteristics of this model: one compiler, one build tool, one runtime, one output format. Everything is integrated and controlled by Microsoft. The tradeoff is that customizing the pipeline requires MSBuild expertise that most engineers don’t have.

<!-- The .csproj you know — this drives the entire build -->
<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <TargetFramework>net9.0</TargetFramework>
    <Nullable>enable</Nullable>
    <ImplicitUsings>enable</ImplicitUsings>
    <LangVersion>13.0</LangVersion>
    <Optimize>true</Optimize>
    <AssemblyName>MyApp</AssemblyName>
    <RootNamespace>MyApp</RootNamespace>
  </PropertyGroup>
</Project>

MSBuild also handles: dependency resolution (NuGet restore), asset copying, linked files, conditional compilation (#if DEBUG), code generation (source generators), and packaging. It is a general-purpose build engine that happens to be the primary one for .NET.

The JS/TS Way

The JavaScript/TypeScript build story is fragmented because there is no single vendor controlling the chain. Instead, several tools each own one layer:

graph TD
    A["Source (.ts)"]
    B["TypeScript Compiler (tsc)\nType erasure, downleveling,\nmodule transformation"]
    C["JavaScript (.js)"]
    D["Bundler\n(Vite / Webpack / esbuild / Turbopack)\nTree-shaking, code-splitting, minification,\nasset handling, hot module replacement"]
    E["Optimized bundle (.js / .css / assets)"]
    F["Runtime (Node.js / Browser V8)"]

    A --> B --> C --> D --> E --> F

Unlike MSBuild, these tools do not automatically compose. Each one has its own configuration file, its own CLI, its own plugin ecosystem, and its own opinion about how the pipeline should work. The good news: most frameworks (Next.js, NestJS, Vite-based projects) wire the chain together for you and expose only the configuration you actually need to touch.

Step 1: TypeScript Compiler (tsc)

tsc is a type checker and transpiler. It does two distinct things, and it helps to separate them mentally:

Type checking — tsc reads your TypeScript, builds a type graph, and reports errors. This is equivalent to Roslyn’s semantic analysis pass. No output is produced; it just tells you whether your types are correct.

Transpilation — tsc strips TypeScript syntax (types, interfaces, decorators-in-some-configurations) and produces plain JavaScript. This is closer to what the C# compiler does when it lowers high-level C# syntax to IL — except TypeScript lowers to JavaScript, not binary code.

Run type checking without emitting files:

# Type-check only (no output files) — equivalent to building to check errors
npx tsc --noEmit

# Compile to JavaScript
npx tsc

# Watch mode — equivalent to dotnet watch build
npx tsc --watch

The key thing to understand: tsc does not optimize. It does not tree-shake, minify, or bundle. It produces one .js file per .ts file, or a concatenated output if configured. For browser applications, raw tsc output is rarely what you ship. You need a bundler.

For NestJS (Node.js backend), tsc output is often sufficient — you run node dist/main.js directly. For Next.js (browser applications), Next.js runs its own build pipeline that uses the TypeScript compiler internally but you never invoke tsc directly for production.

Step 2: Bundlers

Bundlers solve the browser’s module loading problem. A browser cannot natively import 500 separate JavaScript files efficiently (though HTTP/2 mitigates this somewhat), and node_modules references do not work in a browser. A bundler:

1. Starts from an entry point (main.ts, index.ts)
2. Follows all import statements recursively, building a dependency graph
3. Removes dead code that is never imported (tree-shaking)
4. Splits the graph into chunks to enable lazy loading (code-splitting)
5. Minifies the output (removes whitespace, renames variables)
6. Handles non-JS assets (CSS, images, fonts)
7. Outputs optimized bundles for deployment

There are four bundlers you will encounter:

Webpack — the industry standard from roughly 2015-2022. Highly configurable, enormous plugin ecosystem, complex configuration. If you are joining an existing project, you will likely encounter it. webpack.config.js can grow to several hundred lines of configuration. Vite largely replaced it for new projects.

Vite — the modern default for frontend projects. Built on esbuild (for development speed) and Rollup (for production bundling). Configuration is minimal by design. Nearly all new React, Vue, and Svelte projects use Vite unless they use a meta-framework. Development mode uses native ES modules in the browser with no bundling step, which makes hot module replacement near-instant.

esbuild — written in Go, extremely fast (10-100x faster than Webpack). Used internally by Vite for the dev server transformation step. Can be used standalone for simple bundling scenarios. Less configurable than Webpack but fast enough to make configuration concerns moot for many use cases.

Turbopack — Vercel’s Rust-based bundler, currently used in Next.js development mode. Not production-ready for standalone use yet.

A practical summary: you will probably not choose your bundler directly. If you are building a standalone React or Vue app, use Vite. If you are using Next.js, it handles bundling. If you are using NestJS, you probably do not need a bundler at all — just tsc.

Step 3: Framework Build Pipelines

This is where the complexity is hidden from you:

Next.js runs next build, which internally invokes the TypeScript compiler for type checking, then uses its own bundling pipeline (SWC for transformation, Webpack or Turbopack for bundling) to produce optimized server and client bundles. You rarely configure the bundler directly. Next.js has a next.config.js/next.config.ts for framework-level settings.

NestJS runs nest build (or tsc directly), which compiles TypeScript to JavaScript in the dist/ directory. NestJS’s build is straightforward — it is a Node.js application, so there is no browser bundling required. The nest-cli.json file controls build options.

Vite-based apps (standalone React, Vue) run vite build, which runs TypeScript type checking (via vue-tsc or tsc) and then Rollup-based bundling in one command.

# Next.js project
next build          # type-check + bundle + optimize
next dev            # development server with HMR

# NestJS project
nest build          # tsc compilation to dist/
nest start --watch  # watch mode with auto-restart

# Vite project (standalone React/Vue)
vite build          # type-check + bundle
vite dev            # development server with HMR

tsconfig.json in Depth

tsconfig.json is the closest equivalent to .csproj for TypeScript compilation settings. The mapping is not perfect — tsconfig.json controls the compiler only, not the full build pipeline — but understanding the correspondence makes it immediately familiar.

// tsconfig.json — annotated with .csproj equivalents
{
  "compilerOptions": {
    // --- OUTPUT TARGETING ---

    // What JS version to emit. Equivalent to <TargetFramework>.
    // "ES2022" means use modern JS syntax; "ES5" downlevels to IE-compatible JS.
    // Next.js and NestJS on modern Node.js: use "ES2022" or later.
    "target": "ES2022",

    // Module system for emitted code. Equivalent to choosing assembly output type.
    // "ESNext" or "ES2022" for native ES modules (import/export in output).
    // "CommonJS" for Node.js-compatible require() output.
    // "NodeNext" for modern Node.js with native ESM support.
    // NestJS: "CommonJS". Next.js: handled internally, don't set manually.
    "module": "CommonJS",

    // How imports are resolved. The most important setting for avoiding import errors.
    // "NodeNext" — respects package.json "exports" field, requires .js extensions.
    // "Bundler" — assumes a bundler handles resolution; most permissive, used with Vite.
    // "Node16" — older Node.js-compatible resolution.
    // No .NET equivalent — .NET assembly resolution is implicit.
    "moduleResolution": "NodeNext",

    // Output directory for compiled JS. Equivalent to <OutputPath> or bin/ directory.
    "outDir": "./dist",

    // Root directory of source files. Equivalent to the project root in .csproj.
    "rootDir": "./src",

    // --- TYPE CHECKING ---

    // Enables all strict type checking flags. Equivalent to <Nullable>enable</Nullable>
    // plus Roslyn analyzer warnings. Always enable this — the cost of disabling it
    // is technical debt that compounds fast.
    "strict": true,

    // Stricter property initialization checks (part of strict, but worth knowing).
    // Equivalent to nullable reference types in C#.
    "strictNullChecks": true,

    // Disallow implicit 'any' types. Without this, TypeScript silently widens
    // unresolvable types to 'any', defeating the purpose of the type system.
    "noImplicitAny": true,

    // --- INTEROP ---

    // Allow importing CommonJS modules with ES module syntax.
    // Required when mixing import/require in Node.js projects.
    "esModuleInterop": true,

    // Allow importing JSON files directly. No .NET equivalent.
    "resolveJsonModule": true,

    // Preserve JSX syntax for React (let the bundler handle it) vs. compiling it.
    // "preserve" for Next.js/Vite (they handle JSX transformation).
    // "react-jsx" for projects where tsc handles JSX.
    "jsx": "preserve",

    // --- PATH ALIASES ---

    // Import path aliases. Equivalent to setting namespace aliases or project refs.
    // "@/*" means "anything starting with @/ maps to ./src/*"
    // After configuring this, `import { foo } from '@/lib/foo'` works anywhere.
    // Note: bundlers (Vite, webpack) must also be configured to respect these paths.
    "paths": {
      "@/*": ["./src/*"],
      "@components/*": ["./src/components/*"],
      "@lib/*": ["./src/lib/*"]
    },

    // --- EMIT CONTROL ---

    // Do not emit output files — type-check only. Used in CI for checking without
    // building, or when the bundler handles transpilation.
    // Equivalent to running Roslyn as an analyzer without producing output.
    "noEmit": false,

    // Include type declarations from @types/* packages (e.g., @types/node).
    // Types are loaded automatically from node_modules/@types — no explicit includes needed
    // unless you want to restrict which ones are loaded.
    "types": ["node"]
  },

  // Which files to include. Equivalent to <Compile Include="..." /> in .csproj.
  // Default: all .ts/.tsx files in the project root.
  "include": ["src/**/*"],

  // Which files to exclude. node_modules is excluded by default.
  "exclude": ["node_modules", "dist"]
}

The strict flag deserves special attention. It is a shorthand that enables multiple sub-flags: strictNullChecks, noImplicitAny, strictFunctionTypes, strictBindCallApply, strictPropertyInitialization, noImplicitThis, and alwaysStrict. A project without strict: true is a project where TypeScript cannot be trusted, because the type system has holes large enough to drive a truck through. Treat enabling strict on an existing codebase as a migration task, not a one-line change — you will find dozens of latent type errors.

The moduleResolution setting is where most .NET engineers run into trouble. Here is the practical guide:

The target and module Matrix

These two settings interact in ways that confuse .NET engineers because there is no equivalent distinction in .csproj:

• target controls what JavaScript syntax is emitted. ES2022 emits modern syntax (optional chaining, nullish coalescing, class fields). ES5 downlevels to older syntax that older browsers understand.
• module controls how imports and exports are emitted. ESNext keeps import/export. CommonJS converts them to require()/module.exports.

These are independent settings, which is why you can have a target: "ES2022" (modern JS syntax) with module: "CommonJS" (Node.js-style imports) — this is exactly what NestJS uses.

For browser apps, modern frameworks handle this for you: Next.js and Vite set their own targets internally. For Node.js apps (NestJS), the typical configuration is:

// tsconfig.json for NestJS (Node.js backend)
{
  "compilerOptions": {
    "module": "CommonJS",
    "target": "ES2022",
    "moduleResolution": "Node",
    "strict": true,
    "esModuleInterop": true,
    "experimentalDecorators": true,
    "emitDecoratorMetadata": true,
    "outDir": "./dist",
    "rootDir": "./src"
  }
}

Note the experimentalDecorators and emitDecoratorMetadata flags — these are required for NestJS’s decorator-based DI system. Without emitDecoratorMetadata, the runtime reflection that NestJS uses to resolve constructor parameter types does not work. See Article 2.5 for the full explanation of decorators.

Multiple tsconfig Files

In a real project, you will often see multiple tsconfig files, not just one. This is equivalent to having separate build configurations (Debug/Release) but more granular:

tsconfig.json           ← Base configuration (shared settings)
tsconfig.build.json     ← Production build (excludes tests)
tsconfig.test.json      ← Test configuration (includes test files)

// tsconfig.build.json — extends base, used for production builds
{
  "extends": "./tsconfig.json",
  "exclude": ["node_modules", "dist", "**/*.spec.ts", "**/*.test.ts"]
}

// tsconfig.test.json — extends base, used by Vitest/Jest
{
  "extends": "./tsconfig.json",
  "include": ["src/**/*", "test/**/*"]
}

The extends keyword works like inheritance — the child config inherits all settings from the parent and overrides only what it specifies. There is no direct .csproj equivalent; the closest is build configuration transforms or the Directory.Build.props shared properties pattern in multi-project solutions.

What Tree-Shaking Actually Means

Tree-shaking is the bundler equivalent of the C# linker removing unused code from single-file executables. It works by static analysis of import/export statements: if you import { Button } from './components' but never use Button, the bundler removes it from the output bundle.

Tree-shaking only works with ES modules (import/export), not CommonJS (require()). This is one reason modern libraries ship as ES modules even when they also provide CommonJS builds.

// components/index.ts — exports many things
export { Button } from './Button';
export { Modal } from './Modal';
export { Table } from './Table';
export { Chart } from './Chart'; // 500KB library

// page.tsx — only imports Button
import { Button } from './components';

// After tree-shaking: Chart is NOT in the bundle.
// The bundler can prove it is never used.

The implication for library authors: side effects in module-level code defeat tree-shaking. Code that registers global state when a module is import-ed prevents the bundler from safely removing it even if nothing from that module is used. Well-designed libraries mark themselves "sideEffects": false in package.json to tell bundlers they are safe to tree-shake.

Code-Splitting

Code-splitting is the bundler feature that splits your application into multiple chunks loaded on demand, rather than one large bundle loaded upfront. The browser equivalent of lazy loading assemblies.

In Next.js, code-splitting is automatic: each page gets its own chunk, and dynamic imports create additional split points:

// next.js — static import (included in initial bundle)
import { HeavyChart } from './HeavyChart';

// next.js — dynamic import (creates a separate chunk, loaded on demand)
import dynamic from 'next/dynamic';
const HeavyChart = dynamic(() => import('./HeavyChart'), {
  loading: () => <p>Loading chart...</p>,
});

In Vite, you use standard dynamic imports:

// Vite — creates a separate chunk loaded when this import is executed
const { HeavyChart } = await import('./HeavyChart');

You do not need to configure code-splitting manually in most frameworks — the tooling handles it. You do need to be aware of it when deciding where to place large dependencies.

Key Differences

Gotchas for .NET Engineers

1. TypeScript types do not exist at runtime — tsc is not your validator

This is the most important mental model shift in this entire article. In C#, if you declare string Name { get; set; }, the CLR enforces that constraint at runtime. In TypeScript, name: string is erased by tsc and the runtime JavaScript has no knowledge it ever existed.

// This looks like a type-safe function
function processUser(user: { name: string; age: number }) {
  console.log(user.name.toUpperCase());
}

// This compiles without error but throws at runtime
const response = await fetch('/api/user');
const data = await response.json(); // type: any
processUser(data); // No error from tsc — data could be anything

// If the API returns { Name: 'Alice', age: null }, you get:
// TypeError: Cannot read properties of undefined (reading 'toUpperCase')

The solution is runtime validation with Zod at every boundary where external data enters your application (API responses, environment variables, form submissions). See Article 2.3 for the full treatment. The rule of thumb: never trust JSON.parse() or response.json() without validating the shape.

2. Configuring paths in tsconfig is not enough — your bundler also needs them

Path aliases ("paths": { "@/*": ["./src/*"] }) tell tsc how to resolve imports during type checking. They do not tell the bundler (Vite, webpack, Next.js) how to resolve them at build time. If you configure tsconfig.json paths but not the bundler, your app will type-check successfully but fail at runtime.

// This import works for tsc but may fail at bundle time
import { formatDate } from '@/lib/dates';

Each bundler has its own configuration:

// vite.config.ts — must mirror tsconfig paths
import { defineConfig } from 'vite';
import path from 'path';

export default defineConfig({
  resolve: {
    alias: {
      '@': path.resolve(__dirname, './src'),
    },
  },
});

// next.config.ts — Next.js reads tsconfig paths automatically
// No extra configuration needed for Next.js

// webpack.config.js — must mirror tsconfig paths
module.exports = {
  resolve: {
    alias: {
      '@': path.resolve(__dirname, 'src'),
    },
  },
};

Next.js is the exception: it reads tsconfig.json paths and configures webpack/Turbopack automatically. In Vite projects, you must duplicate the configuration.

3. noEmit: true does not mean your build is type-safe

In CI pipelines, a common pattern is to run tsc --noEmit to type-check without producing output. The gotcha: tsc --noEmit only checks files that are included in your tsconfig.json. If your bundler (Vite, Next.js) has a separate mechanism for determining which files to process, there may be files that the bundler builds but tsc --noEmit never sees.

Additionally, tsc --noEmit will not catch errors in files excluded by the exclude field, including test files if they are excluded from the build tsconfig. Run a separate tsc --noEmit using tsconfig.test.json (or your test tsconfig) to catch type errors in test files.

# CI pipeline — type-check production code AND tests
npx tsc --noEmit -p tsconfig.json
npx tsc --noEmit -p tsconfig.test.json

4. experimentalDecorators and emitDecoratorMetadata must be set for NestJS — without them, DI silently fails

NestJS relies on the reflect-metadata package to perform runtime reflection on constructor parameter types. This mechanism requires emitDecoratorMetadata: true in tsconfig, which causes tsc to emit metadata about parameter types alongside the compiled JavaScript. Without it, NestJS cannot determine what types to inject, and you will get cryptic errors at startup — or, worse, undefined injected values.

The TypeScript decorator standard (Stage 3 TC39 proposal) does not support emitDecoratorMetadata. If you are using a project template that has switched to the new decorator standard without experimentalDecorators, NestJS will not work. Always verify both flags are set when setting up a NestJS project.

5. Build output is readable JavaScript — not a security boundary

In .NET, distributing a .dll without source provides some level of obfuscation (though not real security). TypeScript compiles to readable JavaScript. Even with minification, your bundled output is plain text that anyone can read, beautify, and analyze. Source maps — if deployed — make it trivially readable.

Do not put secrets, API keys, or business logic that should remain private in client-side JavaScript. This applies equally to React, Vue, and any browser-targeted code. Server Components in Next.js are one mechanism for running code on the server only; anything in a Client Component runs in the browser and is visible.

6. The module and moduleResolution settings interact in non-obvious ways

If you set "module": "NodeNext" (the modern Node.js ESM-native setting), TypeScript requires that relative imports include the .js extension — even in .ts files:

// With "moduleResolution": "NodeNext" — required
import { foo } from './foo.js'; // .js extension in a .ts file (intentional)

// With "moduleResolution": "Bundler" — both work
import { foo } from './foo';
import { foo } from './foo.js';

The .js extension is correct even though the file on disk is foo.ts. This is because after compilation, the file will be foo.js, and Node.js resolves ESM imports before TypeScript runs. Most .NET engineers find this confusing and try to fix it by removing the extension, which breaks Node.js module resolution. If you are on NestJS and encounter this, check whether moduleResolution is set to NodeNext or Node.

Hands-On Exercise

This exercise builds your intuition for what each layer of the build chain actually does. You will take a simple TypeScript file through each stage manually, then examine how Next.js handles the same process automatically.

Part 1: The raw tsc pipeline

Create a minimal TypeScript project from scratch (no framework):

mkdir build-experiment && cd build-experiment
npm init -y
npm install typescript --save-dev
npx tsc --init

Edit tsconfig.json:

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "CommonJS",
    "strict": true,
    "outDir": "./dist",
    "rootDir": "./src"
  },
  "include": ["src/**/*"]
}

Create src/user.ts:

interface User {
  id: number;
  name: string;
  email: string | null;
}

function formatUser(user: User): string {
  return `${user.name} (${user.email ?? 'no email'})`;
}

export { User, formatUser };

Create src/main.ts:

import { User, formatUser } from './user';

const user: User = { id: 1, name: 'Alice', email: null };
console.log(formatUser(user));

Compile and inspect the output:

npx tsc
cat dist/user.js
cat dist/main.js

Observe: the interface User is completely absent from dist/user.js. The type annotation user: User is absent from dist/main.js. What remains is plain JavaScript — identical behavior, zero type information.

Now try breaking the types and see that tsc catches it:

// In src/main.ts — add this broken call
const badUser: User = { id: 'not-a-number', name: 'Bob', email: 'bob@example.com' };

npx tsc --noEmit
# error TS2322: Type 'string' is not assignable to type 'number'.

Part 2: Examine a Next.js build

In an existing Next.js project (or create one with npx create-next-app@latest):

# Examine the tsconfig.json and note: "moduleResolution": "bundler"
cat tsconfig.json

# Run the production build and examine what it produces
npm run build

# Look at what was generated
ls -la .next/
ls -la .next/static/chunks/

The .next/static/chunks/ directory contains code-split bundles. Each chunk is a separate JavaScript file that the browser loads on demand. Compare the file count to your source files — you will have far fewer bundles than source files (bundled) and the bundles will be significantly smaller than raw tsc output (minified).

Part 3: tsconfig path aliases

Add path aliases to the Next.js project’s tsconfig.json and verify they work:

{
  "compilerOptions": {
    "paths": {
      "@/components/*": ["./src/components/*"],
      "@/lib/*": ["./src/lib/*"]
    }
  }
}

Create src/lib/utils.ts:

export function cn(...classes: string[]): string {
  return classes.filter(Boolean).join(' ');
}

Use the alias in a component:

// src/app/page.tsx
import { cn } from '@/lib/utils';

export default function Page() {
  return <div className={cn('text-gray-900', 'font-semibold')}>Hello</div>;
}

Run npm run dev and verify the import resolves. Then run npx tsc --noEmit separately to verify type checking also passes. Both must succeed: the bundler resolves imports at build time, and tsc resolves them during type checking.

Quick Reference

Further Reading

• TypeScript Compiler Options Reference — The canonical documentation for every tsconfig option. Useful as a reference; do not read linearly.
• Vite Documentation — Getting Started — Covers the development model, configuration, and production build behavior. If you are working on any Vite-based project, read the “Features” and “Build” sections.
• Next.js — TypeScript Configuration — Covers how Next.js reads and extends tsconfig, incremental type checking, and next build behavior.
• esbuild Documentation — If you need to understand why modern JS builds are fast, or if you need to write a custom build script, esbuild’s documentation explains the core concepts well even if you are not using it directly.

1.6 — The JavaScript Library Landscape: A .NET Engineer’s Decoder Ring

For .NET engineers who know: ASP.NET Core — middleware pipelines, controllers, DI, filters, model binding, and the cohesive “one framework does everything” experience. You’ll learn: How the JS/TS ecosystem splits what ASP.NET Core does into separate, composable libraries — and how to map every architectural concept you already know to its TypeScript equivalent. Time: 25-30 minutes

The most disorienting thing about the JavaScript ecosystem is not the syntax. It’s not TypeScript’s type system. It’s the realization that there is no single framework you install and configure. Instead, you’re assembling an architecture from components, and nothing tells you which components belong together.

This article is your decoder ring. By the end, you’ll know exactly how every layer of a TypeScript application maps to what you already know from ASP.NET Core. You’ll understand why the ecosystem is fragmented this way, which libraries dominate each layer, and how to read an unfamiliar JS/TS project and orient yourself within thirty seconds.

The .NET Way (What You Already Know)

When you start a new ASP.NET Core project, you get a framework that handles the entire middle tier from a single dependency. One dotnet new webapi command and you have:

• Routing — via [Route], [HttpGet], and MapControllers()
• Middleware — via app.Use(), app.UseAuthentication(), app.UseAuthorization()
• Dependency injection — via IServiceCollection with AddScoped, AddSingleton, AddTransient
• Model binding — via [FromBody], [FromQuery], [FromRoute]
• Validation — via Data Annotations or FluentValidation
• Auth — via ASP.NET Identity, JWT bearer middleware, and [Authorize]
• Configuration — via IConfiguration, appsettings.json, and environment-based overrides
• Logging — via ILogger<T> with pluggable sinks
• Background services — via IHostedService and BackgroundService

Microsoft designed all of these to work together. They share conventions, they integrate with the same DI container, and they evolve together under a single release cadence. When you add app.UseAuthentication() before app.UseAuthorization(), the framework enforces that ordering. When your controller has a [Authorize] attribute, it integrates with the same auth middleware you configured in Program.cs. The system is opinionated by design.

// Program.cs — everything in one place
var builder = WebApplication.CreateBuilder(args);

builder.Services.AddControllers();
builder.Services.AddAuthentication(JwtBearerDefaults.AuthenticationScheme)
    .AddJwtBearer(options => { /* config */ });
builder.Services.AddScoped<IUserService, UserService>();
builder.Services.AddDbContext<AppDbContext>(options =>
    options.UseSqlServer(builder.Configuration.GetConnectionString("DefaultConnection")));

var app = builder.Build();

app.UseAuthentication();
app.UseAuthorization();
app.MapControllers();

app.Run();

Twelve lines of setup, and your middleware pipeline, DI container, ORM, and auth system are wired together. That’s the ASP.NET Core value proposition: cohesion.

The JavaScript ecosystem makes a different trade. Instead of cohesion, it gives you composability. Everything is separate. That fragmentation is not an accident — it reflects the ecosystem’s history and values. Understanding why the ecosystem is structured this way is the first step to navigating it confidently.

The JavaScript/TypeScript Way

The Fundamental Mental Shift: Libraries, Frameworks, and Meta-Frameworks

Before mapping individual tools, you need to understand a three-way distinction that barely exists in the .NET world but is critical in JavaScript:

React is a library. Next.js is a meta-framework built on React. The distinction matters because React doesn’t do routing, server rendering, or build optimization. Next.js does all of those things by wrapping React with additional conventions and tooling.

This pattern repeats across the ecosystem: Vue is a library (framework, technically), Nuxt is its meta-framework. That extra layer is where you get the ASP.NET Core-like experience.

Frontend Frameworks

These are the libraries/frameworks responsible for building UIs. If your team is building a web frontend (as opposed to a pure API), you’re choosing one of these.

React

React is a component library built by Meta, released in 2013 and still dominant in 2026. The key architectural decisions that define React:

One-way data flow. Data flows down through props (component parameters), and events flow up through callbacks. There is no two-way binding by default. This is the opposite of how WPF/MAUI bindings work and how Blazor’s two-way binding (@bind) works.

JSX. React components return JSX — a syntax extension where HTML-like markup lives inside TypeScript files. If Razor syntax is .cshtml (C# inside HTML), JSX is the inverse: HTML inside TypeScript.

// React component — TypeScript (.tsx file)
// Think of this as a Razor Component but in TypeScript

interface UserCardProps {
  name: string;
  email: string;
  role: "admin" | "user";
}

// Functional component — the modern React pattern (class components are legacy)
function UserCard({ name, email, role }: UserCardProps) {
  return (
    <div className="user-card">
      <h2>{name}</h2>
      <p>{email}</p>
      {role === "admin" && <span className="badge">Administrator</span>}
    </div>
  );
}

// Rough equivalent in Blazor — notice the inverted syntax relationship
// Blazor: C# code in .razor files | React: HTML in .tsx files

@* UserCard.razor *@
@code {
    [Parameter] public string Name { get; set; }
    [Parameter] public string Email { get; set; }
    [Parameter] public string Role { get; set; }
}

<div class="user-card">
    <h2>@Name</h2>
    <p>@Email</p>
    @if (Role == "admin")
    {
        <span class="badge">Administrator</span>
    }
</div>

Hooks. State and side effects in React components are managed through “hooks” — functions that start with use. useState manages local state (like a [Parameter] that the component itself can modify). useEffect handles side effects like data fetching (like OnInitializedAsync and Dispose combined). See Article 3.2 for a full treatment of hooks.

React is not a framework. React handles one thing: rendering UI. It has no router, no HTTP client, no form validation, no state management beyond component-local state. Everything else requires additional libraries. This is why you almost never use React alone — you use it through Next.js, which layers those capabilities on top.

Vue 3

Vue 3 is a progressive framework — more opinionated than React, less opinionated than Angular. It’s the closest thing in the JS world to Blazor’s mental model.

Single File Components (SFC). Vue components live in .vue files with <template>, <script>, and <style> sections. The separation mirrors the Blazor .razor component structure more closely than React’s JSX.

Reactivity system. Vue’s reactivity is built in. When you declare const count = ref(0), Vue automatically tracks when count is read and triggers a re-render when it changes. This is closer to WPF’s INotifyPropertyChanged or Blazor’s auto-re-render behavior than React’s explicit state updates.

Composition API. Vue 3 introduced the Composition API — a way to organize component logic by concern rather than by lifecycle stage (a significant improvement over Vue 2’s Options API). The <script setup> syntax is the modern preferred form:

<!-- UserCard.vue — Vue 3 Single File Component -->
<script setup lang="ts">
// Imports are reactive; no class or export needed with <script setup>
const props = defineProps<{
  name: string;
  email: string;
  role: "admin" | "user";
}>();

// computed is like a C# calculated property — auto-updates when deps change
const displayName = computed(() => `${props.name} (${props.role})`);
</script>

<template>
  <div class="user-card">
    <h2>{{ displayName }}</h2>
    <p>{{ props.email }}</p>
    <span v-if="props.role === 'admin'" class="badge">Administrator</span>
  </div>
</template>

<style scoped>
/* scoped CSS — like Blazor's Component.razor.css isolation */
.user-card { padding: 1rem; }
</style>

Vue is our framework of choice for projects that use the Nuxt meta-framework. See Article 3.3 for a full treatment of Vue 3.

Angular

Angular deserves a section even though we don’t use it, because you will encounter it. Angular is the full-framework approach — closest to ASP.NET Core in philosophy, built by Google, and the dominant choice in large enterprise organizations.

Angular is the only frontend framework that ships with:

• Its own DI container (constructor injection, like ASP.NET Core)
• Its own HTTP client (HttpClient — even named the same)
• Its own routing
• Its own form management (reactive forms, template-driven forms)
• TypeScript as a first-class, non-optional requirement since day one

The module system (NgModule) maps most directly to ASP.NET Core’s service registration model — you declare providers, imports, and exports per module. The component decorator system (@Component(), @Injectable(), @NgModule()) maps directly to ASP.NET Core’s attribute-driven design.

// Angular component — notice how similar the decorator pattern feels to C# attributes
@Component({
  selector: 'app-user-card',
  template: `
    <div class="user-card">
      <h2>{{ displayName }}</h2>
      <p>{{ user.email }}</p>
    </div>
  `
})
export class UserCardComponent {
  @Input() user: User;  // [Parameter] equivalent

  // Constructor injection — identical mental model to ASP.NET Core
  constructor(private userService: UserService) {}

  get displayName(): string {
    return `${this.user.name} (${this.user.role})`;
  }
}

If Angular feels familiar, that’s intentional — the Angular team drew heavily from the ASP.NET MVC pattern. The trade-off is verbosity and a steep initial learning curve. When reading an Angular codebase, your .NET instincts will serve you better there than anywhere else in the JS ecosystem.

Svelte and SolidJS

These two frameworks take a fundamentally different approach: they compile away the framework at build time.

Svelte compiles components into vanilla JavaScript — there is no virtual DOM and no framework runtime shipped to the browser. The compiled output is smaller and often faster than React or Vue at runtime. The syntax is distinctive and worth recognizing.

SolidJS uses a reactive primitive system (similar to Vue’s reactivity) but, like Svelte, compiles to efficient vanilla JS without a virtual DOM. It claims top-of-chart benchmark performance.

Both are mature enough for production use in 2026. Neither has the ecosystem depth or community size of React or Vue. You’ll encounter them in greenfield projects where performance and bundle size are priorities. For this curriculum, they’re awareness-level.

Meta-Frameworks: Where the Real ASP.NET Comparison Lives

Here’s the insight that orients everything: when .NET engineers ask “what’s the equivalent of ASP.NET Core in JavaScript?”, the answer is not React or Vue — it’s the meta-framework layer. React and Vue are rendering libraries; Next.js and Nuxt are the frameworks that add the server-side layer that makes them comparable to ASP.NET.

Next.js

Next.js is a React meta-framework built by Vercel. It’s the closest thing to ASP.NET MVC + Razor Pages in the React world. What Next.js adds on top of React:

• File-based routing. Create app/users/[id]/page.tsx and you have a route at /users/:id. No route registration, no [Route] attributes. The file system is the router — similar to Razor Pages conventions where Pages/Users/Detail.cshtml maps to /Users/Detail.

• Server-side rendering (SSR). Components can render on the server before sending HTML to the browser. This is the model Razor Pages uses — server renders HTML, browser displays it.

• Server Components. A newer paradigm where components marked as server-only never ship JavaScript to the browser. They fetch data directly (no API call needed) and render to HTML. Think of them as Razor Pages with a component model.

• API routes. Create app/api/users/route.ts and you have a backend endpoint. These are full HTTP request handlers — equivalent to ASP.NET Minimal API endpoints. For projects where the same Next.js app needs a lightweight API, this eliminates a separate NestJS deployment.

• Middleware. Next.js has its own middleware layer (also called middleware) that runs at the edge before request routing, similar to ASP.NET Core’s middleware pipeline.

The App Router (the current architecture, introduced in Next.js 13 and stable since Next.js 14) uses a file/folder convention for routing that .NET engineers find navigable:

app/
├── layout.tsx          ← Root layout (like _Layout.cshtml)
├── page.tsx            ← Homepage route "/"
├── users/
│   ├── page.tsx        ← Route "/users"
│   └── [id]/
│       ├── page.tsx    ← Route "/users/:id" (Server Component)
│       └── edit/
│           └── page.tsx ← Route "/users/:id/edit"
└── api/
    └── users/
        ├── route.ts    ← GET/POST "/api/users"
        └── [id]/
            └── route.ts ← GET/PUT/DELETE "/api/users/:id"

Nuxt

Nuxt is to Vue what Next.js is to React. It wraps Vue with the same capabilities — SSR, file-based routing, API routes, middleware — with a Vue-flavored convention system. If anything, Nuxt is slightly more opinionated and convention-driven than Next.js (closer to the “convention over configuration” philosophy of classic ASP.NET MVC).

Nuxt’s auto-import system is distinctive: components placed in components/ and composables placed in composables/ are automatically available everywhere without explicit imports. This is more opinionated than Next.js and either feels magical or like hidden complexity depending on your preference.

For teams using Vue, Nuxt is the natural full-stack choice. See Article 3.5 for depth on Nuxt.

Remix

Remix is an alternative React meta-framework, now part of the React Router project. Its architecture is closer to the traditional HTTP request/response model than Next.js.

Where Next.js gives you Server Components (a React-level concept), Remix keeps the abstraction at the HTTP layer — every route has a loader function for GET requests and an action function for POST/PUT/DELETE requests. This maps more naturally to the MVC action pattern:

// Remix route — maps very closely to an ASP.NET Controller action
export async function loader({ params }: LoaderFunctionArgs) {
  // This is like a controller GET action — runs on the server
  const user = await getUserById(params.id);
  return json(user);
}

export async function action({ request, params }: ActionFunctionArgs) {
  // This is like a controller POST/PUT action
  const formData = await request.formData();
  await updateUser(params.id, formData);
  return redirect(`/users/${params.id}`);
}

// The component just renders — no data fetching here
export default function UserPage() {
  const user = useLoaderData<typeof loader>();
  return <UserForm user={user} />;
}

If you find Next.js’s Server Components model confusing (and many do initially), Remix’s request/response model will feel more intuitive. We don’t use Remix as our primary framework, but knowing its pattern helps read existing codebases.

Backend Frameworks: The ASP.NET Core Equivalents

These are pure server-side Node.js frameworks — they have no UI concerns. If you’re building an API, a background service, or a data layer that only runs on the server, this is the layer you’re in.

NestJS — The Direct ASP.NET Core Equivalent

NestJS is the framework we use for dedicated backend APIs. It is the closest architectural equivalent to ASP.NET Core in the JS ecosystem. Before we dive into each other part of the ecosystem, understand this mapping:

NestJS uses Express or Fastify as its HTTP engine (configurable). Think of Express/Fastify as the Kestrel equivalent — the raw HTTP server that NestJS sits on top of. You almost never interact with Express/Fastify directly in a NestJS project; NestJS abstracts it the same way ASP.NET Core abstracts Kestrel.

The module system is where NestJS diverges most from .NET in structure. NestJS makes DI explicitly module-scoped:

// users.module.ts — NestJS module
// Compare to a well-organized IServiceCollection extension method in .NET

@Module({
  imports: [DatabaseModule],    // ← like builder.Services.AddDbContext()
  controllers: [UsersController],
  providers: [UsersService],    // ← services this module owns
  exports: [UsersService],      // ← services other modules can inject
  // Without exports, UsersService is PRIVATE to this module
  // ASP.NET Core has no equivalent — all registered services are globally available
})
export class UsersModule {}

The exports concept has no direct .NET equivalent — in ASP.NET Core, any registered service is accessible anywhere. NestJS’s explicit exports create stronger module boundaries. This is actually stricter than .NET’s default behavior and worth embracing.

Express.js

Express is the foundational Node.js HTTP framework — minimal by design. No routing conventions, no DI, no model binding. Just middleware functions and route handlers:

// Express — the "raw Kestrel" of Node.js
const app = express();

app.use(express.json());  // ← like app.UseEndpoints() + body parsing

app.get('/users/:id', async (req, res) => {
  const user = await db.findUser(req.params.id);
  res.json(user);
});

app.listen(3000);

Express gives you nothing by default. No validation, no DI, no auth, no logging — you assemble those yourself from middleware packages. If ASP.NET Core out-of-the-box is a furnished apartment, Express is an empty room.

We don’t use Express standalone. It runs underneath NestJS (NestJS’s default adapter). If you’re reading a codebase that uses Express without NestJS, it’s either a very old project or a microservice where minimal overhead was a priority.

Fastify

Fastify is a performance-focused alternative to Express. The API is similar but with different serialization semantics (JSON serialization is explicitly declared and compiled ahead of time, which is faster than Express’s dynamic serialization). Fastify can be swapped in under NestJS instead of Express for performance-sensitive deployments:

// NestJS with Fastify adapter instead of Express
const app = await NestFactory.create<NestFastifyApplication>(
  AppModule,
  new FastifyAdapter({ logger: true })
);

For most applications, the difference between Express and Fastify under NestJS is not measurable in real-world conditions. Consider Fastify when you have benchmarked a specific bottleneck.

Hono

Hono is an ultra-lightweight framework that runs anywhere: Node.js, Deno, Cloudflare Workers, Bun, AWS Lambda. Its defining feature is portability — the same Hono application can run at the edge, in a serverless function, or in a traditional Node.js process with no code changes.

// Hono — extremely minimal, edge-first
import { Hono } from 'hono'

const app = new Hono()

app.get('/users/:id', async (c) => {
  const id = c.req.param('id')
  return c.json({ id, name: 'Chris' })
})

export default app  // works on any runtime

Hono is relevant for edge functions (Next.js middleware, Cloudflare Workers, API routes with minimal cold start requirements). It’s not a NestJS replacement for a full API — it’s a specialized tool for edge-specific workloads.

The Middle-Tier Architecture in Detail

This is the core comparison. Every row maps an ASP.NET Core concern to its NestJS equivalent, because NestJS is your primary backend framework in this stack.

One important difference: NestJS’s request pipeline stages are more explicitly named and more granular than ASP.NET’s filter types. The execution order in NestJS is:

graph TD
    subgraph NestJS["NestJS Pipeline"]
        N1["Incoming Request"]
        N2["Middleware\n← like ASP.NET middleware (app.Use())"]
        N3["Guards\n← like Authorization filters [Authorize]"]
        N4["Interceptors (pre)\n← like Action filters (OnActionExecuting)"]
        N5["Pipes\n← like model binding + validation"]
        N6["Route Handler\n← like your controller action"]
        N7["Interceptors (post)\n← like Action filters (OnActionExecuted)"]
        N8["Exception Filters\n← like exception middleware"]
        N9["Response"]
        N1 --> N2 --> N3 --> N4 --> N5 --> N6 --> N7 --> N8 --> N9
    end

    subgraph ASP["ASP.NET Core Pipeline"]
        A1["Incoming Request"]
        A2["Middleware (authentication, CORS, etc.)"]
        A3["Routing"]
        A4["Authorization (IAuthorizationFilter)"]
        A5["Action Filter (IActionFilter.OnActionExecuting)"]
        A6["Model Binding + Validation"]
        A7["Controller Action"]
        A8["Action Filter (IActionFilter.OnActionExecuted)"]
        A9["Exception Filter (IExceptionFilter)"]
        A10["Result Filter"]
        A11["Response"]
        A1 --> A2 --> A3 --> A4 --> A5 --> A6 --> A7 --> A8 --> A9 --> A10 --> A11
    end

The pipelines are nearly isomorphic. The main structural difference: ASP.NET Core’s filter chain is part of the MVC layer (it doesn’t run for middleware-handled requests), while NestJS’s guards/interceptors/pipes are defined at the controller/handler level and integrate with the underlying HTTP layer more directly.

Side-by-Side: The Same REST Endpoint in ASP.NET Core and NestJS

The most direct way to internalize the mapping is to see the same complete, production-ready endpoint written in both frameworks. Here’s a GET /api/users/:id endpoint with authentication, validation, error handling, and logging:

ASP.NET Core Version

// Controllers/UsersController.cs
using Microsoft.AspNetCore.Authorization;
using Microsoft.AspNetCore.Mvc;
using Microsoft.Extensions.Logging;

namespace MyApp.Controllers;

[ApiController]                           // ← Enables model binding, auto 400 on validation fail
[Route("api/[controller]")]               // ← Base route: "api/users"
[Authorize]                               // ← Requires authenticated user (JWT checked by middleware)
public class UsersController : ControllerBase
{
    private readonly IUserService _userService;
    private readonly ILogger<UsersController> _logger;

    // Constructor injection — DI container resolves these
    public UsersController(IUserService userService, ILogger<UsersController> logger)
    {
        _userService = userService;
        _logger = logger;
    }

    [HttpGet("{id}")]                     // ← Route: GET api/users/{id}
    [ProducesResponseType(typeof(UserDto), 200)]
    [ProducesResponseType(404)]
    public async Task<IActionResult> GetUser(
        [FromRoute] Guid id)              // ← Model binding: reads from URL path
    {
        _logger.LogInformation("Fetching user {UserId}", id);

        var user = await _userService.GetByIdAsync(id);

        if (user is null)
        {
            return NotFound(new ProblemDetails
            {
                Title = "User not found",
                Status = 404
            });
        }

        return Ok(user);
    }
}

// Services/UserService.cs
public class UserService : IUserService
{
    private readonly AppDbContext _db;

    public UserService(AppDbContext db) => _db = db;

    public async Task<UserDto?> GetByIdAsync(Guid id)
    {
        var user = await _db.Users
            .Where(u => u.Id == id && !u.IsDeleted)
            .Select(u => new UserDto(u.Id, u.Name, u.Email, u.Role))
            .FirstOrDefaultAsync();

        return user;
    }
}

// Program.cs — registration
builder.Services.AddScoped<IUserService, UserService>();
builder.Services.AddAuthentication(JwtBearerDefaults.AuthenticationScheme)
    .AddJwtBearer();

NestJS Version

// users/users.controller.ts
import {
  Controller,
  Get,
  Param,
  ParseUUIDPipe,        // ← Equivalent of [FromRoute] + UUID validation
  NotFoundException,
  UseGuards,
  Logger,
} from '@nestjs/common';
import { ApiBearerAuth, ApiTags } from '@nestjs/swagger';  // ← Swashbuckle equivalent
import { JwtAuthGuard } from '../auth/jwt-auth.guard';     // ← [Authorize] equivalent
import { UsersService } from './users.service';

@ApiTags('users')                         // ← Swagger grouping (like [ApiExplorerSettings])
@ApiBearerAuth()                          // ← Documents the JWT requirement in Swagger
@Controller('users')                      // ← [Route("users")] equivalent
@UseGuards(JwtAuthGuard)                  // ← [Authorize] equivalent — applies to all methods
export class UsersController {
  // NestJS Logger is injectable like ILogger<T>, but often used as a static class property
  private readonly logger = new Logger(UsersController.name);

  // Constructor injection — identical mental model to ASP.NET Core
  constructor(private readonly usersService: UsersService) {}

  @Get(':id')                             // ← [HttpGet("{id}")] equivalent
  async findOne(
    @Param('id', ParseUUIDPipe) id: string  // ← [FromRoute] + UUID validation in one decorator
  ) {
    this.logger.log(`Fetching user ${id}`);

    const user = await this.usersService.findById(id);

    if (!user) {
      // NestJS HttpException hierarchy — like ProblemDetails in ASP.NET
      throw new NotFoundException(`User ${id} not found`);
    }

    return user;  // NestJS auto-serializes to JSON (like return Ok(user))
  }
}

// users/users.service.ts
import { Injectable } from '@nestjs/common';
import { PrismaService } from '../prisma/prisma.service';

@Injectable()                             // ← [Service] + IServiceCollection registration signal
export class UsersService {
  constructor(private readonly prisma: PrismaService) {}

  async findById(id: string) {
    // Prisma query — equivalent of LINQ FirstOrDefaultAsync
    return this.prisma.user.findFirst({
      where: {
        id,
        isDeleted: false,
      },
      select: {
        id: true,
        name: true,
        email: true,
        role: true,
      },
    });
    // Returns null if not found — like EF's FirstOrDefaultAsync returning null
  }
}

// users/users.module.ts — the registration equivalent of Program.cs
import { Module } from '@nestjs/common';
import { UsersController } from './users.controller';
import { UsersService } from './users.service';
import { PrismaModule } from '../prisma/prisma.module';

@Module({
  imports: [PrismaModule],                // ← Like builder.Services.AddDbContext()
  controllers: [UsersController],         // ← Controller registration
  providers: [UsersService],             // ← Like builder.Services.AddScoped<UsersService>()
  exports: [UsersService],               // ← Makes UsersService available to other modules
})
export class UsersModule {}

// app.module.ts — the root module, like the top of Program.cs
import { Module } from '@nestjs/common';
import { ConfigModule } from '@nestjs/config';
import { UsersModule } from './users/users.module';

@Module({
  imports: [
    ConfigModule.forRoot({ isGlobal: true }),  // ← IConfiguration global registration
    UsersModule,
  ],
})
export class AppModule {}

// main.ts — application bootstrap, equivalent to Program.cs entry point
import { NestFactory } from '@nestjs/core';
import { AppModule } from './app.module';
import { ValidationPipe } from '@nestjs/common';

async function bootstrap() {
  const app = await NestFactory.create(AppModule);

  app.setGlobalPrefix('api');              // ← Like MapControllers() with route prefix

  app.useGlobalPipes(                      // ← Global validation — like AddFluentValidation()
    new ValidationPipe({
      whitelist: true,                     // ← Strip unknown properties (like [BindNever])
      transform: true,                     // ← Auto-coerce types (like model binding)
    })
  );

  await app.listen(3000);
}

bootstrap();

What to notice:

1. The decorator pattern (@Controller(), @Get(), @UseGuards()) is syntactically identical to C# attributes, but decorators are functions that execute at class definition time — not metadata read at runtime. Article 2.5 covers this distinction in depth.

2. NestJS’s NotFoundException maps to ASP.NET’s return NotFound() / ProblemDetails. NestJS has a full HttpException hierarchy: BadRequestException, UnauthorizedException, ForbiddenException, NotFoundException, ConflictException, and so on.

3. The module (UsersModule) is where .NET’s IServiceCollection registration happens in NestJS. There is no global Program.cs listing all services — each module registers its own providers and explicitly exports what other modules can use.

4. ParseUUIDPipe combines two ASP.NET concepts: model binding ([FromRoute]) and validation ([RegularExpression] or a custom type converter). Pipes in NestJS transform and validate simultaneously.

Key Differences

Gotchas for .NET Engineers

1. NestJS Services Are Singleton by Default — This Will Bite You

In ASP.NET Core, the default assumption for services added with AddScoped<T>() is that a new instance is created per HTTP request. State on a scoped service is safe because it’s isolated per request.

In NestJS, @Injectable() services are singletons by default (the DEFAULT scope). This means a property you set on a service instance during one request will be visible to other concurrent requests. This is equivalent to accidentally calling AddSingleton<T>() for everything in ASP.NET Core.

// THIS IS A BUG — service is singleton, currentUser is shared across requests
@Injectable()
export class UsersService {
  private currentUser: User;  // ← DANGER: shared across all requests

  async processRequest(userId: string) {
    this.currentUser = await this.findById(userId);  // ← race condition
    return this.doSomething();
  }
}

// CORRECT — use request-scoped injection when you need per-request state
@Injectable({ scope: Scope.REQUEST })
export class UsersService {
  private currentUser: User;  // ← now safe — new instance per request
  // ...
}

For stateless services (the common case — query a database, return a result), singleton scope is fine and more efficient. The gotcha is when you store state on a service property. In ASP.NET Core, you’d get a warning-level code smell; in NestJS, it’s a silent race condition.

2. There Is No Global Service Registration — Module Boundaries Are Enforced

If you add a service in AuthModule and try to inject it in UsersController, you’ll get a NestJS injection error at startup: Nest can't resolve dependencies of the UsersController. The service is not visible outside its module unless explicitly exported.

// auth.module.ts — JwtService is NOT available to other modules by default
@Module({
  providers: [JwtService],
  // Missing: exports: [JwtService]
})
export class AuthModule {}

// users.module.ts — this will cause a runtime error at startup
@Module({
  imports: [AuthModule],          // ← importing AuthModule isn't enough
  controllers: [UsersController],
})
export class UsersModule {}

// UsersController will fail to start because JwtService isn't exported:
// ERROR: Nest can't resolve dependencies of the UsersController (?).

// Fix: explicitly export what other modules need
@Module({
  providers: [JwtService],
  exports: [JwtService],          // ← now JwtService is available to any module that imports AuthModule
})
export class AuthModule {}

The ASP.NET Core reflex is to just register a service in Program.cs and have it available everywhere. That reflex will produce confusing startup errors in NestJS until you internalize the explicit export model.

3. Validation Does Not Run Unless You Wire It Up

In ASP.NET Core with [ApiController], model binding and Data Annotation validation are automatic. You get a 400 response with validation details without writing a single line of validation code in your action.

In NestJS, validation requires:

1. A global ValidationPipe configured in main.ts (or per-controller/per-route)
2. class-validator decorators on your DTO class
3. The class-transformer package for type coercion

Without all three, a DTO with @IsEmail() annotations will silently accept any string:

// dto/create-user.dto.ts
import { IsString, IsEmail, MinLength } from 'class-validator';

export class CreateUserDto {
  @IsString()
  @MinLength(2)
  name: string;

  @IsEmail()
  email: string;
}

// ← Decorators alone do NOTHING without ValidationPipe

// main.ts — without this, the DTO decorators above are ignored
app.useGlobalPipes(
  new ValidationPipe({
    whitelist: true,     // strip unknown properties
    transform: true,     // auto-coerce e.g. string "123" → number 123
  })
);

If you’re reaching for Zod instead of class-validator (which is valid — see Article 2.3), you need a custom pipe that calls schema.parse(value) and maps Zod errors to NestJS’s BadRequestException.

4. Frontend Framework Choices Are Not Interchangeable at the Meta-Framework Level

It’s tempting to think React and Vue are drop-in alternatives. For simple component rendering, they are roughly comparable. But at the meta-framework level, Next.js and Nuxt have diverged significantly in their architecture and have different ecosystem assumptions:

• Next.js Server Components are a React-specific concept. There is no direct Nuxt equivalent (Nuxt uses a different server rendering model).
• Nuxt’s auto-imports and Pinia state management are Vue-specific ecosystem choices that have no React analog.
• Libraries that work with React (Radix, shadcn/ui, React Hook Form) don’t work with Vue, and vice versa.

When you read a job description or a project description and see “React” or “Vue,” treat it as a fundamental architectural axis — similar to how “WPF” and “ASP.NET” in .NET imply different component ecosystems despite both being .NET.

5. Express Middleware Is Not the Same as NestJS Middleware

If you encounter an Express middleware package (there are thousands) and want to use it in NestJS, the integration is possible but not automatic. Express middleware is a function signature (req, res, next) => void. NestJS middleware has the same signature and can wrap Express middleware, but NestJS Guards, Interceptors, and Pipes are NestJS-specific and do not accept raw Express middleware.

// This works — using an Express middleware package inside NestJS middleware
import { Injectable, NestMiddleware } from '@nestjs/common';
import cors from 'cors';

@Injectable()
export class CorsMiddleware implements NestMiddleware {
  use(req: Request, res: Response, next: () => void) {
    cors()(req as any, res as any, next);  // wrapping Express middleware
  }
}

// This does NOT work — you cannot use an Express middleware as a NestJS Guard
// Guards have a completely different signature and purpose

NestJS already integrates CORS, rate limiting, compression, and other common concerns directly — reach for @nestjs/* packages first before wrapping raw Express middleware.

6. “Framework” Means Different Things in Frontend vs. Backend Contexts

React is commonly called a “framework” by practitioners even though it’s technically a library (the React team calls it a library). Angular is unambiguously a framework. This inconsistency in terminology causes real confusion when reading job posts, articles, and documentation.

A working rule: if you hear “framework” in a frontend context, ask whether they mean the rendering library (React/Vue/Angular) or the meta-framework (Next.js/Nuxt/Remix/Angular). In a backend context, “framework” almost always means Express, Fastify, or NestJS.

Hands-On Exercise

The goal of this exercise is to build a minimal NestJS module and viscerally experience how the pieces connect. This is not a toy example — it mirrors the structure you’ll use on real projects.

What you’ll build: A ProductsModule in NestJS with a controller and service that returns a list of products. No database — use a hardcoded in-memory list for now. The point is the wiring, not the data.

Prerequisites:

• Node.js 20+ installed
• pnpm installed (npm install -g pnpm)

Step 1: Create a new NestJS project

npx @nestjs/cli new products-api
cd products-api
pnpm install  # or npm install

Step 2: Generate the module, controller, and service using the NestJS CLI

# The NestJS CLI generates the same scaffolding that dotnet new generates
npx nest generate module products
npx nest generate controller products
npx nest generate service products

This generates src/products/products.module.ts, products.controller.ts, and products.service.ts, and automatically updates app.module.ts to import ProductsModule. This is the dotnet new + project reference equivalent.

Step 3: Implement the service

Open src/products/products.service.ts and replace its content:

import { Injectable } from '@nestjs/common';

export interface Product {
  id: string;
  name: string;
  price: number;
  inStock: boolean;
}

@Injectable()
export class ProductsService {
  private readonly products: Product[] = [
    { id: '1', name: 'Widget Pro', price: 29.99, inStock: true },
    { id: '2', name: 'Gadget Plus', price: 49.99, inStock: false },
    { id: '3', name: 'Doohickey Max', price: 14.99, inStock: true },
  ];

  findAll(): Product[] {
    return this.products;
  }

  findOne(id: string): Product | undefined {
    return this.products.find((p) => p.id === id);
  }
}

Step 4: Implement the controller

Open src/products/products.controller.ts:

import { Controller, Get, Param, NotFoundException } from '@nestjs/common';
import { ProductsService } from './products.service';

@Controller('products')
export class ProductsController {
  constructor(private readonly productsService: ProductsService) {}

  @Get()
  findAll() {
    return this.productsService.findAll();
  }

  @Get(':id')
  findOne(@Param('id') id: string) {
    const product = this.productsService.findOne(id);
    if (!product) {
      throw new NotFoundException(`Product ${id} not found`);
    }
    return product;
  }
}

Step 5: Run and test

pnpm run start:dev
# NestJS starts with hot-reload (like dotnet watch)

In another terminal:

curl http://localhost:3000/products
# Returns the array of all products

curl http://localhost:3000/products/1
# Returns Widget Pro

curl http://localhost:3000/products/99
# Returns 404 with { "message": "Product 99 not found", "error": "Not Found", "statusCode": 404 }

Step 6: Reflect on what you just built

Look at src/app.module.ts — NestJS automatically added ProductsModule to imports when you ran the generate commands. This is the equivalent of builder.Services.AddScoped<IProductsService, ProductsService>() + controller registration in Program.cs, but split across a dedicated module file.

Now trace the DI chain: ProductsController declares private readonly productsService: ProductsService in its constructor. NestJS sees that ProductsService is in ProductsModule.providers and the ProductsController is in ProductsModule.controllers, so it resolves the dependency automatically. No [FromServices], no manual app.Services.GetService<T>() — the module system handles it.

Stretch challenge: Add a POST /products endpoint that accepts a body with name, price, and inStock. Add class-validator and configure a global ValidationPipe in main.ts. Verify that sending an invalid body (missing required fields, wrong types) returns a 400 with field-level errors. This is the equivalent of adding [ApiController] + Data Annotations to an ASP.NET Core controller.

Quick Reference

Frontend Framework Chooser

Backend Framework Chooser

Concept Mapping Cheat Sheet

Library vs. Framework vs. Meta-Framework

graph TD
    subgraph Frontend["Frontend Stack"]
        MF1["Meta-Framework\n(Next.js, Nuxt, Remix)"]
        FL["Framework/Library\n(React, Vue)"]
        RT1["Runtime\n(Node.js + V8)"]
        MF1 --> FL --> RT1
    end

    subgraph Backend["Backend Stack"]
        MF2["Meta-Framework\n(NestJS)"]
        HE["HTTP Engine\n(Express or Fastify)"]
        RT2["Runtime\n(Node.js + V8)"]
        MF2 --> HE --> RT2
    end

Further Reading

• NestJS Official Documentation — The authoritative source. The “Overview” section maps well to ASP.NET engineers. Start with Controllers, Providers, Modules.
• Next.js App Router Documentation — Covers the App Router architecture in depth, including Server Components and the routing conventions.
• State of JS 2024 Survey — Annual survey of the JS ecosystem. Useful for understanding which libraries are gaining or losing adoption, so you can calibrate which things are worth learning.
• React Documentation — Thinking in React — The canonical explanation of React’s mental model. Read this after the React fundamentals article (3.1) if the one-way data flow model feels unnatural.

Cross-reference: This article establishes what each library and framework IS in the JS ecosystem. When you’re deciding whether to build your backend in NestJS at all — or whether to keep your existing .NET API and use Next.js as a typed frontend on top of it — see Track 4B, specifically Article 4B.1 (.NET as API) and Article 4B.3 (the decision framework). That track is for teams that have significant .NET investment and want to evaluate when NestJS is the right choice versus keeping C# doing what it does best.

Async/Await: Same Keywords, Different Universe

For .NET engineers who know: C# async/await, Task<T>, Task.WhenAll(), ConfigureAwait(false), and the thread pool model You’ll learn: Why TypeScript’s async/await looks identical to C#’s but operates on a completely different runtime model — and the specific traps that catch .NET engineers off guard Time: 15-20 minutes

The .NET Way (What You Already Know)

In C#, async/await is a compiler transformation over the thread pool. When you await a Task, you yield the current thread back to the thread pool. The runtime captures the current SynchronizationContext and, when the awaited work completes, resumes your code on an appropriate thread — either the original context thread (in ASP.NET Framework or UI apps) or any thread pool thread (in ASP.NET Core, which has no SynchronizationContext).

This is why ConfigureAwait(false) exists: in library code, you explicitly opt out of capturing the synchronization context to avoid deadlocks and improve throughput. In ASP.NET Core you mostly don’t need it, but you’ve probably written it a thousand times in library code, or been told to.

// C# — Await yields the current thread; another thread resumes the continuation
public async Task<Order> GetOrderAsync(int id)
{
    // Thread pool thread T1 starts here
    var order = await _db.Orders.FindAsync(id);
    // T1 is released during the DB call
    // Thread pool thread T2 (possibly the same as T1) resumes here

    var tax = await _taxService.CalculateAsync(order);
    // T2 is released; another thread picks up the continuation
    return order with { Tax = tax };
}

The Task<T> type is the fundamental unit of async work. Task.WhenAll() runs tasks in parallel. Task.WhenAny() returns when the first task completes. AggregateException wraps multiple failures from parallel operations.

You also know that forgetting await compiles fine and produces a Task<T> instead of T — a silent bug you’ve probably chased.

The TypeScript Way

There Are No Threads

Node.js is single-threaded. There is no thread pool, no synchronization context, and no thread switching. When you await a Promise in TypeScript, you yield to the event loop — a single-threaded scheduler that processes callbacks, I/O events, and timers in phases.

// TypeScript — Await yields to the event loop; the same thread resumes the continuation
async function getOrder(id: number): Promise<Order> {
  // The single thread starts here
  const order = await db.orders.findUnique({ where: { id } });
  // The thread is released to the event loop during the I/O wait
  // The same thread resumes here when the DB responds

  const tax = await taxService.calculate(order);
  // Same thread again
  return { ...order, tax };
}

The execution model looks the same from inside the async function, but the runtime mechanics are completely different. In C#, multiple threads may touch your async chain. In TypeScript, one thread always does — it just handles other things between your awaits.

This has real consequences:

• No race conditions on shared mutable state (within a single Node.js process, between async operations). Two await points cannot interleave on different threads because there is only one thread.
• CPU-bound work blocks everything. A tight computation loop blocks the event loop entirely. There is no Task.Run(() => HeavyCpuWork()) equivalent that offloads to a thread pool — you need Worker Threads for that, which is a different topic.
• No ConfigureAwait(false). There is no synchronization context to capture. You will never write it; you do not need to think about it.

Promises vs. Tasks

Promise<T> is the TypeScript equivalent of Task<T>. The mapping is close but not exact.

// TypeScript
const promise: Promise<string> = fetch("https://api.example.com/data")
  .then((res) => res.json())
  .then((data) => data.name);

// C# equivalent
Task<string> task = httpClient
    .GetAsync("https://api.example.com/data")
    .ContinueWith(t => t.Result.Content.ReadFromJsonAsync<Response>())
    .ContinueWith(t => t.Result.Name);

With async/await, both collapse into the same readable form:

// TypeScript
async function getName(): Promise<string> {
  const res = await fetch("https://api.example.com/data");
  const data = await res.json();
  return data.name;
}

// C#
async Task<string> GetNameAsync()
{
    var res = await _httpClient.GetAsync("https://api.example.com/data");
    var data = await res.Content.ReadFromJsonAsync<Response>();
    return data.Name;
}

One critical difference: Promise is eager. The moment you create a Promise, the work starts. Task can be “hot” (already running) or “cold” depending on how it was created, but most APIs return hot tasks. For practical purposes, treat both as: work starts when the object is created.

Promise.all() vs. Task.WhenAll()

Running operations in parallel is one of the most common async patterns, and this is where .NET engineers make their first performance mistake in TypeScript.

// C# — Parallel execution with Task.WhenAll
async Task<(User user, IEnumerable<Order> orders)> GetUserWithOrdersAsync(int userId)
{
    var userTask = _userService.GetByIdAsync(userId);
    var ordersTask = _orderService.GetByUserAsync(userId);

    await Task.WhenAll(userTask, ordersTask);

    return (userTask.Result, ordersTask.Result);
}

// TypeScript — Parallel execution with Promise.all
async function getUserWithOrders(
  userId: number
): Promise<{ user: User; orders: Order[] }> {
  const [user, orders] = await Promise.all([
    userService.getById(userId),
    orderService.getByUser(userId),
  ]);

  return { user, orders };
}

Promise.all() takes an array of Promises and returns a single Promise that resolves when all input Promises resolve. If any one rejects, the returned Promise rejects immediately with that error — the others are abandoned (they still run to completion, but their results are discarded).

This mirrors Task.WhenAll() behavior for the failure case. The difference is that Task.WhenAll() waits for all tasks to finish before throwing, aggregating all exceptions into an AggregateException. Promise.all() short-circuits on the first rejection. If you need all results — successes and failures — use Promise.allSettled().

// TypeScript — Collect all results, including failures
async function getUserAndOrders(userId: number) {
  const results = await Promise.allSettled([
    userService.getById(userId),
    orderService.getByUser(userId),
  ]);

  // results[0].status === 'fulfilled' | 'rejected'
  for (const result of results) {
    if (result.status === "rejected") {
      console.error("One operation failed:", result.reason);
    } else {
      // result.value is the resolved value
    }
  }
}

// C# — Task.WhenAll() always waits for all tasks; exceptions are aggregated
async Task GetAllAsync()
{
    try
    {
        await Task.WhenAll(task1, task2, task3);
    }
    catch (AggregateException ex)
    {
        // ex.InnerExceptions contains ALL failures
        foreach (var inner in ex.InnerExceptions)
            Console.WriteLine(inner.Message);
    }
}

Promise.race() vs. Task.WhenAny()

Promise.race() resolves or rejects as soon as the first Promise in the array settles — for better or worse.

// C# — Return whichever completes first
async Task<string> GetFastestResultAsync()
{
    var task1 = FetchFromPrimaryAsync();
    var task2 = FetchFromSecondaryAsync();
    var firstTask = await Task.WhenAny(task1, task2);
    return await firstTask; // unwrap the result
}

// TypeScript — Same pattern, cleaner syntax
async function getFastestResult(): Promise<string> {
  return await Promise.race([fetchFromPrimary(), fetchFromSecondary()]);
}

A common use case in both ecosystems is implementing a timeout:

// TypeScript — Timeout pattern
function withTimeout<T>(promise: Promise<T>, ms: number): Promise<T> {
  const timeout = new Promise<never>((_, reject) =>
    setTimeout(() => reject(new Error(`Timed out after ${ms}ms`)), ms)
  );
  return Promise.race([promise, timeout]);
}

// Usage
const result = await withTimeout(slowApiCall(), 5000);

// C# equivalent — CancellationToken is the idiomatic approach,
// but you can also race against Task.Delay
async Task<string> WithTimeoutAsync(Task<string> task, int ms)
{
    var timeoutTask = Task.Delay(ms).ContinueWith(_ =>
        throw new TimeoutException());
    var winner = await Task.WhenAny(task, timeoutTask);
    return await winner;
}

Error Handling

In C#, exceptions propagate through await naturally. A faulted Task throws when you await it. AggregateException appears when you call .Result or .Wait() directly, or when Task.WhenAll() collects multiple failures.

In TypeScript, a rejected Promise throws when you await it. The try/catch blocks look identical:

// TypeScript
async function processOrder(id: number): Promise<void> {
  try {
    const order = await orderService.get(id);
    await paymentService.charge(order);
    await notificationService.send(order);
  } catch (err) {
    // err is typed as 'unknown' in strict TypeScript
    if (err instanceof PaymentError) {
      await orderService.markFailed(id);
    }
    throw err; // re-throw if not handled
  }
}

// C#
async Task ProcessOrderAsync(int id)
{
    try
    {
        var order = await _orderService.GetAsync(id);
        await _paymentService.ChargeAsync(order);
        await _notificationService.SendAsync(order);
    }
    catch (PaymentException ex)
    {
        await _orderService.MarkFailedAsync(id);
        throw;
    }
}

The structural difference: in TypeScript catch, the error is typed as unknown (with strict mode and useUnknownInCatchVariables). You must narrow the type before using it. This is the correct behavior — JavaScript throw can throw anything, not just Error objects.

// TypeScript — Proper error narrowing
try {
  await riskyOperation();
} catch (err) {
  // err: unknown
  if (err instanceof Error) {
    console.error(err.message);   // now safe
    console.error(err.stack);     // now safe
  } else {
    console.error("Unknown error:", String(err));
  }
}

There is no AggregateException in TypeScript. When Promise.all() rejects, you get the first rejection error directly — it is not wrapped. If you need to inspect all errors from parallel operations, use Promise.allSettled().

The Callback Era (Context You Need)

JavaScript had async/await added in 2017. Before that, async code used callbacks:

// The callback hell you'll see in old code
fs.readFile("data.json", "utf8", function (err, data) {
  if (err) {
    console.error(err);
    return;
  }
  JSON.parse(data, function (parseErr, parsed) {
    // This isn't even real API — just illustrating the nesting
    database.save(parsed, function (saveErr, result) {
      if (saveErr) {
        console.error(saveErr);
        return;
      }
      console.log("Saved:", result);
    });
  });
});

Promises arrived first as a library pattern, then as a language primitive. async/await is syntax sugar over Promises — await unwraps a Promise, and an async function always returns a Promise.

You’ll encounter callback-style APIs in Node.js core (many fs, http, crypto functions still have callback variants). The standard way to promisify them is util.promisify():

import { promisify } from "util";
import { readFile } from "fs";

const readFileAsync = promisify(readFile);

async function readConfig(): Promise<string> {
  const buffer = await readFileAsync("config.json", "utf8");
  return buffer;
}

Modern Node.js provides fs/promises (and similar modules for other core APIs) that are natively Promise-based, so you rarely need promisify in new code. But when you’re working with third-party libraries from the callback era, you’ll need it.

The Async IIFE Pattern

In C#, you can’t use await at the top level of a class or static method without wrapping it in an async method — though C# 9 added top-level statements that allow it in Program.cs.

In older JavaScript and in some module contexts, you’ll see the async IIFE (immediately invoked function expression) pattern, which creates and immediately calls an async function to get a scope where await is valid:

// Async IIFE — creates an async scope and executes immediately
(async () => {
  const data = await fetchSomeData();
  console.log(data);
})();

// The outer () invokes the async function immediately
// Any rejection here is an unhandled rejection — you must catch it
(async () => {
  try {
    const data = await fetchSomeData();
    console.log(data);
  } catch (err) {
    console.error("Top-level failure:", err);
    process.exit(1);
  }
})();

Modern TypeScript and Node.js support top-level await in ES modules (files with "type": "module" in package.json, or .mts files). This eliminates the need for the IIFE pattern in most cases:

// Top-level await — works in ES modules
const config = await loadConfig();
const db = await connectToDatabase(config.databaseUrl);

console.log("Server ready");

You’ll still encounter async IIFEs in non-module contexts, in test setup code, and in older codebases. Recognize the pattern; you rarely need to write it yourself.

Key Differences

Gotchas for .NET Engineers

Gotcha 1: Forgetting await Is Silent and Produces the Wrong Type

In C#, forgetting await gives you a Task<T> where you expected a T. The compiler often catches this because you’ll try to use a Task<User> where a User is expected, and it won’t compile.

In TypeScript, the same mistake still compiles and runs — you get a Promise<User> where you expected a User. If you then pass it to something that accepts any or unknown, or log it, it prints [object Promise] and no error is thrown.

// This compiles. It is wrong.
async function processUser(id: number): Promise<void> {
  const user = userService.getById(id); // Missing await
  // user is Promise<User>, not User

  console.log(user.name); // undefined — Promise has no .name property
  // TypeScript may warn here if types are strict, but won't always
}

// This is also silently broken
async function saveAndReturn(data: UserInput): Promise<User> {
  const user = userService.create(data); // Missing await
  return user; // Returns Promise<User>, which async wraps in another Promise
  // Caller gets Promise<Promise<User>> — this actually works by accident
  // because await on a thenable unwraps recursively. But the intent is wrong.
}

Enable strict TypeScript and use no-floating-promises in your ESLint configuration. It catches Promises that are created but not awaited or returned:

// .eslintrc or eslint.config.mjs
{
  "rules": {
    "@typescript-eslint/no-floating-promises": "error"
  }
}

Gotcha 2: Sequential Execution When You Intended Parallel

This is the single most common performance mistake .NET engineers make when writing TypeScript for the first time. It looks correct and runs fine — it’s just slow.

// WRONG — Sequential. Each await blocks the next.
async function getDashboardData(userId: number) {
  const user = await userService.getById(userId);    // waits ~50ms
  const orders = await orderService.getByUser(userId); // waits ~80ms
  const notifications = await notificationService.getUnread(userId); // waits ~30ms

  return { user, orders, notifications };
  // Total: ~160ms
}

// CORRECT — Parallel. All three start immediately.
async function getDashboardData(userId: number) {
  const [user, orders, notifications] = await Promise.all([
    userService.getById(userId),
    orderService.getByUser(userId),
    notificationService.getUnread(userId),
  ]);

  return { user, orders, notifications };
  // Total: ~80ms (the slowest single operation)
}

The sequential version is not wrong in the way a bug is wrong — it produces correct results. It is wrong in the way a performance anti-pattern is wrong. In C#, you’d naturally reach for Task.WhenAll() here. In TypeScript, train yourself to reach for Promise.all() whenever you have independent operations.

The only time sequential await is correct is when each operation depends on the result of the previous one.

Gotcha 3: Unhandled Promise Rejections Are Dangerous

In C#, forgetting to await a Task that throws results in an unobserved task exception. Modern .NET raises TaskScheduler.UnobservedTaskException and, depending on configuration, may terminate the process.

In Node.js, unhandled Promise rejections print a warning and, since Node.js 15, terminate the process with exit code 1:

UnhandledPromiseRejectionWarning: Error: DB connection failed
    at Object.<anonymous> (server.ts:12:15)

This means that fire-and-forget async patterns — which might be acceptable in .NET with proper exception handling — are dangerous in Node.js:

// DANGEROUS — If sendEmail rejects, the process may crash
function handleUserSignup(user: User): void {
  emailService.sendWelcome(user); // Missing await, no .catch()
  // Execution continues, but a rejection floats unhandled
}

// SAFE — Explicitly handle the floating promise
function handleUserSignup(user: User): void {
  emailService
    .sendWelcome(user)
    .catch((err) => logger.error("Welcome email failed", { userId: user.id, err }));
}

Register a global handler to catch anything that slips through:

// In your server startup
process.on("unhandledRejection", (reason, promise) => {
  logger.error("Unhandled promise rejection", { reason, promise });
  // In production, crash and let your process manager restart
  process.exit(1);
});

Gotcha 4: Promise.all() Abandons Other Promises on First Failure

In C#, Task.WhenAll() waits for all tasks to complete (including failures) before throwing. This means if you start three parallel operations and one fails, the other two still run to completion — their results are just not returned.

Promise.all() short-circuits: the moment one Promise rejects, the returned Promise rejects immediately. The other Promises are not cancelled (there is no cancellation at the Promise level), but their results are discarded.

// If getOrders() rejects after 10ms,
// getNotifications() continues running but its result is discarded.
// This can leave database connections or resources in unexpected states.
const [user, orders, notifications] = await Promise.all([
  getUser(userId),     // completes in 50ms
  getOrders(userId),   // rejects in 10ms — Promise.all rejects immediately
  getNotifications(userId), // still running, result ignored
]);

If all three operations write to a database or acquire resources, you may end up with partial state. Use Promise.allSettled() when you need to ensure cleanup happens regardless of failures.

Gotcha 5: async in forEach Does Not Work the Way You Expect

This one burns nearly every .NET engineer. In C#, await inside a foreach loop is straightforward — it awaits each iteration before moving to the next.

// C# — Works as expected
foreach (var id in orderIds)
{
    await ProcessOrderAsync(id); // Sequential, as intended
}

// BROKEN — forEach does not await the async callback
orderIds.forEach(async (id) => {
  await processOrder(id); // These all start in parallel AND forEach returns immediately
});
// Execution continues here before any orders are processed

// CORRECT — Use for...of for sequential async iteration
for (const id of orderIds) {
  await processOrder(id); // Properly sequential
}

// CORRECT — Use Promise.all with .map() for parallel async iteration
await Promise.all(orderIds.map((id) => processOrder(id)));

Array.prototype.forEach was designed before Promises existed. It ignores the return value of its callback. An async function returns a Promise, and forEach throws that Promise away. Always use for...of for sequential async loops, or Promise.all() with .map() for parallel async loops.

Hands-On Exercise

The following exercises target the specific patterns that trip up .NET engineers. Work through each one in a TypeScript file you can run with npx tsx exercise.ts.

Setup:

// exercise.ts — paste this, then implement the TODOs below

// Simulated async operations with realistic delays
function delay(ms: number): Promise<void> {
  return new Promise((resolve) => setTimeout(resolve, ms));
}

async function fetchUser(id: number): Promise<{ id: number; name: string }> {
  await delay(100);
  return { id, name: `User ${id}` };
}

async function fetchOrders(
  userId: number
): Promise<Array<{ id: number; total: number }>> {
  await delay(150);
  return [
    { id: 1, total: 99.99 },
    { id: 2, total: 149.5 },
  ];
}

async function fetchPermissions(userId: number): Promise<string[]> {
  await delay(80);
  return ["read", "write"];
}

async function processOrder(orderId: number): Promise<void> {
  await delay(50);
  if (orderId === 2) throw new Error(`Order ${orderId} failed validation`);
}

Exercise 1 — Fix the Sequential Bottleneck:

// This function takes ~330ms. Rewrite it to take ~150ms.
async function getDashboard(userId: number) {
  const user = await fetchUser(userId);
  const orders = await fetchOrders(userId);
  const permissions = await fetchPermissions(userId);
  return { user, orders, permissions };
}

// Verify your answer: log performance.now() before and after calling getDashboard(1)

Exercise 2 — Handle Partial Failures:

// This crashes if any order fails. Rewrite it to process all orders
// and return a summary: { succeeded: number[], failed: Array<{id: number, error: string}> }
async function processAllOrders(orderIds: number[]) {
  await Promise.all(orderIds.map(processOrder));
}

// Test with: processAllOrders([1, 2, 3])
// Order 2 always fails — your function should not crash

Exercise 3 — Fix the forEach Bug:

// This function returns before any orders are processed.
// Fix it so all orders complete before returning, running sequentially.
async function processOrdersSequentially(orderIds: number[]): Promise<void> {
  orderIds.forEach(async (id) => {
    await processOrder(id);
    console.log(`Processed order ${id}`);
  });
}

Exercise 4 — Implement a Timeout:

// fetchOrders takes 150ms. Implement withTimeout() so this fails:
// await withTimeout(fetchOrders(1), 100);
// And this succeeds:
// await withTimeout(fetchOrders(1), 200);

function withTimeout<T>(promise: Promise<T>, ms: number): Promise<T> {
  // TODO
}

Expected outputs and solutions are in the appendix at the bottom of this article.

Exercise Solutions:

// Exercise 1 — Parallel execution
async function getDashboard(userId: number) {
  const [user, orders, permissions] = await Promise.all([
    fetchUser(userId),
    fetchOrders(userId),
    fetchPermissions(userId),
  ]);
  return { user, orders, permissions };
}

// Exercise 2 — Partial failure handling
async function processAllOrders(orderIds: number[]) {
  const results = await Promise.allSettled(orderIds.map(processOrder));
  const succeeded: number[] = [];
  const failed: Array<{ id: number; error: string }> = [];

  results.forEach((result, index) => {
    if (result.status === "fulfilled") {
      succeeded.push(orderIds[index]);
    } else {
      failed.push({ id: orderIds[index], error: result.reason.message });
    }
  });

  return { succeeded, failed };
}

// Exercise 3 — Fix forEach
async function processOrdersSequentially(orderIds: number[]): Promise<void> {
  for (const id of orderIds) {
    await processOrder(id);
    console.log(`Processed order ${id}`);
  }
}

// Exercise 4 — Timeout
function withTimeout<T>(promise: Promise<T>, ms: number): Promise<T> {
  const timeoutPromise = new Promise<never>((_, reject) =>
    setTimeout(() => reject(new Error(`Operation timed out after ${ms}ms`)), ms)
  );
  return Promise.race([promise, timeoutPromise]);
}

Quick Reference

Further Reading

• MDN: Using Promises — The definitive reference for Promise semantics, including the microtask queue model
• Node.js Event Loop Documentation — Required reading for understanding the runtime model underneath async/await
• typescript-eslint: no-floating-promises — The ESLint rule that catches unhandled Promises; enable it in every project
• MDN: Promise.allSettled() — The Promise.all() alternative you’ll reach for once you understand the failure semantics

1.8 — Error Handling: Exceptions vs. the JS Way

For .NET engineers who know: C# exception hierarchy, try/catch/finally, exception filters, IExceptionHandler / global exception middleware in ASP.NET Core You’ll learn: How JavaScript’s minimal error model works, why the JS community reached for return-value patterns, and how to build a disciplined error-handling strategy in TypeScript across NestJS and React Time: 15-20 minutes

The .NET Way (What You Already Know)

C# gives you a rich, typed exception hierarchy. System.Exception sits at the root, below it SystemException and ApplicationException, and below those hundreds of concrete types (ArgumentNullException, InvalidOperationException, DbUpdateConcurrencyException, and your own custom hierarchy).

// C# — Custom exception hierarchy
public class DomainException : ApplicationException
{
    public DomainException(string message) : base(message) { }
}

public class OrderNotFoundException : DomainException
{
    public int OrderId { get; }
    public OrderNotFoundException(int orderId)
        : base($"Order {orderId} was not found.")
    {
        OrderId = orderId;
    }
}

public class InsufficientInventoryException : DomainException
{
    public string Sku { get; }
    public int Requested { get; }
    public int Available { get; }

    public InsufficientInventoryException(string sku, int requested, int available)
        : base($"SKU {sku}: requested {requested}, available {available}.")
    {
        Sku = sku;
        Requested = requested;
        Available = available;
    }
}

You catch by type, leveraging the hierarchy:

// C# — catch by type, exception filters
try
{
    await orderService.PlaceOrderAsync(dto);
}
catch (OrderNotFoundException ex) when (ex.OrderId > 0)
{
    // exception filter: only catches if the condition is true
    logger.LogWarning("Order {OrderId} not found", ex.OrderId);
    return NotFound(ex.Message);
}
catch (DomainException ex)
{
    // catches any remaining DomainException subclass
    return BadRequest(ex.Message);
}
catch (Exception ex)
{
    // last-resort catch
    logger.LogError(ex, "Unexpected error placing order");
    return StatusCode(500, "Internal server error");
}
finally
{
    metrics.IncrementOrderAttempts();
}

And you have global exception handling in ASP.NET Core via IExceptionHandler (or the classic UseExceptionHandler middleware), which gives you one place to translate unhandled exceptions into consistent HTTP responses:

// C# — Global exception handler (ASP.NET Core 8+)
public class GlobalExceptionHandler : IExceptionHandler
{
    public async ValueTask<bool> TryHandleAsync(
        HttpContext context,
        Exception exception,
        CancellationToken cancellationToken)
    {
        var (statusCode, title) = exception switch
        {
            OrderNotFoundException => (404, "Not Found"),
            DomainException => (400, "Bad Request"),
            _ => (500, "Internal Server Error")
        };

        context.Response.StatusCode = statusCode;
        await context.Response.WriteAsJsonAsync(
            new ProblemDetails { Title = title, Detail = exception.Message },
            cancellationToken);

        return true;
    }
}

The model is: throw everywhere, catch at the boundary, translate to HTTP once. It works well because the CLR guarantees that anything thrown is an Exception — you always know what you’re catching.

The JavaScript Way

What JavaScript Actually Has

JavaScript’s built-in Error class is surprisingly thin:

// TypeScript — the Error class
const e = new Error("something went wrong");
e.message;  // "something went wrong"
e.name;     // "Error"
e.stack;    // runtime-specific stack trace string

// Built-in subclasses (all inherit Error)
new TypeError("expected string, got number");
new RangeError("index out of bounds");
new SyntaxError("unexpected token");
new ReferenceError("x is not defined");
new URIError("malformed URI");
new EvalError("...");  // essentially never used

That is the entirety of the standard hierarchy. There is no ApplicationException. There is no checked exception system. There is no AggregateException (though Promise.allSettled and AggregateError partially fill that gap). The standard library throws on programmer errors — TypeError, RangeError — but for domain errors, there is no conventional base class.

Extending Error in TypeScript

You can extend Error, but there is a well-known pitfall with TypeScript and transpilation targets below ES2015:

// TypeScript — extending Error correctly
export class DomainError extends Error {
    constructor(message: string) {
        super(message);
        // Required when targeting ES5 or ES2015 with TypeScript's
        // downlevel emit: the prototype chain breaks without this.
        Object.setPrototypeOf(this, new.target.prototype);
        this.name = new.target.name; // "DomainError", not "Error"
    }
}

export class OrderNotFoundError extends DomainError {
    constructor(public readonly orderId: number) {
        super(`Order ${orderId} was not found.`);
        Object.setPrototypeOf(this, new.target.prototype);
    }
}

export class InsufficientInventoryError extends DomainError {
    constructor(
        public readonly sku: string,
        public readonly requested: number,
        public readonly available: number,
    ) {
        super(`SKU ${sku}: requested ${requested}, available ${available}.`);
        Object.setPrototypeOf(this, new.target.prototype);
    }
}

The Object.setPrototypeOf(this, new.target.prototype) call is the TypeScript equivalent of a footgun warning label. If you target ES2015 or higher (which you should in 2026 — see your tsconfig.json target field), you do not need it. But if you ever find instanceof returning false for a custom error class in production, this is why.

The Critical Difference: You Can Throw Anything

In C#, the compiler enforces that throw accepts only Exception-derived types. In JavaScript, you can throw any value:

// TypeScript — this compiles and runs without error
throw "a plain string";
throw 42;
throw { code: "ERR_BAD", detail: "something" };
throw null;
throw undefined;

This means your catch block cannot assume it received an Error:

// TypeScript — safe catch pattern
try {
    await riskyOperation();
} catch (err) {
    // err has type: unknown (with noUncheckedIndexedAccess and strict mode)
    // err has type: any (without strict)

    if (err instanceof Error) {
        console.error(err.message, err.stack);
    } else {
        // someone threw a non-Error value; handle defensively
        console.error("Non-Error thrown:", String(err));
    }
}

With "useUnknownInCatchVariables": true (enabled by TypeScript’s strict flag since 4.4), err in a catch block has type unknown, which forces you to narrow it before use. This is the correct behavior and you should have strict: true in your tsconfig.json.

A utility function to normalize caught values is worth having in your shared utilities:

// TypeScript — normalize unknown thrown value to Error
export function toError(thrown: unknown): Error {
    if (thrown instanceof Error) return thrown;
    if (typeof thrown === "string") return new Error(thrown);
    if (typeof thrown === "object" && thrown !== null) {
        return new Error(JSON.stringify(thrown));
    }
    return new Error(String(thrown));
}

// Usage
try {
    await riskyOperation();
} catch (err) {
    const error = toError(err);
    logger.error({ err: error }, "Operation failed");
}

try/catch/finally — What Is the Same, What Is Different

The syntax is identical to C#. The behavior differences are subtle:

// TypeScript — try/catch/finally, parallel to C#
async function fetchOrder(id: number): Promise<Order> {
    try {
        const row = await db.order.findUniqueOrThrow({ where: { id } });
        return mapToOrder(row);
    } catch (err) {
        if (err instanceof OrderNotFoundError) {
            throw err; // re-throw — no wrapping needed
        }
        // Prisma throws PrismaClientKnownRequestError with code "P2025"
        // when findUniqueOrThrow finds nothing. Translate it.
        if (isPrismaNotFoundError(err)) {
            throw new OrderNotFoundError(id);
        }
        throw err; // unknown error — let it propagate
    } finally {
        // runs regardless of outcome, same as C#
        metrics.recordDbQuery("order.findUnique");
    }
}

The key behavioral difference from C# is: finally runs even when the function is async and the catch block re-throws. JavaScript Promises handle this correctly. What is different from C# is that there are no when exception filters in JS — you do type narrowing inside the catch body.

The Result Pattern — When Not to Throw

The JavaScript community, especially TypeScript engineers influenced by Rust and functional programming, has embraced the Result<T, E> pattern for expected failure modes. The idea: rather than throwing for conditions that are part of normal operation (user not found, validation failed, payment declined), return a discriminated union that the caller is forced to handle.

This is not how C# normally works, but it has a clear analog: TryParse methods (int.TryParse, Dictionary.TryGetValue) that return bool and output the value via out parameters. The Result pattern is the functional version of that.

Rolling Your Own (Simple, No Dependencies)

// TypeScript — simple Result type
type Result<T, E extends Error = Error> =
    | { ok: true; value: T }
    | { ok: false; error: E };

function ok<T>(value: T): Result<T, never> {
    return { ok: true, value };
}

function err<E extends Error>(error: E): Result<never, E> {
    return { ok: false, error };
}

// Usage
async function findUser(
    email: string,
): Promise<Result<User, UserNotFoundError | DatabaseError>> {
    try {
        const row = await db.user.findUnique({ where: { email } });
        if (!row) return err(new UserNotFoundError(email));
        return ok(mapToUser(row));
    } catch (thrown) {
        return err(new DatabaseError(toError(thrown)));
    }
}

// Caller is forced to check
const result = await findUser("alice@example.com");
if (!result.ok) {
    if (result.error instanceof UserNotFoundError) {
        return { status: 404, body: "Not found" };
    }
    return { status: 500, body: "Database error" };
}
const user = result.value; // TypeScript knows this is User here

Using neverthrow

neverthrow is the most widely adopted Result library for TypeScript. It follows the Rust/Haskell model closely and adds methods like .map(), .mapErr(), .andThen() (flat-map) that let you chain operations without nested if (!result.ok) checks:

pnpm add neverthrow

// TypeScript — neverthrow
import { Result, ok, err, ResultAsync } from "neverthrow";

// ResultAsync wraps Promise<Result<T, E>> with the same chaining API
function findUser(email: string): ResultAsync<User, UserNotFoundError | DatabaseError> {
    return ResultAsync.fromPromise(
        db.user.findUniqueOrThrow({ where: { email } }),
        (thrown) => new DatabaseError(toError(thrown)),
    ).andThen((row) =>
        row ? ok(mapToUser(row)) : err(new UserNotFoundError(email)),
    );
}

function getProfile(
    email: string,
): ResultAsync<Profile, UserNotFoundError | DatabaseError | ProfileError> {
    return findUser(email)
        .andThen((user) => fetchProfile(user.id)) // chains only on ok
        .map((profile) => enrichProfile(profile)); // transforms value on ok
}

// At the call boundary
const result = await getProfile("alice@example.com");
result.match(
    (profile) => res.json(profile),       // ok branch
    (error) => res.status(mapStatus(error)).json({ message: error.message }),
);

The C# mental model for .andThen() is SelectMany / flatMap over a Maybe<T> or an Either<L, R>. If you have used Railway Oriented Programming in F# or functional patterns in C#, this will feel familiar.

When to Use Result vs. Throw

This is where the community has strong opinions. Here is the opinionated recommendation for this stack:

Throw (exceptions) for:

• Programmer errors — null where null is impossible, index out of bounds, contract violations. These are bugs, not expected failure modes. Crashing loudly is correct.
• Infrastructure failures with no reasonable local recovery — database is completely unreachable, file system full. These bubble up to your global handler.
• Anywhere in your stack where a calling NestJS controller or React error boundary will catch and handle them. The framework does the heavy lifting.

Return Result for:

• Domain operations with multiple expected outcomes the caller must handle: findUser might return UserNotFoundError; placeOrder might return InsufficientInventoryError or PaymentDeclinedError. These are not exceptional — they are anticipated branches.
• Service-layer functions called by other service functions, where the caller wants to compose operations and handle errors uniformly.
• Functions that can fail in multiple ways and the caller needs to distinguish the error type to respond differently.

The rule of thumb: if a caller should always handle the failure case, use Result. If a failure is genuinely unexpected and the framework should catch it, throw.

NestJS: Exception Filters vs. ASP.NET Exception Middleware

NestJS’s equivalent of ASP.NET’s IExceptionHandler / UseExceptionHandler is the Exception Filter. The conceptual mapping is direct.

ASP.NET Core                         NestJS
─────────────────────────────────    ─────────────────────────────────
IExceptionHandler                    ExceptionFilter (interface)
app.UseExceptionHandler(...)         app.useGlobalFilters(...)
[TypeFilter(typeof(MyFilter))]       @UseFilters(MyFilter)  (controller/route)
ProblemDetails response shape        custom or HttpException shape

Built-in HttpException Hierarchy

NestJS ships with a small but practical exception hierarchy:

import {
    HttpException,
    BadRequestException,    // 400
    UnauthorizedException,  // 401
    ForbiddenException,     // 403
    NotFoundException,      // 404
    ConflictException,      // 409
    UnprocessableEntityException, // 422
    InternalServerErrorException, // 500
} from "@nestjs/common";

// In a controller or service — throw NestJS HTTP exceptions
// and they are automatically translated to HTTP responses
throw new NotFoundException(`Order ${id} not found`);
throw new BadRequestException({ message: "Invalid input", fields: errors });

NestJS’s default exception filter catches anything that is an HttpException and writes a JSON response. Anything that is not an HttpException gets a generic 500 response. This is the equivalent of ASP.NET Core’s default exception handler behavior.

Writing a Global Exception Filter

For a real application you want one place that translates your domain errors to HTTP responses — exactly like ASP.NET’s IExceptionHandler:

// TypeScript — NestJS global exception filter
// src/common/filters/global-exception.filter.ts
import {
    ExceptionFilter,
    Catch,
    ArgumentsHost,
    HttpException,
    HttpStatus,
    Logger,
} from "@nestjs/common";
import { Request, Response } from "express";
import { DomainError, OrderNotFoundError, InsufficientInventoryError } from "../errors";

@Catch() // no argument = catch everything (like catch (Exception ex) in C#)
export class GlobalExceptionFilter implements ExceptionFilter {
    private readonly logger = new Logger(GlobalExceptionFilter.name);

    catch(exception: unknown, host: ArgumentsHost): void {
        const ctx = host.switchToHttp();
        const response = ctx.getResponse<Response>();
        const request = ctx.getRequest<Request>();

        const { status, message } = this.resolveError(exception);

        if (status >= 500) {
            this.logger.error(
                { err: exception, path: request.url },
                "Unhandled exception",
            );
        }

        response.status(status).json({
            statusCode: status,
            message,
            path: request.url,
            timestamp: new Date().toISOString(),
        });
    }

    private resolveError(exception: unknown): { status: number; message: string } {
        // NestJS HTTP exceptions — already translated
        if (exception instanceof HttpException) {
            return {
                status: exception.getStatus(),
                message: String(exception.message),
            };
        }

        // Domain errors — translate to HTTP status codes
        if (exception instanceof OrderNotFoundError) {
            return { status: HttpStatus.NOT_FOUND, message: exception.message };
        }
        if (exception instanceof InsufficientInventoryError) {
            return { status: HttpStatus.UNPROCESSABLE_ENTITY, message: exception.message };
        }
        if (exception instanceof DomainError) {
            return { status: HttpStatus.BAD_REQUEST, message: exception.message };
        }

        // Truly unexpected
        return {
            status: HttpStatus.INTERNAL_SERVER_ERROR,
            message: "An unexpected error occurred.",
        };
    }
}

Register it globally in main.ts:

// TypeScript — main.ts
import { NestFactory } from "@nestjs/core";
import { AppModule } from "./app.module";
import { GlobalExceptionFilter } from "./common/filters/global-exception.filter";

async function bootstrap() {
    const app = await NestFactory.create(AppModule);
    app.useGlobalFilters(new GlobalExceptionFilter());
    await app.listen(3000);
}
bootstrap();

You can also scope filters to a specific controller or route with the @UseFilters() decorator, which is the NestJS equivalent of ASP.NET’s [TypeFilter] or [ExceptionFilter] attributes.

React: Error Boundaries

On the frontend, React’s equivalent of a global exception handler for rendering errors is the Error Boundary. It is a class component (the one remaining valid use case for class components in 2026) that implements componentDidCatch and getDerivedStateFromError. When any component in its subtree throws during rendering, React calls the boundary instead of crashing the entire page.

// TypeScript — React error boundary
// src/components/ErrorBoundary.tsx
import React, { Component, ErrorInfo, ReactNode } from "react";

interface Props {
    fallback: ReactNode | ((error: Error) => ReactNode);
    children: ReactNode;
    onError?: (error: Error, info: ErrorInfo) => void;
}

interface State {
    error: Error | null;
}

export class ErrorBoundary extends Component<Props, State> {
    state: State = { error: null };

    static getDerivedStateFromError(error: Error): State {
        return { error };
    }

    componentDidCatch(error: Error, info: ErrorInfo): void {
        this.props.onError?.(error, info);
        // Sentry.captureException(error, { extra: info }); // see Sentry section
    }

    render(): ReactNode {
        if (this.state.error) {
            const { fallback } = this.props;
            return typeof fallback === "function"
                ? fallback(this.state.error)
                : fallback;
        }
        return this.props.children;
    }
}

// Usage — wrap your application or sections of it
function App() {
    return (
        <ErrorBoundary
            fallback={(err) => (
                <div role="alert">
                    <h2>Something went wrong</h2>
                    <p>{err.message}</p>
                </div>
            )}
            onError={(err, info) => console.error(err, info)}
        >
            <Router />
        </ErrorBoundary>
    );
}

Error boundaries only catch errors that occur during rendering, in lifecycle methods, and in constructors of components in their subtree. They do not catch errors in:

• Event handlers (use regular try/catch inside the handler)
• Asynchronous code (setTimeout, fetch callbacks — these happen outside React’s call stack)
• The error boundary itself

For async data-fetching errors, TanStack Query surfaces them through the error property of its query result, and you render an error state from the component. React 19 introduces an onCaughtError / onUncaughtError callback on createRoot, but error boundaries remain the primary mechanism.

Node.js: Unhandled Rejection and Uncaught Exception Handlers

In .NET, unhandled exceptions in background threads crash the process (unless AppDomain.UnhandledException or TaskScheduler.UnobservedTaskException is wired up). In Node.js, the equivalents are:

// TypeScript / Node.js — process-level error handlers
// src/main.ts or a dedicated setup file

// Equivalent to AppDomain.UnhandledException for async code.
// In Node.js 15+, an unhandled rejection terminates the process by default.
// In older versions it was a warning. Always handle this explicitly.
process.on("unhandledRejection", (reason: unknown, promise: Promise<unknown>) => {
    const error = reason instanceof Error ? reason : new Error(String(reason));
    logger.fatal({ err: error }, "Unhandled promise rejection — process will exit");
    // Give Sentry time to flush before exiting
    Sentry.captureException(error);
    Sentry.flush(2000).then(() => process.exit(1));
});

// Equivalent to AppDomain.UnhandledException for synchronous throws.
// This is your last-resort handler. The process is in an undefined state.
process.on("uncaughtException", (error: Error) => {
    logger.fatal({ err: error }, "Uncaught exception — process will exit");
    Sentry.captureException(error);
    Sentry.flush(2000).then(() => process.exit(1));
});

// Graceful shutdown on SIGTERM (equivalent to Windows Service stop / ASP.NET
// Core application lifetime cancellation token)
process.on("SIGTERM", () => {
    logger.info("SIGTERM received — shutting down gracefully");
    server.close(() => process.exit(0));
});

NestJS registers these handlers for you when you use NestFactory.create, but if you are writing raw Node.js scripts or custom bootstrap code, you need them explicitly.

The critical rule: do not swallow unhandled rejections. The pattern process.on("unhandledRejection", () => {}) — doing nothing — is a production debugging nightmare. Always log and always exit or re-throw. The process is corrupt at that point.

Sentry Integration

Sentry fills the role of Application Insights for error tracking in this stack. The integration hooks directly into your exception filter (NestJS) and error boundary (React).

NestJS

pnpm add @sentry/node @sentry/profiling-node

// TypeScript — Sentry init in main.ts (before everything else)
import * as Sentry from "@sentry/node";
import { nodeProfilingIntegration } from "@sentry/profiling-node";

Sentry.init({
    dsn: process.env.SENTRY_DSN,
    environment: process.env.NODE_ENV,
    integrations: [nodeProfilingIntegration()],
    tracesSampleRate: process.env.NODE_ENV === "production" ? 0.1 : 1.0,
    profilesSampleRate: 1.0,
    beforeSend(event, hint) {
        // Suppress 4xx errors from Sentry — they are expected
        const status = (hint?.originalException as any)?.status;
        if (status && status >= 400 && status < 500) return null;
        return event;
    },
});

In your global exception filter, add Sentry.captureException(exception) for server errors:

// TypeScript — updated GlobalExceptionFilter with Sentry
import * as Sentry from "@sentry/node";

// Inside the catch() method, after resolveError:
if (status >= 500) {
    Sentry.captureException(exception, {
        extra: { path: request.url, method: request.method },
        user: { id: request.user?.id }, // if you have auth context
    });
}

Next.js / React

pnpm add @sentry/nextjs

Sentry’s Next.js SDK wraps the instrumentation.ts file:

// TypeScript — instrumentation.ts (Next.js 15+ / App Router)
export async function register() {
    if (process.env.NEXT_RUNTIME === "nodejs") {
        const Sentry = await import("@sentry/nextjs");
        Sentry.init({
            dsn: process.env.NEXT_PUBLIC_SENTRY_DSN,
            tracesSampleRate: 0.1,
        });
    }
}

Wire the error boundary to Sentry:

// TypeScript — ErrorBoundary.tsx with Sentry
import * as Sentry from "@sentry/nextjs";

componentDidCatch(error: Error, info: ErrorInfo): void {
    Sentry.captureException(error, { extra: { componentStack: info.componentStack } });
    this.props.onError?.(error, info);
}

Sentry groups errors by their stack trace fingerprint, deduplicates across users, and shows you the release version and user context. The beforeSend callback is the equivalent of Application Insights’ ITelemetryProcessor — use it to filter noise (4xx errors, bot traffic) before they hit your quota.

Designing Error Hierarchies in TypeScript

Given everything above, here is the recommended hierarchy design for a NestJS + React project:

// TypeScript — error hierarchy
// src/common/errors/index.ts

// ─── Base ────────────────────────────────────────────────────────────────────

export class AppError extends Error {
    constructor(
        message: string,
        public readonly code: string,
        public readonly metadata?: Record<string, unknown>,
    ) {
        super(message);
        Object.setPrototypeOf(this, new.target.prototype);
        this.name = new.target.name;
    }
}

// ─── Domain errors (expected, part of the domain model) ──────────────────────

export class DomainError extends AppError {}

export class NotFoundError extends DomainError {
    constructor(resource: string, id: string | number) {
        super(`${resource} '${id}' not found.`, "NOT_FOUND", { resource, id });
    }
}

export class ConflictError extends DomainError {
    constructor(message: string) {
        super(message, "CONFLICT");
    }
}

export class ValidationError extends DomainError {
    constructor(
        message: string,
        public readonly fields?: Record<string, string[]>,
    ) {
        super(message, "VALIDATION_ERROR", { fields });
    }
}

// ─── Infrastructure errors (unexpected, environment-level failures) ───────────

export class InfrastructureError extends AppError {}

export class DatabaseError extends InfrastructureError {
    constructor(cause: Error) {
        super("A database error occurred.", "DATABASE_ERROR");
        this.cause = cause; // Node.js 16.9+ Error.cause support
    }
}

export class ExternalServiceError extends InfrastructureError {
    constructor(service: string, cause: Error) {
        super(`External service '${service}' failed.`, "EXTERNAL_SERVICE_ERROR", {
            service,
        });
        this.cause = cause;
    }
}

Map this to HTTP status codes in your global exception filter:

// TypeScript — status code mapping
function resolveHttpStatus(error: unknown): number {
    if (error instanceof NotFoundError) return 404;
    if (error instanceof ConflictError) return 409;
    if (error instanceof ValidationError) return 422;
    if (error instanceof DomainError) return 400;
    if (error instanceof InfrastructureError) return 503;
    return 500;
}

This keeps the HTTP concern out of your domain model — your services throw NotFoundError, not NotFoundException. The filter translates at the boundary, which is the same separation you get in ASP.NET with IExceptionHandler.

Key Differences

Gotchas for .NET Engineers

Gotcha 1: instanceof Fails Across Module Boundaries

In C#, type identity is determined by the assembly-qualified type name. In JavaScript, instanceof checks the prototype chain — and the prototype is specific to the module instance. If your error classes are instantiated in one bundle chunk and the catch block is in another, instanceof can return false for what looks like the same class.

This is most likely to bite you in:

• Monorepos where the error classes live in a shared package that gets bundled twice (once into the API, once into a worker)
• Node.js environments with multiple copies of the same package in node_modules (pnpm’s strict mode prevents this; npm and yarn can allow duplicate installs)
• Code that uses vm.runInContext or worker threads that don’t share the same module registry

The fix: ensure error classes are a single shared dependency, and use pnpm’s strict mode to prevent duplicate packages. As a defensive measure, you can check error.name or error.code string properties instead of instanceof for errors that cross process boundaries.

Gotcha 2: async Functions Swallow Throws as Rejected Promises

In C#, a throw inside a method propagates synchronously up the call stack, regardless of whether the method is async. In JavaScript, a throw inside an async function does not propagate synchronously — it becomes a rejected Promise. If that promise is not awaited and not .catch()ed, it becomes an unhandled rejection.

// This looks like it throws synchronously, but it does not
async function doWork(): Promise<void> {
    throw new Error("This becomes a rejected Promise, not a synchronous throw");
}

// Caller without await — the error is silently lost in older Node.js
doWork(); // Missing await — in Node 15+, this crashes the process on next tick

// Correct
await doWork(); // error propagates to the caller's catch block

This is the same problem Article 1.7 covers with async/await, but it is especially treacherous in error handling because .NET engineers instinctively assume throw stops execution immediately and propagates up. In an async context in JS, it does stop the function, but the propagation is through the Promise chain, not the synchronous call stack.

Gotcha 3: NestJS’s Default Filter Does Not Catch What You Think

NestJS ships with a default HttpExceptionFilter that handles HttpException and its subclasses. Anything that is NOT an HttpException — including your own custom domain errors — gets caught by NestJS’s internal catch-all, which returns a plain { statusCode: 500, message: "Internal server error" } response and logs the full error internally.

This means: if you throw new OrderNotFoundError(id) from a service and you have not registered a global filter that handles it, the client gets a 500, not a 404. The error is logged to the NestJS internal logger but not sent to Sentry and not translated.

The fix is the global exception filter shown above. Register it before your application starts listening, and test it explicitly — throw a custom domain error from a test endpoint and verify the status code and Sentry capture.

Gotcha 4: Error Boundaries Do Not Catch Event Handler Errors

A React error boundary catches errors thrown during rendering. It does not catch errors thrown inside onClick, onSubmit, or any other DOM event handler. This surprises .NET engineers who expect a top-level handler to catch everything.

// This error is NOT caught by an error boundary above this component
function DeleteButton({ id }: { id: number }) {
    async function handleClick() {
        try {
            await deleteOrder(id); // may throw
        } catch (err) {
            // Must handle here — the error boundary will not see this
            toast.error("Failed to delete order");
        }
    }
    return <button onClick={handleClick}>Delete</button>;
}

Use try/catch inside event handlers. For async mutations, TanStack Query’s useMutation has an onError callback that gives you a consistent place to handle mutation errors without wrapping every mutate() call in try/catch.

Gotcha 5: The Stack Trace Is Often Useless in Production Without Source Maps

In .NET, stack traces reference your original C# source files with line numbers. In production Node.js and browser JavaScript, the code is compiled and minified — stack traces point to mangled variable names and single-line bundles.

Source maps fix this. NestJS with ts-node or SWC in production mode generates source maps. Sentry’s SDK automatically resolves source maps if they are uploaded during deployment. Without source maps, your Sentry errors will show at t.<anonymous> (main.js:1:45821) — useless for debugging.

Configure source map upload in your CI pipeline:

# Example: upload source maps to Sentry during deployment
pnpm dlx @sentry/cli releases files $SENTRY_RELEASE upload-sourcemaps ./dist

Hands-On Exercise

This exercise builds the complete error handling layer for a NestJS order management API. You will implement every pattern from this article: custom error hierarchy, global exception filter, Sentry integration, and a Result-based service method.

Prerequisites: A running NestJS project (from Track 4 exercises, or nest new order-api).

Step 1 — Create the error hierarchy

Create src/common/errors/index.ts with AppError, DomainError, NotFoundError, ValidationError, and DatabaseError exactly as shown in the “Designing Error Hierarchies” section above.

Step 2 — Create a Result type

Install neverthrow: pnpm add neverthrow

Create src/common/result.ts that re-exports Result, ResultAsync, ok, err from neverthrow.

Step 3 — Write an OrderService method using Result

// src/orders/orders.service.ts
import { Injectable } from "@nestjs/common";
import { PrismaService } from "../prisma/prisma.service";
import { ResultAsync, ok, err } from "neverthrow";
import { NotFoundError, DatabaseError } from "../common/errors";
import { toError } from "../common/utils/to-error";

@Injectable()
export class OrdersService {
    constructor(private readonly prisma: PrismaService) {}

    findOne(id: number): ResultAsync<Order, NotFoundError | DatabaseError> {
        return ResultAsync.fromPromise(
            this.prisma.order.findUnique({ where: { id } }),
            (thrown) => new DatabaseError(toError(thrown)),
        ).andThen((row) =>
            row ? ok(mapToOrder(row)) : err(new NotFoundError("Order", id)),
        );
    }
}

Step 4 — Write the controller, throwing instead of returning

In the controller, call the service and translate the Result to an exception or a response. Controllers are your boundary — they should throw (or use NestJS HttpException) rather than return Result:

// src/orders/orders.controller.ts
@Get(":id")
async findOne(@Param("id", ParseIntPipe) id: number) {
    const result = await this.ordersService.findOne(id);
    return result.match(
        (order) => order,
        (error) => { throw error; }, // domain error propagates to global filter
    );
}

Step 5 — Register the global exception filter

Implement and register GlobalExceptionFilter in main.ts as shown in the NestJS section.

Step 6 — Verify behavior

Use curl or the Swagger UI to request an order that does not exist. Verify you receive a 404 with your error shape, not a 500. Introduce a deliberate bug (throw an untyped object) and verify the global filter handles it gracefully and returns a 500 with no stack trace exposed to the client.

Step 7 — Add Sentry (optional but recommended)

Install @sentry/node, initialize in main.ts, and add Sentry.captureException to the global filter for 5xx responses. Trigger a 500 and verify the event appears in your Sentry dashboard with a readable stack trace.

Quick Reference

Further Reading

• TypeScript Handbook — Error Handling — The official docs do not have an “error handling” chapter, but the section on unknown in catch blocks and type narrowing is directly relevant.
• NestJS — Exception Filters — Complete coverage of filter scoping, binding, and inheritance.
• neverthrow — README and API — The canonical source for the Result/ResultAsync API, including chaining patterns and interop with Promise-based code.
• Sentry — NestJS Integration Guide — Step-by-step setup including source maps, release tracking, and performance tracing for NestJS specifically.

Configuration & Environment: appsettings.json vs. .env

For .NET engineers who know: IConfiguration, appsettings.json, appsettings.{Environment}.json, user secrets, Azure Key Vault You’ll learn: How Node.js handles configuration through environment variables and .env files, how that maps to the layered provider model you already know, and how validation with Zod replaces the type safety that IConfiguration gives you for free. Time: 10-15 min read

The .NET Way (What You Already Know)

ASP.NET Core’s configuration system is layered and well-integrated into the framework. At startup, WebApplication.CreateBuilder() assembles a configuration pipeline from multiple providers in priority order:

// What the builder does internally — you don't write this, but this is what happens:
// 1. appsettings.json                 (base config, committed to source)
// 2. appsettings.{Environment}.json   (overrides per environment)
// 3. User Secrets                     (development only, ~/.microsoft/usersecrets/)
// 4. Environment variables            (highest priority, used in production)
// 5. Command-line arguments           (highest of all)

// Consuming config is strongly typed through IConfiguration or IOptions<T>:
var builder = WebApplication.CreateBuilder(args);
var dbConnectionString = builder.Configuration.GetConnectionString("DefaultConnection");
var stripeKey = builder.Configuration["Stripe:SecretKey"];

// Or with IOptions<T> for strongly typed sections:
builder.Services.Configure<StripeOptions>(
    builder.Configuration.GetSection("Stripe")
);

Your appsettings.json has hierarchy, and IOptions<T> gives you compile-time safety:

{
  "ConnectionStrings": {
    "DefaultConnection": "Server=localhost;Database=MyApp;..."
  },
  "Stripe": {
    "SecretKey": "sk_test_...",
    "WebhookSecret": "whsec_..."
  },
  "FeatureFlags": {
    "EnableNewCheckout": false
  }
}

User secrets (dotnet user-secrets set) keep sensitive values off disk during development without polluting your committed files. Azure Key Vault handles production secrets with rotation and audit logging.

The key design property here is layering: lower-priority sources set defaults, higher-priority sources override them. Nothing from appsettings.json leaks into production unless you want it to.

The Node.js Way

Node.js has no built-in configuration system. There is no IConfiguration. The runtime gives you one thing: process.env, a flat dictionary of environment variables.

// This is the entirety of Node.js's built-in config support:
const dbUrl = process.env.DATABASE_URL;
const stripeKey = process.env.STRIPE_SECRET_KEY;

// Both are string | undefined. No hierarchy. No type safety. No validation.

That’s it. Everything else — loading from files, validation, hierarchy — is provided by libraries.

.env Files and dotenv

The .env file convention is the community’s solution for local development. You put your environment variables in a file named .env at the project root, and the dotenv library loads them into process.env at startup.

# .env — local development values, NEVER committed to source control
DATABASE_URL="postgresql://postgres:password@localhost:5432/myapp"
STRIPE_SECRET_KEY="sk_test_your_stripe_test_key_here"
STRIPE_WEBHOOK_SECRET="whsec_test_abc123"
CLERK_SECRET_KEY="sk_test_clerk_abc123"
FEATURE_FLAG_NEW_CHECKOUT="false"
NODE_ENV="development"
PORT="3000"

Notice the structure: flat key-value pairs using SCREAMING_SNAKE_CASE. The nested hierarchy you get from appsettings.json (e.g., Stripe:SecretKey) becomes a flat name with underscores.

# .env.example — committed to source control, documents required variables
# Copy this to .env and fill in your values.
DATABASE_URL=""
STRIPE_SECRET_KEY=""
STRIPE_WEBHOOK_SECRET=""
CLERK_SECRET_KEY=""
FEATURE_FLAG_NEW_CHECKOUT="false"
NODE_ENV="development"
PORT="3000"

.env.example is the Node.js equivalent of documenting your required configuration — it tells new developers what they need to fill in. It is committed. .env is not.

Install dotenv and load it as early as possible in your entry point:

// src/main.ts (NestJS) or src/index.ts
import 'dotenv/config'; // must be first import — loads .env into process.env

import { NestFactory } from '@nestjs/core';
import { AppModule } from './app.module';

async function bootstrap() {
  const app = await NestFactory.create(AppModule);
  await app.listen(process.env.PORT ?? 3000);
}
bootstrap();

The dotenv/config import style (rather than calling dotenv.config()) ensures the load happens synchronously before any other module initialization. This matters because modules may read process.env at import time.

NestJS ConfigModule: The IConfiguration Equivalent

Raw process.env is untyped and unvalidated. NestJS provides @nestjs/config to give you a structured, validated, injectable configuration service — the closest thing to IConfiguration in the NestJS world.

First, define a validation schema using Zod (our stack’s choice) or class-validator:

// src/config/env.schema.ts
import { z } from 'zod';

export const envSchema = z.object({
  // Server
  NODE_ENV: z.enum(['development', 'staging', 'production']).default('development'),
  PORT: z.coerce.number().int().positive().default(3000),

  // Database
  DATABASE_URL: z.string().url(),

  // Stripe
  STRIPE_SECRET_KEY: z.string().startsWith('sk_'),
  STRIPE_WEBHOOK_SECRET: z.string().startsWith('whsec_'),

  // Clerk
  CLERK_SECRET_KEY: z.string().startsWith('sk_'),

  // Feature flags — coerce from string to boolean
  FEATURE_FLAG_NEW_CHECKOUT: z
    .string()
    .transform((val) => val === 'true')
    .default('false'),
});

// Infer the TypeScript type from the schema
export type Env = z.infer<typeof envSchema>;

Notice z.coerce.number() for PORT: environment variables are always strings, so you need explicit coercion for non-string types. This is a fundamental difference from appsettings.json where the JSON parser handles type conversion for you.

Now register ConfigModule in your app module with validation:

// src/app.module.ts
import { Module } from '@nestjs/common';
import { ConfigModule } from '@nestjs/config';
import { envSchema } from './config/env.schema';

@Module({
  imports: [
    ConfigModule.forRoot({
      isGlobal: true,           // No need to import ConfigModule in every feature module
      envFilePath: '.env',       // Path to your .env file
      validate: (config) => {
        const result = envSchema.safeParse(config);
        if (!result.success) {
          // Log the specific validation errors and crash at startup
          console.error('Invalid environment configuration:');
          console.error(result.error.format());
          throw new Error('Configuration validation failed');
        }
        return result.data;
      },
    }),
  ],
})
export class AppModule {}

Failing at startup with a clear error message is the right behavior. It is far better to crash immediately with “STRIPE_SECRET_KEY is required” than to start successfully and fail on the first Stripe API call.

Inject ConfigService wherever you need configuration values:

// src/payments/payments.service.ts
import { Injectable } from '@nestjs/common';
import { ConfigService } from '@nestjs/config';
import type { Env } from '../config/env.schema';
import Stripe from 'stripe';

@Injectable()
export class PaymentsService {
  private readonly stripe: Stripe;

  constructor(private readonly config: ConfigService<Env, true>) {
    // The second generic argument `true` makes get() return a non-nullable type
    this.stripe = new Stripe(this.config.get('STRIPE_SECRET_KEY'));
  }

  async createPaymentIntent(amount: number): Promise<Stripe.PaymentIntent> {
    return this.stripe.paymentIntents.create({ amount, currency: 'usd' });
  }
}

The ConfigService<Env, true> generic gives you type-safe access: this.config.get('STRIPE_SECRET_KEY') returns string, not string | undefined. If you try to get a key that doesn’t exist in Env, TypeScript will complain at compile time.

Next.js Built-in Environment Handling

Next.js has its own configuration system built on top of the same .env convention, with one critical addition: the NEXT_PUBLIC_ prefix.

# .env.local (Next.js project)

# Server-only variables — never exposed to the browser
DATABASE_URL="postgresql://postgres:password@localhost:5432/myapp"
STRIPE_SECRET_KEY="sk_test_..."
CLERK_SECRET_KEY="sk_test_..."

# Client-side variables — prefixed with NEXT_PUBLIC_, bundled into the browser JS
NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY="pk_test_..."
NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY="pk_test_..."
NEXT_PUBLIC_APP_URL="http://localhost:3000"

The NEXT_PUBLIC_ prefix is Next.js’s build-time mechanism for safely exposing variables to client-side code. At build time, Next.js replaces references to process.env.NEXT_PUBLIC_* with their literal values in the browser bundle. Variables without the prefix are only available in Server Components, API routes, and middleware.

This distinction maps to a .NET concept you know: server-side values versus configuration exposed in Blazor WebAssembly or bundled JavaScript. The difference is that Next.js enforces the boundary at build time through naming convention rather than through a framework mechanism.

// app/page.tsx — React Server Component (runs on server)
// Both server and public vars are accessible here
const dbUrl = process.env.DATABASE_URL;                        // works
const stripeKey = process.env.STRIPE_SECRET_KEY;              // works
const publishableKey = process.env.NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY; // works

// components/checkout-form.tsx — Client Component ('use client')
// Only NEXT_PUBLIC_ vars are available at runtime
const publishableKey = process.env.NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY; // works
const secretKey = process.env.STRIPE_SECRET_KEY; // undefined — never reaches browser

Next.js also provides environment-specific file loading with a clear priority order:

.env.local          (highest priority, always gitignored)
.env.development    (loaded when NODE_ENV=development)
.env.production     (loaded when NODE_ENV=production)
.env                (lowest priority, can be committed for non-secret defaults)

This is the layered model you recognize from appsettings.json — base config at the bottom, environment-specific overrides above it, local overrides at the top.

For type safety in Next.js, you can use the same Zod validation pattern at the module level:

// src/lib/env.ts (Next.js project)
import { z } from 'zod';

const serverEnvSchema = z.object({
  DATABASE_URL: z.string().url(),
  STRIPE_SECRET_KEY: z.string().startsWith('sk_'),
  CLERK_SECRET_KEY: z.string(),
  NODE_ENV: z.enum(['development', 'test', 'production']).default('development'),
});

const clientEnvSchema = z.object({
  NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY: z.string().startsWith('pk_'),
  NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY: z.string().startsWith('pk_'),
  NEXT_PUBLIC_APP_URL: z.string().url(),
});

// Validate server env only when running on the server
export const serverEnv = typeof window === 'undefined'
  ? serverEnvSchema.parse(process.env)
  : ({} as z.infer<typeof serverEnvSchema>); // never accessed client-side

// Validate client env everywhere
export const clientEnv = clientEnvSchema.parse({
  NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY: process.env.NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY,
  NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY: process.env.NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY,
  NEXT_PUBLIC_APP_URL: process.env.NEXT_PUBLIC_APP_URL,
});

The typeof window === 'undefined' check guards server-only validation from running in the browser. Libraries like t3-env (from the T3 stack) provide a more ergonomic wrapper around this pattern if you find yourself repeating it.

How Render Handles Environment Variables

On Render, environment variables are set through the dashboard or the render.yaml blueprint file. There are no .env files in production — the platform injects variables directly into process.env at runtime.

# render.yaml — Infrastructure as code for Render
services:
  - type: web
    name: my-api
    env: node
    buildCommand: pnpm install && pnpm build
    startCommand: pnpm start
    envVars:
      - key: NODE_ENV
        value: production
      - key: DATABASE_URL
        fromDatabase:
          name: my-postgres
          property: connectionString
      - key: STRIPE_SECRET_KEY
        sync: false   # Must be set manually in the Render dashboard — not stored in yaml
      - key: CLERK_SECRET_KEY
        sync: false   # Same — sensitive values are never in source control

sync: false tells Render that the value is not in the yaml file and must be configured manually in the dashboard. This is the equivalent of Azure Key Vault references in your ARM templates — a pointer without the secret itself.

Render provides a feature called Secret Files for configuration that must be a file (e.g., service account JSON for Google APIs). This is less common but useful to know.

Key Differences

The biggest structural difference: .NET’s IConfiguration gives you type safety through the type system (C# classes bound to configuration sections). In Node.js, you earn that type safety at runtime through schema validation with Zod. The end result — crash on misconfiguration, typed access in code — is the same, but the mechanism is different.

Gotchas for .NET Engineers

1. process.env is always strings, and there is no automatic type conversion.

In appsettings.json, you write "EnableNewCheckout": false and IOptions<FeatureFlags> gives you a bool. In process.env, everything is a string. process.env.FEATURE_FLAG_NEW_CHECKOUT is "false" — the string — not the boolean. This bites .NET engineers constantly:

// Wrong — this will ALWAYS be truthy because non-empty strings are truthy in JS
if (process.env.FEATURE_FLAG_NEW_CHECKOUT) {
  // This runs even when the value is "false"
}

// Correct — explicit comparison or Zod coercion
if (process.env.FEATURE_FLAG_NEW_CHECKOUT === 'true') { ... }

// Best — use Zod to coerce at the boundary so the rest of your code gets a boolean
z.string().transform((val) => val === 'true')

The same applies to numbers. process.env.PORT is "3000", not 3000. process.env.PORT + 1 is "30001", not 3001.

2. dotenv does NOT override existing environment variables.

If DATABASE_URL is already set in the shell environment before your app starts, dotenv will not overwrite it with the value from your .env file. This is intentional and correct behavior for production (where real env vars should win), but it catches developers off guard locally:

# If you have DATABASE_URL set in your shell profile or CI environment:
export DATABASE_URL="postgresql://prod-server/myapp"

# And your .env has:
DATABASE_URL="postgresql://localhost/myapp_dev"

# dotenv will NOT overwrite — your app connects to prod. This is a bad day.

You can force an override with dotenv.config({ override: true }), but do this with caution and only in development contexts.

3. The .env file must never be committed, and recovery requires more than .gitignore.

In .NET, user secrets live in ~/.microsoft/usersecrets/ — outside the project directory entirely, so it’s physically impossible to commit them. .env files live in your project root, next to .gitignore. If someone adds .env to .gitignore after committing it, the file is still in git history.

# If .env was ever committed, gitignore is not enough. You must:
git filter-branch --force --index-filter \
  'git rm --cached --ignore-unmatch .env' \
  --prune-empty --tag-name-filter cat -- --all

# And immediately rotate every secret that was in that file.

Prevention is straightforward: add .env to your global gitignore (~/.gitignore_global) so it is never committed in any project:

echo ".env" >> ~/.gitignore_global
git config --global core.excludesFile ~/.gitignore_global

Many teams also add a pre-commit hook that scans for .env files or common secret patterns using secretlint or detect-secrets. This is the equivalent of what Azure DevOps’ secret scanning does automatically.

4. There is no equivalent of IOptions<T> reload on file change without extra setup.

ASP.NET Core’s IOptionsMonitor<T> reloads configuration when appsettings.json changes on disk. process.env is populated once at startup and does not re-read the .env file at runtime. If you change a .env value, you must restart the process. This is rarely a problem in practice — but if you’re building something that needs live config reloads, you’ll need to implement it explicitly.

5. NestJS ConfigModule’s validate function receives raw process.env, including all system variables.

When you call envSchema.parse(config) in the validate callback, config is the entire process.env merged with your .env file — hundreds of variables including PATH, HOME, USER, etc. Use z.object().strip() (the Zod default) rather than z.object().strict(), or your validation will fail on system variables you didn’t declare:

// This will fail — strict() rejects unknown keys, and there are many
const envSchema = z.object({ DATABASE_URL: z.string() }).strict();

// This is correct — strip() (default) ignores undeclared keys
const envSchema = z.object({ DATABASE_URL: z.string() });

6. Environment variable naming conventions collide with .NET’s hierarchy separator.

IConfiguration uses : to navigate hierarchy: Stripe:SecretKey. When environment variables override appsettings.json values in .NET, they use __ as the hierarchy separator: Stripe__SecretKey. In Node.js, there is no hierarchy — you just flatten everything: STRIPE_SECRET_KEY. This isn’t a bug, but engineers porting configuration from .NET to Node.js sometimes create confusing double-underscore variable names that don’t mean anything in the new context.

Hands-On Exercise

Convert the following appsettings.json structure to a fully validated .env + Zod setup for a NestJS application. The goal is a ConfigService that provides typed access to every value, with the application crashing at startup if any required variable is missing or malformed.

Starting point — appsettings.json:

{
  "ConnectionStrings": {
    "DefaultConnection": "Server=localhost;Database=SchoolVision;User Id=sa;Password=..."
  },
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft.AspNetCore": "Warning"
    }
  },
  "Clerk": {
    "SecretKey": "sk_test_...",
    "PublishableKey": "pk_test_..."
  },
  "Stripe": {
    "SecretKey": "sk_test_...",
    "WebhookSecret": "whsec_...",
    "PriceIds": {
      "MonthlyPlan": "price_...",
      "AnnualPlan": "price_..."
    }
  },
  "Storage": {
    "BucketName": "my-bucket",
    "Region": "us-east-1",
    "AccessKeyId": "AKIA...",
    "SecretAccessKey": "..."
  }
}

What to produce:

1. A .env.example file with all required variable names (empty values)
2. A .env file with local development values (filled in, not committed)
3. A src/config/env.schema.ts with a Zod schema validating every variable
4. The ConfigModule.forRoot() registration in AppModule using your schema
5. One example service that injects ConfigService<Env, true> and uses a typed value

Verify your work by:

• Renaming .env to .env.bak and starting the app — it should crash with a clear error listing missing variables
• Setting PORT=abc and starting the app — it should crash with “Expected number, received nan” or similar
• Running tsc --noEmit — there should be no type errors on config.get(...) calls

Migration guide — flattening the hierarchy:

# appsettings.json key              → .env variable name
ConnectionStrings:DefaultConnection → DATABASE_URL
Clerk:SecretKey                     → CLERK_SECRET_KEY
Clerk:PublishableKey                → NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY  (if Next.js)
Stripe:SecretKey                    → STRIPE_SECRET_KEY
Stripe:WebhookSecret                → STRIPE_WEBHOOK_SECRET
Stripe:PriceIds:MonthlyPlan         → STRIPE_PRICE_MONTHLY
Stripe:PriceIds:AnnualPlan          → STRIPE_PRICE_ANNUAL
Storage:BucketName                  → S3_BUCKET_NAME
Storage:Region                      → AWS_REGION
Storage:AccessKeyId                 → AWS_ACCESS_KEY_ID
Storage:SecretAccessKey             → AWS_SECRET_ACCESS_KEY
Logging:LogLevel:Default            → LOG_LEVEL  (default: "info")

Quick Reference

dotenv and NestJS ConfigModule commands:

# Install dependencies
pnpm add @nestjs/config dotenv zod

# Verify a variable is loaded
node -e "require('dotenv').config(); console.log(process.env.DATABASE_URL)"

# Check which .env file Next.js is loading
NEXT_PUBLIC_DEBUG=1 pnpm dev

# Audit your .env.example vs .env for missing keys
diff <(grep -v '^#' .env.example | cut -d= -f1 | sort) \
     <(grep -v '^#' .env | cut -d= -f1 | sort)

Further Reading

• NestJS Configuration documentation — the official guide for ConfigModule, ConfigService, and custom configuration namespaces
• Next.js Environment Variables — covers .env file priority, NEXT_PUBLIC_ prefix, and runtime vs. build-time availability
• Zod documentation — the schema library used throughout this stack for validation; the “coercion” section is particularly relevant for environment variable parsing
• t3-env — a thin wrapper around Zod for Next.js and server-side environment validation; worth reading as a reference implementation of the patterns in this article

Testing Philosophy: xUnit/NUnit vs. Jest/Vitest

For .NET engineers who know: xUnit, NUnit, Moq, test projects, [Fact], [Theory], FluentAssertions You’ll learn: How JS/TS testing maps to your existing mental model — and the one place it genuinely has no equivalent Time: 15-20 min read

The .NET Way (What You Already Know)

In .NET, tests live in separate projects. Your OrderService in MyApp.Core gets a companion MyApp.Core.Tests project, with a <ProjectReference> pointing back to production code. The test runner discovers tests through attributes: [Fact] marks a single test, [Theory] with [InlineData] parameterizes it. Setup and teardown are handled via the constructor (runs before each test) and IDisposable.Dispose() (runs after). For shared setup across a class, IClassFixture<T> gives you a single instance; for shared state across multiple classes, ICollectionFixture<T> coordinates it.

Mocking is a separate library concern. Moq intercepts interfaces, letting you stub return values with Setup() and verify call behavior with Verify(). The test project installs Moq via NuGet; production code never touches it.

// MyApp.Core.Tests/OrderServiceTests.cs
public class OrderServiceTests : IDisposable
{
    private readonly Mock<IOrderRepository> _mockRepo;
    private readonly Mock<IEmailService> _emailService;
    private readonly OrderService _sut;

    public OrderServiceTests()
    {
        _mockRepo = new Mock<IOrderRepository>();
        _emailService = new Mock<IEmailService>();
        _sut = new OrderService(_mockRepo.Object, _emailService.Object);
    }

    [Fact]
    public async Task PlaceOrder_ValidOrder_ReturnsOrderId()
    {
        // Arrange
        var order = new Order { ProductId = 1, Quantity = 2 };
        _mockRepo.Setup(r => r.SaveAsync(order)).ReturnsAsync(42);

        // Act
        var result = await _sut.PlaceOrderAsync(order);

        // Assert
        Assert.Equal(42, result);
        _emailService.Verify(e => e.SendConfirmationAsync(42), Times.Once);
    }

    [Theory]
    [InlineData(0)]
    [InlineData(-1)]
    public async Task PlaceOrder_InvalidQuantity_Throws(int quantity)
    {
        var order = new Order { ProductId = 1, Quantity = quantity };
        await Assert.ThrowsAsync<ArgumentException>(() => _sut.PlaceOrderAsync(order));
    }

    public void Dispose()
    {
        // cleanup if needed
    }
}

Coverage is measured by dotnet test --collect:"XPlat Code Coverage", reported as Cobertura XML, and visualized in Azure DevOps or via ReportGenerator. The CI pipeline is explicit: build the test project, run it, fail if coverage drops below threshold.

The Vitest Way

Test File Location: No Separate Project

The first thing to internalize: there is no test project. Tests live alongside the code they test.

src/
  services/
    order.service.ts          ← production code
    order.service.test.ts     ← tests, right here
    order.service.spec.ts     ← also valid, same thing

Both *.test.ts and *.spec.ts are valid conventions — spec comes from the BDD world, test is more common in utility code. Pick one per project and be consistent. We use *.test.ts for unit tests and *.spec.ts for integration tests to make them visually distinct in large codebases.

Vitest finds test files by scanning for these patterns automatically — no <ProjectReference>, no build target, no separate csproj. The tradeoff: test code is closer to production code (faster feedback loop, easier navigation), but you need your build process to exclude test files from production bundles. Vitest handles this; the TypeScript compiler is typically configured to ignore *.test.ts files in tsconfig.app.json while tsconfig.test.json includes them.

The describe/it/expect API

Where xUnit uses class structure to group tests, Vitest uses describe blocks. Where [Fact] marks a test, it (or test — they’re identical) marks one. Where xUnit has assertion methods on Assert.*, Vitest chains expectations from expect().

One note on toBe vs. toEqual: toBe uses Object.is — reference equality, like ReferenceEquals() in C#. toEqual does a deep structural comparison, like Assert.Equivalent() in xUnit or Should().BeEquivalentTo() in FluentAssertions. You will almost always want toEqual for objects, and toBe for primitives.

Setup and Teardown

Constructor/Dispose maps directly to beforeEach/afterEach. The scoping works the same way: beforeEach inside a describe block runs before each test in that block only.

// setup/teardown mapping
describe("OrderService", () => {
  let sut: OrderService;
  let mockRepo: MockedObject<OrderRepository>;

  beforeEach(() => {
    // runs before each test — same as xUnit constructor
    mockRepo = createMockRepo();
    sut = new OrderService(mockRepo);
  });

  afterEach(() => {
    // runs after each test — same as Dispose()
    vi.restoreAllMocks();
  });

  beforeAll(() => {
    // runs once before all tests in this describe — same as IClassFixture
  });

  afterAll(() => {
    // runs once after all tests in this describe
  });
});

Mocking: Built-In, No Separate Library

Moq requires an interface, a mock object, and a setup call per method. Vitest’s mocking is built into the framework and works differently: you mock at the module level, not the interface level.

vi.fn() creates a mock function (equivalent to Mock<IService>().Setup(s => s.Method())):

const mockSave = vi.fn().mockResolvedValue(42);

vi.spyOn() wraps an existing method on an object, letting you track calls without replacing the implementation (unless you want to). Equivalent to Moq’s CallBase behavior:

const spy = vi.spyOn(emailService, 'sendConfirmation').mockResolvedValue(undefined);

vi.mock() replaces an entire module — no equivalent in the .NET world because .NET doesn’t have a module system at that level. More on this in the Gotchas section.

Verifying calls uses the mock’s own properties rather than a separate Verify() call:

// Moq: _emailService.Verify(e => e.SendConfirmationAsync(42), Times.Once);
expect(spy).toHaveBeenCalledTimes(1);
expect(spy).toHaveBeenCalledWith(42);

// Or, checking the most recent call's arguments
expect(spy).toHaveBeenLastCalledWith(42);

Parameterized Tests: it.each

[Theory] + [InlineData] maps to it.each. Two syntaxes:

// Array of arrays — each inner array is one test case
it.each([
  [0, "zero"],
  [-1, "negative"],
  [-999, "large negative"],
])("rejects quantity %i (%s)", async (quantity, _description) => {
  await expect(sut.placeOrder({ productId: 1, quantity }))
    .rejects.toThrow(ValidationError);
});

// Tagged template literal — more readable for named params
it.each`
  quantity | description
  ${0}     | ${"zero"}
  ${-1}    | ${"negative"}
`("rejects $description quantity", async ({ quantity }) => {
  await expect(sut.placeOrder({ productId: 1, quantity }))
    .rejects.toThrow(ValidationError);
});

Side-by-Side: Testing the Same Service

Here is the same OrderService tested in both languages, demonstrating every concept above in parallel.

The service under test

// C# — OrderService.cs
public class OrderService
{
    private readonly IOrderRepository _repository;
    private readonly IEmailService _emailService;

    public OrderService(IOrderRepository repository, IEmailService emailService)
    {
        _repository = repository;
        _emailService = emailService;
    }

    public async Task<int> PlaceOrderAsync(Order order)
    {
        if (order.Quantity <= 0)
            throw new ArgumentException("Quantity must be positive", nameof(order));

        var orderId = await _repository.SaveAsync(order);
        await _emailService.SendConfirmationAsync(orderId);
        return orderId;
    }

    public async Task<IReadOnlyList<Order>> GetOrdersAsync(int userId)
    {
        return await _repository.GetByUserAsync(userId);
    }
}

// TypeScript — order.service.ts
export class OrderService {
  constructor(
    private readonly repository: OrderRepository,
    private readonly emailService: EmailService,
  ) {}

  async placeOrder(order: Order): Promise<number> {
    if (order.quantity <= 0) {
      throw new ValidationError("Quantity must be positive");
    }

    const orderId = await this.repository.save(order);
    await this.emailService.sendConfirmation(orderId);
    return orderId;
  }

  async getOrders(userId: number): Promise<Order[]> {
    return this.repository.getByUser(userId);
  }
}

The tests

// C# — OrderServiceTests.cs (xUnit + Moq)
public class OrderServiceTests : IDisposable
{
    private readonly Mock<IOrderRepository> _mockRepo;
    private readonly Mock<IEmailService> _mockEmail;
    private readonly OrderService _sut;

    public OrderServiceTests()
    {
        _mockRepo = new Mock<IOrderRepository>();
        _mockEmail = new Mock<IEmailService>();
        _sut = new OrderService(_mockRepo.Object, _mockEmail.Object);
    }

    // --- PlaceOrder tests ---

    [Fact]
    public async Task PlaceOrder_ValidOrder_SavesAndSendsEmail()
    {
        // Arrange
        var order = new Order { ProductId = 1, Quantity = 3 };
        _mockRepo.Setup(r => r.SaveAsync(order)).ReturnsAsync(99);
        _mockEmail.Setup(e => e.SendConfirmationAsync(99)).Returns(Task.CompletedTask);

        // Act
        var result = await _sut.PlaceOrderAsync(order);

        // Assert
        Assert.Equal(99, result);
        _mockEmail.Verify(e => e.SendConfirmationAsync(99), Times.Once);
    }

    [Theory]
    [InlineData(0)]
    [InlineData(-1)]
    [InlineData(-100)]
    public async Task PlaceOrder_InvalidQuantity_ThrowsArgumentException(int quantity)
    {
        var order = new Order { ProductId = 1, Quantity = quantity };

        var ex = await Assert.ThrowsAsync<ArgumentException>(
            () => _sut.PlaceOrderAsync(order)
        );
        Assert.Contains("Quantity", ex.Message);

        // Verify nothing was saved
        _mockRepo.Verify(r => r.SaveAsync(It.IsAny<Order>()), Times.Never);
    }

    // --- GetOrders tests ---

    [Fact]
    public async Task GetOrders_ReturnsUserOrders()
    {
        // Arrange
        var expected = new List<Order>
        {
            new() { Id = 1, UserId = 5 },
            new() { Id = 2, UserId = 5 },
        };
        _mockRepo.Setup(r => r.GetByUserAsync(5)).ReturnsAsync(expected);

        // Act
        var result = await _sut.GetOrdersAsync(5);

        // Assert
        Assert.Equal(2, result.Count);
        Assert.All(result, o => Assert.Equal(5, o.UserId));
    }

    public void Dispose()
    {
        // nothing to dispose in this test, but the pattern is here
    }
}

// TypeScript — order.service.test.ts (Vitest)
import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
import { OrderService } from "./order.service";
import { ValidationError } from "../errors";
import type { OrderRepository } from "./order.repository";
import type { EmailService } from "../email/email.service";

describe("OrderService", () => {
  let sut: OrderService;
  let mockRepo: { save: ReturnType<typeof vi.fn>; getByUser: ReturnType<typeof vi.fn> };
  let mockEmail: { sendConfirmation: ReturnType<typeof vi.fn> };

  beforeEach(() => {
    mockRepo = {
      save: vi.fn(),
      getByUser: vi.fn(),
    };
    mockEmail = {
      sendConfirmation: vi.fn(),
    };
    sut = new OrderService(
      mockRepo as unknown as OrderRepository,
      mockEmail as unknown as EmailService,
    );
  });

  afterEach(() => {
    vi.restoreAllMocks();
  });

  // --- placeOrder tests ---

  describe("placeOrder", () => {
    it("saves the order and sends a confirmation email", async () => {
      // Arrange
      const order = { productId: 1, quantity: 3 };
      mockRepo.save.mockResolvedValue(99);
      mockEmail.sendConfirmation.mockResolvedValue(undefined);

      // Act
      const result = await sut.placeOrder(order);

      // Assert
      expect(result).toBe(99);
      expect(mockEmail.sendConfirmation).toHaveBeenCalledTimes(1);
      expect(mockEmail.sendConfirmation).toHaveBeenCalledWith(99);
    });

    it.each([
      [0],
      [-1],
      [-100],
    ])("throws ValidationError for quantity %i", async (quantity) => {
      const order = { productId: 1, quantity };

      await expect(sut.placeOrder(order)).rejects.toThrow(ValidationError);
      await expect(sut.placeOrder(order)).rejects.toThrow("Quantity must be positive");

      // Verify nothing was saved
      expect(mockRepo.save).not.toHaveBeenCalled();
    });
  });

  // --- getOrders tests ---

  describe("getOrders", () => {
    it("returns orders for the given user", async () => {
      // Arrange
      const expected = [
        { id: 1, userId: 5 },
        { id: 2, userId: 5 },
      ];
      mockRepo.getByUser.mockResolvedValue(expected);

      // Act
      const result = await sut.getOrders(5);

      // Assert
      expect(result).toHaveLength(2);
      expect(result.every((o) => o.userId === 5)).toBe(true);
    });
  });
});

Snapshot Testing (No .NET Equivalent)

Snapshot testing is the one Vitest feature with no .NET analog. It serializes the output of a function — usually a rendered UI component, but any serializable value works — to a .snap file on first run. Subsequent runs compare against the saved snapshot and fail if anything changed.

// First run: creates __snapshots__/api-response.test.ts.snap
it("returns the expected order shape", async () => {
  const result = await sut.placeOrder({ productId: 1, quantity: 2 });
  expect(result).toMatchSnapshot();
});

// If you change the return shape, the test fails with a diff.
// To accept the new output as correct: vitest --update-snapshots

Snapshots are most valuable for:

• UI component output (rendered HTML/JSX)
• API response shapes you want to detect accidental changes to
• Complex serialized structures where writing toEqual assertions would be tedious

The downside: snapshots can become a rubber stamp that developers update without reviewing. Treat a snapshot update PR the same way you’d treat a schema migration — verify the diff is intentional.

Test Configuration

In .NET, xunit.runner.json configures test runner behavior and you edit *.csproj properties for parallelism. In Vitest, configuration lives in vitest.config.ts (or inline in vite.config.ts):

// vitest.config.ts
import { defineConfig } from "vitest/config";
import tsconfigPaths from "vite-tsconfig-paths";

export default defineConfig({
  plugins: [tsconfigPaths()],  // resolves path aliases from tsconfig
  test: {
    globals: true,             // removes need to import describe/it/expect in every file
    environment: "node",       // or "jsdom" for React component tests
    coverage: {
      provider: "v8",          // or "istanbul"
      reporter: ["text", "lcov", "html"],
      thresholds: {
        lines: 80,
        branches: 75,
        functions: 80,
        statements: 80,
      },
      exclude: [
        "node_modules",
        "**/*.test.ts",
        "**/*.spec.ts",
        "**/index.ts",         // barrel files
      ],
    },
    setupFiles: ["./src/test/setup.ts"],  // global test setup — like TestInitialize
  },
});

The globals: true option is worth highlighting. Without it, you must import describe, it, expect, and vi at the top of every test file — the same boilerplate every time. With globals: true, they’re available everywhere, matching how Jest traditionally works. Our projects enable this; you’ll see test files without imports and that is intentional.

Coverage Reporting

# Run tests with coverage
pnpm vitest run --coverage

# Output: text summary in terminal + HTML report in ./coverage/

 % Coverage report from v8
 File               | % Stmts | % Branch | % Funcs | % Lines
--------------------|---------|----------|---------|--------
 order.service.ts   |   94.12 |    83.33 |   100.0 |   94.12

Coverage integrates with SonarCloud via the LCOV reporter (see Article 7.2) and with GitHub Actions to post coverage summaries on PRs. The HTML report at ./coverage/index.html shows line-by-line coverage with branch indicators — equivalent to Visual Studio’s test coverage highlighting.

Our Testing Strategy

Three tiers, each with a different tool:

Unit Tests — Vitest

Tests for individual services, utilities, and pure functions. Dependencies are mocked. These run in milliseconds and should make up the majority of your test suite.

pnpm vitest run          # run once
pnpm vitest              # watch mode — runs affected tests on file change
pnpm vitest --coverage   # with coverage

Integration Tests — Vitest + Supertest

Tests for NestJS API endpoints — the real request pipeline (middleware, guards, pipes, serialization) against a real database running in Docker. Supertest makes HTTP requests to your NestJS application without starting a network listener.

// order.integration.spec.ts
import { Test } from "@nestjs/testing";
import { INestApplication } from "@nestjs/common";
import request from "supertest";
import { AppModule } from "../app.module";

describe("Order API (integration)", () => {
  let app: INestApplication;

  beforeAll(async () => {
    const module = await Test.createTestingModule({
      imports: [AppModule],
    }).compile();

    app = module.createNestApplication();
    await app.init();
  });

  afterAll(async () => {
    await app.close();
  });

  it("POST /orders creates an order", async () => {
    const response = await request(app.getHttpServer())
      .post("/orders")
      .send({ productId: 1, quantity: 2 })
      .set("Authorization", `Bearer ${testToken}`)
      .expect(201);

    expect(response.body).toMatchObject({
      id: expect.any(Number),
      productId: 1,
      quantity: 2,
    });
  });
});

This is the JS equivalent of WebApplicationFactory<Program> in ASP.NET integration tests — same concept, slightly different wiring. See Article 5.7 for database setup with Testcontainers.

E2E Tests — Playwright

Tests for complete user flows through the browser. Playwright drives Chromium, Firefox, or WebKit, and its API reads like a well-typed Selenium without the friction.

// tests/e2e/place-order.spec.ts
import { test, expect } from "@playwright/test";

test("user can place an order", async ({ page }) => {
  await page.goto("/login");
  await page.fill('[name="email"]', "test@example.com");
  await page.fill('[name="password"]', "secret");
  await page.click('[type="submit"]');

  await page.goto("/products/1");
  await page.fill('[name="quantity"]', "2");
  await page.click("text=Add to Cart");
  await page.click("text=Checkout");

  await expect(page.locator(".order-confirmation")).toBeVisible();
  await expect(page.locator(".order-id")).toContainText(/ORDER-\d+/);
});

pnpm playwright test            # run all E2E tests
pnpm playwright test --ui       # interactive UI mode (closest to Test Explorer)
pnpm playwright test --debug    # step-through debugging with browser visible

Key Differences

Gotchas for .NET Engineers

1. vi.mock() hoists to the top of the file — and it’s surprising

vi.mock() calls are automatically moved to the top of the file by Vitest, before any imports. This means you cannot use variables defined in your test file inside a vi.mock() factory function — they haven’t been initialized yet.

// THIS WILL NOT WORK as expected
const mockSave = vi.fn().mockResolvedValue(42);  // defined here

vi.mock("./order.repository", () => ({
  OrderRepository: vi.fn().mockImplementation(() => ({
    save: mockSave,  // ERROR: mockSave is undefined at hoist time
  })),
}));

// CORRECT: use vi.fn() inside the factory, configure in beforeEach
vi.mock("./order.repository", () => ({
  OrderRepository: vi.fn().mockImplementation(() => ({
    save: vi.fn(),
  })),
}));

describe("OrderService", () => {
  beforeEach(() => {
    // Access the mocked module to configure behavior per test
    const { OrderRepository } = await import("./order.repository");
    vi.mocked(OrderRepository).mockImplementation(() => ({
      save: vi.fn().mockResolvedValue(42),
    }));
  });
});

In practice, you often avoid vi.mock() entirely for services you control by injecting mock objects directly via the constructor — the same pattern as Moq. vi.mock() is most useful for third-party modules and Node.js built-ins you can’t inject.

2. Forgetting await on async expect — the test passes when it should fail

This is the single most common Vitest mistake for engineers coming from any background:

// WRONG: the assertion is a Promise, never awaited — test passes regardless
it("throws on invalid input", () => {
  expect(sut.placeOrder({ quantity: 0 })).rejects.toThrow();
  //                                      ^ no await — this Promise is ignored
});

// CORRECT
it("throws on invalid input", async () => {
  await expect(sut.placeOrder({ quantity: 0 })).rejects.toThrow();
});

In .NET, Assert.ThrowsAsync<T>() forces you to await it because it returns a Task<T>. Vitest’s expect(promise).rejects.toThrow() is just a fluent chain that returns a Promise — and if you forget await, Vitest sees no failed assertion, marks the test green, and moves on. Always await assertions against Promises.

3. Module mocking scope is file-wide, not test-wide

When you call vi.mock(), it affects every test in the file. If you need different behavior for different tests, configure the mock in beforeEach rather than at the module level, and use vi.resetAllMocks() or vi.restoreAllMocks() in afterEach to clean up between tests.

A common pattern for different per-test behavior:

vi.mock("./email.service");

import { EmailService } from "./email.service";
const MockedEmailService = vi.mocked(EmailService);

describe("OrderService", () => {
  afterEach(() => {
    vi.clearAllMocks();  // clears call history, keeps implementations
  });

  it("sends email on success", async () => {
    MockedEmailService.prototype.sendConfirmation.mockResolvedValue(undefined);
    // ...
  });

  it("still saves order if email fails", async () => {
    MockedEmailService.prototype.sendConfirmation.mockRejectedValue(new Error("SMTP down"));
    // ...
  });
});

4. toBe vs. toEqual is not like == vs. Equals()

Coming from C#, you might assume toBe is value equality and toEqual is reference equality — the opposite is true. toBe uses Object.is(), which is reference equality for objects. toEqual does a deep structural comparison.

const a = { id: 1 };
const b = { id: 1 };

expect(a).toBe(b);     // FAILS — different references
expect(a).toEqual(b);  // PASSES — same shape

expect(1).toBe(1);     // PASSES — primitives compared by value

For asserting on returned objects, almost always use toEqual or toMatchObject (partial match — like BeEquivalentTo with Excluding()).

5. Test isolation requires manual mock cleanup — it is not automatic

In .NET, each test class instantiation gives you fresh mock objects (because [Fact] creates a new class instance). In Vitest, mock state accumulates across tests unless you reset it. The three reset methods have different scopes:

vi.clearAllMocks();    // clears call history (.mock.calls, .mock.results)
                       // does NOT reset implementations set with mockReturnValue()

vi.resetAllMocks();    // clears call history AND removes implementations
                       // mocks return undefined after this

vi.restoreAllMocks();  // only applies to vi.spyOn() mocks
                       // restores original implementation

Convention: put vi.clearAllMocks() in afterEach in your global setup file (vitest.config.ts → setupFiles), and only call vi.resetAllMocks() or vi.restoreAllMocks() when you explicitly need to change implementation mid-suite.

Hands-On Exercise

You have a PricingService that calculates order totals. It depends on a ProductRepository to fetch product prices and a DiscountService to apply promotions.

1. Write the PricingService in src/pricing/pricing.service.ts with a calculateTotal(items: OrderItem[]): Promise<number> method that:

   • Fetches each product’s price via ProductRepository.getPrice(productId: number)
   • Applies discounts via DiscountService.getDiscount(userId: number): Promise<number> (returns a percentage 0-100)
   • Returns the discounted total
   • Throws ValidationError if any items array is empty

2. Write the tests in src/pricing/pricing.service.test.ts covering:

   • Happy path: correct total with discount applied
   • Zero discount: total equals sum of prices
   • Empty items array: throws ValidationError
   • Parameterized: 0%, 10%, 50%, 100% discount all produce correct totals
   • Repository or discount service failure: error propagates correctly

3. Run with pnpm vitest pricing.service (Vitest matches by filename fragment)

4. Add coverage reporting and verify the service hits 90%+ line coverage

5. Bonus: add one snapshot test for a fixed input that captures the exact output shape

Quick Reference

.NET → Vitest concept map

Further Reading

• Vitest Documentation — the canonical reference; it is terse and accurate
• Playwright Documentation — E2E testing setup and API reference
• NestJS Testing — TestingModule, Supertest integration, and mocking providers in the DI container
• Vitest Mocking Guide — the definitive reference for vi.mock(), vi.fn(), vi.spyOn(), and their edge cases

TypeScript for C# Engineers: The Type System Compared

For .NET engineers who know: C# generics, interfaces, nullable reference types, and the nominal type system You’ll learn: How TypeScript’s structural type system differs from C#’s nominal one, and how to apply the discipline required to make it safe Time: 15-20 min read

The .NET Way (What You Already Know)

C#’s type system is nominal. The type’s name is its identity. If you define two classes with identical properties, they are not interchangeable — the compiler enforces the distinction.

public class Dog
{
    public string Name { get; set; }
    public int Age { get; set; }
}

public class Cat
{
    public string Name { get; set; }
    public int Age { get; set; }
}

// This does not compile. Dog and Cat are different types,
// regardless of their identical shape.
Dog myPet = new Cat { Name = "Whiskers", Age = 3 }; // CS0029

This is the guarantee that makes C# refactoring reliable. When you rename a type, the compiler finds every violation. The type system tracks what something is, not merely what it looks like.

Nullable reference types (introduced in C# 8.0, enforced by default from C# 10.0 with <Nullable>enable</Nullable>) extend this guarantee: the compiler can prove at compile time whether a variable can be null, and it forces you to handle that case explicitly.

string name = null;           // CS8600: Converting null literal to non-nullable type
string? nullable = null;      // Fine — you've declared the intent
int length = nullable.Length; // CS8602: Dereference of possibly null reference
int safeLength = nullable?.Length ?? 0; // Correct

Keep this mental model in mind. TypeScript’s type system solves the same problems but makes different trade-offs, and several of them will surprise you.

The TypeScript Way

Structural Typing: Shape Over Name

TypeScript’s type system is structural. Compatibility is determined by shape, not by the type’s declared name.

// TypeScript
interface Dog {
  name: string;
  age: number;
}

interface Cat {
  name: string;
  age: number;
}

// This is valid TypeScript. Dog and Cat have the same shape.
const myDog: Dog = { name: "Rex", age: 4 };
const myCat: Cat = myDog; // No error. Shape matches.

Side by side:

Structural typing is powerful — it lets you model duck-typed JS naturally. But it means the compiler will accept assignments you might not intend. Discipline fills that gap.

Primitive Types: The Mapping

C# has a rich set of numeric types. TypeScript has one: number. This is JavaScript’s IEEE 754 double-precision float underneath.

The number collapse is the biggest practical difference. If your C# code distinguishes between int counts and decimal currency amounts, TypeScript won’t enforce that for you. You’ll need either branded types (see Article 2.6) or Zod schemas (see Article 2.3) to enforce the distinction at runtime.

// TypeScript: all of these are `number`
const count: number = 42;
const price: number = 9.99;
const ratio: number = 0.001;

// C# equivalent:
// int count = 42;
// decimal price = 9.99m;
// double ratio = 0.001;

interface vs. type: The Opinionated Answer

TypeScript has two constructs for defining shapes: interface and type. This causes more unnecessary debate than it deserves. Here is the practical guidance:

Use interface for:

• Object shapes (API responses, DTOs, component props, domain models)
• Anything that other interfaces or classes might extend or implement

Use type for:

• Union types (type Status = 'active' | 'inactive')
• Intersection types (type AdminUser = User & Admin)
• Mapped and conditional types
• Aliases for primitives or tuples

The most important distinction: interfaces are open (they can be re-declared and merged across modules). Types are closed (one declaration, no merging). In practice, this means library authors prefer interfaces because consumers can extend them; application code can use either.

// Interface — open, extensible, preferred for object shapes
interface User {
  id: string;
  email: string;
}

// This declaration merges with the one above — works with interface, fails with type
interface User {
  displayName: string;
}
// Result: User now has id, email, and displayName

// Type alias — closed, preferred for unions and computed shapes
type Status = 'pending' | 'active' | 'suspended';
type NullableString = string | null;
type UserOrAdmin = User | AdminUser;

// Extending an interface (like C# interface inheritance)
interface AdminUser extends User {
  role: 'admin';
  permissions: string[];
}

C# comparison:

// C# interface — also used for object shapes and contracts
public interface IUser
{
    string Id { get; }
    string Email { get; }
}

// C# doesn't have union types — you'd use inheritance, discriminated unions,
// or a OneOf library to approximate this.

Classes in TypeScript vs. C#

TypeScript classes are syntactic sugar over JavaScript’s prototype chain. They look like C# classes but behave differently in important ways.

// TypeScript
class UserService {
  private readonly baseUrl: string;

  constructor(baseUrl: string) {
    this.baseUrl = baseUrl;
  }

  // Shorthand: parameter properties (no C# equivalent — saves the assignment)
  // constructor(private readonly baseUrl: string) {}

  async getUser(id: string): Promise<User> {
    const response = await fetch(`${this.baseUrl}/users/${id}`);
    return response.json() as User;
  }
}

// C#
public class UserService
{
    private readonly string _baseUrl;

    public UserService(string baseUrl)
    {
        _baseUrl = baseUrl;
    }

    public async Task<User> GetUser(string id)
    {
        using var client = new HttpClient();
        var response = await client.GetFromJsonAsync<User>($"{_baseUrl}/users/{id}");
        return response!;
    }
}

Access modifiers in TypeScript:

TypeScript also has # (ES private fields), which are enforced at runtime:

class Counter {
  #count = 0;           // True private — inaccessible at runtime too
  private legacy = 0;   // Compile-time only — accessible at runtime via any

  increment() {
    this.#count++;
    this.legacy++;
  }
}

const c = new Counter();
// (c as any).legacy     // Works at runtime — TypeScript's `private` is erased
// (c as any)['#count']  // Does NOT work — # fields are truly private

Parameter properties are a TypeScript shorthand worth knowing. Instead of declaring a field, declaring a constructor parameter, and assigning one to the other (the C# way), TypeScript lets you do it in one place:

class ProductService {
  // This single line: declares the field AND assigns it from the constructor parameter
  constructor(
    private readonly db: Database,
    private readonly cache: CacheService
  ) {}
}

Generics: Familiar Territory

Generics in TypeScript map closely to C# generics in syntax and intent. The differences are mostly about what constraints you can express.

// TypeScript generic function
function first<T>(items: T[]): T | undefined {
  return items[0];
}

// Generic interface
interface Repository<T> {
  findById(id: string): Promise<T | null>;
  save(entity: T): Promise<T>;
  delete(id: string): Promise<void>;
}

// Generic with constraint
function getProperty<T, K extends keyof T>(obj: T, key: K): T[K] {
  return obj[key];
}

// Constraint: T must have an `id` property
interface HasId {
  id: string;
}

function findById<T extends HasId>(items: T[], id: string): T | undefined {
  return items.find(item => item.id === id);
}

// C# generics for comparison
T? First<T>(IEnumerable<T> items) => items.FirstOrDefault();

interface IRepository<T>
{
    Task<T?> FindById(string id);
    Task<T> Save(T entity);
    Task Delete(string id);
}

// Constraint: T must implement IHasId
T? FindById<T>(IEnumerable<T> items, string id) where T : IHasId
{
    return items.FirstOrDefault(x => x.Id == id);
}

Where TypeScript generics diverge from C#:

• TypeScript uses extends for constraints (not where)
• keyof T is a TypeScript-only concept — it produces a union of string literal types representing the property names of T
• TypeScript’s generics are purely structural: T extends HasId means “T’s shape must include the id: string property,” not “T must be declared as implementing HasId”
• No runtime generic type information (unlike C# where typeof(T) and reflection work at runtime)

Enums: The Trap

TypeScript has enums, and they look familiar to C# engineers. Resist the temptation to use them freely. TypeScript enums have several design problems.

The problem with numeric enums:

enum Direction {
  North,  // 0
  South,  // 1
  East,   // 2
  West    // 3
}

// These are all valid TypeScript — no error:
const d: Direction = 100;  // Any number is assignable to a numeric enum
const d2: Direction = 0 | 1; // Bitwise ops produce numbers, all accepted

The problem with string enums:

enum Status {
  Active = 'ACTIVE',
  Inactive = 'INACTIVE',
}

// String enums are nominal — they don't accept plain strings:
const s: Status = 'ACTIVE'; // Error: Type '"ACTIVE"' is not assignable to type 'Status'
// You're forced to use Status.Active everywhere — adds friction, no real safety

The compiled output problem:

TypeScript is supposed to be a type layer over JavaScript — types are erased at compile time. Enums break this rule: they compile to a JavaScript object (an IIFE), which means your runtime bundle includes enum code even though TypeScript types don’t exist at runtime. const enum avoids this by inlining values, but it has its own issues with module boundaries.

What to use instead:

// Option 1: const object + typeof — the recommended pattern
const Direction = {
  North: 'north',
  South: 'south',
  East: 'east',
  West: 'west',
} as const;

type Direction = typeof Direction[keyof typeof Direction];
// Direction is now: 'north' | 'south' | 'east' | 'west'

function move(dir: Direction) { /* ... */ }
move('north');           // Works
move(Direction.North);   // Works
move('diagonal');        // Error — not in the union

// Option 2: string union literal types — the simplest approach
type Status = 'active' | 'inactive' | 'suspended';

// Option 3: When you need an enum-like object with iteration capability
const HttpStatus = {
  Ok: 200,
  Created: 201,
  BadRequest: 400,
  NotFound: 404,
  InternalServerError: 500,
} as const;

type HttpStatus = typeof HttpStatus[keyof typeof HttpStatus];

The as const assertion is the key: it tells TypeScript to infer the narrowest possible types (literal types like 'north', not string) and makes all properties readonly.

null and undefined: Two Nothings

C# has one null. TypeScript has two: null and undefined. They are distinct types with distinct semantics.

• null — an intentional absence of a value. Explicitly assigned.
• undefined — an uninitialized value. The default state in JavaScript when a variable is declared but not assigned, when an object property doesn’t exist, or when a function returns without a value.

// Both are distinct
let a: string | null = null;       // Intentional null
let b: string | undefined;         // Uninitialized — value is `undefined`
let c: string | null | undefined;  // Could be either

// Optional properties use undefined, not null
interface Config {
  baseUrl: string;
  timeout?: number;    // Same as: timeout: number | undefined
  apiKey?: string;
}

// Optional function parameters
function connect(url: string, timeout?: number): void {
  const t = timeout ?? 5000; // Nullish coalescing — same as C# ??
}

connect('https://api.example.com');         // timeout is undefined
connect('https://api.example.com', 3000);   // timeout is 3000

C# comparison:

// C# — one null to rule them all
string? name = null;
int? timeout = null;

// C# doesn't distinguish "intentional null" from "not provided"
// Optional parameters use default values instead
void Connect(string url, int timeout = 5000) { }

The strict null checks flag (strictNullChecks) is what makes TypeScript’s type system safe for nullability. With it enabled, null and undefined are not assignable to other types unless you explicitly declare them. Without it, TypeScript’s nullability is essentially C# without nullable reference types — a false sense of security.

Always enable strictNullChecks. It’s included in strict: true (more on that below).

Non-null assertion operator:

// The ! operator — tells TypeScript "I know this isn't null"
// Equivalent to C#'s null-forgiving operator (!) from C# 8.0
const input = document.getElementById('email')!; // Tell TS: this exists
const value = input.value; // No null error

// Use sparingly — it's lying to the type system if you're wrong

any, unknown, and never

These three types have no clean C# equivalents and are worth understanding precisely.

any — the type system opt-out:

let x: any = 'hello';
x = 42;           // Fine
x = true;         // Fine
x.nonExistent();  // No error — you've turned off type checking for x
const y: string = x; // Fine — any is assignable to anything

// Avoid any. It's contagious — it spreads through your codebase.
// The only legitimate uses: interfacing with untyped JS libraries
// before types are available, or rapid prototyping.

unknown — the safe alternative to any:

let x: unknown = getExternalData();

// Unlike any, you can't use unknown without narrowing first:
x.toUpperCase();         // Error: Object is of type 'unknown'
const y: string = x;    // Error: Type 'unknown' not assignable to 'string'

// You must narrow it first:
if (typeof x === 'string') {
  x.toUpperCase(); // Fine inside the narrowed block
}

// Or use a type assertion (risky — you're responsible):
const s = x as string;

unknown is what you should use when you genuinely don’t know the type upfront — when parsing JSON from an external source, for example. It forces you to verify before using, rather than silently propagating an unchecked assumption.

never — the bottom type:

never is the type for values that can never exist. It’s the TypeScript equivalent of void in C# for functions that throw unconditionally, but it’s also used in exhaustiveness checking.

// A function that never returns (always throws or loops forever)
function fail(message: string): never {
  throw new Error(message);
}

// Exhaustiveness checking — the most useful application
type Shape = 'circle' | 'square' | 'triangle';

function area(shape: Shape): number {
  switch (shape) {
    case 'circle': return Math.PI * 5 * 5;
    case 'square': return 25;
    case 'triangle': return 12.5;
    default:
      // If you add a new Shape variant and forget to handle it,
      // the compiler will flag this assignment — shape would be `never`
      // only if all cases are exhausted
      const _exhaustive: never = shape;
      throw new Error(`Unhandled shape: ${shape}`);
  }
}

This exhaustiveness pattern is the TypeScript equivalent of C#’s pattern matching exhaustiveness in switch expressions.

The strict Compiler Flag Family

The TypeScript compiler has a collection of strictness flags. The strict: true setting in tsconfig.json enables all of them. You should always start with strict: true and work from there. Disabling individual flags is an escape hatch for migrating legacy code, not a permanent configuration.

{
  "compilerOptions": {
    "strict": true
  }
}

strict: true enables:

Additional flags worth considering beyond strict:

{
  "compilerOptions": {
    "strict": true,
    "noUncheckedIndexedAccess": true,  // array[i] returns T | undefined, not T
    "exactOptionalPropertyTypes": true, // undefined must be explicit in optional props
    "noImplicitReturns": true,          // All code paths must return a value
    "noFallthroughCasesInSwitch": true  // No accidental switch case fallthrough
  }
}

noUncheckedIndexedAccess is particularly valuable for .NET engineers: it makes array indexing honest. In C#, items[0] throws at runtime if the array is empty. In TypeScript without this flag, items[0] has type T even though it might be undefined. With this flag, items[0] has type T | undefined, and you’re forced to check.

Key Differences

Gotchas for .NET Engineers

1. private is not private at runtime

TypeScript’s private keyword is enforced only by the compiler. At runtime, after compilation to JavaScript, all properties are accessible. This matters for security, serialization, and interop.

class ApiClient {
  private apiKey: string;

  constructor(apiKey: string) {
    this.apiKey = apiKey;
  }
}

const client = new ApiClient('secret-key-123');
console.log((client as any).apiKey); // Prints: secret-key-123

// If you need actual runtime privacy, use # (ES private fields):
class SafeClient {
  #apiKey: string;

  constructor(apiKey: string) {
    this.#apiKey = apiKey;
  }
}

const safe = new SafeClient('secret-key-123');
console.log((safe as any)['#apiKey']); // undefined — truly inaccessible

The implication: never use TypeScript’s private to hide sensitive data. It’s a development-time contract, not a security mechanism.

2. number cannot represent decimal safely

C# decimal is a 128-bit type designed for financial arithmetic. TypeScript’s number is a 64-bit IEEE 754 float — the same type C# uses for double. Financial calculations in TypeScript are dangerous without an arbitrary precision library.

// This produces the wrong result — classic floating point issue
console.log(0.1 + 0.2); // 0.30000000000000004

// C# decimal avoids this:
// decimal a = 0.1m; decimal b = 0.2m; // 0.1 + 0.2 = 0.3 exactly

// For financial values in TypeScript, use a library:
// - dinero.js (recommended for currency)
// - decimal.js or big.js (arbitrary precision)
import Dinero from 'dinero.js';
const price = Dinero({ amount: 1099, currency: 'USD' }); // $10.99 in cents
const tax = price.percentage(8);
const total = price.add(tax);

If your .NET codebase uses decimal anywhere that matters financially, plan for this when bringing that logic to TypeScript.

3. Type assertions (as) are not casts — they are lies the compiler accepts

In C#, a cast throws InvalidCastException at runtime if the types are incompatible. TypeScript’s as operator tells the compiler to trust you — it performs no runtime check whatsoever.

// This compiles fine and produces a corrupt object silently:
const user = JSON.parse(apiResponse) as User;
// user looks like User to TypeScript — but if the API returns unexpected data,
// you won't find out until runtime when you access user.email and it's undefined

// C# equivalent would throw at deserialization:
// var user = JsonSerializer.Deserialize<User>(apiResponse);
// Missing required fields throw an exception

// The correct TypeScript approach: validate at the boundary with Zod
import { z } from 'zod';

const UserSchema = z.object({
  id: z.string(),
  email: z.string().email(),
  displayName: z.string(),
});

// This throws a descriptive error if the shape doesn't match:
const user = UserSchema.parse(JSON.parse(apiResponse));

See Article 2.3 for the full runtime validation story with Zod.

4. Structural typing allows unintended assignments across domain types

This is the most significant discipline gap relative to C#. In C#, you can’t pass an OrderId where a UserId is expected even if both are Guid. In TypeScript with structural typing, you can pass a User where an Order is expected if their shapes happen to match.

interface UserId {
  value: string;
}

interface OrderId {
  value: string;
}

// Identical shapes — TypeScript considers them compatible:
const userId: UserId = { value: 'user-123' };
const orderId: OrderId = userId; // No error. This is a bug in the making.

function deleteOrder(id: OrderId): void { /* ... */ }
deleteOrder(userId); // TypeScript accepts this

The solution is branded types, covered in Article 2.6:

type UserId = string & { readonly _brand: 'UserId' };
type OrderId = string & { readonly _brand: 'OrderId' };

function createUserId(value: string): UserId {
  return value as UserId;
}

function deleteOrder(id: OrderId): void { /* ... */ }
const userId = createUserId('user-123');
deleteOrder(userId); // Now this correctly errors

5. TypeScript enums produce JavaScript output — and numeric enums have spurious assignability

As covered above, numeric enums accept any number. This is a known design issue. The TypeScript team has acknowledged it. The practical solution is to avoid numeric enums entirely and use the const object pattern.

// Broken — any number is assignable
enum Priority { Low = 1, Medium = 2, High = 3 }
const p: Priority = 9999; // No error

// Correct — only the declared values are valid
const Priority = { Low: 1, Medium: 2, High: 3 } as const;
type Priority = typeof Priority[keyof typeof Priority]; // 1 | 2 | 3
const p: Priority = 9999; // Error: Type '9999' is not assignable to type '1 | 2 | 3'

6. Date serialization between TypeScript and other backends

TypeScript’s Date object is a thin wrapper around a Unix timestamp. When you serialize it to JSON (JSON.stringify), it produces an ISO 8601 string. When you deserialize JSON, JSON.parse does NOT automatically convert ISO strings back to Date objects — they remain strings.

const event = { name: 'Launch', date: new Date('2026-03-01') };
const json = JSON.stringify(event);
// '{"name":"Launch","date":"2026-03-01T00:00:00.000Z"}'

const parsed = JSON.parse(json);
parsed.date instanceof Date; // false — it's a string
typeof parsed.date;          // 'string'

// You must explicitly convert, or use Zod's z.coerce.date():
import { z } from 'zod';
const EventSchema = z.object({
  name: z.string(),
  date: z.coerce.date(), // Converts ISO string to Date
});

This is especially relevant when consuming .NET or Python APIs, where date serialization formats can differ. Map dates at the boundary, not deep in your application code.

Hands-On Exercise

You have a C# domain model for an invoice system. Your task is to translate it to TypeScript using the patterns from this article.

The C# source:

public enum InvoiceStatus
{
    Draft,
    Sent,
    Paid,
    Overdue,
    Cancelled
}

public class LineItem
{
    public Guid Id { get; init; }
    public string Description { get; init; }
    public decimal UnitPrice { get; init; }
    public int Quantity { get; init; }
    public decimal Total => UnitPrice * Quantity;
}

public class Invoice
{
    public Guid Id { get; init; }
    public string InvoiceNumber { get; init; }
    public Guid CustomerId { get; init; }
    public InvoiceStatus Status { get; init; }
    public DateTimeOffset IssuedAt { get; init; }
    public DateTimeOffset? DueDate { get; init; }
    public IReadOnlyList<LineItem> LineItems { get; init; }
    public decimal? Notes { get; init; }
}

public interface IInvoiceRepository
{
    Task<Invoice?> GetById(Guid id);
    Task<IReadOnlyList<Invoice>> GetByCustomer(Guid customerId, InvoiceStatus? status = null);
    Task<Invoice> Save(Invoice invoice);
}

Your task:

1. Convert InvoiceStatus to a const object + union type (not a TypeScript enum).
2. Define LineItem and Invoice as TypeScript interfaces. Use readonly properties throughout.
3. Add a computed total property to LineItem that TypeScript can express structurally.
4. Decide: where does decimal precision matter here, and how would you note the risk in your types?
5. Convert IInvoiceRepository to a TypeScript interface with correct return types (use Promise<T>, not Task<T>).
6. Add proper null vs. undefined semantics — where is something intentionally absent vs. not yet provided?
7. Enable strict: true in a minimal tsconfig.json and verify your types compile.

Stretch goal: Add a branded type for InvoiceId and CustomerId so they cannot be accidentally swapped.

Quick Reference

tsconfig.json minimum for a new project:

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "NodeNext",
    "moduleResolution": "NodeNext",
    "strict": true,
    "noUncheckedIndexedAccess": true,
    "noImplicitReturns": true,
    "noFallthroughCasesInSwitch": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "outDir": "./dist"
  }
}

Further Reading

• TypeScript Handbook: Type Compatibility — the official explanation of structural typing, with clear examples
• TypeScript Handbook: Everyday Types — covers primitives, unions, and interfaces without assuming JavaScript background
• TypeScript strict mode — what each flag does — the official tsconfig reference for every strict flag
• Matt Pocock’s Total TypeScript — Enums — the definitive case against TypeScript enums, from the author of the most widely used TypeScript course

Advanced TypeScript Types: Things C# Can’t Do

For .NET engineers who know: C# generics, interfaces, abstract classes, LINQ, pattern matching You’ll learn: TypeScript’s advanced type system features — union types, conditional types, mapped types, discriminated unions, and more — with honest assessments of when to use them and when they are overkill Time: 25-30 min read

The .NET Way (What You Already Know)

C#’s type system is rich but nominally typed: a Dog is a Dog because it was declared class Dog, not because it happens to have a Bark() method. Generics give you parameterized types (List<T>, Task<T>, IRepository<T>), interfaces define contracts, and abstract classes share implementation. You use where T : class and where T : IEntity to constrain generic parameters.

The C# type system is deliberately conservative. It prioritizes correctness and expressibility for object-oriented patterns. What it does not offer natively: the ability to express “this value is one of these specific string literals,” the ability to derive a new type from an existing one by picking a subset of its properties, or the ability to write a type that resolves differently depending on what type you pass in.

For most enterprise .NET code, these constraints are invisible. The pattern matching added in C# 7-9 addressed some gaps. But there are entire categories of type-level computation that C# cannot do at all.

TypeScript’s type system can. And in real-world TypeScript projects, these features appear constantly — in library code you will consume, in the patterns your team already uses, and in the errors you will debug when you get them wrong.

This article covers the advanced features. Approach them as a toolkit, not a showcase. Each one solves a specific problem. Each one has a failure mode where it adds complexity with no real benefit.

The TypeScript Way

Union Types: “This or That”

A union type says a value can be one of several types:

// TypeScript
type StringOrNumber = string | number;

function format(value: StringOrNumber): string {
  return String(value);
}

format("hello"); // ok
format(42);      // ok
format(true);    // error: Argument of type 'boolean' is not assignable

Closest C# analogy: None that’s clean. You might reach for a common base class, an object parameter, or an overloaded method. The closest structural approximation is a discriminated union via a sealed class hierarchy — but that requires multiple class declarations and a runtime dispatch pattern. TypeScript’s union type is a first-class, zero-runtime-cost construct.

Practical use case: API responses often have different shapes depending on success or failure.

// Without union types — you'd need a class hierarchy or object with optional fields
type ApiResponse<T> =
  | { status: "success"; data: T }
  | { status: "error"; code: number; message: string };

function handleResponse(response: ApiResponse<User>): void {
  if (response.status === "success") {
    console.log(response.data.name); // TypeScript knows .data exists here
  } else {
    console.log(response.message);   // TypeScript knows .message exists here
  }
}

When not to use it: If your “union” grows to five or more members and you are constantly checking the discriminant, you may actually want a class hierarchy or a dedicated state machine. Union types with many arms are hard to extend — every check site needs updating.

Intersection Types: “This and That”

Where union types are “or,” intersection types are “and”:

// TypeScript
type Named = { name: string };
type Aged = { age: number };
type Person = Named & Aged;

const person: Person = { name: "Chris", age: 40 }; // must satisfy both

Closest C# analogy: Implementing multiple interfaces. class Person : INamed, IAged. The difference: intersection types work on object literal shapes without class declarations. You compose types structurally, not nominally.

Practical use case: Merging types in utility functions — for example, a generic “with ID” wrapper:

type WithId<T> = T & { id: string };

type UserDto = { name: string; email: string };
type UserRecord = WithId<UserDto>;
// { name: string; email: string; id: string }

function save<T>(entity: T): WithId<T> {
  return { ...entity, id: crypto.randomUUID() };
}

When not to use it: Intersecting two types that have conflicting properties for the same key produces never for that property, which silently breaks things:

type A = { id: string };
type B = { id: number };
type Broken = A & B; // { id: never } — no value can satisfy this

Intersections work best when the merged types have non-overlapping properties.

Literal Types: Exact Values as Types

In C#, a string can hold any string. In TypeScript, you can create a type that only accepts specific string (or number, or boolean) values:

// TypeScript
type Direction = "north" | "south" | "east" | "west";
type HttpMethod = "GET" | "POST" | "PUT" | "DELETE" | "PATCH";
type Port = 80 | 443 | 8080;

function move(direction: Direction): void {
  // direction is guaranteed to be one of the four values
}

move("north");  // ok
move("up");     // error: Argument of type '"up"' is not assignable

Closest C# analogy: enum, but better in two ways. First, string literal types carry their value as their identity — you do not need to convert between enum and string for serialization. Second, literal types participate in the full type system and can be used anywhere a type can appear.

C# comparison:

// C# — you need an enum and then string conversion for JSON, API contracts, etc.
public enum Direction { North, South, East, West }

// TypeScript — the string literal IS the value
type Direction = "north" | "south" | "east" | "west";
const d: Direction = "north"; // serializes directly

Practical use case: Strongly typed event names, CSS property values, configuration keys — anywhere you have a fixed, small set of valid string values.

When not to use it: If the set of valid values is dynamic, comes from a database, or needs to be extended without code changes. In those cases, a validated string at runtime (via Zod — see Article 2.3) is the right tool, not a compile-time literal type.

Template Literal Types: Type-Level String Interpolation

TypeScript can construct string literal types by combining other string literals — at the type level, not at runtime:

// TypeScript
type EventName = "click" | "focus" | "blur";
type HandlerName = `on${Capitalize<EventName>}`;
// "onClick" | "onFocus" | "onBlur"

type CSSProperty = "margin" | "padding";
type CSSDirection = "Top" | "Bottom" | "Left" | "Right";
type CSSFullProperty = `${CSSProperty}${CSSDirection}`;
// "marginTop" | "marginBottom" | ... | "paddingRight" (8 combinations)

C# analogy: None. C# has no mechanism to compute string types at compile time.

Practical use case: Typed event maps, typed route parameters, typed CSS-in-TS:

// Typed route parameter extraction
type ExtractParams<Route extends string> =
  Route extends `${string}:${infer Param}/${infer Rest}`
    ? Param | ExtractParams<`/${Rest}`>
    : Route extends `${string}:${infer Param}`
    ? Param
    : never;

type UserRouteParams = ExtractParams<"/users/:userId/posts/:postId">;
// "userId" | "postId"

// Practical typed router:
function buildRoute<T extends string>(
  template: T,
  params: Record<ExtractParams<T>, string>
): string {
  let result: string = template;
  for (const [key, value] of Object.entries(params)) {
    result = result.replace(`:${key}`, value as string);
  }
  return result;
}

const url = buildRoute("/users/:userId/posts/:postId", {
  userId: "abc",
  postId: "123",
});
// TypeScript enforces that you provide exactly userId and postId

When not to use it: Template literal types get unwieldy fast. If the combinations produce more than a dozen string values, they become expensive for the compiler and hard to read in error messages. The router example above is near the limit of practical complexity.

Discriminated Unions: The Functional State Pattern

A discriminated union is a union of types that share a common “discriminant” field — a literal-typed property that uniquely identifies which member of the union you have. This is the TypeScript equivalent of a sealed class hierarchy in C#, but it composes more cleanly.

// TypeScript
type LoadingState =
  | { status: "idle" }
  | { status: "loading" }
  | { status: "success"; data: User[] }
  | { status: "error"; error: Error };

// The closest C# equivalent — much more ceremony
public abstract record LoadingState;
public record Idle : LoadingState;
public record Loading : LoadingState;
public record Success(IEnumerable<User> Data) : LoadingState;
public record Error(Exception Exception) : LoadingState;

// Pattern matching in C# 9+
var result = state switch {
    Success s => s.Data,
    Error e   => throw e.Exception,
    _         => throw new InvalidOperationException()
};

TypeScript’s version — with switch statements or conditional chains — is more compact, requires no base type, and the compiler narrows the type automatically based on the discriminant check:

// TypeScript narrowing via discriminated union
function render(state: LoadingState): string {
  switch (state.status) {
    case "idle":
      return "Waiting...";
    case "loading":
      return "Loading...";
    case "success":
      return state.data.map((u) => u.name).join(", "); // data is typed here
    case "error":
      return `Error: ${state.error.message}`;           // error is typed here
  }
}

The compiler also enforces exhaustiveness when you configure it correctly. Add a default branch that assigns to never:

function assertNever(value: never): never {
  throw new Error(`Unhandled discriminant: ${JSON.stringify(value)}`);
}

function render(state: LoadingState): string {
  switch (state.status) {
    case "idle":    return "Waiting...";
    case "loading": return "Loading...";
    case "success": return state.data.map((u) => u.name).join(", ");
    case "error":   return `Error: ${state.error.message}`;
    default:        return assertNever(state); // compiler error if a case is missing
  }
}

Practical use case: UI state machines, API response shapes, command/event types in CQRS-like patterns, WebSocket message types.

When not to use it: Discriminated unions do not support inheritance-like composition well. If you need to add behavior to each variant (methods, not just data), a class hierarchy remains more ergonomic.

Conditional Types: Type-Level If/Else

Conditional types apply a conditional at the type level:

// T extends U ? X : Y
type IsString<T> = T extends string ? true : false;

type A = IsString<string>;  // true
type B = IsString<number>;  // false
type C = IsString<"hello">; // true — "hello" extends string

On its own this looks academic. In combination with generics, it enables patterns that are genuinely useful:

// Extract the resolved type from a Promise
type Awaited<T> = T extends Promise<infer R> ? R : T;
// (This is now built into TypeScript, but understanding it matters)

type UserData = Awaited<Promise<User>>;  // User
type NumberData = Awaited<number>;       // number

// NonNullable removes null and undefined from a type
type NonNullable<T> = T extends null | undefined ? never : T;

type MaybeString = string | null | undefined;
type DefinitelyString = NonNullable<MaybeString>; // string

C# analogy: The closest C# mechanism is generic constraints (where T : class) combined with overloaded methods — but this enforces constraints rather than computing output types. C# has no way to say “if T is X, return Y, otherwise return Z” in the type system.

Practical use case — typed API client method overloads:

// Different return types based on whether pagination is requested
type PaginatedResponse<T> = { data: T[]; total: number; page: number };

type QueryResult<T, Paginated extends boolean> =
  Paginated extends true ? PaginatedResponse<T> : T[];

async function query<T, P extends boolean = false>(
  endpoint: string,
  paginate?: P
): Promise<QueryResult<T, P>> {
  // implementation
  throw new Error("not implemented");
}

const users = await query<User>("/users");           // User[]
const paged = await query<User>("/users", true);     // PaginatedResponse<User>

When not to use it: Conditional types can nest multiple levels deep and become essentially unreadable. If you find yourself writing T extends A ? (T extends B ? X : Y) : Z, step back and ask whether two separate functions or a union return type solves the problem more clearly. They are powerful; they are also the most common source of “I wrote this, and now I cannot debug it” type-system problems.

Mapped Types: Transform Every Key in a Type

Mapped types iterate over the keys of a type and produce a new type by applying a transformation:

// The syntax: { [K in keyof T]: transformation }
type Readonly<T> = { readonly [K in keyof T]: T[K] };
type Partial<T> = { [K in keyof T]?: T[K] };
type Required<T> = { [K in keyof T]-?: T[K] }; // -? removes optional
type Nullable<T> = { [K in keyof T]: T[K] | null };

These are all built into TypeScript, but understanding that they are derived — not primitive — changes how you think about the type system.

The built-in utility types you will use constantly:

type User = {
  id: string;
  name: string;
  email: string;
  role: "admin" | "user";
  createdAt: Date;
};

// Partial<T> — all fields optional (PATCH request body)
type UpdateUserDto = Partial<User>;
// { id?: string; name?: string; email?: string; ... }

// Pick<T, K> — only keep specified keys
type UserSummary = Pick<User, "id" | "name">;
// { id: string; name: string }

// Omit<T, K> — remove specified keys
type CreateUserDto = Omit<User, "id" | "createdAt">;
// { name: string; email: string; role: "admin" | "user" }

// Record<K, V> — typed dictionary
type UsersByRole = Record<"admin" | "user", User[]>;
// { admin: User[]; user: User[] }

// Required<T> — remove all optionals
type FullUser = Required<Partial<User>>;
// Same as User — all fields mandatory again

C# comparison:

// C# — requires separate class declarations for each shape
public class User { public string Id; public string Name; public string Email; }
public class UpdateUserDto { public string? Name; public string? Email; }       // manual
public class CreateUserDto { public string Name; public string Email; }         // manual
public class UserSummary { public string Id; public string Name; }              // manual

// TypeScript — derived from User automatically
type UpdateUserDto = Partial<Omit<User, "id" | "createdAt">>;
type CreateUserDto = Omit<User, "id" | "createdAt">;
type UserSummary = Pick<User, "id" | "name">;

If you change the User type in TypeScript, all three derived types update automatically. In C#, you update four separate classes manually.

Custom mapped types — a real example:

// Convert every method in a type to return a Promise version
type Promisify<T> = {
  [K in keyof T]: T[K] extends (...args: infer A) => infer R
    ? (...args: A) => Promise<R>
    : T[K];
};

interface SyncRepository {
  findById(id: string): User;
  save(user: User): void;
  delete(id: string): boolean;
}

type AsyncRepository = Promisify<SyncRepository>;
// {
//   findById(id: string): Promise<User>;
//   save(user: User): Promise<void>;
//   delete(id: string): Promise<boolean>;
// }

When not to use it: Do not create custom mapped types for one-off situations. If you only need a specific shape once, just declare that type explicitly. Mapped types earn their complexity when you need to derive several types from one source of truth, or when you are building library/utility code that will be reused across many types.

The infer Keyword: Extract Type Components

infer appears inside conditional types and lets you capture a part of a matched type into a named type variable:

// Extract the return type of a function
type ReturnType<T> = T extends (...args: any[]) => infer R ? R : never;

type GetUser = () => Promise<User>;
type UserResult = ReturnType<GetUser>; // Promise<User>

// Extract the element type of an array
type ElementType<T> = T extends (infer E)[] ? E : never;

type Names = ElementType<string[]>; // string
type Ids = ElementType<number[]>;   // number

// Extract the resolved value from a Promise
type UnwrapPromise<T> = T extends Promise<infer V> ? V : T;

type ResolvedUser = UnwrapPromise<Promise<User>>; // User
type PassThrough = UnwrapPromise<string>;          // string

C# analogy: Reflection-based type extraction at runtime — but TypeScript’s infer operates entirely at compile time with zero runtime cost.

Practical use case — extracting function parameter types for wrapper functions:

// NestJS interceptor pattern: wrap any async service method with retry logic
type AsyncFn = (...args: any[]) => Promise<any>;

type RetryWrapper<T extends AsyncFn> = (
  ...args: Parameters<T>
) => Promise<Awaited<ReturnType<T>>>;

function withRetry<T extends AsyncFn>(fn: T, maxAttempts = 3): RetryWrapper<T> {
  return async (...args) => {
    let lastError: unknown;
    for (let attempt = 0; attempt < maxAttempts; attempt++) {
      try {
        return await fn(...args);
      } catch (err) {
        lastError = err;
      }
    }
    throw lastError;
  };
}

async function fetchUser(id: string): Promise<User> {
  // implementation
  throw new Error("not implemented");
}

const robustFetchUser = withRetry(fetchUser); // (id: string) => Promise<User>
// Type fully preserved through the wrapper

When not to use it: infer is exclusively for advanced utility types and library-level code. Application code should rarely need it directly. If you find yourself reaching for infer in a controller or service, you are almost certainly over-engineering the solution.

The satisfies Operator: Validate Without Widening

Added in TypeScript 4.9, satisfies validates that a value conforms to a type without changing the inferred type of the value. This is the distinction between “I know this fits the type” and “I want TypeScript to infer the specific type but also confirm it fits.”

type ColorMap = Record<string, string | [number, number, number]>;

// Without satisfies — TypeScript widens to the annotation type
const colors: ColorMap = {
  red: [255, 0, 0],
  green: "#00ff00",
  blue: [0, 0, 255],
};

// colors.red has type `string | [number, number, number]`
// TypeScript loses the knowledge that red is specifically a tuple
colors.red.toUpperCase(); // error — TS thinks it might be a tuple

// With satisfies — validation without widening
const palette = {
  red: [255, 0, 0],
  green: "#00ff00",
  blue: [0, 0, 255],
} satisfies ColorMap;

// palette.red has type [number, number, number] — the specific inferred type
// palette.green has type string — specific inferred type
palette.red.map((c) => c * 2); // ok — TypeScript knows it's a tuple
palette.green.toUpperCase();   // ok — TypeScript knows it's a string

C# analogy: None direct. The closest concept is an implicit type conversion that validates the target interface without losing the concrete type, but C# does not work this way — you either declare the variable as the interface type (and lose access to concrete members) or the concrete type (and lose the validation).

Practical use case — NestJS configuration objects:

// NestJS module options often have broad types
type DbConfig = {
  host: string;
  port: number;
  ssl?: boolean;
  poolSize?: number;
};

// Using satisfies: TypeScript validates the config AND keeps the specific types
const dbConfig = {
  host: "localhost",
  port: 5432,
  ssl: false,
  poolSize: 10,
} satisfies DbConfig;

// Without satisfies, if you annotated as DbConfig:
// dbConfig.host would be `string` (fine, but...)
// dbConfig.port would be `number` (fine)
// But if you had a literal type context, satisfies preserves it

// More useful example with a route config
type RouteConfig = {
  method: "GET" | "POST" | "PUT" | "DELETE";
  path: string;
  requiresAuth: boolean;
};

const routes = {
  getUsers: { method: "GET", path: "/users", requiresAuth: true },
  createUser: { method: "POST", path: "/users", requiresAuth: true },
} satisfies Record<string, RouteConfig>;

// routes.getUsers.method is "GET" — not just "GET" | "POST" | "PUT" | "DELETE"
// TypeScript validates the shape but preserves the literal types

When not to use it: satisfies solves a specific problem: you want type validation without losing the specific inferred type. If you do not need access to the specific inferred type afterward (i.e., the widened annotation type is fine), a plain type annotation is simpler and clearer.

Type Narrowing and Type Guards: Recover Specificity from Broad Types

Type narrowing is how TypeScript automatically refines a broad type to a more specific one based on runtime checks. It is built into the language and powers discriminated unions, but it also works with typeof, instanceof, in, and truthiness checks:

function process(input: string | number | null): string {
  if (input === null) {
    return "empty";                      // narrowed to null
  }
  if (typeof input === "string") {
    return input.toUpperCase();          // narrowed to string
  }
  return input.toFixed(2);              // narrowed to number — TypeScript deduced this
}

User-defined type guards let you write a function that narrows types in ways the compiler cannot infer automatically. The return type value is SomeType is the key:

// TypeScript type guard
function isUser(value: unknown): value is User {
  return (
    typeof value === "object" &&
    value !== null &&
    "id" in value &&
    "name" in value &&
    typeof (value as any).id === "string" &&
    typeof (value as any).name === "string"
  );
}

function processApiResponse(raw: unknown): string {
  if (isUser(raw)) {
    return raw.name; // TypeScript now knows raw is User
  }
  return "unknown entity";
}

C# comparison:

// C# pattern matching narrowing
object input = GetValue();
if (input is string s) {
    Console.WriteLine(s.ToUpper()); // s is string here
}
if (input is User u) {
    Console.WriteLine(u.Name);      // u is User here
}

C# pattern matching is similar, but it relies on the CLR’s nominal type system. TypeScript’s structural narrowing is more flexible: you can narrow based on property shapes, not just declared types.

The in narrowing operator is particularly useful with discriminated unions or when working with object types:

type Cat = { meow: () => void };
type Dog = { bark: () => void };

function makeNoise(animal: Cat | Dog): void {
  if ("meow" in animal) {
    animal.meow(); // narrowed to Cat
  } else {
    animal.bark(); // narrowed to Dog
  }
}

Assertion functions are a stricter variant of type guards — they throw if the assertion fails rather than returning boolean:

function assertIsUser(value: unknown): asserts value is User {
  if (!isUser(value)) {
    throw new Error(`Expected User, got: ${JSON.stringify(value)}`);
  }
}

function processFromApi(raw: unknown): void {
  assertIsUser(raw); // throws if raw is not a User
  console.log(raw.name); // TypeScript knows raw is User here
}

When not to use custom type guards: If you are in code that already uses Zod for validation (see Article 2.3), Zod’s .parse() and .safeParse() are both a type guard and a runtime validator combined — writing a manual type guard duplicates work Zod already does. Reserve manual type guards for situations where Zod is not present or would be overkill.

Key Differences

Gotchas for .NET Engineers

Gotcha 1: TypeScript Types Do Not Exist at Runtime

This is the foundational error .NET engineers make. In C#, if you have a User variable, the CLR knows it is a User. You can use GetType(), is, as, and reflection. The type is real at runtime.

In TypeScript, types are erased during compilation. At runtime, you have JavaScript objects. There is no typeof user === User in TypeScript — typeof only returns "object", "string", "number", "boolean", "function", "symbol", or "undefined".

// This is a common mistake
type User = { id: string; name: string };

const response: User = await fetch("/api/users/1").then((r) => r.json());
// TypeScript is satisfied. But if the API returns { id: 123, name: null },
// TypeScript does NOT catch this. The assertion in the type annotation is a lie
// the compiler accepts without question.

// Correct approach: runtime validation with Zod
import { z } from "zod";

const UserSchema = z.object({ id: z.string(), name: z.string() });
const response = UserSchema.parse(await fetch("/api/users/1").then((r) => r.json()));
// Now throws if the shape is wrong — same guarantees as C# deserialization with validation

Every advanced type feature in this article operates at compile time only. They give you better intellisense and catch more errors during development. They provide zero protection against malformed data at runtime.

Gotcha 2: any Silently Disables the Type System, Including Your Advanced Types

When a value is typed as any, TypeScript stops checking it entirely. Advanced types have no effect when any appears in the chain:

type StrictUser = {
  id: string;
  name: string;
};

function getUser(): any {
  return { id: 123, name: null }; // wrong types — but any masks it
}

const user: StrictUser = getUser(); // TypeScript allows this — no error
console.log(user.name.toUpperCase()); // runtime error: Cannot read properties of null

In C#, the equivalent would be returning object and casting — and you have been trained to treat that as a code smell. Apply the same instinct to any in TypeScript. unknown is the safe alternative: it requires you to narrow before you use it.

function getUser(): unknown {
  return { id: 123, name: null };
}

const user = getUser();
user.name; // error: Object is of type 'unknown'

// Must narrow first:
if (isUser(user)) {
  user.name; // ok — narrowed to User
}

any also infects downstream types. A conditional type applied to any resolves to any. A mapped type over any resolves to any. The advanced features in this article do not protect you from any.

Gotcha 3: Complex Type Errors Are Hard to Interpret

C# type errors are usually specific: “Cannot implicitly convert type ‘int’ to ‘string’.” TypeScript type errors on complex generic types can be paragraphs long:

Type '{ id: string; name: string; }' is not assignable to type 'Partial<Omit<Required<User>, "createdAt" | "updatedAt">> & WithId<Pick<User, "role">>'.
  Type '{ id: string; name: string; }' is not assignable to type 'WithId<Pick<User, "role">>'.
    Property 'role' is missing in type '{ id: string; name: string; }' but required in type 'Pick<User, "role">'.

This is not TypeScript failing — it is correct. But it is hard to read. Two practices help:

First, decompose complex types into named intermediate types. Instead of one deeply nested type expression, give each layer a name. The error messages then reference the named type, which is easier to locate.

// Hard to debug when something goes wrong:
type UserPatchRequest = Partial<Omit<Required<User>, "id" | "createdAt">> & { _version: number };

// Easier to debug:
type MutableUserFields = Omit<User, "id" | "createdAt">;
type RequiredMutableFields = Required<MutableUserFields>;
type OptionalMutableFields = Partial<RequiredMutableFields>;
type UserPatchRequest = OptionalMutableFields & { _version: number };

Second, use the TypeScript playground or VS Code’s “Go to Type Definition” to inspect what a complex type resolves to. Hover over the type name — VS Code will show the fully expanded shape. This is the equivalent of evaluating a LINQ expression in the debugger to see the actual SQL.

Gotcha 4: Discriminated Unions Do Not Protect Against Missing Cases Without Exhaustiveness Checking

A switch statement over a discriminated union that does not cover all members compiles without error by default:

type Status = "pending" | "active" | "suspended" | "deleted";

function getLabel(status: Status): string {
  switch (status) {
    case "pending":  return "Pending";
    case "active":   return "Active";
    // Missing: "suspended" and "deleted"
    // TypeScript does not complain — the function just returns undefined at runtime
  }
}

Add explicit exhaustiveness checking to catch this at compile time:

function assertNever(value: never): never {
  throw new Error(`Unhandled case: ${JSON.stringify(value)}`);
}

function getLabel(status: Status): string {
  switch (status) {
    case "pending":   return "Pending";
    case "active":    return "Active";
    case "suspended": return "Suspended";
    case "deleted":   return "Deleted";
    default:          return assertNever(status); // compile error if a case is missing
  }
}

Now if you add "archived" to Status, every assertNever call becomes a compile error. This is the TypeScript equivalent of C# exhaustive pattern matching with switch expressions that require all cases.

Gotcha 5: Partial<T> Does Not Mean “Optional Fields for Updates” — It Means “All Fields Optional”

A common pattern from C# PATCH endpoints is to accept a DTO where all fields are optional and apply only the provided ones. Partial<T> looks like the right tool. It is close, but it accepts {} as a valid value — an update with no fields set:

type UserUpdateDto = Partial<User>;

function updateUser(id: string, dto: UserUpdateDto): Promise<User> {
  // dto could be {}, which is technically valid but useless
  // dto could also contain undefined values explicitly
  throw new Error("not implemented");
}

updateUser("abc", {}); // TypeScript allows this — is it intentional?

If you need “at least one field must be provided,” you need a more precise type:

// RequireAtLeastOne: at least one key from T must be present
type RequireAtLeastOne<T, Keys extends keyof T = keyof T> =
  Pick<T, Exclude<keyof T, Keys>> &
  { [K in Keys]-?: Required<Pick<T, K>> & Partial<Pick<T, Exclude<Keys, K>>> }[Keys];

type NonEmptyUserUpdate = RequireAtLeastOne<Partial<Omit<User, "id" | "createdAt">>>;

This type is complex enough that it belongs in a shared utility file with a comment explaining it. In practice, many teams skip this precision and add a runtime check instead — which is also defensible.

Hands-On Exercise

This exercise uses the types from a real NestJS + Prisma project structure.

Setup: You have a User model from Prisma:

// Generated by Prisma — do not modify
type User = {
  id: string;
  email: string;
  name: string;
  role: "admin" | "user" | "guest";
  isActive: boolean;
  createdAt: Date;
  updatedAt: Date;
};

Tasks:

1. Define a CreateUserDto that omits id, createdAt, updatedAt, and isActive (which defaults to true on creation).

2. Define an UpdateUserDto that makes all remaining fields optional and excludes id and the date fields. Then write a type guard function isNonEmptyUpdate(dto: UpdateUserDto): boolean that returns true only if at least one field is actually set (not undefined).

3. Define a UserSummary type using Pick that includes only id, name, and role.

4. Define a UserApiResponse as a discriminated union with these three shapes:

   • Success: { status: "success"; user: UserSummary }
   • Not found: { status: "not_found"; requestedId: string }
   • Forbidden: { status: "forbidden"; reason: string }

5. Write a handleUserResponse(response: UserApiResponse): string function that returns a human-readable message for each case. Add exhaustiveness checking with assertNever.

6. Define a UserEventMap type using template literal types and Record, where the keys are "user:created", "user:updated", "user:deleted", and each value is a function that receives the relevant data type.

Expected output: After completing the exercise, open VS Code and hover over UserApiResponse in the switch statement’s default case. It should show never — confirming exhaustiveness. Hover over each branch’s response.user or response.requestedId — TypeScript should show the narrowed type.

Quick Reference

Utility Types Cheat Sheet

Pattern Decision Guide

When to Use Each Feature

Further Reading

• TypeScript Handbook: Advanced Types — The official reference for everything covered in this article. Read the “Conditional Types,” “Mapped Types,” and “Template Literal Types” sections.
• TypeScript Utility Types Reference — Complete list of built-in utility types with examples.
• TypeScript 4.9 Release Notes: satisfies — The original motivation and examples for the satisfies operator, from the TypeScript team.
• Type Challenges — A curated set of type-system problems ranging from warm-up to extreme. Working through the medium-level challenges is the most effective way to develop fluency with conditional types and infer. Treat it as a kata repository, not a completionist exercise.

TypeScript Through the Layers: End-to-End Type Safety with Zod

For .NET engineers who know: EF Core models, DTOs, Data Annotations, FluentValidation, NSwag client generation, and ASP.NET Core model binding You’ll learn: How TypeScript achieves end-to-end type safety across the full stack — database through UI — using Prisma, Zod, NestJS, tRPC, and React, and why runtime validation is a structural requirement rather than an afterthought Time: 25-30 min read

This is one of the two most important articles in this curriculum. If you take one architectural insight from the entire course, it should be this: in the TypeScript stack, types are a compile-time fiction. Nothing enforces them at runtime unless you deliberately add that enforcement. Zod is how you add it. Everything else in this article builds on that premise.

The .NET Way (What You Already Know)

In ASP.NET Core, type safety flows naturally from the CLR’s enforced type system. When a request arrives at your API, the runtime itself participates in validation and type enforcement at every step.

Consider the standard layered flow in a .NET application:

// 1. EF Core model — the database schema expressed as a C# class
[Table("users")]
public class User
{
    public int Id { get; set; }
    public string Name { get; set; } = null!;
    public string Email { get; set; } = null!;
    public DateTime CreatedAt { get; set; }
}

// 2. DTO — a separate class that shapes the API surface
public class CreateUserDto
{
    [Required]
    [StringLength(100, MinimumLength = 2)]
    public string Name { get; set; } = null!;

    [Required]
    [EmailAddress]
    public string Email { get; set; } = null!;
}

// 3. Controller — ASP.NET binds the request body to CreateUserDto,
//    validates Data Annotations, and provides a strongly typed parameter.
//    [ApiController] returns 400 automatically if validation fails.
[ApiController]
[Route("api/[controller]")]
public class UsersController : ControllerBase
{
    private readonly AppDbContext _db;

    public UsersController(AppDbContext db) => _db = db;

    [HttpPost]
    public async Task<ActionResult<UserResponseDto>> Create([FromBody] CreateUserDto dto)
    {
        var user = new User
        {
            Name = dto.Name,
            Email = dto.Email,
            CreatedAt = DateTime.UtcNow
        };
        _db.Users.Add(user);
        await _db.SaveChangesAsync();

        return Ok(new UserResponseDto { Id = user.Id, Name = user.Name, Email = user.Email });
    }
}

// 4. NSwag generates a typed C# client from the OpenAPI spec.
//    The frontend (Blazor or a separate .NET client) uses it with full type safety.
var client = new UsersClient(httpClient);
var result = await client.CreateAsync(new CreateUserDto { Name = "Alice", Email = "alice@example.com" });
// result.Id, result.Name, result.Email — all typed

Notice what the CLR does for you behind the scenes:

• [FromBody] binding physically constructs a CreateUserDto instance from the JSON body
• Data Annotations are verified by the model binder at request time — the CLR will not call your action with an invalid dto
• The User EF entity is a CLR object. If you assign user.Email = 42, the compiler refuses
• NSwag reads your compiled assembly’s reflection metadata to generate the OpenAPI spec, which is then used to produce a typed client

The C# type system is enforced by the runtime. Types are not descriptions — they are contracts the CLR upholds.

The TypeScript Stack Way

TypeScript’s type system is erased at runtime. This single fact explains almost every architectural decision in this article.

After tsc compiles your TypeScript to JavaScript, every type annotation, every interface, every generic parameter vanishes. The resulting JavaScript has no concept of User, CreateUserDto, or string. What remains is a plain JavaScript object with properties. If JSON comes in from an HTTP request and you tell TypeScript it is a User, TypeScript believes you — because at runtime, TypeScript is not there to disagree.

This is not a flaw to work around. It is the trade-off TypeScript made: a rich, expressive type system at development time, with zero runtime overhead. The consequence is that you must construct your own runtime type enforcement deliberately. Zod is the standard tool for doing so.

Here is the same layered flow, rebuilt in TypeScript:

graph TD
    subgraph dotnet[".NET Stack"]
        D1["EF Model (C# class)"]
        D2["DTO (C# class)"]
        D3["Data Annotations (declarative)"]
        D4["Controller [FromBody]"]
        D5["NSwag → C# client"]
        D6["Blazor/Razor (C# types)"]
        D1 --> D2 --> D3 --> D4 --> D5 --> D6
    end

    subgraph ts["TypeScript Stack"]
        T1["Prisma schema → generated TS types"]
        T2["Zod schema → z.infer<> → TS type"]
        T3["Zod .parse() (runtime validation)"]
        T4["NestJS Pipe + Zod schema"]
        T5["tRPC router → typed client"]
        T6["React component (inferred TS types)"]
        T1 --> T2 --> T3 --> T4 --> T5 --> T6
    end

Each layer of that diagram is a section of this article. We will walk through each one — with complete, runnable code — building a single feature from schema to UI.

The feature: creating and retrieving a user with a name, email, and optional bio. Simple enough to be clear, realistic enough to surface the patterns you actually need.

Layer 1: Database to TypeScript — Prisma Schema

In EF Core, your C# entity class both defines the database schema and provides the CLR type you work with in code. In Prisma, these roles are filled by a schema.prisma file.

// prisma/schema.prisma

generator client {
  provider = "prisma-client-js"
}

datasource db {
  provider = "postgresql"
  url      = env("DATABASE_URL")
}

model User {
  id        Int      @id @default(autoincrement())
  name      String   @db.VarChar(100)
  email     String   @unique @db.VarChar(255)
  bio       String?
  createdAt DateTime @default(now())
  updatedAt DateTime @updatedAt
}

After running prisma generate, the Prisma CLI generates a fully typed client from this schema. You never write the TypeScript types for your database models — they are derived from the schema automatically.

// This type is generated by Prisma — you do not write it manually
// It mirrors the model definition exactly
type User = {
  id: number;
  name: string;
  email: string;
  bio: string | null;  // Optional fields become T | null in Prisma
  createdAt: Date;
  updatedAt: Date;
};

The Prisma client then gives you typed query methods:

import { PrismaClient } from '@prisma/client';

const prisma = new PrismaClient();

// Return type is inferred as User | null — equivalent to .FindAsync() in EF
const user = await prisma.user.findUnique({ where: { id: 1 } });

// Return type is inferred as User[]
const users = await prisma.user.findMany({
  where: { email: { contains: '@example.com' } },
  orderBy: { createdAt: 'desc' },
});

This is the .NET equivalent: EF’s DbSet<User> mapped to a User class, with LINQ providing typed queries. The key difference is that Prisma derives the types from the schema file, while EF Core derives the schema from the C# class. Neither approach is superior — they solve the same problem from opposite directions.

EF Core vs. Prisma at a glance:

Layer 2: The Zod Schema — Where Types Meet Runtime

This is the core concept of the article. Read this section carefully.

In .NET, your DTO class serves two purposes simultaneously:

1. It declares the type — the C# class definition tells the compiler what shape the object has
2. It carries validation rules — Data Annotations like [Required], [StringLength], [EmailAddress] declare what constitutes a valid value

Both happen in one class because the CLR can inspect the class at runtime via reflection. Data Annotations are not erased — they are metadata stored in the compiled assembly.

In TypeScript, you cannot do this with a single interface or type. A TypeScript interface can declare the shape, but at runtime that interface is gone. You need a separate mechanism for runtime validation. Historically, teams used two separate things: a TypeScript interface (for the type) plus a validation library like class-validator or Joi (for the runtime check). This creates duplication: you declare the same shape twice and must keep them synchronized manually.

Zod eliminates this duplication. You define a Zod schema once. From that schema, Zod infers the TypeScript type. You get runtime validation AND compile-time types from a single source of truth.

import { z } from 'zod';

// Define the schema once — this is both your validator AND your type source
const createUserSchema = z.object({
  name: z.string().min(2).max(100),
  email: z.string().email(),
  bio: z.string().max(500).optional(),
});

// Extract the TypeScript type from the schema — no separate interface needed
// This is equivalent to writing the CreateUserDto class in C#
type CreateUserInput = z.infer<typeof createUserSchema>;
// Inferred type:
// {
//   name: string;
//   email: string;
//   bio?: string | undefined;
// }

// Runtime validation — equivalent to Data Annotations being checked by [ApiController]
const result = createUserSchema.safeParse({
  name: 'Alice',
  email: 'not-an-email',
  bio: 'Software engineer',
});

if (!result.success) {
  // result.error is a ZodError with structured field-level errors
  console.log(result.error.flatten());
  // {
  //   fieldErrors: { email: ['Invalid email'] },
  //   formErrors: []
  // }
}

if (result.success) {
  // result.data is typed as CreateUserInput — TypeScript knows the shape
  const { name, email, bio } = result.data;
  // name: string, email: string, bio: string | undefined
}

The two Zod methods you will use constantly:

• schema.parse(data) — validates and returns typed data, or throws a ZodError if invalid. Use inside try/catch blocks or NestJS pipes.
• schema.safeParse(data) — never throws; returns { success: true, data: T } or { success: false, error: ZodError }. Use when you need to handle validation errors gracefully.

Building a richer schema that mirrors FluentValidation:

import { z } from 'zod';

// Equivalent to a FluentValidation AbstractValidator<CreateUserDto>
const createUserSchema = z.object({
  name: z
    .string({ required_error: 'Name is required' })
    .min(2, 'Name must be at least 2 characters')
    .max(100, 'Name must not exceed 100 characters')
    .trim(),

  email: z
    .string({ required_error: 'Email is required' })
    .email('Must be a valid email address')
    .toLowerCase(),

  bio: z
    .string()
    .max(500, 'Bio must not exceed 500 characters')
    .optional(),

  // Equivalent to [Range(18, 120)] in Data Annotations
  age: z
    .number()
    .int('Age must be a whole number')
    .min(18, 'Must be at least 18 years old')
    .max(120)
    .optional(),
});

// You can also define a response schema — equivalent to a UserResponseDto
const userResponseSchema = z.object({
  id: z.number().int().positive(),
  name: z.string(),
  email: z.string().email(),
  bio: z.string().nullable(),  // nullable() means string | null (not undefined)
  createdAt: z.string().datetime(),
});

// Types inferred from the schemas
type CreateUserInput = z.infer<typeof createUserSchema>;
type UserResponse = z.infer<typeof userResponseSchema>;

// Transformations — equivalent to [FromBody] + AutoMapper mapping in one step
const createUserSchema = z.object({
  name: z.string().min(2).max(100).trim(),
  email: z.string().email().toLowerCase().trim(),
  bio: z.string().max(500).optional(),
}).transform((data) => ({
  ...data,
  // Any transform applied during parsing
  displayName: data.name.split(' ')[0],
}));

Where to put your schemas in a monorepo:

In a monorepo with a shared package, schemas that are used on both the frontend and backend belong in a shared location:

packages/
  shared/
    src/
      schemas/
        user.schema.ts      // createUserSchema, userResponseSchema
        product.schema.ts
      index.ts
apps/
  api/                      // NestJS — imports from @repo/shared
  web/                      // Next.js — imports from @repo/shared

This gives you the equivalent of sharing FluentValidation rules between a .NET API and a Blazor WebAssembly frontend — the same validation logic runs on both sides. In .NET this is hard because your validation lives in C# and your frontend is likely a different language. In a TypeScript monorepo, the shared validation is automatic.

Layer 3: API Validation with NestJS Pipes

NestJS pipes are the equivalent of ASP.NET Core’s model binding pipeline. A pipe receives the raw request data (already parsed from JSON by the NestJS framework), validates it, transforms it, and hands the result to your controller action.

Without a validation pipe, your controller receives any. With a Zod pipe, it receives a correctly typed, validated object.

Here is the Zod pipe implementation:

// src/common/pipes/zod-validation.pipe.ts
import {
  PipeTransform,
  Injectable,
  ArgumentMetadata,
  BadRequestException,
} from '@nestjs/common';
import { ZodSchema, ZodError } from 'zod';

@Injectable()
export class ZodValidationPipe implements PipeTransform {
  constructor(private readonly schema: ZodSchema) {}

  transform(value: unknown, _metadata: ArgumentMetadata) {
    const result = this.schema.safeParse(value);

    if (!result.success) {
      // Format Zod errors into a structure the frontend can consume
      const errors = this.formatZodErrors(result.error);
      throw new BadRequestException({
        message: 'Validation failed',
        errors,
      });
    }

    return result.data;
  }

  private formatZodErrors(error: ZodError) {
    return error.errors.map((e) => ({
      path: e.path.join('.'),
      message: e.message,
      code: e.code,
    }));
  }
}