@astroscope/boot 0.1.0

package/README.md

@@ -0,0 +1,106 @@
+# @astroscope/boot
+
+Run initialization and cleanup code for your Astro server.
+
+## Examples
+
+See the [demo/boot](../../demo/boot) directory for a working example.
+
+## Installation
+
+```bash
+bun add @astroscope/boot
+```
+
+## Usage
+
+1. Create a boot file at `src/boot.ts` (or `src/boot/index.ts`):
+
+```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:
+
+```ts
+// 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"`
+
+```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).
+
+- **Type**: `boolean`
+- **Default**: `false`
+
+```ts
+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

package/dist/index.cjs

@@ -0,0 +1,150 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+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 __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  default: () => boot
+});
+module.exports = __toCommonJS(index_exports);
+var import_node_fs = __toESM(require("fs"), 1);
+var import_node_path = __toESM(require("path"), 1);
+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";
+}
+function boot(options = {}) {
+  const entry = resolveEntry(options.entry);
+  const hmr = options.hmr ?? false;
+  let isBuild = false;
+  let isSSR = false;
+  let bootChunkRef = null;
+  return {
+    name: "@astroscope/boot",
+    hooks: {
+      "astro:config:setup": ({ command, updateConfig, logger }) => {
+        isBuild = command === "build";
+        updateConfig({
+          vite: {
+            plugins: [
+              {
+                name: "@astroscope/boot",
+                configureServer(server) {
+                  if (isBuild) return;
+                  server.httpServer?.once("listening", async () => {
+                    try {
+                      const module2 = await server.ssrLoadModule(
+                        `/${entry}`
+                      );
+                      if (module2.onStartup) {
+                        await module2.onStartup();
+                      }
+                    } catch (error) {
+                      logger.error(`Error running startup script: ${error}`);
+                    }
+                  });
+                  server.httpServer?.once("close", async () => {
+                    try {
+                      const module2 = await server.ssrLoadModule(
+                        `/${entry}`
+                      );
+                      if (module2.onShutdown) {
+                        await module2.onShutdown();
+                      }
+                    } catch (error) {
+                      logger.error(`Error running shutdown script: ${error}`);
+                    }
+                  });
+                  if (hmr) {
+                    server.watcher.on("change", async (changedPath) => {
+                      if (!changedPath.endsWith(entry)) return;
+                      logger.info("boot file changed, re-running onStartup...");
+                      try {
+                        server.moduleGraph.invalidateAll();
+                        const module2 = await server.ssrLoadModule(
+                          `/${entry}`
+                        );
+                        if (module2.onStartup) {
+                          await module2.onStartup();
+                        }
+                      } catch (error) {
+                        logger.error(`Error running startup script: ${error}`);
+                      }
+                    });
+                  }
+                },
+                configResolved(config) {
+                  isSSR = !!config.build?.ssr;
+                },
+                buildStart() {
+                  if (!isSSR) return;
+                  try {
+                    bootChunkRef = this.emitFile({
+                      type: "chunk",
+                      id: entry,
+                      name: "boot"
+                    });
+                  } catch {
+                  }
+                },
+                writeBundle(outputOptions) {
+                  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)) 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"
+                    );
+                  }
+                  let content = import_node_fs.default.readFileSync(entryPath, "utf-8");
+                  const bootImport = `import { onStartup, onShutdown } from './${bootChunkName}';
+await onStartup?.();
+if (onShutdown) process.on('SIGTERM', async () => { await onShutdown(); process.exit(0); });
+`;
+                  content = bootImport + content;
+                  import_node_fs.default.writeFileSync(entryPath, content);
+                  logger.info(`injected ${bootChunkName} into entry.mjs`);
+                }
+              }
+            ]
+          }
+        });
+      }
+    }
+  };
+}

package/dist/index.d.cts

@@ -0,0 +1,17 @@
+import { AstroIntegration } from 'astro';
+
+interface BootOptions {
+    /**
+     * Path to the boot file relative to the project root.
+     * @default "src/boot.ts"
+     */
+    entry?: string;
+    /**
+     * Enable HMR for the boot file. When true, `onStartup` will re-run when the boot file changes.
+     * @default false
+     */
+    hmr?: boolean;
+}
+declare function boot(options?: BootOptions): AstroIntegration;
+
+export { type BootOptions, boot as default };

package/dist/index.d.ts

