From 693ec3a0059e194a2ed281949aa62d95bbabd30b Mon Sep 17 00:00:00 2001
From: Corbin Crutchley <git@crutchcorn.dev>
Date: Mon, 4 May 2026 04:12:36 -0700
Subject: [PATCH] docs: update mention of sidecar

---
 README.md               | 14 +------------
 docs/getting-started.md | 44 +++++++++++++++++++++++++++++++++++------
 2 files changed, 39 insertions(+), 19 deletions(-)

diff --git a/README.md b/README.md
index 1be1f88..8aa6e80 100644
--- a/README.md
+++ b/README.md
@@ -96,19 +96,7 @@ export default defineConfig({
 </cf_Island>
 ```
 
-## Run it
-
-```bash
-npm run dev      # Vite dev server (HMR)
-npm run ssr      # Node SSR sidecar
-```
-
-For production:
-
-```bash
-npm run build      # builds client + SSR bundles
-npm run ssr:prod   # runs the sidecar against the built bundle
-```
+That's it — start your CF server and load the page. `coldspa.Bootstrap` auto-spawns the Vite dev server and Node SSR sidecar in the background and tears them down on app stop. For Docker, supervised deployments, or opting out, see [Getting started](docs/getting-started.md).
 
 ## Documentation
 
diff --git a/docs/getting-started.md b/docs/getting-started.md
index 5fc324e..6a7afc0 100644
--- a/docs/getting-started.md
+++ b/docs/getting-started.md
@@ -22,19 +22,46 @@ box install coldspa
 
 This drops the package at `./modules/coldspa/`, including `Island.cfm`, `Slot.cfm`, the renderer files (`coldspa/renderers/Vue.cfm`, `coldspa/renderers/React.cfm`), and the SSR sidecar.
 
-## 2. Register the custom tag path
+## 2. Wire up `Application.cfc`
 
-Add the module's directory to your app's custom tag paths so `<cf_Island>` and `<cf_Slot>` resolve from anywhere:
+Two things need to happen here:
+
+1. Register the module's directory as a custom tag path so `<cf_Island>` and `<cf_Slot>` resolve from anywhere.
+2. Delegate the three lifecycle methods to `coldspa.Bootstrap` so Coldspa can cache its config and auto-spawn the Vite dev server + Node SSR sidecar.
 
 ```cfc
 // Application.cfc
 component {
     this.name = "MyApp";
     this.customTagPaths = expandPath("/modules/coldspa");
+
+    function onApplicationStart() {
+        new coldspa.Bootstrap().onApplicationStart();
+        return true;
+    }
+
+    function onApplicationStop() {
+        new coldspa.Bootstrap().onApplicationStop();
+    }
+
+    function onRequestStart(targetPage) {
+        new coldspa.Bootstrap().onRequestStart();
+        return true;
+    }
 }
 ```
 
-ColdBox users can skip this step — the bundled `ModuleConfig.cfc` wires it automatically.
+What each delegate does:
+
+- `onApplicationStart` — caches `application.coldspaConfig` and (in dev) spawns `vite` and the SSR sidecar in the background. In production it validates `dist/.vite/manifest.json` and runs `npm run build` once if it's missing.
+- `onApplicationStop` — tears down the spawned Node processes so they don't outlive the CF app.
+- `onRequestStart` — enables the `?reloadConfig=1` and `?reloadApp=1` dev hooks. No-op otherwise.
+
+Logs from the spawned processes land in `WEB-INF/coldspa-logs/{vite,ssr,manager}.log`.
+
+**ColdBox users can skip this step entirely** — the bundled `ModuleConfig.cfc` registers the custom tag path *and* hooks `Bootstrap` into the `afterAspectsLoad`, `preReinit`, and `preProcess` interceptors.
+
+**Managing Node yourself?** If you'd rather run Vite/SSR under systemd, docker-compose, or your platform's process supervisor, set `COLDSPA_NO_BOOTSTRAP=1` in the CF process env. `Bootstrap.onApplicationStart` will still cache config but skip the spawn. Coldspa also auto-detects this when `npm` isn't on PATH (the typical CF-in-Docker case) — see [Docker & cross-host setups](docker).
 
 ## 3. Install the Node side
 
@@ -133,14 +160,19 @@ defineProps({ hello: { type: String, default: '' } });
 
 ## 9. Run it
 
-In two terminals:
+Start your CF server. That's it — `Bootstrap.onApplicationStart` spawns both `vite` and the SSR sidecar for you in the background. Load the page and you should see your component server-rendered into the response, then hydrated when it scrolls into view.
+
+If you'd rather drive the Node side yourself (set `COLDSPA_NO_BOOTSTRAP=1` first), use two terminals:
 
 ```bash
 npm run dev      # Vite dev server (HMR)
 npm run ssr      # Node SSR sidecar
 ```
 
-Load the page. You should see your component server-rendered into the response, then hydrated when it scrolls into view.
+During iteration:
+
+- `?reloadConfig=1` — re-reads `coldspa.config.json` + env vars without bouncing the app.
+- `?reloadApp=1` — also tears down and re-spawns the Node processes.
 
 ## 10. Build for production
 
@@ -149,7 +181,7 @@ npm run build      # builds client bundle (dist/) AND SSR bundle (dist-ssr/)
 npm run ssr:prod   # runs the sidecar against the built bundle
 ```
 
-Set `isDev: false` (or unset `CF_ENV`) so CFML reads from `dist/.vite/manifest.json` instead of the dev server.
+Set `isDev: false` (or `CF_ENV=production`) so CFML reads from `dist/.vite/manifest.json` instead of the dev server. With `Bootstrap` wired up, the production sidecar (`npm run ssr:prod` equivalent) is launched automatically on `onApplicationStart` — no separate process to babysit. Set `COLDSPA_NO_BOOTSTRAP=1` if you'd rather run it under systemd / docker-compose / your platform's supervisor.
 
 ## Where to next
 
-- 
2.51.2