Noções Básicas de Express

Q: O Express 5 está pronto para produção?

Sim no Node 24 LTS. É a versão principal latest atual do npm. Migre do Express 4 usando os padrões do guia de migração oficial em Migração para Express 5.

Q: Devo usar app.listen ou http.createServer?

app.listen é bom para a maioria dos aplicativos. Use createServer(app) quando precisar de acesso direto ao servidor subjacente para upgrades de WebSocket ou ajuste de tempo limite.

Q: Como estruturar um aplicativo Express grande?

Routers por domínio (/users, /orders), serviços para lógica de negócios, app.ts e server.ts separados. Veja Melhores Práticas do Express.

Q: O Express suporta ESM?

Sim. Defina "type": "module" em package.json e use import express from "express".

10 exemplos para construir sua primeira API Express 5 - 7 básicos e 3 intermediários.

Pré-requisitos

mkdir express-api && cd express-api
npm init -y
npm pkg set type=module
npm install express@5
npm install -D typescript@5.6 tsx @types/express @types/node

Para ordenação de middleware e reforço de segurança, consulte Ordenação de Middleware e Middleware de Segurança.

Exemplos Básicos

1. Servidor Hello World

import express from "express";
 
const app = express();
const port = 3000;
 
app.get("/", (_req, res) => {
  res.send("Hello from Express 5\n");
});
 
app.listen(port, () => {
  console.log(`http://localhost:${port}`);
});

app é uma função que envolve http.createServer do Node
res.send() define Content-Type automaticamente com base na carga útil
Express 5 requer Node 18+; use Node 24 LTS em produção

2. Análise de Corpo JSON

import express from "express";
 
const app = express();
app.use(express.json({ limit: "1mb" }));
 
app.post("/users", (req, res) => {
  const { name, email } = req.body;
  res.status(201).json({ id: 1, name, email });
});

express.json() deve ser registrado antes das rotas que leem req.body
Defina limit para evitar ataques de carga útil grandes
Fastify inclui análise JSON por padrão com validação de esquema

3. Parâmetros de Rota

import express from "express";
 
const app = express();
 
app.get("/users/:id", (req, res) => {
  const { id } = req.params;
  res.json({ id, name: "Ada Lovelace" });
});

req.params contém segmentos de rota nomeados
Express 5 alterou a sintaxe de roteamento wildcard - veja Migração para Express 5
Valide o formato id no manipulador ou em um middleware de validação

4. Strings de Consulta

import express from "express";
 
const app = express();
 
app.get("/search", (req, res) => {
  const q = req.query.q as string | undefined;
  const page = Number(req.query.page ?? 1);
  res.json({ q, page, results: [] });
});

req.query é analisado automaticamente
Converta valores de consulta em TypeScript; eles chegam como strings ou arrays
Use uma biblioteca de validação (Zod) na fronteira para APIs de produção

5. Router para Rotas Modulares

import express, { Router } from "express";
 
const app = express();
const usersRouter = Router();
 
usersRouter.get("/", (_req, res) => {
  res.json([{ id: 1, name: "Ada" }]);
});
 
usersRouter.get("/:id", (req, res) => {
  res.json({ id: req.params.id });
});
 
app.use("/users", usersRouter);

Router é um mini-aplicativo com sua própria pilha de middleware
Monte routers em prefixos de caminho para organizar APIs grandes
Módulos NestJS servem um propósito de agrupamento semelhante com DI

6. Middleware para Logging de Requisições

import express from "express";
 
const app = express();
 
app.use((req, _res, next) => {
  console.log(`${req.method} ${req.url}`);
  next();
});
 
app.get("/health", (_req, res) => {
  res.json({ status: "ok" });
});

O middleware é executado na ordem de registro
Chame next() para passar o controle para o próximo manipulador
Veja Padrão de Middleware para o padrão subjacente

7. Servindo Arquivos Estáticos

import express from "express";
import { join } from "node:path";
 
const app = express();
 
app.use("/static", express.static(join(import.meta.dirname, "public")));

express.static serve arquivos de um diretório
Coloque o middleware estático antes das rotas da API ou use um prefixo de caminho dedicado
Em produção, nginx ou uma CDN geralmente servem ativos estáticos em vez disso

Exemplos Intermediários

8. Manipuladores de Rota Assíncronos (Express 5)

import express from "express";
 
const app = express();
 
app.get("/users/:id", async (req, res) => {
  const user = await findUser(req.params.id);
  if (!user) {
    res.status(404).json({ error: "Not found" });
    return;
  }
  res.json(user);
});
 
async function findUser(id: string) {
  if (id === "999") return null;
  return { id, name: "Ada" };
}

