CtrlK
BlogDocsLog inGet started
Tessl Logo

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

SecuritybySnyk

Pending

The risk profile of this skill

Overview
Eval results
Files

@astrojs/node

@astrojs/node is a Node.js adapter for the Astro framework that enables server-side rendering (SSR) deployments to Node.js environments. It provides functionality to deploy Astro sites as standalone Node.js applications or middleware, supporting both hybrid and server-side rendering modes with session management, static asset serving, and comprehensive server configuration options.

Package Information

  • Package Name: @astrojs/node
  • Package Type: npm
  • Language: TypeScript
  • Installation: npm install @astrojs/node

Core Imports

import node from "@astrojs/node";

For server runtime exports:

import { createExports, start } from "@astrojs/node/server.js";

For preview server:

import createPreviewServer from "@astrojs/node/preview.js";

For direct access to named exports:

import { createIntegration, getAdapter } from "@astrojs/node";

Basic Usage

Basic Integration Setup

import { defineConfig } from "astro/config";
import node from "@astrojs/node";

export default defineConfig({
  output: "server",
  adapter: node({
    mode: "standalone"
  })
});

Middleware Mode Setup

import { defineConfig } from "astro/config";
import node from "@astrojs/node";

export default defineConfig({
  output: "server",
  adapter: node({
    mode: "middleware"
  })
});

Express Integration

import express from "express";
import { createExports } from "./dist/server.js";

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

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

Architecture

@astrojs/node is built around several key components:

  • Integration Factory: Main function that creates the Astro integration with lifecycle hooks
  • Server Runtime: Handles SSR requests, static file serving, and server creation
  • Adapter System: Provides configuration and feature flags to Astro's build system
  • Preview Server: Development preview server for testing built applications
  • Handler System: Request handlers for middleware and standalone modes
  • Session Management: Filesystem-based session storage with configurable options

Capabilities

Integration Configuration

Main integration factory function for configuring the @astrojs/node adapter with mode selection, experimental features, and build hooks.

/** Default export - primary way to use the adapter */
export default function createIntegration(userOptions: UserOptions): AstroIntegration;

/** Named export - alternative import method */  
export function createIntegration(userOptions: UserOptions): AstroIntegration;

interface UserOptions {
  /** Deployment mode: middleware or standalone server */
  mode: 'middleware' | 'standalone';
  /** Disable HTML streaming for hosting constraints */
  experimentalDisableStreaming?: boolean;
  /** Enable static headers in framework API file */
  experimentalStaticHeaders?: boolean;
  /** Host for fetching prerendered error pages */
  experimentalErrorPageHost?: string | URL;
}

interface AstroIntegration {
  name: string;
  hooks: {
    'astro:config:setup': (params: ConfigSetupParams) => Promise<void>;
    'astro:build:generated': (params: BuildGeneratedParams) => void;
    'astro:config:done': (params: ConfigDoneParams) => void;
    'astro:build:done': () => Promise<void>;
  };
}

Integration Configuration

Server Runtime

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

function createExports(
  manifest: SSRManifest, 
  options: Options
): {
  options: Options;
  handler: RequestHandler;
  startServer: () => ServerResult;
};

function start(manifest: SSRManifest, options: Options): void;

interface Options extends UserOptions {
  host: string | boolean;
  port: number;
  server: string;
  client: string;
  assets: string;
  trailingSlash?: SSRManifest['trailingSlash'];
  experimentalStaticHeaders: boolean;
}

Server Runtime

Request Handlers

Handler creation functions for different deployment modes including middleware, standalone, and static file serving.

function createMiddleware(app: NodeApp, options: Options): RequestHandler;

function createStandaloneHandler(
  app: NodeApp, 
  options: Options
): (req: http.IncomingMessage, res: http.ServerResponse) => void;

function createAppHandler(app: NodeApp, options: Options): RequestHandler;

