Node.js Adapter

Relevant source files

• packages/astro/src/core/app/node.ts
• packages/astro/src/core/routing/astro-designed-error-pages.ts
• packages/astro/src/core/routing/priority.ts
• packages/astro/src/vite-plugin-astro-server/response.ts
• packages/astro/test/units/app/node.test.ts
• packages/integrations/node/src/index.ts
• packages/integrations/node/src/log-listening-on.ts
• packages/integrations/node/src/middleware.ts
• packages/integrations/node/src/preview.ts
• packages/integrations/node/src/serve-app.ts
• packages/integrations/node/src/serve-static.ts
• packages/integrations/node/src/server.ts
• packages/integrations/node/src/standalone.ts
• packages/integrations/node/src/types.ts
• packages/integrations/node/test/fixtures/api-route/package.json
• packages/integrations/node/test/fixtures/bad-urls/package.json
• packages/integrations/node/test/fixtures/encoded/package.json
• packages/integrations/node/test/fixtures/errors/package.json
• packages/integrations/node/test/fixtures/headers/package.json
• packages/integrations/node/test/fixtures/image/package.json
• packages/integrations/node/test/fixtures/locals/package.json
• packages/integrations/node/test/fixtures/node-middleware/package.json
• packages/integrations/node/test/fixtures/prerender-404-500/package.json
• packages/integrations/node/test/fixtures/prerender/package.json

Purpose and Scope

The Node.js adapter (@astrojs/node) enables deployment of Astro applications to Node.js environments by transforming Astro's build output into a server application compatible with any Node.js runtime. It supports two operational modes—standalone HTTP server mode and middleware mode for integration with existing Node.js frameworks such as Express or Fastify. Additionally, it provides session management with a default filesystem-based session driver, supports static headers for security (e.g., CSP), and integrates image optimization via Sharp.

This adapter interfaces Astro’s SSR runtime with Node.js-specific HTTP constructs (IncomingMessage and ServerResponse). It also includes features to control request body size limits, HTTP/HTTPS server creation with optional SSL certificate loading, and runtime environment setup for environment variables accessibility.

Sources: packages/integrations/node/src/index.ts10-30 packages/astro/src/core/app/node.ts51-126 packages/integrations/node/src/types.ts3-33

---

Adapter Modes

The adapter operates in two distinct modes, selectable via the mode option in the user configuration packages/integrations/node/src/types.ts3-10

Standalone Mode

In standalone mode, the adapter generates a complete HTTP/HTTPS server that listens on a configured host and port. This server handles requests for static assets and prerendered pages via a static file handler, falling back to Astro's SSR rendering for dynamic requests. This mode allows the built script itself to launch the server.

The standalone server supports:

• Serving static files and prerendered pages with proper trailing slash handling packages/integrations/node/src/serve-static.ts91-122
• Applies CSP and other security headers from a generated static headers JSON file packages/integrations/node/src/serve-static.ts70-89
• Creation of HTTP or HTTPS servers including automatic loading of SSL certificates if SERVER_CERT_PATH and SERVER_KEY_PATH environment variables are set packages/integrations/node/src/standalone.ts74-84
• Listening to the port defined by environment or config with clean server destruction via server-destroy packages/integrations/node/src/standalone.ts25-85

Sources: packages/integrations/node/src/standalone.ts20-110 packages/integrations/node/src/serve-static.ts43-175

Middleware Mode

Middleware mode builds a request handler intended to be plugged into existing Node.js HTTP middleware frameworks, such as Express or Connect. It does not start a server nor handle static files directly; these responsibilities lie with the external application.

This middleware:

• Wraps Astro’s SSR request handling pipeline packages/integrations/node/src/middleware.ts13-14
• Gracefully handles errors and integrates with middleware error chaining by checking if the first argument is an Error instance packages/integrations/node/src/middleware.ts22-29
• Uses an Express-compatible signature (req, res, next, locals?) packages/integrations/node/src/types.ts45-50
• Supports streaming rendering optionally controlled by the experimentalDisableStreaming option packages/integrations/node/src/server.ts10

Sources: packages/integrations/node/src/middleware.ts1-42

---

Configuration Architecture Diagram