Express 5 encaminha promessas rejeitadas para o middleware de erro automaticamente
Express 4 exigia express-async-errors ou invólucros try/catch manuais
Sempre retorne após enviar respostas de erro para evitar envio duplo

9. Middleware de Erro

import express, { type Request, type Response, type NextFunction } from "express";
 
const app = express();
 
app.get("/fail", () => {
  throw new Error("Something broke");
});
 
app.use((err: Error, _req: Request, res: Response, _next: NextFunction) => {
  console.error(err);
  res.status(500).json({ error: "Internal server error" });
});

O middleware de erro tem 4 parâmetros: (err, req, res, next)
Registre-o após todas as rotas
Nunca exponha rastros de pilha para clientes em produção

10. Configuração Baseada em Ambiente

import express from "express";
 
const app = express();
const port = Number(process.env.PORT ?? 3000);
const isDev = process.env.NODE_ENV !== "production";
 
if (isDev) {
  app.use((req, _res, next) => {
    console.log(`[dev] ${req.method} ${req.path}`);
    next();
  });
}
 
app.get("/health", (_req, res) => {
  res.json({ env: process.env.NODE_ENV ?? "development" });
});
 
app.listen(port);

Use PORT do ambiente (Heroku, Railway, K8s definem isso)
Limite o middleware de depuração com base em NODE_ENV
Veja Noções Básicas de Configuração para validação de esquema

FAQs

O Express 5 está pronto para produção?

Sim no Node 24 LTS. É a versão principal latest atual do npm. Migre do Express 4 usando os padrões do guia de migração oficial em Migração para Express 5.

Express vs Fastify para um novo projeto?

Express se a familiaridade da equipe e o tamanho do ecossistema forem mais importantes. Fastify se a taxa de transferência e a validação de esquema JSON forem prioridades. Veja ADR Fastify vs Express.

Devo usar `app.listen` ou `http.createServer`?

app.listen é bom para a maioria dos aplicativos. Use createServer(app) quando precisar de acesso direto ao servidor subjacente para upgrades de WebSocket ou ajuste de tempo limite.

Como estruturar um aplicativo Express grande?

Routers por domínio (/users, /orders), serviços para lógica de negócios, app.ts e server.ts separados. Veja Melhores Práticas do Express.

O Express suporta ESM?

Sim. Defina "type": "module" em package.json e use import express from "express".

Relacionados

Ordenação de Middleware - sequência de registro
Tratamento de Erros no Express - erros assíncronos e síncronos
Middleware de Segurança - helmet, cors, limites de taxa
Noções Básicas de Fastify - alternativa de desempenho
Melhores Práticas do Express - lista de verificação da seção

Versões da Stack: Esta página foi escrita para Node.js 24.18.0 (LTS Ativo), npm 10+, TypeScript 5.6+, Express 5, Fastify 5 e NestJS 11.

Pré-requisitos

mkdir express-api && cd express-api
npm init -y
npm pkg set type=module
npm install express@5
npm install -D typescript@5.6 tsx @types/express @types/node

Para ordenação de middleware e reforço de segurança, consulte Ordenação de Middleware e Middleware de Segurança.

Exemplos Básicos

1. Servidor Hello World

import express from "express";
 
const app = express();
const port = 3000;
 
app.get("/", (_req, res) => {
  res.send("Hello from Express 5\n");
});
 
app.listen(port, () => {
  console.log(`http://localhost:${port}`);
});

app é uma função que envolve http.createServer do Node
res.send() define Content-Type automaticamente com base na carga útil
Express 5 requer Node 18+; use Node 24 LTS em produção

2. Análise de Corpo JSON

import express from "express";
 
const app = express();
app.use(express.json({ limit: "1mb" }));
 
app.post("/users", (req, res) => {
  const { name, email } = req.body;
  res.status(201).json({ id: 1, name, email });
});

express.json() deve ser registrado antes das rotas que leem req.body
Defina limit para evitar ataques de carga útil grandes
Fastify inclui análise JSON por padrão com validação de esquema

3. Parâmetros de Rota

import express from "express";
 
const app = express();
 
app.get("/users/:id", (req, res) => {
  const { id } = req.params;
  res.json({ id, name: "Ada Lovelace" });
});

req.params contém segmentos de rota nomeados
Express 5 alterou a sintaxe de roteamento wildcard - veja Migração para Express 5
Valide o formato id no manipulador ou em um middleware de validação

4. Strings de Consulta

import express from "express";
 
const app = express();
 
app.get("/search", (req, res) => {
  const q = req.query.q as string | undefined;
  const page = Number(req.query.page ?? 1);
  res.json({ q, page, results: [] });
});

