@astroscope/boot 0.1.3 → 0.2.1

package/README.md

@@ -20,15 +20,17 @@ npm install @astroscope/boot
 
 ```ts
 // src/boot.ts
-export async function onStartup() {
+import type { BootContext } from "@astroscope/boot";
+
+export async function onStartup({ dev, host, port }: BootContext) {
   console.log("Starting up...");
 
   await someAsyncInitialization();
 
-  console.log("Ready!");
+  console.log(`Ready at ${host}:${port} (dev: ${dev})`);
 }
 
-export async function onShutdown() {
+export async function onShutdown({ dev }: BootContext) {
   console.log("Shutting down...");
 
   await closeConnections();
@@ -50,6 +52,23 @@ export default defineConfig({
 });
 ```
 
+## Boot Context
+
+Both `onStartup` and `onShutdown` receive a `BootContext` object:
+
+```ts
+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`
@@ -70,6 +89,45 @@ Called when the server is shutting down (SIGTERM in production, server close in
 - Cleaning up resources
 - Graceful shutdown of external services
 
+## V8 Warmup
+
+The package includes a warmup utility that pre-imports all page modules and middleware to warm up the V8 JIT compiler, reducing cold start latency for the first requests.
+
+```ts
+// src/boot.ts
+import type { BootContext } from "@astroscope/boot";
+import { warmup } from "@astroscope/boot/warmup";
+
+export async function onStartup({ host, port }: BootContext) {
+  const result = await warmup();
+
+  if (result.success.length > 0) {
+    console.log(`Warmed up ${result.success.length} modules in ${result.duration}ms`);
+  }
+
+  if (result.failed.length > 0) {
+    console.warn(`Failed to warm up: ${result.failed.join(", ")}`);
+  }
+
+  console.log(`Server ready at ${host}:${port}`);
+}
+```
+
+### `WarmupResult`
+
+```ts
+interface WarmupResult {
+  /** Modules that were successfully loaded */
+  success: string[];
+  /** Modules that failed to load */
+  failed: string[];
+  /** Time taken in milliseconds */
+  duration: number;
+}
+```
+
+In development mode, `warmup()` is a no-op that returns empty results. In production, it reads a manifest generated during the build and imports all discovered page modules and middleware in parallel.
+
 ## Options
 
 ### `entry`

package/dist/index.cjs

@@ -30,11 +30,15 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
+  boot: () => boot,
   default: () => boot
 });
 module.exports = __toCommonJS(index_exports);
+
+// src/integration.ts
 var import_node_fs = __toESM(require("fs"), 1);
 var import_node_path = __toESM(require("path"), 1);
+var import_magic_string = __toESM(require("magic-string"), 1);
 
 // src/ignored.ts
 var ignoredSuffixes = [
@@ -79,47 +83,67 @@ var ignoredSuffixes = [
   ".less"
 ];
 
-// src/index.ts
+// src/integration.ts
 function resolveEntry(entry) {
   if (entry) return entry;
-  if (import_node_fs.default.existsSync("src/boot.ts")) return "src/boot.ts";
   if (import_node_fs.default.existsSync("src/boot/index.ts")) return "src/boot/index.ts";
   return "src/boot.ts";
 }
+var WARMUP_MANIFEST_FILE = "warmup-manifest.json";
+function getServerDefaults(config) {
+  return {
+    host: typeof config?.server?.host === "string" ? config.server.host : config?.server?.host === true ? "0.0.0.0" : "localhost",
+    port: config?.server?.port ?? 4321
+  };
+}
 function boot(options = {}) {
   const entry = resolveEntry(options.entry);
   const hmr = options.hmr ?? false;
   let isBuild = false;
   let isSSR = false;
   let bootChunkRef = null;
+  let astroConfig = null;
+  let pageModules = [];
+  let middlewarePath = null;
   return {
     name: "@astroscope/boot",
     hooks: {
-      "astro:config:setup": ({ command, updateConfig, logger }) => {
+      "astro:config:setup": ({ command, updateConfig, logger, config }) => {
         isBuild = command === "build";
+        astroConfig = config;
         updateConfig({
           vite: {
             plugins: [
               {
                 name: "@astroscope/boot",
+                enforce: "pre",
                 configureServer(server) {
                   if (isBuild) return;
+                  const getBootContext = () => {
+                    const addr = server.httpServer?.address();
+                    if (addr && typeof addr === "object") {
+                      const host2 = addr.address === "::" || addr.address === "0.0.0.0" ? "localhost" : addr.address;
+                      return { dev: true, host: host2, port: addr.port };
+                    }
+                    const defaults = getServerDefaults(astroConfig);
+                    const host = process.env["HOST"] ?? defaults.host;
+                    const port = process.env["PORT"] ? Number(process.env["PORT"]) : defaults.port;
+                    return { dev: true, host, port };
+                  };
                   server.httpServer?.once("listening", async () => {
                     try {
+                      const bootContext = getBootContext();
                       const module2 = await server.ssrLoadModule(`/${entry}`);
-                      if (module2.onStartup) {
-                        await module2.onStartup();
-                      }
+                      await module2.onStartup?.(bootContext);
                     } catch (error) {
                       logger.error(`Error running startup script: ${error}`);
                     }
                   });
                   server.httpServer?.once("close", async () => {
                     try {
+                      const bootContext = getBootContext();
                       const module2 = await server.ssrLoadModule(`/${entry}`);
-                      if (module2.onShutdown) {
-                        await module2.onShutdown();
-                      }
+                      await module2.onShutdown?.(bootContext);
                     } catch (error) {
                       logger.error(`Error running shutdown script: ${error}`);
                     }
@@ -146,22 +170,19 @@ function boot(options = {}) {
                     const rerunBoot = async (changedFile) => {
                       logger.info(`boot dependency changed: ${changedFile}, rerunning hooks...`);
                       try {
+                        const bootContext = getBootContext();
                         const oldModule = await server.ssrLoadModule(bootModuleId);
-                        if (oldModule.onShutdown) {
-                          await oldModule.onShutdown();
-                        }
+                        await oldModule.onShutdown?.(bootContext);
                         server.moduleGraph.invalidateAll();
                         const newModule = await server.ssrLoadModule(bootModuleId);
-                        if (newModule.onStartup) {
-                          await newModule.onStartup();
-                        }
+                        await newModule.onStartup?.(bootContext);
                       } catch (error) {
                         logger.error(`Error during boot HMR: ${error}`);
                       }
                     };
                     const shouldIgnore = (filePath) => {
-                      const path2 = filePath.toLowerCase();
-                      return ignoredSuffixes.some((suffix) => path2.endsWith(suffix));
+                      const p = filePath.toLowerCase();
+                      return ignoredSuffixes.some((suffix) => p.endsWith(suffix));
                     };
                     server.watcher.on("change", async (changedPath) => {
                       if (shouldIgnore(changedPath)) return;
@@ -172,48 +193,68 @@ function boot(options = {}) {
                     });
                   }
                 },
-                configResolved(config) {
-                  isSSR = !!config.build?.ssr;
+                configResolved(config2) {
+                  isSSR = !!config2.build?.ssr;
                 },
                 buildStart() {
                   if (!isSSR) return;
                   try {
-                    bootChunkRef = this.emitFile({
-                      type: "chunk",
-                      id: entry,
-                      name: "boot"
-                    });
+                    bootChunkRef = this.emitFile({ type: "chunk", id: entry, name: "boot" });
                   } catch {
                   }
                 },
-                writeBundle(outputOptions) {
-                  if (!isSSR) return;
-                  const outDir = outputOptions.dir;
-                  if (!outDir || !bootChunkRef) return;
-                  const entryPath = import_node_path.default.join(outDir, "entry.mjs");
-                  if (!import_node_fs.default.existsSync(entryPath)) {
-                    logger.warn("entry.mjs not found - boot injection skipped");
-                    return;
-                  }
+                generateBundle(_, bundle) {
+                  if (!isSSR || !bootChunkRef) return;
                   const bootChunkName = this.getFileName(bootChunkRef);
                   if (!bootChunkName) {
                     logger.warn("boot chunk not found");
                     return;
                   }
-                  const sourcemapPath = `${entryPath}.map`;
-                  if (import_node_fs.default.existsSync(sourcemapPath)) {
-                    logger.warn(
-                      "sourcemap detected for entry.mjs - line numbers may be off by 2 lines due to boot injection"
-                    );
+                  const entryChunk = bundle["entry.mjs"];
+                  if (!entryChunk || entryChunk.type !== "chunk") {
+                    logger.warn("entry.mjs not found - boot injection skipped");
+                    return;
+                  }
+                  pageModules = [];
+                  middlewarePath = null;
+                  for (const [fileName, chunk] of Object.entries(bundle)) {
+                    if (chunk.type !== "chunk") continue;
+                    if (fileName.startsWith("pages/") && fileName.endsWith(".mjs")) {
+                      pageModules.push(fileName);
+                    }
+                    if (fileName.includes("_astro-internal_middleware") || fileName.includes("_noop-middleware")) {
+                      middlewarePath = fileName;
+                    }
                   }
-                  let content = import_node_fs.default.readFileSync(entryPath, "utf-8");
-                  const bootImport = `import * as __boot from './${bootChunkName}';
-await __boot.onStartup?.();
-if (__boot.onShutdown) process.on('SIGTERM', async () => { await __boot.onShutdown(); process.exit(0); });
+                  const { host, port } = getServerDefaults(astroConfig);
+                  const bootImport = `globalThis.__astroscope_server_url = import.meta.url;
+import * as __boot from './${bootChunkName}';
+const __bootContext = { dev: false, host: process.env.HOST ?? '${host}', port: process.env.PORT ? Number(process.env.PORT) : ${port} };
+await __boot.onStartup?.(__bootContext);
+if (__boot.onShutdown) process.on('SIGTERM', async () => { await __boot.onShutdown(__bootContext); process.exit(0); });
 `;
-                  content = bootImport + content;
-                  import_node_fs.default.writeFileSync(entryPath, content);
+                  const s = new import_magic_string.default(entryChunk.code);
+                  s.prepend(bootImport);
+                  entryChunk.code = s.toString();
+                  if (entryChunk.map) {
+                    entryChunk.map = s.generateMap({ hires: true });
+                  }
                   logger.info(`injected ${bootChunkName} into entry.mjs`);
+                },
+                writeBundle(outputOptions) {
+                  if (!isSSR) return;
+                  const outDir = outputOptions.dir;
+                  if (!outDir) return;
+                  const modules = [];
+                  if (middlewarePath) {
+                    modules.push(`./${middlewarePath}`);
+                  }
+                  for (const page of pageModules) {
+                    modules.push(`./${page}`);
+                  }
+                  const manifestPath = import_node_path.default.join(outDir, "chunks", WARMUP_MANIFEST_FILE);
+                  import_node_fs.default.writeFileSync(manifestPath, JSON.stringify({ modules }));
+                  logger.info(`generated warmup for ${pageModules.length} pages`);
                 }
               }
             ]
@@ -223,3 +264,7 @@ if (__boot.onShutdown) process.on('SIGTERM', async () => { await __boot.onShutdo
     }
   };
 }
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  boot
+});

package/dist/index.d.cts

@@ -1,4 +1,5 @@
 import { AstroIntegration } from 'astro';
+export { B as BootContext, W as WarmupResult } from './types-CxpusND2.cjs';
 
 interface BootOptions {
     /**
@@ -17,30 +18,7 @@ interface BootOptions {
  *
  * Runs `onStartup` and `onShutdown` functions exported from your boot file
  * during server startup and shutdown.
- *
- * @example
- * ```ts
- * // astro.config.ts
- * import { defineConfig } from "astro/config";
- * import boot from "@astroscope/boot";
- *
- * export default defineConfig({
- *   integrations: [boot()],
- * });
- * ```
- *
- * @example
- * ```ts
- * // src/boot.ts
- * export async function onStartup() {
- *   console.log("Server starting...");
- * }
- *
- * export async function onShutdown() {
- *   console.log("Server shutting down...");
- * }
- * ```
  */
 declare function boot(options?: BootOptions): AstroIntegration;
 
-export { type BootOptions, boot as default };
+export { type BootOptions, boot, boot as default };

package/dist/index.d.ts

@@ -1,4 +1,5 @@
 import { AstroIntegration } from 'astro';
+export { B as BootContext, W as WarmupResult } from './types-CxpusND2.js';
 
 interface BootOptions {
     /**
@@ -17,30 +18,7 @@ interface BootOptions {
  *
  * Runs `onStartup` and `onShutdown` functions exported from your boot file
  * during server startup and shutdown.
- *
- * @example
- * ```ts
- * // astro.config.ts
- * import { defineConfig } from "astro/config";
- * import boot from "@astroscope/boot";
- *
- * export default defineConfig({
- *   integrations: [boot()],
- * });
- * ```
- *
- * @example
- * ```ts
- * // src/boot.ts
- * export async function onStartup() {
- *   console.log("Server starting...");
- * }
- *
- * export async function onShutdown() {
- *   console.log("Server shutting down...");
- * }
- * ```
  */
 declare function boot(options?: BootOptions): AstroIntegration;
 
-export { type BootOptions, boot as default };
+export { type BootOptions, boot, boot as default };

package/dist/index.js

@@ -1,6 +1,7 @@
-// src/index.ts
+// src/integration.ts
 import fs from "fs";
 import path from "path";
+import MagicString from "magic-string";
 
 // src/ignored.ts
 var ignoredSuffixes = [
@@ -45,47 +46,67 @@ var ignoredSuffixes = [
   ".less"
 ];
 
-// src/index.ts
+// src/integration.ts
 function resolveEntry(entry) {
   if (entry) return entry;
-  if (fs.existsSync("src/boot.ts")) return "src/boot.ts";
   if (fs.existsSync("src/boot/index.ts")) return "src/boot/index.ts";
   return "src/boot.ts";
 }
+var WARMUP_MANIFEST_FILE = "warmup-manifest.json";
+function getServerDefaults(config) {
+  return {
+    host: typeof config?.server?.host === "string" ? config.server.host : config?.server?.host === true ? "0.0.0.0" : "localhost",
+    port: config?.server?.port ?? 4321
+  };
+}
 function boot(options = {}) {
   const entry = resolveEntry(options.entry);
   const hmr = options.hmr ?? false;
   let isBuild = false;
   let isSSR = false;
   let bootChunkRef = null;
+  let astroConfig = null;
+  let pageModules = [];
+  let middlewarePath = null;
   return {
     name: "@astroscope/boot",
     hooks: {
-      "astro:config:setup": ({ command, updateConfig, logger }) => {
+      "astro:config:setup": ({ command, updateConfig, logger, config }) => {
         isBuild = command === "build";
+        astroConfig = config;
         updateConfig({
           vite: {
             plugins: [
               {
                 name: "@astroscope/boot",
+                enforce: "pre",
                 configureServer(server) {
                   if (isBuild) return;
+                  const getBootContext = () => {
+                    const addr = server.httpServer?.address();
+                    if (addr && typeof addr === "object") {
+                      const host2 = addr.address === "::" || addr.address === "0.0.0.0" ? "localhost" : addr.address;
+                      return { dev: true, host: host2, port: addr.port };
+                    }
+                    const defaults = getServerDefaults(astroConfig);
+                    const host = process.env["HOST"] ?? defaults.host;
+                    const port = process.env["PORT"] ? Number(process.env["PORT"]) : defaults.port;
+                    return { dev: true, host, port };
+                  };
                   server.httpServer?.once("listening", async () => {
                     try {
+                      const bootContext = getBootContext();
                       const module = await server.ssrLoadModule(`/${entry}`);
-                      if (module.onStartup) {
-                        await module.onStartup();
-                      }
+                      await module.onStartup?.(bootContext);
                     } catch (error) {
                       logger.error(`Error running startup script: ${error}`);
                     }
                   });
                   server.httpServer?.once("close", async () => {
                     try {
+                      const bootContext = getBootContext();
                       const module = await server.ssrLoadModule(`/${entry}`);
-                      if (module.onShutdown) {
-                        await module.onShutdown();
-                      }
+                      await module.onShutdown?.(bootContext);
                     } catch (error) {
                       logger.error(`Error running shutdown script: ${error}`);
                     }
@@ -112,22 +133,19 @@ function boot(options = {}) {
                     const rerunBoot = async (changedFile) => {
                       logger.info(`boot dependency changed: ${changedFile}, rerunning hooks...`);
                       try {
+                        const bootContext = getBootContext();
                         const oldModule = await server.ssrLoadModule(bootModuleId);
-                        if (oldModule.onShutdown) {
-                          await oldModule.onShutdown();
-                        }
+                        await oldModule.onShutdown?.(bootContext);
                         server.moduleGraph.invalidateAll();
                         const newModule = await server.ssrLoadModule(bootModuleId);
-                        if (newModule.onStartup) {
-                          await newModule.onStartup();
-                        }
+                        await newModule.onStartup?.(bootContext);
                       } catch (error) {
                         logger.error(`Error during boot HMR: ${error}`);
                       }
                     };
                     const shouldIgnore = (filePath) => {
-                      const path2 = filePath.toLowerCase();
-                      return ignoredSuffixes.some((suffix) => path2.endsWith(suffix));
+                      const p = filePath.toLowerCase();
+                      return ignoredSuffixes.some((suffix) => p.endsWith(suffix));
                     };
                     server.watcher.on("change", async (changedPath) => {
                       if (shouldIgnore(changedPath)) return;
@@ -138,48 +156,68 @@ function boot(options = {}) {
                     });
                   }
                 },
-                configResolved(config) {
-                  isSSR = !!config.build?.ssr;
+                configResolved(config2) {
+                  isSSR = !!config2.build?.ssr;
                 },
                 buildStart() {
                   if (!isSSR) return;
                   try {
-                    bootChunkRef = this.emitFile({
-                      type: "chunk",
-                      id: entry,
-                      name: "boot"
-                    });
+                    bootChunkRef = this.emitFile({ type: "chunk", id: entry, name: "boot" });
                   } catch {
                   }
                 },
-                writeBundle(outputOptions) {
-                  if (!isSSR) return;
-                  const outDir = outputOptions.dir;
-                  if (!outDir || !bootChunkRef) return;
-                  const entryPath = path.join(outDir, "entry.mjs");
-                  if (!fs.existsSync(entryPath)) {
-                    logger.warn("entry.mjs not found - boot injection skipped");
-                    return;
-                  }
+                generateBundle(_, bundle) {
+                  if (!isSSR || !bootChunkRef) return;
                   const bootChunkName = this.getFileName(bootChunkRef);
                   if (!bootChunkName) {
                     logger.warn("boot chunk not found");
                     return;
                   }
-                  const sourcemapPath = `${entryPath}.map`;
-                  if (fs.existsSync(sourcemapPath)) {
-                    logger.warn(
-                      "sourcemap detected for entry.mjs - line numbers may be off by 2 lines due to boot injection"
-                    );
+                  const entryChunk = bundle["entry.mjs"];
+                  if (!entryChunk || entryChunk.type !== "chunk") {
+                    logger.warn("entry.mjs not found - boot injection skipped");
+                    return;
                   }
-                  let content = fs.readFileSync(entryPath, "utf-8");
-                  const bootImport = `import * as __boot from './${bootChunkName}';
-await __boot.onStartup?.();
-if (__boot.onShutdown) process.on('SIGTERM', async () => { await __boot.onShutdown(); process.exit(0); });
+                  pageModules = [];
+                  middlewarePath = null;
+                  for (const [fileName, chunk] of Object.entries(bundle)) {
+                    if (chunk.type !== "chunk") continue;
+                    if (fileName.startsWith("pages/") && fileName.endsWith(".mjs")) {
+                      pageModules.push(fileName);
+                    }
+                    if (fileName.includes("_astro-internal_middleware") || fileName.includes("_noop-middleware")) {
+                      middlewarePath = fileName;
+                    }
+                  }
+                  const { host, port } = getServerDefaults(astroConfig);
+                  const bootImport = `globalThis.__astroscope_server_url = import.meta.url;
+import * as __boot from './${bootChunkName}';
+const __bootContext = { dev: false, host: process.env.HOST ?? '${host}', port: process.env.PORT ? Number(process.env.PORT) : ${port} };
+await __boot.onStartup?.(__bootContext);
+if (__boot.onShutdown) process.on('SIGTERM', async () => { await __boot.onShutdown(__bootContext); process.exit(0); });
 `;
-                  content = bootImport + content;
-                  fs.writeFileSync(entryPath, content);
+                  const s = new MagicString(entryChunk.code);
+                  s.prepend(bootImport);
+                  entryChunk.code = s.toString();
+                  if (entryChunk.map) {
+                    entryChunk.map = s.generateMap({ hires: true });
+                  }
                   logger.info(`injected ${bootChunkName} into entry.mjs`);
+                },
+                writeBundle(outputOptions) {
+                  if (!isSSR) return;
+                  const outDir = outputOptions.dir;
+                  if (!outDir) return;
+                  const modules = [];
+                  if (middlewarePath) {
+                    modules.push(`./${middlewarePath}`);
+                  }
+                  for (const page of pageModules) {
+                    modules.push(`./${page}`);
+                  }
+                  const manifestPath = path.join(outDir, "chunks", WARMUP_MANIFEST_FILE);
+                  fs.writeFileSync(manifestPath, JSON.stringify({ modules }));
+                  logger.info(`generated warmup for ${pageModules.length} pages`);
                 }
               }
             ]
@@ -190,5 +228,6 @@ if (__boot.onShutdown) process.on('SIGTERM', async () => { await __boot.onShutdo
   };
 }
 export {
+  boot,
   boot as default
 };

package/dist/types-CxpusND2.d.cts

@@ -0,0 +1,18 @@
+interface BootContext {
+    /** Whether running in development mode (vite dev server) */
+    dev: boolean;
+    /** Server host from Astro config */
+    host: string;
+    /** Server port from Astro config */
+    port: number;
+}
+interface WarmupResult {
+    /** Modules that were successfully loaded */
+    success: string[];
+    /** Modules that failed to load */
+    failed: string[];
+    /** Time taken in milliseconds */
+    duration: number;
+}
+
+export type { BootContext as B, WarmupResult as W };

package/dist/types-CxpusND2.d.ts

@@ -0,0 +1,18 @@
+interface BootContext {
+    /** Whether running in development mode (vite dev server) */
+    dev: boolean;
+    /** Server host from Astro config */
+    host: string;
+    /** Server port from Astro config */
+    port: number;
+}
+interface WarmupResult {
+    /** Modules that were successfully loaded */
+    success: string[];
+    /** Modules that failed to load */
+    failed: string[];
+    /** Time taken in milliseconds */
+    duration: number;
+}
+
+export type { BootContext as B, WarmupResult as W };

package/dist/warmup.cjs

@@ -0,0 +1,79 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/warmup.ts
+var warmup_exports = {};
+__export(warmup_exports, {
+  warmup: () => warmup
+});
+module.exports = __toCommonJS(warmup_exports);
+var import_node_fs = require("fs");
+var import_node_path = require("path");
+var import_node_url = require("url");
+var import_meta = {};
+var WARMUP_MANIFEST_FILE = "warmup-manifest.json";
+function isDevMode() {
+  return Boolean(import_meta.env?.["DEV"]);
+}
+function loadManifest() {
+  if (isDevMode()) {
+    return null;
+  }
+  const serverUrl = globalThis.__astroscope_server_url;
+  if (!serverUrl) {
+    return null;
+  }
+  const serverDir = (0, import_node_path.dirname)((0, import_node_url.fileURLToPath)(serverUrl));
+  const manifestPath = (0, import_node_path.join)(serverDir, "chunks", WARMUP_MANIFEST_FILE);
+  if (!(0, import_node_fs.existsSync)(manifestPath)) {
+    return null;
+  }
+  const manifest = JSON.parse((0, import_node_fs.readFileSync)(manifestPath, "utf-8"));
+  return {
+    modules: manifest.modules ?? [],
+    serverDir
+  };
+}
+async function warmup() {
+  const manifest = loadManifest();
+  if (!manifest || manifest.modules.length === 0) {
+    return { success: [], failed: [], duration: 0 };
+  }
+  const { modules, serverDir } = manifest;
+  const start = Date.now();
+  const resolvedModules = modules.map((mod) => {
+    const absolutePath = (0, import_node_path.resolve)(serverDir, mod);
+    return (0, import_node_url.pathToFileURL)(absolutePath).href;
+  });
+  const results = await Promise.allSettled(resolvedModules.map((mod) => import(mod)));
+  const success = [];
+  const failed = [];
+  for (let i = 0; i < results.length; i++) {
+    if (results[i].status === "fulfilled") {
+      success.push(modules[i]);
+    } else {
+      failed.push(modules[i]);
+    }
+  }
+  return { success, failed, duration: Date.now() - start };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  warmup
+});

package/dist/warmup.d.cts

@@ -0,0 +1,22 @@
+import { W as WarmupResult } from './types-CxpusND2.cjs';
+
+declare global {
+    var __astroscope_server_url: string | undefined;
+}
+/**
+ * Warms up V8 by importing all page modules and middleware.
+ *
+ * In development mode, this is a no-op that returns empty results.
+ * In production, reads the warmup manifest and imports all discovered modules.
+ *
+ * @example
+ * ```ts
+ * import { warmup } from '@astroscope/boot/warmup';
+ *
+ * const result = await warmup();
+ * console.log(`warmed up ${result.success.length} modules`);
+ * ```
+ */
+declare function warmup(): Promise<WarmupResult>;
+
+export { WarmupResult, warmup };

package/dist/warmup.d.ts

@@ -0,0 +1,22 @@
+import { W as WarmupResult } from './types-CxpusND2.js';
+
+declare global {
+    var __astroscope_server_url: string | undefined;
+}
+/**
+ * Warms up V8 by importing all page modules and middleware.
+ *
+ * In development mode, this is a no-op that returns empty results.
+ * In production, reads the warmup manifest and imports all discovered modules.
+ *
+ * @example
+ * ```ts
+ * import { warmup } from '@astroscope/boot/warmup';
+ *
+ * const result = await warmup();
+ * console.log(`warmed up ${result.success.length} modules`);
+ * ```
+ */
+declare function warmup(): Promise<WarmupResult>;
+
+export { WarmupResult, warmup };

package/dist/warmup.js

@@ -0,0 +1,53 @@
+// src/warmup.ts
+import { existsSync, readFileSync } from "fs";
+import { dirname, join, resolve } from "path";
+import { fileURLToPath, pathToFileURL } from "url";
+var WARMUP_MANIFEST_FILE = "warmup-manifest.json";
+function isDevMode() {
+  return Boolean(import.meta.env?.["DEV"]);
+}
+function loadManifest() {
+  if (isDevMode()) {
+    return null;
+  }
+  const serverUrl = globalThis.__astroscope_server_url;
+  if (!serverUrl) {
+    return null;
+  }
+  const serverDir = dirname(fileURLToPath(serverUrl));
+  const manifestPath = join(serverDir, "chunks", WARMUP_MANIFEST_FILE);
+  if (!existsSync(manifestPath)) {
+    return null;
+  }
+  const manifest = JSON.parse(readFileSync(manifestPath, "utf-8"));
+  return {
+    modules: manifest.modules ?? [],
+    serverDir
+  };
+}
+async function warmup() {
+  const manifest = loadManifest();
+  if (!manifest || manifest.modules.length === 0) {
+    return { success: [], failed: [], duration: 0 };
+  }
+  const { modules, serverDir } = manifest;
+  const start = Date.now();
+  const resolvedModules = modules.map((mod) => {
+    const absolutePath = resolve(serverDir, mod);
+    return pathToFileURL(absolutePath).href;
+  });
+  const results = await Promise.allSettled(resolvedModules.map((mod) => import(mod)));
+  const success = [];
+  const failed = [];
+  for (let i = 0; i < results.length; i++) {
+    if (results[i].status === "fulfilled") {
+      success.push(modules[i]);
+    } else {
+      failed.push(modules[i]);
+    }
+  }
+  return { success, failed, duration: Date.now() - start };
+}
+export {
+  warmup
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astroscope/boot",
-  "version": "0.1.3",
+  "version": "0.2.1",
   "description": "Startup and graceful shutdown hooks for Astro SSR",
   "type": "module",
   "main": "./dist/index.js",
@@ -10,6 +10,10 @@
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js",
       "require": "./dist/index.cjs"
+    },
+    "./warmup": {
+      "types": "./dist/warmup.d.ts",
+      "import": "./dist/warmup.js"
     }
   },
   "files": [
@@ -37,17 +41,20 @@
   },
   "homepage": "https://github.com/smnbbrv/astroscope/tree/main/packages/boot#readme",
   "scripts": {
-    "build": "tsup src/index.ts --format esm,cjs --dts",
+    "build": "tsup src/index.ts src/warmup.ts --format esm,cjs --dts",
     "typecheck": "tsc --noEmit",
     "lint": "eslint 'src/**/*.{ts,tsx}'",
     "lint:fix": "eslint 'src/**/*.{ts,tsx}' --fix"
   },
   "devDependencies": {
-    "astro": "^5.16.9",
+    "astro": "^5.17.1",
     "tsup": "^8.5.1",
     "typescript": "^5.9.3"
   },
   "peerDependencies": {
     "astro": "^5.0.0"
+  },
+  "dependencies": {
+    "magic-string": "^0.30.21"
   }
 }