Sources: packages/integrations/node/src/index.ts32-123 packages/integrations/node/src/server.ts16-25 packages/integrations/node/src/standalone.ts20-41 packages/integrations/node/src/middleware.ts13-41

---

Build Output Structure

The adapter modifies the build output to produce files and folders optimized for Node.js deployment. Notably, it supports static headers generation for prerendered pages enabling CSP and related security enhancements.

During the astro:build:done lifecycle hook, if staticHeaders is enabled, a headers JSON file (_headers.json) is written to the output directory to map routes to their static headers (mainly CSP) packages/integrations/node/src/index.ts92-121

Directory/File	Description
dist/server/	SSR server bundle built by Astro
dist/server/entry.mjs	Node.js server entrypoint script
dist/client/	Static client assets, including prerendered HTML
dist/client/_astro/	Hashed JS/CSS bundles for client
dist/_headers.json	JSON file containing static headers (CSP) per route

Sources: packages/integrations/node/src/index.ts98-118 packages/integrations/node/src/shared.ts5

---

Build Configuration Flow Diagram

Sources: packages/integrations/node/src/index.ts10-30 packages/integrations/node/src/index.ts85-121 packages/integrations/node/src/server.ts1-26

---

Request Handling Architecture

The Node.js adapter interfaces between Node.js native request/response objects and Astro's internal SSR and routing mechanisms.

Standalone Mode Request Flow

The standalone server handler (createStandaloneHandler) orchestrates request processing in two phases packages/integrations/node/src/standalone.ts50-68:

1. Static Handler - Uses createStaticHandler to serve static files and prerendered pages. It handles trailing slash redirects, asset caching headers, and applies static security headers from the loaded headers JSON if enabled packages/integrations/node/src/serve-static.ts43-175

2. App Handler - If no static file matches, the request is forwarded to the SSR handler (createAppHandler). This handler:

   • Converts Node.js requests to web standard Request objects via createRequestFromNodeRequest packages/integrations/node/src/serve-app.ts96-100
   • Matches a route via Astro’s routing (app.match) packages/integrations/node/src/serve-app.ts111
   • Calls the SSR renderer (app.render) with the matched route packages/integrations/node/src/serve-app.ts115-121
   • Writes the rendered response to the ServerResponse via writeResponse packages/integrations/node/src/serve-app.ts122

The request flow includes URI validation with 400 error fallback if URL decoding fails packages/integrations/node/src/standalone.ts58-65

Sources: packages/integrations/node/src/standalone.ts47-65 packages/integrations/node/src/server.ts16-19 packages/integrations/node/src/serve-static.ts43-175 packages/integrations/node/src/serve-app.ts53-135

---

Middleware Mode Request Flow

The middleware handler (createMiddleware) wraps around createAppHandler and provides a Node.js Connect-style middleware. It supports error handling by forwarding errors to the Express error middleware chain or responding with a 500 error internally packages/integrations/node/src/middleware.ts22-39

Request processing steps include:

• Conversion of Node.js requests into web Request packages/integrations/node/src/serve-app.ts96
• Astro route matching packages/integrations/node/src/serve-app.ts111
• SSR render invocation packages/integrations/node/src/serve-app.ts115
• Writing the response or calling next() if no route matched packages/integrations/node/src/serve-app.ts123-128

Sources: packages/integrations/node/src/middleware.ts1-42 packages/integrations/node/src/server.ts16-19 packages/integrations/node/src/serve-app.ts56-135

---

Static File Serving and Static Headers

The adapter serves static assets and prerendered content using createStaticHandler. It handles:

• Resolving URL paths inside the client directory, guarding against directory traversal packages/integrations/node/src/serve-static.ts18-35
• Trailing slash normalization according to configured options (never, ignore, always) packages/integrations/node/src/serve-static.ts91-122
• Application of static headers to prerendered routes, particularly Content-Security-Policy headers, if enabled packages/integrations/node/src/serve-static.ts70-89
• Serving hashed assets with immutable cache control packages/integrations/node/src/serve-static.ts166-170

Static Headers Implementation

During build, CSP headers for prerendered routes are collected and stored in _headers.json in the output directory packages/integrations/node/src/index.ts92-121

At runtime:

• The standalone server loads this headers JSON file (readHeadersJson) on startup if staticHeaders is enabled packages/integrations/node/src/server.ts12
• When serving a prerendered route, it applies the stored headers to the HTTP response packages/integrations/node/src/serve-static.ts84-87

