Docker & cross-host setups
When CF and the Vite/Node sidecar live on different hosts (most commonly: CF in a Docker container, Vite/Node on the host), two URLs need to work from different perspectives:
+Docker & cross-host setups
When CF and the Vite/Node sidecar live on different hosts (most commonly: CF in a Docker container, Vite/Node on the host), two URLs need to work from different perspectives:
ssrUrl— CF → Node sidecar (server-to-server). Set this on the CF container.viteUrl— Browser → Vite dev server. Set this so generated<script src="...">URLs are reachable from the user’s browser.
Don’t run Node inside the CF container
Section titled “Don’t run Node inside the CF container”Coldspa’s Application.cfc will try to spawn npm run dev and npm run ssr on application start. In a typical Docker setup the CF container has no Node installed, so the spawn fails — Coldspa detects that npm isn’t on PATH and skips the spawn (with a one-line note in WEB-INF/coldspa-logs/manager.log). You’re then expected to run Vite/Node externally and point ssrUrl/viteUrl at them.
If you’d like to suppress the auto-spawn entirely (and the npm probe), set COLDSPA_NO_BOOTSTRAP=1 on the CF container.
Common patterns
Section titled “Common patterns”Getting Started
This walks through wiring Coldspa into a fresh project from scratch — installing both halves (CFML + Node), setting up the renderer, and rendering your first island.
+Getting Started
This walks through wiring Coldspa into a fresh project from scratch — installing both halves (CFML + Node), setting up the renderer, and rendering your first island.
Prerequisites
Section titled “Prerequisites”- ColdFusion (Adobe ColdFusion 2023+ or Lucee 5+) @@ -83,10 +83,25 @@
- Register the module’s directory as a custom tag path so
<cf_Island>and<cf_Slot>resolve from anywhere.
+ - Delegate the three lifecycle methods to
coldspa.Bootstrapso Coldspa can cache its config and auto-spawn the Vite dev server + Node SSR sidecar.
+ onApplicationStart— cachesapplication.coldspaConfigand (in dev) spawnsviteand the SSR sidecar in the background. In production it validatesdist/.vite/manifest.jsonand runsnpm run buildonce if it’s missing.
+onApplicationStop— tears down the spawned Node processes so they don’t outlive the CF app.
+onRequestStart— enables the?reloadConfig=1and?reloadApp=1dev hooks. No-op otherwise.
+
Via CommandBox:
box install coldspaThis 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
Section titled “2. Register the custom tag path”Add the module’s directory to your app’s custom tag paths so <cf_Island> and <cf_Slot> resolve from anywhere:
component { this.name = "MyApp"; this.customTagPaths = expandPath("/modules/coldspa");}ColdBox users can skip this step — the bundled ModuleConfig.cfc wires it automatically.
2. Wire up Application.cfc
Section titled “2. Wire up Application.cfc”Two things need to happen here:
+-
+
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; }}What each delegate does:
+-
+
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.
3. Install the Node side
Section titled “3. Install the Node side”Coldspa uses Vite for asset bundling and a small Node sidecar for server-side rendering.
npm install coldspa vite vue # Vue# ornpm install coldspa vite react react-dom @vitejs/plugin-react # React<cf_Island
framework="#Vue#"
path="./src/App.vue"
props="#{ hello: 'World' }#"
strategy="visible">
<p>This sentence comes from the default slot in CFML.</p>
</cf_Island>
9. Run it
Section titled “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:
npm run dev # Vite dev server (HMR)npm run ssr # Node SSR sidecarLoad the page. You should see your component server-rendered into the response, then hydrated when it scrolls into view.
+During iteration:
+-
+
?reloadConfig=1— re-readscoldspa.config.json+ env vars without bouncing the app.
+?reloadApp=1— also tears down and re-spawns the Node processes.
+
10. Build for production
Section titled “10. Build for production”npm run build # builds client bundle (dist/) AND SSR bundle (dist-ssr/)npm run ssr:prod # runs the sidecar against the built bundleSet 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
Section titled “Where to next”- Hydration strategies —
load,idle,visible,client
diff --git a/pagefind/fragment/en_41da34f.pf_fragment b/pagefind/fragment/en_41da34f.pf_fragment
new file mode 100644
index 0000000000000000000000000000000000000000..de0fd500cf7c5a241fc034d93598b05f51fb273a
GIT binary patch
literal 1057
zcmb2|=3oE;rvIg(|MQg01?r~0{3jY>;C|_~=L&llrt96a+B90e^e=Ntvpu~l{mt69
zt&2ET@?TVcGr1&(nOk$Y#>B^Sf7*OLYi=wWpP;yPMrX{Pw5_3$_OJD_G%u7EFXrC4
zLihWn7kSsty*RY^TS`&!pU#85frmn6bgUMKy-?WMbmf8f%L5UOVtQUXH7-`JSYs0Q
zi&x~5)%{n8J=QNVt@3=Z;ZfM9ok|nx|Nmp>N`ClkTeWe{;R{dZU)*-`Hiw)35%tKb
z&c6?P{LU+`Da`Br$X=gXw9erH*DeDA?@hDr8SPlN^por__k@GlPi3v;*_xl