@astroscope/boot

Note: This package is in active development. APIs may change between versions.

Startup and graceful shutdown hooks for Astro SSR. Run initialization code before the server starts and cleanup code when it shuts down.

Examples

See the demo/boot directory for a working example.

Installation

npm install @astroscope/boot

Usage

1. Create a boot file at src/boot.ts (or src/boot/index.ts):

// src/boot.ts
import type { BootContext } from '@astroscope/boot';

export async function onStartup({ dev, host, port }: BootContext) {
  console.log('Starting up...');

  await someAsyncInitialization();

  console.log(`Ready at ${host}:${port} (dev: ${dev})`);
}

export async function onShutdown({ dev }: BootContext) {
  console.log('Shutting down...');

  await closeConnections();

  console.log('Goodbye!');
}

2. Add the integration to your Astro config:

// astro.config.ts
import { defineConfig } from 'astro/config';
import boot from '@astroscope/boot';

export default defineConfig({
  output: 'server',
  integrations: [boot()],
});

Boot Context

Both onStartup and onShutdown receive a BootContext object:

interface BootContext {
  /** Whether running in development mode */
  dev: boolean;
  /** Server host (from Astro config or HOST env var) */
  host: string;
  /** Server port (from Astro config or PORT env var) */
  port: number;
}

In development, host and port are read from the actual server address. In production, they default to Astro config values but can be overridden via HOST and PORT environment variables at runtime.

Lifecycle Hooks

onStartup

Called before the server starts handling requests. Use this for:

• Database connection initialization
• Loading configuration
• Warming caches
• Setting up external service clients

onShutdown

Called when the server is shutting down (SIGTERM in production, server close in development). Use this for:

• Closing database connections
• Flushing buffers
• Cleaning up resources
• Graceful shutdown of external services

Warmup

Enabled by default. Pre-imports the modules the SSR server actually loads on the first requests, so the first request doesn't pay the cost of evaluating route and middleware modules from cold.

The preloaded chunks are determined by

• astro pages
• api routes
• actions
• middleware

Warmup runs in parallel with onStartup and is awaited before the server starts handling requests.

To disable:

boot({ warmup: false });

Options

entry

Path to the boot file relative to the project root.

• Type: string
• Default: "src/boot.ts"

boot({ entry: 'src/startup.ts' });

watch

Restart the dev server when the boot file (or any of its dependencies) changes, and when Vite issues an SSR full-reload (which would otherwise wipe singletons configured in onStartup).

Make sure your onShutdown releases everything onStartup acquired (sockets, ports, intervals, locks) — the previous module is fully shut down before the new one starts on each restart.

• Type: boolean
• Default: true

boot({ watch: false });

warmup

Pre-import server modules on startup to eliminate cold-start latency on the first request. Production-only — no effect in dev. See Warmup above for details.

• Type: boolean
• Default: true

boot({ warmup: false });

Requirements

• Node.js runtime
• SSR output mode (output: "server")

License

MIT