Skip to main content
Express is a minimalist and flexible web framework for Node.js, designed to simplify and streamline the building of APIs and web applications. It provides a lightweight routing system, middleware support, and a straightforward API that gives developers full control without unnecessary complexity. Express is widely used due to its ease of use, large ecosystem of plugins, and compatibility with virtually any Node.js architecture, making it a popular choice for both small projects and large-scale applications. Express can only be used on Application Hosting; it cannot be deployed as a static site.

​
Configuration

With Express, you can either compile TypeScript to JavaScript for production or run TypeScript directly.
  • Sevalla will run npm run build followed by npm start
  • Provides faster startup and better runtime performance
Examplepackage.json: 
{
  "scripts": {
    "start": "node dist/index.js",
    "build": "tsc",
    "dev": "tsx watch src/index.ts"
  }
}

​
Run TypeScript directly

  • Sevalla will run npm start using tsx or ts-node
  • Simpler setup with no build step.
Examplepackage.json: 
{
  "scripts": {
    "start": "tsx src/index.ts",
    "dev": "tsx watch src/index.ts"
  }
}

​
Containerization

​
Dockerfile

The build for Dockerfiles is fully customizable. We recommend the following best practices when using a Dockerfile for Express on Sevalla:
  • Use Alpine images - Smaller image size (~40MB vs ~900MB).
  • Multi-stage builds - Separate build and runtime dependencies.
  • Layer caching - Copy package.json before the source code.
  • Security - Run as a non-root user in production.
  • .dockerignore - Exclude unnecessary files.
The following is an example Dockerfile for Express: 
# Build stage
FROM node:lts-alpine AS builder

WORKDIR /app

COPY package.json package-lock.json* ./
RUN npm ci

COPY . .
RUN npm run build

# Production stage
FROM node:lts-alpine

WORKDIR /app

COPY package.json package-lock.json* ./
RUN npm ci --only=production

COPY --from=builder /app/dist ./dist

EXPOSE 3000

ENV PORT=3000
ENV HOST=0.0.0.0
ENV NODE_ENV=production

CMD ["node", "dist/index.js"]

​
Nixpacks

Nixpacks offers less customization than Dockerfiles, but you can still adjust the build process by creating a nixpacks.toml file and using Nixpacks-specific environment variables. This allows you to fine-tune how dependencies are installed, how your application is built, and which runtime settings are applied. You can control the Node.js version used during the build by using an .nvmrc file, the engines field in package.json, or the NIXPACKS_NODE_VERSION environment variable. If none are set, Nixpacks defaults to Node.js 18. We recommend the following best practices when using Nixpacks for Express on Sevalla:
  • Commit lock files - Always include package-lock.json, yarn.lock, or pnpm-lock.yaml for deterministic, reproducible builds.
  • Specify your Node.js version - Use the engines field in package.json or an .nvmrc file to ensure consistent versioning.
  • Use npm ci - Faster and more reliable than npm install in CI/CD environments.
  • Set NODE_ENV=production - Helps optimize performance and reduce bundle size.
  • Test builds locally - Use the Nixpacks CLI to identify build issues before deploying.
  • Keep configuration minimal - Allow Nixpacks to auto-detect your setup; only add a nixpacks.toml file for advanced customization.
  • Optimize TypeScript builds - After compiling, run npm prune --production to remove dev dependencies.
  • Define a startscript - Ensure package.json includes a start script for consistent server startup.
The following is an example nixpacks.toml configuration for Express: 
# nixpacks.toml

[phases.setup]
nixPkgs = ["nodejs_22"]

[phases.install]
cmds = ["npm ci"]

[phases.build]
cmds = ["npm run build"]

[start]
cmd = "npm start"

​
Buildpacks

Buildpacks, automatically detects your project’s lock file and installs dependencies using the appropriate package manager. When using Buildpacks, you cannot directly modify the underlying build phases or control how dependencies are installed; Buildpacks determine this based on your project’s structure and configuration. However, you can influence the final runtime behavior by defining the appropriate start script in your package.json file, which Buildpacks will use when launching your Express application.

​
CDN

Sevalla provides a premium, Cloudflare-powered CDN for Application Hosting at no additional cost. To get the most out of Sevalla’s CDN when deploying your Express application, we recommend the following best practices:
  • Enable the CDN for all production applications.
  • Set appropriate Cache-Control headers on API routes to ensure proper caching behavior.
  • Purge the CDN cache after deploying critical updates to avoid serving stale content.
  • Use versioned URLs for static assets, for example /static/app.v123.js .

​
Optimizing Express for CDN

​
Static files with cache headers

// src/index.ts
import express from "express";
import path from "path";

