/netlify-server

name: netlify-server
description: Build and deploy a long-lived Node.js backend on Netlify Server (Early Access) from netlify/server/index.ts. Use this skill whenever someone wants to run an Express, Fastify, Hono or Koa app on Netlify as it is, add a backend or REST/GraphQL API that keeps database pools and caches warm, build real-time features such as chat, live dashboards or multiplayer with WebSockets or Server-Sent Events, or stream AI responses and run agent loops. It also covers background work after responding with waitUntil, startup and graceful shutdown hooks, load-aware health checks, edge caching of server responses, region/size/scale settings, local testing with netlify dev, reading server logs with netlify logs or log drains, and debugging a server that gets no requests, fails to start, drops database connections after a minute, or returns 429/500/501/502.

Netlify Server

Early Access, so APIs may change. It is available on credit-based plans and on Enterprise plans with credits enabled. It requires **Node.js 24+** for both build and local dev, and **Netlify CLI 27.17.0+** for both local dev and deploys.

It is free during Early Access and intended for evaluation, experimentation, and low-volume production use. At GA it will bill credits for reserved memory (GB-hours) and active CPU (vCPU-hours). **Every request the server handles already counts toward the web requests meter.**

Reach for this / avoid this

// ✅ netlify/server/index.ts — handler (same signature as Netlify Functions)
import type { Context, Config } from "@netlify/server";
export default async (req: Request, context: Context) =>
  new Response(`Hello from ${context.geo.city ?? "somewhere"}`);
export const config: Config = { path: "/api/*" };

// ✅ Fetchable app (Hono etc.): export as is
export default app;
// ✅ Node request listener: wrap it, do NOT call listen(). WebSockets work.
export default createServer(handleRequest);
// ✅ Framework that starts itself (Express/Fastify): listen on PORT within 10 s
app.listen(process.env.PORT);

// ❌ export default (req, res) => {...}   // two params = treated as a fetch handler, breaks
// ❌ export default expressApp            // works, but WebSocket upgrades get 501
// ❌ server.close(() => process.exit(0))  // cuts off shutdown hooks and background work
// ❌ setInterval / fire-and-forget promise // invisible to Netlify; the instance can stop mid-work

You don't configure ports, add health endpoints, or install adapters. Install the package with `npm install @netlify/server`.

Entry file and detection

• Use **one** server per project: `netlify/server/index.ts`, `.mts`, `.js`, or `.mjs`. **The build fails if more than one exists.**
• Startup runs once per instance:

1. `PORT` is set. 2. The entry file is imported, running top-level code (top-level `await` is awaited). 3. `onStart` hooks run in order. 4. The default export is inspected.

• No traffic arrives until all steps finish. Any throw fails the start.

Netlify uses the **first matching row** for the default export:

| Default export | Run as | WebSockets | |---|---|---| | `http.Server` without `listen()` | Requests sent to it | `upgrade` event (`ws`, Socket.IO) | | Object with `fetch` (Fetchable, e.g. Hono) | `fetch(request, context)` | `upgradeWebSocket` | | Express/Connect app, or a function with ≥3 params | Wrapped in its own HTTP server | **501** | | Any other function | `(request, context) => Response` | `upgradeWebSocket` | | Anything else / nothing | Waits for your code to listen | `upgrade` event |

> ⚠️ **Self-started servers must listen within 10 s after start hooks finish.** > - If your code starts several servers, the one on `process.env.PORT` wins. If none listens on it, the start fails. > - Reserved ports are `53` and `15000–15099`. > - Only Node.js HTTP servers are supported, not raw TCP.

Create shared resources such as a DB pool at top level so they are reused across requests.

> ⚠️ **Outbound connections are closed after 60 s without data in either direction.** TCP keepalives don't count. > - Set your pool's idle timeout **below 60 s** (e.g. `idleTimeoutMillis: 30_000`), or it hands out dead connections. > - Quiet connections such as Postgres `LISTEN` need traffic at least every 60 s (e.g. `SELECT 1`), or must reconnect on close. The symptom is `Connection terminated unexpectedly`.

Examples

// netlify/server/index.mjs — Express, self-started
import express from "express";
import { getContext } from "@netlify/server";
const app = express();
app.get("/api/hello", (req, res) => {
  const { geo } = getContext();
  res.json({ message: `Hello from ${geo.city ?? "somewhere"}` });
});
app.listen(process.env.PORT || 3000);

// Fastify
const app = Fastify();
app.get("/api/hello", async () => ({ message: `Hello from ${getContext().geo.city ?? "somewhere"}` }));
await app.listen({ port: Number(process.env.PORT) || 3000 });

Background work after responding

export default async (req: Request, context: Context) => {
  const order = await saveOrder(await req.json());
  context.waitUntil(sendConfirmationEmail(order)); // keeps the instance alive until settled
  return Response.json(order, { status: 201 });
};
// In frameworks: const { waitUntil } = getContext();

How `waitUntil` behaves:

• It is not bound by the request duration limit.
• Rejections are logged.
• On replacement, background work gets up to 90 s. Persist critical work to Netlify Database or Netlify Blobs.

WebSockets (handler/Fetchable)

import { upgradeWebSocket } from "@netlify/server";
export default async (req: Request) => {
  if (req.headers.get("upgrade") === "websocket") {
    const { socket, response } = upgradeWebSocket(req, { idleTimeout: 30 }); // pings off unless set
    socket.onmessage = (e) => socket.send(`Echo: ${e.data}`);
    return response; // return as is
  }
  return new Response("Connect with a WebSocket client");
};

###