tessl/npm-astrojs--node

Node.js adapter for Astro framework enabling server-side rendering and standalone server deployments

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Securityby

Pending

The risk profile of this skill

Overview

Eval results

Files

Server Runtime

Name: tessl/npm-astrojs--node
Author: tessl

Server runtime functions for creating request handlers, starting servers, and managing the application lifecycle in production environments.

Capabilities

Create Server Exports

Creates the main server exports including handler, startServer function, and options for production deployment.

/**
 * Creates server exports including handler, startServer function, and configuration
 * @param manifest - SSR manifest from Astro build containing routing and config data
 * @param options - Resolved adapter options including build paths and user settings
 * @returns Object with handler function, startServer function, and options
 */
function createExports(
  manifest: SSRManifest, 
  options: Options
): {
  options: Options;
  handler: RequestHandler;
  startServer: () => ServerResult;
};

interface ServerResult {
  server: PreviewServer & { server: http.Server | https.Server };
  done: Promise<void>;
}

type RequestHandler = (
  req: IncomingMessage,
  res: ServerResponse,
  next?: (err?: unknown) => void,
  locals?: object
) => void | Promise<void>;

Usage Examples:

// Using in standalone mode
import { createExports } from "./dist/server.js";
const { handler, startServer, options } = createExports(manifest, options);

// Start the server
const { server, done } = startServer();

// Or use handler manually
import http from "http";
const server = http.createServer(handler);
server.listen(3000);

// Using in middleware mode with Express
import express from "express";
import { createExports } from "./dist/server.js";

const app = express();
const { handler } = createExports(manifest, options);

// Mount Astro as middleware
app.use(handler);
app.listen(3000);

Auto-Start Function

Automatically starts the server if running in standalone mode and auto-start is not disabled.

/**
 * Auto-starts standalone server if conditions are met
 * @param manifest - SSR manifest from Astro build
 * @param options - Resolved adapter options
 * @returns void - No return value, starts server as side effect
 */
function start(manifest: SSRManifest, options: Options): void;

Startup Conditions:

options.mode must be 'standalone'
process.env.ASTRO_NODE_AUTOSTART must not be 'disabled'
Server will start automatically when module is imported

Usage Example:

// In generated server entry file
import { start } from "@astrojs/node/server.js";
import manifest from "./manifest.js";

// Auto-starts server if conditions are met
start(manifest, {
  mode: "standalone",
  host: "localhost",
  port: 8080,
  // ... other options
});

Static Headers Processing

When experimentalStaticHeaders is enabled, the runtime processes static headers for prerendered pages.

Headers File Reading

/**
 * Reads and parses static headers JSON file
 * @param outDir - Build output directory containing headers file
 * @returns Parsed headers data or undefined if file doesn't exist or is invalid
 */
function readHeadersJson(outDir: string | URL): NodeAppHeadersJson | undefined;

type NodeAppHeadersJson = Array<{
  pathname: string;
  headers: Array<{ key: string; value: string }>;
}>;

Headers File Location:

File name: _experimentalHeaders.json
Location: Build output directory (outDir)
Format: JSON array of pathname-to-headers mappings

Error Handling:

Invalid JSON logs error to console but doesn't throw
Missing file returns undefined without error
Malformed entries are silently ignored

NodeApp Configuration

The runtime configures the NodeApp instance with headers and streaming settings:

const app = new NodeApp(manifest, !options.experimentalDisableStreaming);

if (headersMap) {
  app.setHeadersMap(headersMap);
}

Options Resolution

The runtime receives fully resolved options that extend user options with build configuration:

interface Options extends UserOptions {
  /** Resolved host configuration from Astro config */
  host: string | boolean;
  /** Resolved port from Astro config */
  port: number;
  /** Server build output directory path */
  server: string;
  /** Client build output directory path */  
  client: string;
  /** Assets directory path for static files */
  assets: string;
  /** Trailing slash behavior from SSR manifest */
  trailingSlash?: SSRManifest['trailingSlash'];
  /** Static headers feature flag (resolved to boolean) */
  experimentalStaticHeaders: boolean;
}

interface UserOptions {
  mode: 'middleware' | 'standalone';
  experimentalDisableStreaming?: boolean;
  experimentalStaticHeaders?: boolean;
  experimentalErrorPageHost?: string | URL;
}

Handler Selection

The runtime selects the appropriate handler based on deployment mode:

const handler = options.mode === 'middleware'
  ? createMiddleware(app, options)
  : createStandaloneHandler(app, options);

Middleware Handler

Designed for Express/Connect-style middleware chains
Includes error handling for middleware pattern
Supports next() callback for delegation
Handles error middleware pattern (4-parameter function)

Standalone Handler

Complete request handler for standalone servers
Combines static file serving with SSR rendering
Validates request URLs and handles malformed requests
No dependency on external middleware frameworks

Environment Variables

The server runtime respects several environment variables:

ASTRO_NODE_AUTOSTART: Set to 'disabled' to prevent auto-start
ASTRO_NODE_LOGGING: Set to 'disabled' to suppress startup logging
PORT: Override port for standalone mode
HOST: Override host binding

SSR Manifest Integration

The runtime integrates closely with Astro's SSR manifest:

interface SSRManifest {
  /** Trailing slash configuration for URL handling */
  trailingSlash?: 'always' | 'never' | 'ignore';
  /** Build output directory for static files and headers */
  outDir: string | URL;
  /** Route matching and rendering data */
  // ... other Astro SSR manifest properties
}

Key Manifest Usage: