@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
export async function onStartup() {
  console.log("Starting up...");

  await someAsyncInitialization();

  console.log("Ready!");
}

export async function onShutdown() {
  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()],
});

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

Options

entry

Path to the boot file relative to the project root.

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

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

hmr

Re-run onStartup when the boot file changes during development. This is disabled by default to avoid side effects, because onStartup may perform operations that should only run once (e.g., database connections). Please ensure your onShutdown function destroys any resources created by onStartup to prevent leaks / unexpected behavior.

• Type: boolean
• Default: false

boot({ hmr: true });

How it works

• Development: The boot file runs after the dev server starts listening (Vite limitation). onShutdown is called when the dev server closes.
• Production: onStartup runs before the server starts handling requests. onShutdown is called on SIGTERM.

Requirements

• Only works with SSR output mode (output: "server")

License

MIT