Express + TypeScript Starter Guide for APIs

Overview

If you want a dependable Express TypeScript starter, the goal is not to type every line as aggressively as possible. The goal is to create a backend setup that stays easy to understand, easy to refactor, and hard to accidentally break.

A good typescript api express starter usually includes five things:

• A clear runtime entry point
• A strict but realistic tsconfig.json
• Typed route handlers and shared API shapes
• Runtime validation for external input
• Predictable error handling and logging

That combination matters because Express sits at a boundary layer. Incoming requests are untrusted. Query strings are loosely typed. Route params are strings. Request bodies may or may not match what your code expects. TypeScript helps with developer confidence, but by itself it does not validate runtime input.

A maintainable starter also avoids overengineering. For many teams, a strong baseline looks like this:

src/
  app.ts
  server.ts
  routes/
    users.routes.ts
  controllers/
    users.controller.ts
  services/
    users.service.ts
  middleware/
    error-handler.ts
    not-found.ts
  schemas/
    user.schema.ts
  types/
    api.ts
  config/
    env.ts

This structure keeps responsibilities separate without creating too many layers. Routes define HTTP concerns. Controllers translate request to application calls. Services hold business logic. Middleware handles cross-cutting behavior. Shared types stay explicit.

A basic Express starter often begins with two files:

// src/app.ts
import express from 'express';
import { usersRouter } from './routes/users.routes';
import { notFound } from './middleware/not-found';
import { errorHandler } from './middleware/error-handler';

export const app = express();

app.use(express.json());
app.use('/users', usersRouter);
app.use(notFound);
app.use(errorHandler);

// src/server.ts
import { app } from './app';

const port = process.env.PORT || 3000;

app.listen(port, () => {
  console.log(`API listening on port ${port}`);
});

Keep the app setup separate from the server startup. That small decision makes testing easier because you can import the app without starting a network listener.

For TypeScript settings, prefer a strict baseline and relax only where needed:

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "NodeNext",
    "moduleResolution": "NodeNext",
    "rootDir": "src",
    "outDir": "dist",
    "strict": true,
    "noUncheckedIndexedAccess": true,
    "exactOptionalPropertyTypes": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true
  },
  "include": ["src"]
}

If you run into import or module edge cases, it is worth reviewing a dedicated guide on TypeScript module resolution errors. Those issues are common in Node projects and can make an otherwise simple starter feel unstable.

For API shapes, define explicit types instead of relying on inferred anonymous objects everywhere:

// src/types/api.ts
export type ApiSuccess<T> = {
  success: true;
  data: T;
};

export type ApiError = {
  success: false;
  error: {
    code: string;
    message: string;
  };
};

This pattern makes response contracts easier to share across controllers, tests, and clients. If you want to go deeper on this, see How to Type API Responses in TypeScript Without Lying to the Compiler.

One of the most important parts of any express request type typescript setup is being honest about what TypeScript can and cannot guarantee. Type annotations can describe what your code expects after parsing and validation. They cannot prove that an unknown HTTP payload already matches your interface.

That is why a realistic starter uses both static types and runtime validation:

// src/schemas/user.schema.ts
import { z } from 'zod';

export const createUserSchema = z.object({
  email: z.string().email(),
  name: z.string().min(1)
});

export type CreateUserInput = z.infer<typeof createUserSchema>;

You do not have to use Zod specifically, but you should use some validation approach for request bodies, params, and query values that matter. For comparison points, see Zod vs io-ts vs Valibot vs Yup for TypeScript Runtime Validation.

Then wire validation into a controller:

// src/controllers/users.controller.ts
import { Request, Response, NextFunction } from 'express';
import { createUserSchema } from '../schemas/user.schema';
import { createUser } from '../services/users.service';

export async function createUserHandler(
  req: Request,
  res: Response,
  next: NextFunction
) {
  try {
    const input = createUserSchema.parse(req.body);
    const user = await createUser(input);

    res.status(201).json({
      success: true,
      data: user
    });
  } catch (error) {
    next(error);
  }
}