function createStaticHandler(
  app: NodeApp, 
  options: Options
): (req: IncomingMessage, res: ServerResponse, ssr: () => unknown) => void;

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

Request Handlers

Preview Server

Development preview server functionality for testing built applications locally with configurable host and port options.

function createPreviewServer(preview: PreviewParams): Promise<PreviewServer>;

interface PreviewParams {
  serverEntrypoint: URL;
  host?: string;
  port?: number;
  headers?: Record<string, string>;
  logger: AstroIntegrationLogger;
}

interface PreviewServer {
  host: string;
  port: number;
  closed(): Promise<void>;
  stop(): Promise<void>;
}

Preview Server

Server Management

Server creation and management utilities for HTTP/HTTPS servers with graceful shutdown and networking features.

function createServer(
  listener: http.RequestListener, 
  host: string, 
  port: number
): PreviewServer & { server: http.Server | https.Server };

function standalone(
  app: NodeApp, 
  options: Options
): { 
  server: PreviewServer & { server: http.Server | https.Server }; 
  done: Promise<void>; 
};

function hostOptions(host: Options['host']): string;

function logListeningOn(
  logger: AstroIntegrationLogger,
  server: http.Server | https.Server,
  configuredHost: string | boolean | undefined
): Promise<void>;

Server Management

Runtime Polyfills and Constants

Node.js runtime polyfills and shared constants used across the adapter implementation.

/** Applies Node.js polyfills for Astro runtime compatibility */
function applyPolyfills(): void;

/** Static headers JSON file name constant */
const STATIC_HEADERS_FILE: '_experimentalHeaders.json';

The adapter automatically applies polyfills during server initialization to ensure compatibility between Astro's runtime expectations and Node.js environment capabilities.

Environment Variables

@astrojs/node respects several environment variables for runtime configuration:

  • PORT: Override server port (default: 8080 for standalone, 4321 for preview)
  • HOST: Override server host binding
  • SERVER_CERT_PATH: Path to HTTPS certificate file
  • SERVER_KEY_PATH: Path to HTTPS private key file
  • ASTRO_NODE_AUTOSTART: Set to 'disabled' to prevent auto-start in standalone mode
  • ASTRO_NODE_LOGGING: Set to 'disabled' to suppress server startup logging

Common Types

interface SSRManifest {
  trailingSlash?: 'always' | 'never' | 'ignore';
  outDir: string | URL;
  // ... other Astro SSR manifest properties
}

interface NodeApp {
  getAdapterLogger(): AstroIntegrationLogger;
  match(request: Request, prerender?: boolean): RouteData | undefined;
  render(request: Request | IncomingMessage, options?: RenderOptions): Promise<Response>;
  removeBase(pathname: string): string;
  headersMap?: NodeAppHeadersJson;
  setHeadersMap(headers: NodeAppHeadersJson): void;
}

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

interface AstroAdapter {
  name: string;
  serverEntrypoint: string;
  previewEntrypoint: string;
  exports: string[];
  args: Options;
  adapterFeatures: AdapterFeatures;
  supportedAstroFeatures: SupportedFeatures;
}

interface AdapterFeatures {
  buildOutput: 'server';
  edgeMiddleware: false;
  experimentalStaticHeaders: boolean;
}

interface SupportedFeatures {
  hybridOutput: 'stable';
  staticOutput: 'stable';
  serverOutput: 'stable';
  sharpImageService: 'stable';
  i18nDomains: 'experimental';
  envGetSecret: 'stable';
}

interface RenderOptions {
  addCookieHeader?: boolean;
  locals?: object;
  routeData?: RouteData;
  prerenderedErrorPageFetch?: (url: string) => Promise<Response>;
}

interface RouteData {
  route: string;
  prerender?: boolean;
  pathname?: string;
  // ... other Astro route data properties
}
Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/@astrojs/node@9.4.x
Publish Source
CLI
Badge
tessl/npm-astrojs--node badge