const app = express();
const PORT = process.env.PORT || 3000;

// Serve static files with caching
app.use(
  "/static",
  express.static(path.join(__dirname, "../public"), {
    maxAge: "1y", // Cache for 1 year
    immutable: true,
    setHeaders: (res, filePath) => {
      res.setHeader("Cache-Control", "public, max-age=31536000, immutable");
    },
  })
);

// API endpoint with shorter cache
app.get("/api/data", (req, res) => {
  const data = { message: "Hello from Express!" };

  res.setHeader("Content-Type", "application/json");
  res.setHeader("Cache-Control", "public, max-age=3600, s-maxage=3600");
  res.json(data);
});

// 404 handler
app.use((req, res) => {
  res.status(404).send("Not Found");
});

app.listen(PORT, () => {
  console.log(`Server running on port ${PORT}`);
});

​
Edge caching

Edge caching stores your Sevalla site cache on Cloudflare’s 260+ global data centers, delivering responses from the location nearest to each visitor for faster performance. To maximize the benefits of Sevalla’s Edge Caching for your Express application, we recommend the following best practices:
  • Set appropriate Cache-Control headers in loaders to control caching behavior.
  • Combine edge caching with the CDN for a complete caching strategy.

​
Optimizing Express for edge caching

// src/index.ts
import express from "express";

const app = express();
const PORT = process.env.PORT || 3000;

// API with edge caching
app.get("/api/products", (req, res) => {
  const products = getProducts(); // Your data fetching logic

  res.setHeader("Content-Type", "application/json");
  res.setHeader("Cache-Control", "public, max-age=60, s-maxage=3600");
  res.json(products);
});

// User-specific data (don't cache)
app.get("/api/user/profile", (req, res) => {
  const userData = { user: "data" };

  res.setHeader("Content-Type", "application/json");
  res.setHeader("Cache-Control", "private, no-cache");
  res.json(userData);
});

app.listen(PORT, () => {
  console.log(`Server running on port ${PORT}`);
});

​
Cache-Control

With Sevalla’s Cloudflare integration,Cache-Controlheaders are respected at the edge, giving you precise control over how content is cached and served globally. The following are some common directives you can use in your Express application:
  • public, s-maxage=3600 - Caches the response on the CDN for 1 hour, improving performance for frequently accessed content.
  • public, max-age=31536000, immutable - Ideal for versioned static assets, allowing them to be cached for up to 1 year with no revalidation.
  • private - Prevents CDN caching and ensures the response is only cached by the end user’s browser, for personalized or sensitive data.
Sevalla does not yet support the stale-while-revalidate Cache-Control directive. To prevent unexpected caching behavior, we recommend not using this directive in your API or asset caching settings.

​
Health checks

Ensure your application remains available during deployments by implementing health checks:
  • Always implement health checks for production applications.
  • Keep checks lightweight; responses should complete in under 1 second.
  • Verify critical dependencies (e.g., databases, Redis) as part of the checks.
  • Return 200 for degraded states to allow deployments to continue smoothly.
  • Return 503 only for critical failures that require pod restarts.

​
Basic health check

// src/index.ts
import express from "express";

const app = express();
const PORT = process.env.PORT || 3000;

app.get("/api/health", (req, res) => {
  res.json({
    status: "ok",
    timestamp: new Date().toISOString(),
    runtime: "Node.js",
    version: process.version,
  });
});

app.listen(PORT, () => {
  console.log(`Server running on port ${PORT}`);
});

​
Graceful shutdown

​Implement graceful shutdown to cleanly close connections during deployments. The following example demonstrates how to implement a graceful shutdown in an Express server by closing HTTP server and database connections safely upon receiving deployment or termination signals: 
// src/index.ts
import express from "express";
import { Server } from "http";
import { pool } from "./lib/db";

const app = express();
const PORT = process.env.PORT || 3000;

// ... your routes

const server: Server = app.listen(PORT, () => {
  console.log(`Server running on port ${PORT}`);
});

// Graceful shutdown
process.on("SIGTERM", async () => {
  console.log("Received SIGTERM, closing connections...");

  // Stop accepting new connections
  server.close(async () => {
    console.log("HTTP server closed");

    // Close database pool
    await pool.end();

    console.log("Server closed gracefully");
    process.exit(0);
  });

  // Force close after 30 seconds
  setTimeout(() => {
    console.error("Forced shutdown after timeout");
    process.exit(1);
  }, 30000);
});

process.on("SIGINT", async () => {
  console.log("Received SIGINT, closing connections...");
  server.close(async () => {
    await pool.end();
    process.exit(0);
  });
});