This is simple, explicit, and maintainable. It avoids pretending that req.body is safe before validation. That one habit prevents many subtle bugs in a node api typescript codebase.

Maintenance cycle

A starter is not finished when it compiles. It stays useful only if you review it on a schedule. The most practical maintenance cycle for an Express + TypeScript starter is quarterly or at least twice a year, depending on how often your team creates new API projects from it.

During each review cycle, check these layers in order:

1. Node and package compatibility
2. TypeScript compiler configuration
3. Express middleware and request typing conventions
4. Validation, error handling, and logging patterns
5. Developer experience: scripts, linting, testing, and local setup

Here is a lightweight maintenance checklist you can actually use:

1. Confirm the runtime assumptions

Make sure your starter still reflects your preferred Node runtime, module format, and local development workflow. If your team uses native ESM, make sure the starter is not quietly mixing CommonJS-era assumptions into imports, build scripts, or test setup. If you are unsure where to start, compare your baseline with a current Node.js + TypeScript setup.

2. Review tsconfig drift

Many starters accumulate old compiler options because they were copied forward from previous projects. Review whether each option still serves a purpose. In practice, stale config often shows up in:

• Outdated module or moduleResolution values
• Path alias settings that no longer match runtime execution
• Options disabled long ago to work around one temporary issue

If your starter relies on aliases, verify that TypeScript, your runtime, test runner, and build tooling all agree. For that workflow, the TypeScript path aliases guide is a useful reference.

3. Re-check route typing patterns

Express typing gets messy when teams alternate between strongly typed handlers and loosely typed any-based shortcuts. A maintenance review is a good time to standardize how you type:

• Route params
• Request bodies after validation
• Query strings
• Response payloads
• Custom request properties such as req.user

For example, params can be typed directly:

type UserParams = {
  userId: string;
};

export async function getUserHandler(
  req: Request<UserParams>,
  res: Response
) {
  const { userId } = req.params;
  res.json({ success: true, data: { userId } });
}

But if your application starts attaching authenticated user data to the request, avoid scattering custom type assertions everywhere. Instead, centralize the augmentation pattern so developers know where that type comes from.

4. Audit middleware order

Middleware order is one of the easiest things to break during incremental edits. On each maintenance pass, verify that your starter still applies middleware in a sensible sequence:

• Request parsing
• Security or CORS-related middleware if applicable
• Authentication
• Route registration
• Not-found handler
• Central error handler

This sounds basic, but bad ordering can create confusing runtime behavior that TypeScript will not catch.

5. Review linting and formatting

Your starter should make the correct patterns easy to follow. If your lint config is outdated or too noisy, developers will ignore it. A good maintenance cycle includes checking that the project still works well with your current linting approach. If you are standardizing around modern ESLint setup, revisit ESLint + TypeScript Flat Config.

6. Keep sample code small and representative

A starter should include enough examples to teach the house style, but not so many that it turns into a partial application. One or two representative resources, such as users and health, are usually enough to demonstrate routing, validation, service calls, and error handling.

Signals that require updates

You do not need to wait for a scheduled review if your starter is showing signs of drift. Some signals suggest the template needs immediate attention.

Repeated copy-paste fixes across new projects

If every new API starts with the same cleanup work, your starter is already outdated. Common examples include replacing broken scripts, updating import syntax, fixing body typing, or patching environment variable handling.

Frequent type assertions around requests

If developers keep writing req.body as Something or (req.user as AuthUser), the starter is probably missing a safer pattern. That usually means validation is not integrated cleanly, or shared request types are not documented well enough.

Growing disagreement about interface vs type usage

This does not sound like an API issue at first, but inconsistent type authoring quickly affects route contracts, DTOs, and middleware extensions. If your codebase is mixing conventions arbitrarily, pause and document the current rule of thumb. For background, see Interface vs Type in TypeScript.

Starter-specific setup docs are longer than the code

If onboarding requires a long list of caveats, hidden assumptions, and manual fixes, your starter is carrying too much historical baggage. A good starter should explain a few decisions, not require a survival guide.

Search intent around Express + TypeScript has shifted

