@jasonshimmy/vite-plugin-cer-app 0.23.2 → 0.25.0

package/docs/cli.md

@@ -1,324 +0,0 @@
-# CLI Reference
-
-The framework provides two CLI programs:
-
-- **`cer-app`** — dev server, build, preview, and generate commands
-- **`create-cer-app`** — project scaffolding
-
-Both are available after installing `@jasonshimmy/vite-plugin-cer-app` as a dev dependency, or globally:
-
-```sh
-npm install -g @jasonshimmy/vite-plugin-cer-app
-```
-
----
-
-## `cer-app`
-
-### `cer-app dev`
-
-Starts the Vite development server. Reads `cer.config.ts` from the current directory.
-
-```sh
-cer-app dev [options]
-```
-
-| Option | Default | Description |
-|---|---|---|
-| `-p, --port <port>` | `3000` | Port to listen on |
-| `--host <host>` | `localhost` | Host to bind to |
-| `--root <root>` | `process.cwd()` | Project root directory |
-
-**Examples:**
-
-```sh
-cer-app dev
-cer-app dev --port 4000
-cer-app dev --host 0.0.0.0 --port 8080
-cer-app dev --root ./packages/my-app
-```
-
-**Behavior:**
-
-- Loads and transpiles `cer.config.ts` (or `cer.config.js`)
-- Starts the Vite dev server with `cerApp()` plugins applied
-- In SSR mode: intercepts HTML requests and renders server-side
-- In SPA mode: standard Vite HMR
-- Watches `app/` and `server/` directories; full-reloads when pages or components are added/removed
-- Responds to `SIGTERM` and `SIGINT` with graceful shutdown
-
----
-
-### `cer-app build`
-
-Builds the application for production.
-
-```sh
-cer-app build [options]
-```
-
-| Option | Default | Description |
-|---|---|---|
-| `--root <root>` | `process.cwd()` | Project root directory |
-| `--mode <mode>` | From `cer.config.ts` | Override rendering mode: `spa`, `ssr`, or `ssg` |
-
-**Examples:**
-
-```sh
-cer-app build
-cer-app build --mode ssr
-cer-app build --mode ssg
-cer-app build --root ./packages/my-app
-```
-
-**Per-mode behavior:**
-
-| Mode | Actions |
-|---|---|
-| `spa` | Standard `vite build` to `dist/` |
-| `ssr` | Dual build: client bundle to `dist/client/`, server bundle to `dist/server/server.js` |
-| `ssg` | Dual build + enumerate routes + render all paths to `dist/<path>/index.html` |
-
----
-
-### `cer-app preview`
-
-Serves the production build locally.
-
-```sh
-cer-app preview [options]
-```
-
-| Option | Default | Description |
-|---|---|---|
-| `-p, --port <port>` | `4173` | Port to listen on |
-| `--host <host>` | `localhost` | Host to bind to |
-| `--root <root>` | `process.cwd()` | Project root directory |
-| `--ssr` | Auto-detected | Load `dist/server/server.js` as the request handler |
-
-**Examples:**
-
-```sh
-cer-app preview                     # SPA/SSG static file server
-cer-app preview --ssr               # SSR server using dist/server/server.js
-cer-app preview --port 8080
-```
-
-**Behavior:**
-
-- If `dist/server/server.js` exists (or `--ssr` is passed), starts an SSR preview server
-- Static assets from `dist/client/` are served first; HTML requests fall through to the SSR handler
-- Otherwise, starts a static file server with SPA fallback (serves `index.html` for unknown paths)
-- Returns 404 for paths not found in `dist/` (static mode only)
-- **Path traversal protection:** all file requests are validated against the `dist/` root — requests attempting to escape it (e.g. `GET /../../../../etc/passwd`) receive a `400` response
-- **Security headers:** every response includes `X-Content-Type-Options: nosniff`, `X-Frame-Options: DENY`, and `Referrer-Policy: strict-origin-when-cross-origin`
-- **Smart Cache-Control:** Vite content-hashes assets placed in `/assets/` — these are served with `Cache-Control: public, max-age=31536000, immutable`. All other files (HTML, etc.) use `Cache-Control: no-cache` so browsers always revalidate
-- **Graceful shutdown:** on `SIGTERM` or `SIGINT`, the server stops accepting new connections and waits for in-flight requests to finish before exiting. A 10-second timeout triggers a forced exit if connections do not drain
-- **Request timeouts:** `headersTimeout` (10 s) aborts connections that stall while sending headers; `requestTimeout` (30 s) limits the total time allowed per request/response cycle, protecting against slow-client attacks
-
----
-
-### `cer-app generate`
-
-Runs the SSG build pipeline. Alias for `cer-app build --mode ssg`.
-
-```sh
-cer-app generate [options]
-```
-
-| Option | Default | Description |
-|---|---|---|
-| `--root <root>` | `process.cwd()` | Project root directory |
-
-**Example:**
-
-```sh
-cer-app generate
-```
-
-**Output:**
-
-```
-dist/
-  index.html
-  about/index.html
-  blog/
-    hello-world/index.html
-  ssg-manifest.json
-```
-
----
-
-### `cer-app adapt`
-
-Adapts the production build for a deployment platform.
-
-Run this after `cer-app build` to produce the platform-specific output alongside `dist/`.
-You can also configure `adapter` in `cer.config.ts` so the adapter runs automatically at the end of every build.
-
-```sh
-cer-app adapt [options]
-```
-
-| Option | Default | Description |
-|---|---|---|
-| `--platform <platform>` | *(required)* | Target platform: `vercel`, `netlify`, or `cloudflare` |
-| `--root <root>` | `process.cwd()` | Project root directory |
-
-**Examples:**
-
-```sh
-cer-app adapt --platform vercel
-cer-app adapt --platform netlify
-cer-app adapt --platform cloudflare
-cer-app adapt --platform vercel --root ./packages/my-app
-```
-
-**Vercel behavior (`--platform vercel`):**
-
-- Writes `.vercel/output/` following the [Vercel Build Output API v3](https://vercel.com/docs/build-output-api/v3).
-- SSR builds: creates a Node.js Serverless Function at `.vercel/output/functions/index.func/` that routes `/api/*` to the exported API handlers and passes everything else to the SSR handler. Content-hashed assets are copied to `.vercel/output/static/` for CDN delivery.
-- SPA/SSG builds: copies static files to `.vercel/output/static/` with a SPA fallback route.
-- Deploy with `vercel deploy --prebuilt`.
-
-**Netlify behavior (`--platform netlify`):**
-
-- Writes `netlify/functions/ssr.mjs` — a Netlify Functions v2 bridge that converts the Web `Request`/`Response` API to the Node.js-style handler used by the server bundle. Handles `/api/*` routing inline.
-- Copies content-hashed assets to `.netlify/publish/` (no `index.html` — HTML is served by the function).
-- Writes `netlify.toml` with the publish directory, `Cache-Control` headers for assets, and a catch-all redirect to the SSR function.
-- SPA/SSG builds: writes `netlify.toml` only (no function needed).
-- SSR responses are streamed via the Web Streams `TransformStream` API — HTML chunks are forwarded to the client as they are written rather than waiting for the full page to render.
-- Deploy with `netlify deploy`.
-
-**Cloudflare behavior (`--platform cloudflare`):**
-
-- Writes `dist/_worker.js` — a Cloudflare Pages [Advanced Mode](https://developers.cloudflare.com/pages/functions/advanced-mode/) worker. The client HTML template is inlined in the worker as a string constant so `node:fs` is never needed at runtime.
-- Requires the `nodejs_compat` compatibility flag (written automatically into `wrangler.toml`) for `AsyncLocalStorage` and `node:stream` support.
-- Copies content-hashed assets to `dist/` alongside the worker. Cloudflare Pages CDN serves matched static files first; all other requests fall through to `_worker.js`.
-- SPA/SSG builds: no worker generated — Cloudflare Pages serves `dist/` as a static site.
-- SSR responses are streamed via the Web Streams `TransformStream` API — HTML chunks are forwarded to the client as they are written rather than waiting for the full page to render.
-- Deploy with `wrangler pages deploy dist`.
-
-**Auto-run via `cer.config.ts`:**
-
-```ts
-// cer.config.ts — built-in adapter
-export default defineConfig({
-  mode: 'ssr',
-  adapter: 'vercel',  // 'vercel' | 'netlify' | 'cloudflare'
-})
-```
-
-```ts
-// cer.config.ts — custom adapter (Railway, Fly.io, bare Node.js, Docker, …)
-export default defineConfig({
-  mode: 'ssr',
-  adapter: async (root) => {
-    const { cp, mkdir } = await import('node:fs/promises')
-    await mkdir(`${root}/deploy`, { recursive: true })
-    await cp(`${root}/dist`, `${root}/deploy/dist`, { recursive: true })
-  },
-})
-```
-
-Pass `--platform custom` to `cer-app adapt` to run a function adapter without re-building:
-
-```sh
-cer-app adapt --platform custom
-```
-
-See [`adapter` in configuration.md](./configuration.md#adapter) for the full options reference.
-
----
-
-## `create-cer-app`
-
-Scaffolds a new project from a template.
-
-> **Note:** Because the scaffolder is bundled inside `@jasonshimmy/vite-plugin-cer-app` rather than published as a standalone `create-cer-app` package, you must use the `--package` flag with `npx`:
->
-> ```sh
-> npx --package @jasonshimmy/vite-plugin-cer-app create-cer-app [project-name] [options]
-> ```
-
-| Argument / Option | Description |
-|---|---|
-| `[project-name]` | Name of the project (also used as the output directory) |
-| `--mode <mode>` | Rendering mode: `spa`, `ssr`, or `ssg` (skips interactive prompt) |
-| `--dir <dir>` | Output directory (defaults to `project-name`) |
-
-**Examples:**
-
-```sh
-npx --package @jasonshimmy/vite-plugin-cer-app create-cer-app                          # interactive prompts
-npx --package @jasonshimmy/vite-plugin-cer-app create-cer-app my-app                   # prompts for mode
-npx --package @jasonshimmy/vite-plugin-cer-app create-cer-app my-app --mode ssr        # no prompts
-npx --package @jasonshimmy/vite-plugin-cer-app create-cer-app my-blog --mode ssg --dir ./sites/blog
-```
-
-**Scaffolded files (all modes):**
-
-```
-my-app/
-  app/
-    app.ts          ← framework bootstrap (router, plugins, layout shell)
-    pages/index.ts
-    layouts/default.ts
-  index.html
-  cer.config.ts
-  package.json
-```
-
-**Per-mode differences:**
-
-| Mode | `cer.config.ts` | `package.json` scripts |
-|---|---|---|
-| SPA | `mode: 'spa'` | `dev`, `build`, `preview` |
-| SSR | `mode: 'ssr'` | `dev`, `build`, `preview --ssr` |
-| SSG | `mode: 'ssg'`, `ssg.routes: 'auto'` | `dev`, `build`, `preview`, `generate` |
-
----
-
-## Config file loading
-
-Both `cer-app dev` and `cer-app build` load `cer.config.ts` by:
-
-1. Bundling it with Vite into a temporary `.mjs` file in `node_modules/.cer-app-cache/`
-2. Dynamically importing the result
-
-This allows TypeScript syntax in `cer.config.ts` with full type checking. The cached bundle is regenerated on every CLI invocation.
-
-If no `cer.config.ts` or `cer.config.js` is found, defaults are used and a warning is printed.
-
----
-
-## Using with `npm run`
-
-After scaffolding, scripts are already set up in `package.json`:
-
-```json
-{
-  "scripts": {
-    "dev": "cer-app dev",
-    "build": "cer-app build",
-    "preview": "cer-app preview",
-    "generate": "cer-app generate"
-  }
-}
-```
-
-```sh
-npm run dev
-npm run build
-npm run preview
-```
-
----
-
-## Using with `npx` (no global install)
-
-```sh
-npx cer-app dev
-npx cer-app build
-npx --package @jasonshimmy/vite-plugin-cer-app create-cer-app my-app
-```

package/docs/components.md

@@ -1,237 +0,0 @@
-# Components
-
-Files in `app/components/` are automatically registered as custom elements and available throughout the application — no explicit import required.
-
----
-
-## Creating a component
-
-```ts
-// app/components/ui/my-button.ts
-component('my-button', () => {
-  const props = useProps({ label: 'Click me', disabled: false })
-
-  return html`
-    <button :disabled="${props.disabled}">
-      ${props.label}
-    </button>
-  `
-})
-```
-
-Use it in any page or layout:
-
-```ts
-// app/pages/index.ts
-component('page-index', () => {
-  return html`
-    <div>
-      <my-button label="Submit"></my-button>
-    </div>
-  `
-})
-```
-
-No import is needed. The framework scans each file's `html\`` templates and injects static `import` statements automatically.
-
----
-
-## File → tag name
-
-The tag name is derived from the file path relative to `app/components/`, with path separators replaced by dashes. The file must call `component()` with the matching tag name.
-
-| File | Expected tag name |
-|---|---|
-| `app/components/my-button.ts` | `my-button` |
-| `app/components/ui/card.ts` | `ui-card` (or any name — tag name is from the `component()` call, not the path) |
-| `app/components/forms/text-input.ts` | `forms-text-input` |
-
-> **Note:** The tag name comes from the `component('tag-name', …)` call inside the file — the file path does not enforce a specific tag name.
-
----
-
-## Code splitting
-
-Components are automatically code-split per page. Only the components a given page actually uses are loaded when that page is visited.
-
-The framework's build plugin (`cerComponentImports`) scans each page, layout, and component file for custom element tags in `html\`` template literals. For every tag it finds, it injects a static `import` at the top of that file pointing to the component's source file. Rollup then uses these graph edges to split components into the chunk for the page that uses them.
-
-**Example:** A project with 500 components where `/home` uses `<ks-badge>` and `/about` uses nothing will produce:
-
-- `home` chunk: includes `ks-badge.ts` + transitive deps
-- `about` chunk: does not include any component files
-
-Transitive dependencies are handled automatically: if `ks-card` uses `<ks-badge>` in its own template, the transform injects a `ks-badge` import into `ks-card.ts`, and Rollup traces the full dependency graph.
-
-**Components used in layouts** load eagerly by design. Since layouts are imported for every route, their component imports are always included in the initial bundle.
-
----
-
-## Auto-import behavior
-
-When `autoImports.components` is `true` (the default), the framework's Vite transform hook:
-
-1. Builds a manifest mapping tag names → source files by scanning `app/components/`
-2. Transforms each page, layout, and component file: reads its `html\`` templates, extracts custom element tag names, and prepends static `import` statements for the matching source files
-3. Rollup uses these imports as graph edges for automatic chunk splitting
-
-No generated virtual module is involved. Component registration is purely driven by the module graph.
-
----
-
-## Opting out
-
-If you need to manage component registration manually, set `autoImports.components: false` in `cer.config.ts` and import components explicitly:
-
-```ts
-// cer.config.ts
-export default defineConfig({
-  autoImports: { components: false },
-})
-```
-
-```ts
-// app/plugins/components.ts — import from a plugin so they register before the first render
-import '../components/ui/my-button.ts'
-import '../components/forms/text-input.ts'
-```
-
----
-
-## Runtime auto-imports inside component files
-
-Files in `app/components/` also benefit from `autoImports.runtime`. When `runtime: true` (the default), `component`, `html`, `ref`, `useProps`, `useEmit`, and all other runtime identifiers are injected automatically at the top of each component file if they are used.
-
-This means you can write:
-
-```ts
-// app/components/my-counter.ts
-component('my-counter', () => {
-  const count = ref(0)
-  return html`
-    <button @click="${() => count.value++}">Count: ${count}</button>
-  `
-})
-```
-
-Without needing to add:
-
-```ts
-import { component, html, ref } from '@jasonshimmy/custom-elements-runtime'
-```
-
----
-
-## Accessing slot content with `useSlots()`
-
-Use `useSlots()` inside a component's render function to read the content passed to named or default slots:
-
-```ts
-// app/components/ui-badge.ts
-component('ui-badge', () => {
-  const slots = useSlots()
-
-  return html`
-    <span class="badge">
-      ${slots.default ?? 'badge'}
-    </span>
-  `
-})
-```
-
-Usage in a page:
-
-```ts
-// app/pages/index.ts
-component('page-index', () => {
-  return html`
-    <ui-badge>v1.0.0</ui-badge>
-    <ui-badge>beta</ui-badge>
-  `
-})
-```
-
-`slots.default` contains the light-DOM children passed to the component. Named slots are accessed by their slot name:
-
-```ts
-// app/components/app-card.ts
-component('app-card', () => {
-  const slots = useSlots()
-
-  return html`
-    <div class="card">
-      <header>${slots.header}</header>
-      <main>${slots.default}</main>
-      <footer>${slots.footer}</footer>
-    </div>
-  `
-})
-```
-
-```html
-<!-- usage -->
-<app-card>
-  <span slot="header">Title</span>
-  Body content goes here
-  <span slot="footer">Footer</span>
-</app-card>
-```
-
----
-
-## `defineAsyncComponent`
-
-`defineAsyncComponent` registers a custom element whose implementation is loaded asynchronously. Use it for heavy components that should not block the initial render.
-
-```ts
-defineAsyncComponent(
-  'ks-chart',
-  () => import('./chart-impl').then(m => m.render),  // returns a render fn
-  {
-    loading: () => html`<p>Loading chart…</p>`,          // shown while loading
-    error:   () => html`<p>Failed to load chart.</p>`,   // shown on rejection
-    timeout: 5000,                                        // ms before showing error (optional)
-  },
-)
-```
-
-The element transitions through four states:
-
-| State | Description |
-|---|---|
-| `loading` | Loader promise is pending. The `loading` template is rendered if provided. |
-| `resolved` | Loader resolved. The returned render function is called and its output is rendered. |
-| `error` | Loader rejected or timeout exceeded. The `error` template is rendered if provided. |
-| `idle` | No loader started yet (element connected before the loader is called). |
-
-**Loader return value:** The promise must resolve with a render function `() => TemplateResult | string`. The render function is called inside the component's normal reactive context — `useProps`, `ref`, etc. are available.
-
-**Timeout:** If `timeout` is set and the loader does not resolve within that many milliseconds, the state moves to `error` and the `error` template is rendered.
-
-**Options:**
-
-```ts
-interface AsyncComponentOptions {
-  loading?: () => TemplateResult | string  // rendered while pending
-  error?:   () => TemplateResult | string  // rendered on failure
-  timeout?: number                          // milliseconds before treating as error
-}
-```
-
-`defineAsyncComponent` is auto-imported — no import statement is needed in files under `app/`.
-
-If you need it outside auto-imported directories:
-
-```ts
-import { defineAsyncComponent } from '@jasonshimmy/custom-elements-runtime'
-```
-
----
-
-## HMR
-
-Changes to a component file's render logic trigger standard Vite HMR — no full reload required, because the static import edge is already in Vite's module graph.
-
-If a component file's registered tag name changes (e.g. the `component('old-name', …)` call is edited to `component('new-name', …)`), the framework detects the manifest change and sends a full-reload so all pages pick up the updated import graph.
-
-When a new component file is added to `app/components/`, the manifest is updated synchronously via `watchChange`, and a full reload is triggered so the new tag becomes available.