Sources: packages/integrations/node/src/index.ts85-121 packages/integrations/node/src/server.ts12 packages/integrations/node/src/serve-static.ts43-175

---

Session Storage

The Node.js adapter provides a default session storage driver using the filesystem if none is configured packages/integrations/node/src/index.ts45-54 This default uses the fsLite driver from astro/config/sessionDrivers and stores sessions within a sessions folder inside the Astro cache directory.

• Enables session state persistence in Node.js without external dependencies.
• Supports cookie and TTL configurations passed through Astro config packages/integrations/node/src/index.ts51-52

Sources: packages/integrations/node/src/index.ts43-54 packages/integrations/node/src/index.ts7

---

Server Integration Patterns

Custom Server Support

• The standalone server supports custom SSL certificate loading by specifying environment variables packages/integrations/node/src/standalone.ts74-82:

  • SERVER_CERT_PATH: file path to SSL certificate.
  • SERVER_KEY_PATH: file path to SSL private key.

• If these are present, a HTTPS server is created instead of HTTP, facilitating secure deployments without external proxies.

• The server uses the server-destroy package to support a stop() method that allows graceful shutdown and cleanup of open connections packages/integrations/node/src/standalone.ts85-103

Sources: packages/integrations/node/src/standalone.ts71-110

---

Runtime Environment Setup

• The adapter ensures that astro:env references environment variables by mapping process.env through setGetEnv packages/integrations/node/src/server.ts8
• This setup enables accessing environment variables like PORT, HOST, and others from within the Astro runtime.

Environment Variable	Purpose
PORT	Defines the HTTP server port (default: 8080 if unset) packages/integrations/node/src/standalone.ts25
HOST	Defines the server host (default: localhost or 0.0.0.0, with boolean handling) packages/integrations/node/src/standalone.ts13-26
ASTRO_NODE_AUTOSTART	When set to disabled, prevents automatic startup of the standalone server packages/integrations/node/src/server.ts23
ASTRO_NODE_LOGGING	When set to disabled, suppresses startup logging messages packages/integrations/node/src/standalone.ts34

Sources: packages/integrations/node/src/server.ts2-25 packages/integrations/node/src/standalone.ts25-39

---

Preview Server

To facilitate testing of production builds locally, the adapter exports a createPreviewServer() function packages/integrations/node/src/preview.ts10 This function:

• Imports the server entrypoint module dynamically packages/integrations/node/src/preview.ts14
• Disables automatic standalone startup by setting ASTRO_NODE_AUTOSTART to disabled packages/integrations/node/src/preview.ts13
• Creates and starts an HTTP/HTTPS server listening on the specified host and port packages/integrations/node/src/preview.ts44-62
• If configured, attaches a listener to inject preview headers into 200 responses packages/integrations/node/src/preview.ts48-56
• Awaits server readiness and logs server listening info packages/integrations/node/src/preview.ts58-63

This allows running a production-like preview server using Node.js without explicitly invoking the full standalone start script.

Sources: packages/integrations/node/src/preview.ts10-65

---

Summary Mermaid Diagram Bridging Natural Language and Code Entities

Sources: packages/integrations/node/src/standalone.ts47-68 packages/integrations/node/src/serve-static.ts43-175 packages/integrations/node/src/serve-app.ts56-135 packages/astro/src/core/app/node.ts205-209

---

Sources: packages/integrations/node/src/index.ts32-123 packages/integrations/node/src/server.ts16-25 packages/integrations/node/src/standalone.ts20-41 packages/integrations/node/src/middleware.ts13-41 packages/integrations/node/src/preview.ts10-65

---

References

• packages/integrations/node/src/index.ts lines 10–123, 85–121
• packages/integrations/node/src/standalone.ts lines 20–110
• packages/integrations/node/src/server.ts lines 1–26, 16–25, 23–25
• packages/integrations/node/src/middleware.ts lines 1–42
• packages/integrations/node/src/serve-static.ts lines 43–175
• packages/integrations/node/src/serve-app.ts lines 50–135
• packages/integrations/node/src/preview.ts lines 1–67
• packages/astro/src/core/app/node.ts lines 1–138
• packages/integrations/node/src/index.ts:7