This is especially important for a resource meant to be revisited. If readers now expect clearer guidance on runtime validation, typed error handling, ESM setup, or monorepo compatibility, your article and starter should evolve with that. Search behavior changes what “starter guide” means over time.

Your application architecture has moved beyond the starter

When teams begin sharing packages across services, the original single-app starter may no longer reflect reality. At that point, it may need a companion guide for monorepos, shared types, or project references. If that applies to your team, bookmark the TypeScript monorepo setup guide.

Common issues

Most Express + TypeScript problems are not advanced. They come from a few recurring mismatches between runtime behavior and type expectations. A good starter anticipates them.

Issue: treating request bodies as trusted objects

This is the classic mistake in many express typescript example projects. A route handler assumes req.body already matches the intended shape because TypeScript says so. But the incoming payload may be missing fields, contain wrong types, or include extra data.

Better pattern: validate first, derive the trusted type from the schema, and only then pass the parsed input into services.

Issue: custom request properties are untyped

Authentication middleware often sets values such as req.user. Without a consistent typing strategy, downstream handlers fall back to type assertions or unsafe optional access. Over time, that weakens confidence across the codebase.

Better pattern: define the extension once and make the authenticated route boundary explicit. If needed, create helper middleware or wrapper functions that narrow the request type after auth succeeds.

Issue: inconsistent async error handling

Some handlers use try/catch, others throw directly, and others forget to pass errors to the central handler. That inconsistency creates debugging friction.

Better pattern: choose one convention and apply it everywhere. For many teams, explicit try/catch with next(error) remains the clearest baseline for a starter because it is easy to read and hard to misunderstand.

Issue: environment variables are used without validation

process.env values are strings or undefined. If your starter reads them casually throughout the app, errors surface late and unpredictably.

Better pattern: validate environment variables at startup in one module and export a typed config object.

// src/config/env.ts
import { z } from 'zod';

const envSchema = z.object({
  PORT: z.string().default('3000')
});

export const env = envSchema.parse(process.env);

Issue: module resolution confusion

Import path errors, ESM/CJS friction, and missing type declarations are common in backend TypeScript projects. These issues are frustrating because they often appear unrelated to your API logic.

Better pattern: keep the starter conservative, documented, and aligned with one runtime story. If problems appear, work through them systematically instead of layering workarounds. Two useful references are missing type errors and module resolution errors.

Issue: response types drift from real output

It is easy to declare a clean response type and then forget to update it when controller behavior changes. That creates false confidence for maintainers and client code.

Better pattern: keep response shapes simple, centralize common wrappers, and test representative endpoints. The less decorative your response contracts are, the easier they are to keep honest.

When to revisit

If you treat your starter as a living reference rather than a one-time scaffold, it becomes much more valuable. Revisit this topic on a regular schedule and after meaningful tooling changes.

A practical rule is to revisit your Express + TypeScript starter when any of the following happens:

• You start a new API project
• You upgrade Node or TypeScript
• You change validation libraries or middleware conventions
• You adopt a new linting or testing setup
• You notice repeated debugging pain in request typing or error handling
• You move from a single service to a shared package or monorepo model

When you revisit, do not try to redesign everything. Walk through this short action list:

1. Run the starter from scratch on a clean machine or container.
2. Create one sample route with params, query, body validation, and a typed response.
3. Confirm your error handler catches both validation failures and unexpected exceptions.
4. Check whether custom request properties are typed without repetitive assertions.
5. Review tsconfig.json, scripts, and import paths for drift.
6. Remove any patterns that exist only for historical reasons.

If your team also works in frontend frameworks, it can help to keep your backend conventions aligned with your broader TypeScript approach. For example, the same emphasis on explicit contracts and type-safe boundaries appears in this Next.js + TypeScript guide.

The real value of an express typescript starter is not speed alone. It is consistency. A starter that gives every new API the same clear layout, validation story, error strategy, and type boundaries reduces decision fatigue and makes debugging easier months later. That is why this topic is worth revisiting: the starter is small, but the habits it encodes affect every project built on top of it.