From ed75539fbb95dd264ed66c04ae0f38a9069d2e1a Mon Sep 17 00:00:00 2001 From: Corbin Crutchley Date: Mon, 4 May 2026 02:57:59 -0700 Subject: [PATCH] chore: update for NPM publish --- LICENSE | 21 ++++++ README.md | 124 +++++++++++------------------------ coldspa/vite/ssr-server.js | 1 + docs/configuration.md | 43 ++++++++++++ docs/docker.md | 28 ++++++++ docs/hydration-strategies.md | 27 ++++++++ package-lock.json | 73 ++++++++++++++++++--- package.json | 66 +++++++++++++++++-- vite.config.js | 2 +- vite.config.react.js | 2 +- vite.config.vue.js | 2 +- 11 files changed, 284 insertions(+), 105 deletions(-) create mode 100644 LICENSE create mode 100644 docs/configuration.md create mode 100644 docs/docker.md create mode 100644 docs/hydration-strategies.md diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000..aa4db8b --- /dev/null +++ b/LICENSE @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2026-present Corbin Crutchley + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. \ No newline at end of file diff --git a/README.md b/README.md index fff2f92..7d1fe81 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,31 @@ # Coldspa -Astro-style framework islands for ColdFusion. Mount Vue (and React, soon) components into CFML pages with server-side rendering and progressive hydration. +Give your CFML a spa day. The Islands Architecture for ColdFusion. Mount Vue or React components into CFML pages with server-side rendering and progressive hydration. + +## Install + +```bash +npm install coldspa vite vue # or: react react-dom +``` + +## Configure Vite + +```js +// vite.config.js +import { defineConfig } from 'vite'; +import coldspa from 'coldspa/vite'; + +export default defineConfig({ + plugins: [ + coldspa({ + frameworks: ['vue'], // or ['vue', 'react'] + globs: { vue: '/src/**/*.vue' } // where your components live + }) + ] +}); +``` + +## Use it from CFML ```cfml @@ -10,13 +35,18 @@ Astro-style framework islands for ColdFusion. Mount Vue (and React, soon) compon path="./src/App.vue" props="#{ hello: 'World' }#" strategy="visible"> + +

Default-slot content rendered by CFML.

+ + +

Header from CFML

+ ``` -## Quick start +## Run it ```bash -npm install npm run dev # Vite dev server (HMR) npm run ssr # Node SSR sidecar ``` @@ -28,88 +58,10 @@ npm run build # builds client + SSR bundles npm run ssr:prod # runs the sidecar against the built bundle ``` -## Hydration strategies - -`strategy=` controls when (and whether) the component renders. - -| Strategy | SSR'd HTML? | Client boots when… | -|-----------|-------------|-----------------------------------------------------| -| `load` | yes | the module loads (default) | -| `idle` | yes | `requestIdleCallback` fires | -| `visible` | yes | the mount enters the viewport (`IntersectionObserver`) | -| `client` | **no** | the module loads (no SSR HTML or CSS is emitted) | - -Use `client` for components that depend on browser-only APIs (window, IndexedDB, etc.) or where SSR isn't worth the round-trip. - -## Configuration - -Coldspa resolves config in this order (highest priority first): - -1. **Environment variables** — for CI/CD, Docker, prod -2. **`coldspa.config.json`** in the webroot — for local dev / Admin UI -3. **Built-in defaults** - -### Environment variables - -| Variable | Effect | -|---------------------|--------------------------------------------------------------------------| -| `CF_ENV` | `development` / `dev` switches Coldspa to dev mode | -| `COLDSPA_SSR_URL` | Where **CF** reaches the SSR sidecar (server-to-server) | -| `COLDSPA_VITE_URL` | Where the **browser** reaches the Vite dev server (used for asset URLs) | -| `COLDSPA_DEBUG` | `1` / `true` emits diagnostic HTML comments per island | -| `COLDSPA_SSR_PORT` | (sidecar) Port to listen on. Default `5174` | -| `COLDSPA_SSR_HOST` | (sidecar) Bind address. Default `0.0.0.0`. Use `127.0.0.1` to lock down | -| `NODE_ENV` | (sidecar) `production` switches sidecar to use built bundle | - -### `coldspa.config.json` - -Lives in the webroot. Should be `.gitignore`d (it can be edited via the CF Admin UI). Any keys you set here are merged on top of defaults but overridden by env vars. - -```json -{ - "isDev": true, - "debug": false, - "ssrUrl": "http://127.0.0.1:5174", - "viteUrl": "http://localhost:5173", - "vitePort": "5173" -} -``` - -| Key | Default | Description | -|------------|--------------------------|-------------------------------------------------------------| -| `isDev` | `false` | Dev mode (uses Vite dev server) vs prod (uses `dist/`) | -| `debug` | `false` | Emit `` diagnostic comments | -| `ssrUrl` | `http://127.0.0.1:5174` | SSR sidecar URL (server-to-server) | -| `viteUrl` | unset | Browser-facing Vite URL. Falls back to `localhost:vitePort` | -| `vitePort` | `"5173"` | Used to build the default `viteUrl` if `viteUrl` is unset | - -After editing `coldspa.config.json`, request any page with `?reloadApp=1` to bust the cached config (or restart CF). - -### Docker / cross-host setups - -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 `