req.query é analisado automaticamente
Converta valores de consulta em TypeScript; eles chegam como strings ou arrays
Use uma biblioteca de validação (Zod) na fronteira para APIs de produção

5. Router para Rotas Modulares

import express, { Router } from "express";
 
const app = express();
const usersRouter = Router();
 
usersRouter.get("/", (_req, res) => {
  res.json([{ id: 1, name: "Ada" }]);
});
 
usersRouter.get("/:id", (req, res) => {
  res.json({ id: req.params.id });
});
 
app.use("/users", usersRouter);

Router é um mini-aplicativo com sua própria pilha de middleware
Monte routers em prefixos de caminho para organizar APIs grandes
Módulos NestJS servem um propósito de agrupamento semelhante com DI

6. Middleware para Logging de Requisições

import express from "express";
 
const app = express();
 
app.use((req, _res, next) => {
  console.log(`${req.method} ${req.url}`);
  next();
});
 
app.get("/health", (_req, res) => {
  res.json({ status: "ok" });
});

O middleware é executado na ordem de registro
Chame next() para passar o controle para o próximo manipulador
Veja Padrão de Middleware para o padrão subjacente

7. Servindo Arquivos Estáticos

import express from "express";
import { join } from "node:path";
 
const app = express();
 
app.use("/static", express.static(join(import.meta.dirname, "public")));

express.static serve arquivos de um diretório
Coloque o middleware estático antes das rotas da API ou use um prefixo de caminho dedicado
Em produção, nginx ou uma CDN geralmente servem ativos estáticos em vez disso

Exemplos Intermediários

8. Manipuladores de Rota Assíncronos (Express 5)

import express from "express";
 
const app = express();
 
app.get("/users/:id", async (req, res) => {
  const user = await findUser(req.params.id);
  if (!user) {
    res.status(404).json({ error: "Not found" });
    return;
  }
  res.json(user);
});
 
async function findUser(id: string) {
  if (id === "999") return null;
  return { id, name: "Ada" };
}

Express 5 encaminha promessas rejeitadas para o middleware de erro automaticamente
Express 4 exigia express-async-errors ou invólucros try/catch manuais
Sempre retorne após enviar respostas de erro para evitar envio duplo

9. Middleware de Erro

import express, { type Request, type Response, type NextFunction } from "express";
 
const app = express();
 
app.get("/fail", () => {
  throw new Error("Something broke");
});
 
app.use((err: Error, _req: Request, res: Response, _next: NextFunction) => {
  console.error(err);
  res.status(500).json({ error: "Internal server error" });
});

O middleware de erro tem 4 parâmetros: (err, req, res, next)
Registre-o após todas as rotas
Nunca exponha rastros de pilha para clientes em produção

10. Configuração Baseada em Ambiente

import express from "express";
 
const app = express();
const port = Number(process.env.PORT ?? 3000);
const isDev = process.env.NODE_ENV !== "production";
 
if (isDev) {
  app.use((req, _res, next) => {
    console.log(`[dev] ${req.method} ${req.path}`);
    next();
  });
}
 
app.get("/health", (_req, res) => {
  res.json({ env: process.env.NODE_ENV ?? "development" });
});
 
app.listen(port);

Use PORT do ambiente (Heroku, Railway, K8s definem isso)
Limite o middleware de depuração com base em NODE_ENV
Veja Noções Básicas de Configuração para validação de esquema

FAQs

O Express 5 está pronto para produção?

Sim no Node 24 LTS. É a versão principal latest atual do npm. Migre do Express 4 usando os padrões do guia de migração oficial em Migração para Express 5.

Express vs Fastify para um novo projeto?

Devo usar `app.listen` ou `http.createServer`?

app.listen é bom para a maioria dos aplicativos. Use createServer(app) quando precisar de acesso direto ao servidor subjacente para upgrades de WebSocket ou ajuste de tempo limite.

Como estruturar um aplicativo Express grande?

Routers por domínio (/users, /orders), serviços para lógica de negócios, app.ts e server.ts separados. Veja Melhores Práticas do Express.

O Express suporta ESM?

Sim. Defina "type": "module" em package.json e use import express from "express".

Relacionados

Ordenação de Middleware - sequência de registro
Tratamento de Erros no Express - erros assíncronos e síncronos
Middleware de Segurança - helmet, cors, limites de taxa
Noções Básicas de Fastify - alternativa de desempenho
Melhores Práticas do Express - lista de verificação da seção

Versões da Stack: Esta página foi escrita para Node.js 24.18.0 (LTS Ativo), npm 10+, TypeScript 5.6+, Express 5, Fastify 5 e NestJS 11.

Noções Básicas de Express

Buscar na documentação

Noções Básicas de Express