Integration Configuration

/**
 * Creates the @astrojs/node integration with configuration and lifecycle hooks
 * @param userOptions - User configuration options for the adapter
 * @returns Configured AstroIntegration with hooks and metadata
 * @throws AstroError if mode is not specified or experimentalErrorPageHost is invalid
 */
function createIntegration(userOptions: UserOptions): AstroIntegration;

interface UserOptions {
  /** 
   * Deployment mode - Required
   * - 'middleware': Build for use within another Node.js server (Express, etc.)
   * - 'standalone': Build as a complete standalone server application
   */
  mode: 'middleware' | 'standalone';
  
  /** 
   * Disable HTML streaming for hosting environments with constraints
   * @default false
   */
  experimentalDisableStreaming?: boolean;

  /** 
   * Enable static headers in framework API file for CSP and other headers
   * Saves headers to _experimentalHeaders.json for static pages
   * @default false
   */
  experimentalStaticHeaders?: boolean;

  /** 
   * Host URL for fetching prerendered error pages
   * Useful when server is behind reverse proxy or load balancer
   * Must be a valid URL with http: or https: protocol
   * Path components are ignored
   */
  experimentalErrorPageHost?: string | URL;
}

interface AstroIntegration {
  name: '@astrojs/node';
  hooks: {
    /** Configure Astro settings including sessions, image endpoint, and Vite config */
    'astro:config:setup': (params: ConfigSetupParams) => Promise<void>;
    /** Capture route-to-headers mapping for static header generation */
    'astro:build:generated': (params: BuildGeneratedParams) => void;
    /** Set the adapter with final resolved options */
    'astro:config:done': (params: ConfigDoneParams) => void;
    /** Write static headers file if experimentalStaticHeaders is enabled */
    'astro:build:done': () => Promise<void>;
  };
}

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

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

// Advanced configuration with experimental features
export default defineConfig({
  output: "server",
  adapter: node({
    mode: "standalone",
    experimentalStaticHeaders: true,
    experimentalErrorPageHost: "https://cdn.example.com",
    experimentalDisableStreaming: true
  })
});

// Middleware mode for Express integration
export default defineConfig({
  output: "server", 
  adapter: node({
    mode: "middleware"
  })
});

/**
 * Creates AstroAdapter instance with specified options and feature support
 * @param options - Internal options including user options plus build paths
 * @returns Configured AstroAdapter for Astro's build system
 */
function getAdapter(options: Options): AstroAdapter;

interface Options extends UserOptions {
  /** Server host configuration - resolved from Astro config */
  host: string | boolean;
  /** Server port - resolved 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 configuration from SSR manifest */
  trailingSlash?: SSRManifest['trailingSlash'];
  /** Static headers feature flag - always boolean in Options */
  experimentalStaticHeaders: boolean;
}

interface AstroAdapter {
  name: '@astrojs/node';
  /** Server entrypoint module path */
  serverEntrypoint: '@astrojs/node/server.js';
  /** Preview server entrypoint module path */
  previewEntrypoint: '@astrojs/node/preview.js';
  /** Exported functions from server entrypoint */
  exports: ['handler', 'startServer', 'options'];
  /** Adapter configuration options */
  args: Options;
  /** Adapter build and runtime features */
  adapterFeatures: {
    buildOutput: 'server';
    edgeMiddleware: false;
    experimentalStaticHeaders: boolean;
  };
  /** Astro feature support levels */
  supportedAstroFeatures: {
    hybridOutput: 'stable';
    staticOutput: 'stable';
    serverOutput: 'stable';
    sharpImageService: 'stable';
    i18nDomains: 'experimental';
    envGetSecret: 'stable';
  };
}

interface ConfigSetupParams {
  updateConfig: (config: Partial<AstroConfig>) => void;
  config: AstroConfig;
  logger: AstroIntegrationLogger;
}

interface BuildGeneratedParams {
  experimentalRouteToHeaders?: RouteToHeaders;
}

type RouteToHeaders = Map<string, { headers: Headers }>;

interface ConfigDoneParams {
  setAdapter: (adapter: AstroAdapter) => void;
  config: AstroConfig;
}

[
  {
    "pathname": "/path/to/page",
    "headers": [
      {
        "key": "Content-Security-Policy", 
        "value": "default-src 'self'"
      }
    ]
  }
]

{
  driver: 'fs-lite',
  options: {
    base: fileURLToPath(new URL('sessions', config.cacheDir))
  }
}