@@ -0,0 +1,17 @@
+import { AstroIntegration } from 'astro';
+
+interface BootOptions {
+    /**
+     * Path to the boot file relative to the project root.
+     * @default "src/boot.ts"
+     */
+    entry?: string;
+    /**
+     * Enable HMR for the boot file. When true, `onStartup` will re-run when the boot file changes.
+     * @default false
+     */
+    hmr?: boolean;
+}
+declare function boot(options?: BootOptions): AstroIntegration;
+
+export { type BootOptions, boot as default };

package/dist/index.js

@@ -0,0 +1,119 @@
+// src/index.ts
+import fs from "fs";
+import path from "path";
+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";
+}
+function boot(options = {}) {
+  const entry = resolveEntry(options.entry);
+  const hmr = options.hmr ?? false;
+  let isBuild = false;
+  let isSSR = false;
+  let bootChunkRef = null;
+  return {
+    name: "@astroscope/boot",
+    hooks: {
+      "astro:config:setup": ({ command, updateConfig, logger }) => {
+        isBuild = command === "build";
+        updateConfig({
+          vite: {
+            plugins: [
+              {
+                name: "@astroscope/boot",
+                configureServer(server) {
+                  if (isBuild) return;
+                  server.httpServer?.once("listening", async () => {
+                    try {
+                      const module = await server.ssrLoadModule(
+                        `/${entry}`
+                      );
+                      if (module.onStartup) {
+                        await module.onStartup();
+                      }
+                    } catch (error) {
+                      logger.error(`Error running startup script: ${error}`);
+                    }
+                  });
+                  server.httpServer?.once("close", async () => {
+                    try {
+                      const module = await server.ssrLoadModule(
+                        `/${entry}`
+                      );
+                      if (module.onShutdown) {
+                        await module.onShutdown();
+                      }
+                    } catch (error) {
+                      logger.error(`Error running shutdown script: ${error}`);
+                    }
+                  });
+                  if (hmr) {
+                    server.watcher.on("change", async (changedPath) => {
+                      if (!changedPath.endsWith(entry)) return;
+                      logger.info("boot file changed, re-running onStartup...");
+                      try {
+                        server.moduleGraph.invalidateAll();
+                        const module = await server.ssrLoadModule(
+                          `/${entry}`
+                        );
+                        if (module.onStartup) {
+                          await module.onStartup();
+                        }
+                      } catch (error) {
+                        logger.error(`Error running startup script: ${error}`);
+                      }
+                    });
+                  }
+                },
+                configResolved(config) {
+                  isSSR = !!config.build?.ssr;
+                },
+                buildStart() {
+                  if (!isSSR) return;
+                  try {
+                    bootChunkRef = this.emitFile({
+                      type: "chunk",
+                      id: entry,
+                      name: "boot"
+                    });
+                  } catch {
+                  }
+                },
+                writeBundle(outputOptions) {
+                  const outDir = outputOptions.dir;
+                  if (!outDir || !bootChunkRef) return;
+                  const entryPath = path.join(outDir, "entry.mjs");
+                  if (!fs.existsSync(entryPath)) 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"
+                    );
+                  }
+                  let content = fs.readFileSync(entryPath, "utf-8");
+                  const bootImport = `import { onStartup, onShutdown } from './${bootChunkName}';
+await onStartup?.();
+if (onShutdown) process.on('SIGTERM', async () => { await onShutdown(); process.exit(0); });
+`;
+                  content = bootImport + content;
+                  fs.writeFileSync(entryPath, content);
+                  logger.info(`injected ${bootChunkName} into entry.mjs`);
+                }
+              }
+            ]
+          }
+        });
+      }
+    }
+  };
+}
+export {
+  boot as default
+};

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@astroscope/boot",
+  "version": "0.1.0",
+  "description": "Boot integration for Astro",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "sideEffects": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/smnbbrv/astroscope.git",
+    "directory": "packages/boot"
+  },
+  "keywords": [
+    "astro",
+    "astro-integration",
+    "boot",
+    "frameworks"
+  ],
+  "author": "smnbbrv",
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/smnbbrv/astroscope/issues"
+  },
+  "homepage": "https://github.com/smnbbrv/astroscope/tree/main/packages/boot#readme",
+  "scripts": {
+    "build": "tsup src/index.ts --format esm,cjs --dts",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint 'src/**/*.{ts,tsx}'",
+    "lint:fix": "eslint 'src/**/*.{ts,tsx}' --fix"
+  },
+  "devDependencies": {
+    "astro": "^5.1.0",
+    "tsup": "^8.5.1",
+    "typescript": "^5.9.3"
+  },
+  "peerDependencies": {
+    "astro": "^5.0.0"
+  }
+}