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

package/docs/data-loading.md

@@ -1,336 +0,0 @@
-# Data Loading
-
-Each page can export a `loader` function that runs on the server before the page renders. The data is serialized into the HTML response and rehydrated on the client without a second fetch.
-
----
-
-## Defining a loader
-
-```ts
-// app/pages/blog/[slug].ts
-import type { PageLoader } from '@jasonshimmy/vite-plugin-cer-app/types'
-
-component('page-blog-slug', () => {
-  const data = usePageData<{ title: string; body: string }>()
-
-  return html`
-    <article>
-      <h1>${data?.title ?? ''}</h1>
-      <div>${data?.body ?? ''}</div>
-    </article>
-  `
-})
-
-export const loader: PageLoader = async ({ params }) => {
-  const { data: post } = await useFetch(`https://api.example.com/posts/${params.slug}`)
-  return { title: post?.title, body: post?.body }
-}
-```
-
-The object returned by `loader` is made available via `usePageData()` in the page component. Primitive values (strings, numbers, booleans) are also forwarded as HTML element attributes so `useProps()` can read them.
-
----
-
-## `PageLoader` signature
-
-```ts
-type PageLoader<
-  Params extends Record<string, string> = Record<string, string>,
-  Data = Record<string, unknown>,
-> = (ctx: PageLoaderContext<Params>) => Promise<Data> | Data
-
-interface PageLoaderContext<P extends Record<string, string>> {
-  params: P                     // URL path parameters
-  query: Record<string, string> // Parsed query string
-  req?: IncomingMessage         // Raw Node.js request (present during SSR/SSG server render; absent during client-side navigation)
-}
-```
-
----
-
-## SSR data flow
-
-1. A request arrives for `/blog/hello-world`
-2. The router matches `app/pages/blog/[slug].ts`
-3. The server calls `loader({ params: { slug: 'hello-world' }, query, req })`
-4. The returned data is serialized as `window.__CER_DATA__` in a `<script>` tag in the HTML `<head>`:
-   ```html
-   <script>window.__CER_DATA__ = {"title":"Hello World","body":"..."}</script>
-   ```
-5. The server renders `<page-blog-slug>` directly into the layout using Declarative Shadow DOM
-6. The full HTML (pre-rendered content + client scripts) is sent to the browser
-
----
-
-## Client hydration flow
-
-1. Browser receives the full HTML — content is immediately visible via Declarative Shadow DOM before any JS runs
-2. Client JS boots; `usePageData()` reads `window.__CER_DATA__` and returns the hydrated values
-3. After the initial `router.replace()` in `.cer/app.ts` completes, `.cer/app.ts` clears the loader data from `globalThis` so subsequent client-side navigations trigger a fresh fetch instead of reusing stale server data
-4. Components that received SSR data skip their `useOnConnected` fetch — no duplicate request
-
----
-
-## Client-side navigation and loaders
-
-Loaders run on the client too — before every navigation. This means `useProps()` and `usePageData()` both work correctly for client-side route transitions, not just on initial SSR/SSG load.
-
-When `router.push('/path')` is called:
-1. The route module is dynamically imported
-2. If the module exports a `loader`, it is called with `{ params, query }`
-3. Primitive return values (strings, numbers, booleans) are set as HTML attributes on the page element so `useProps()` can read them
-4. All return values are stored in `globalThis.__CER_DATA__` so `usePageData()` also returns them
-5. The page component renders with the correct data immediately — no loading flash or re-render
-
-```ts
-// app/pages/profile.ts
-component('page-profile', () => {
-  // Works on initial load AND client navigation
-  const props = useProps<{ username: string; bio: string }>({ username: '', bio: '' })
-
-  return html`
-    <h1>${props.username}</h1>
-    <p>${props.bio}</p>
-  `
-})
-
-export const loader = async ({ params }: { params: { id: string } }) => {
-  const { data: user } = await useFetch(`/api/users/${params.id}`)
-  return { username: user?.name, bio: user?.bio }
-}
-```
-
-> **Note:** Only primitive values (strings, numbers, booleans) are forwarded as element attributes. Complex objects (arrays, nested objects) should be accessed via `usePageData()` instead of `useProps()`.
-
----
-
-## Accessing loader data in components
-
-Use `usePageData()` to read loader data — it receives everything the loader returned (primitives and complex objects alike) and works in all modes: SSR, SSG, and client-side navigation.
-
-```ts
-component('page-user', () => {
-  const ssrData = usePageData<{ user: { id: string; name: string; email: string } }>()
-  const user = ref(ssrData?.user ?? { id: '', name: '', email: '' })
-
-  useOnConnected(async () => {
-    if (ssrData) return  // already hydrated
-    const { data } = await useFetch(`/api/users/${user.value.id}`)
-    if (data) user.value = data
-  })
-
-  return html`
-    <h1>Hello, ${user.value.name}</h1>
-    <p>${user.value.email}</p>
-  `
-})
-
-export const loader: PageLoader<{ id: string }> = async ({ params }) => {
-  const user = await fetchUser(params.id)
-  return { user }
-}
-```
-
-`useProps()` is an alternative for **primitive values only** (strings, numbers, booleans). It reads element HTML attributes rather than the loader payload directly, which means it also picks up attributes passed by parent components in the component tree — but it cannot receive arrays or objects.
-
-```ts
-component('page-profile', () => {
-  // Works for primitives only — use usePageData() if you need objects or arrays
-  const props = useProps<{ username: string; bio: string }>({ username: '', bio: '' })
-
-  return html`
-    <h1>${props.username}</h1>
-    <p>${props.bio}</p>
-  `
-})
-
-export const loader = async ({ params }: { params: { id: string } }) => {
-  const { data: user } = await useFetch(`/api/users/${params.id}`)
-  return { username: user?.name, bio: user?.bio }  // primitives only
-}
-```
-
-> **Rule of thumb:** reach for `usePageData()` first. Only prefer `useProps()` when you specifically need the element attribute binding model — for example, when the same component is also used as a child that receives attributes from a parent.
-
----
-
-## SSG and loaders
-
-In SSG mode, `loader` is called at build time for each generated path. The data is baked into the static HTML file and no server is required at runtime.
-
-```ts
-// app/pages/blog/[slug].ts
-export const meta = {
-  ssg: {
-    paths: async () => [
-      { params: { slug: 'hello-world' } },
-      { params: { slug: 'second-post' } },
-    ],
-  },
-}
-
-export const loader: PageLoader<{ slug: string }> = async ({ params }) => {
-  // Called once per path during `cer-app generate`
-  const post = await fetchPost(params.slug)
-  return { post }
-}
-```
-
----
-
-## Dev server behavior
-
-In `mode: 'ssr'` and `mode: 'ssg'`, the dev server runs the server entry module and calls your `loader` on every HTML request — matching production behaviour. Both `usePageData()` and `useProps()` receive real loader data during development.
-
-In `mode: 'spa'`, no loaders run in the dev server. `usePageData()` always returns `null` and `useProps()` returns its defaults. Use `useOnConnected` to fetch data client-side in SPA mode.
-
----
-
-## Error handling in loaders
-
-When a `loader` throws, the SSR error boundary intercepts it:
-
-- If `app/error.ts` exists, the server renders the `page-error` component instead of the normal page and returns the appropriate HTTP status.
-- If `app/error.ts` does not exist, the error is logged to the server console and a blank 500 response is returned.
-
-To send a specific HTTP status code from a loader, attach a `status` property to the thrown error:
-
-```ts
-export const loader: PageLoader<{ id: string }> = async ({ params }) => {
-  const item = await db.item.findById(params.id)
-  if (!item) {
-    const err = Object.assign(new Error('Not Found'), { status: 404 })
-    throw err
-  }
-  return { item }
-}
-```
-
-Unhandled errors without a `status` property default to HTTP 500.
-
----
-
-## Error boundary — `app/error.ts`
-
-Create `app/error.ts` to define a custom error page shown when navigation fails. The file must export a custom element named `page-error`:
-
-```ts
-// app/error.ts
-component('page-error', () => {
-  const props = useProps<{ error: string; status: string }>({
-    error: 'An unexpected error occurred.',
-    status: '500',
-  })
-
-  return html`
-    <div style="padding:2rem">
-      <h2 style="color:#c00">Error ${props.status}</h2>
-      <p>${props.error}</p>
-      <button @click="${() => (globalThis as any).resetError?.()}">
-        Try again
-      </button>
-    </div>
-  `
-})
-```
-
-### Props received by `page-error`
-
-| Prop | Type | Source |
-|------|------|--------|
-| `error` | `string` | Error message from the thrown value |
-| `status` | `string` | HTTP status code as a string (`"404"`, `"500"`, etc.) — **SSR only** |
-
-### `resetError()`
-
-The framework exposes `globalThis.resetError()` as a global function. Calling it clears the error state and re-navigates to the current path, giving the user a way to recover without a full page reload.
-
-```ts
-// Call from a button click handler inside page-error
-(globalThis as any).resetError?.()
-```
-
-### SSR vs. client-side behavior
-
-| Scenario | Behavior |
-|----------|----------|
-| **Loader throws during SSR** | Server renders `page-error` with `error` and `status` props; response uses the thrown status code |
-| **Navigation throws on the client** | `cer-layout-view` renders `page-error` with `error` prop only (no HTTP status in the browser) |
-| **No `app/error.ts` defined (SSR)** | Error is logged to the server console; blank 500 response |
-| **No `app/error.ts` defined (client)** | Raw error message rendered in a `<div>` |
-
-> **SPA mode:** There is no server-side error boundary in SPA mode. The `loader` function is never called server-side, so `page-error` is only rendered for client-side navigation errors. To handle loading failures in SPA, catch errors inside `useOnConnected` and render an error state manually.
-
----
-
-## Loader vs. client-side fetching
-
-Use `loader` for data that:
-- Must be present on initial render (SEO, no loading spinner)
-- Is fetched from a database or internal service not accessible from the browser
-- Benefits from server-side caching or authentication via cookies
-
-Use client-side fetching (`fetch` or composables) for:
-- Data loaded after user interaction
-- Paginated or infinite-scroll content
-- Real-time updates
-
----
-
-## TypeScript generics
-
-The `PageLoader` type accepts two generics:
-
-```ts
-// PageLoader<Params, Data>
-export const loader: PageLoader<
-  { id: string },               // URL params shape
-  { user: User; posts: Post[] } // Return data shape
-> = async ({ params }) => {
-  return { user: await fetchUser(params.id), posts: await fetchPosts(params.id) }
-}
-```
-
----
-
-## Multi-mode data loading (SPA fallback)
-
-When building a page that needs to work in **all three modes** — SSR/SSG (with a `loader`) and SPA (no server, no loader) — use the following pattern:
-
-1. In SSR/SSG, the server runs `loader` and injects the data via `window.__CER_DATA__`. `usePageData()` returns it immediately; `useOnConnected` sees `ssrData` and skips the client fetch.
-2. In SPA mode there is no server, so `ssrData` is `null`. The client tries the API first, then falls back to a direct module import.
-
-```ts
-// app/pages/blog/index.ts
-component('page-blog-index', () => {
-  const ssrData = usePageData<{ posts: Post[] }>()
-  const posts = ref<Post[]>(ssrData?.posts ?? [])
-
-  useOnConnected(async () => {
-    if (ssrData) return  // SSR/SSG: already hydrated, skip the fetch
-
-    // SPA: try the API server first
-    try {
-      const r = await fetch('/api/posts')
-      if (r.ok) {
-        posts.value = await r.json()
-        return
-      }
-    } catch { /* no API server in static preview */ }
-
-    // SPA static fallback: import data directly from source
-    const { posts: staticPosts } = await import('../data/posts')
-    posts.value = staticPosts
-  })
-
-  return html`<ul>${posts.value.map(p => html`<li>${p.title}</li>`)}</ul>`
-})
-
-// loader runs in SSR and SSG only
-export const loader = async () => {
-  const { data: posts } = await useFetch<Post[]>('/api/posts')
-  return { posts: posts ?? [] }
-}
-```
-
-The key rule: **always check `ssrData` before fetching on the client**. This prevents a redundant network request when the data was already serialized by the server.

package/docs/getting-started.md

@@ -1,237 +0,0 @@
-# Getting Started
-
-## Prerequisites
-
-- Node.js 18+
-- `@jasonshimmy/custom-elements-runtime` ≥ 3.0.0
-- Vite ≥ 5.0.0
-
----
-
-## Option A — Scaffold with `create-cer-app` (recommended)
-
-```sh
-npx --package @jasonshimmy/vite-plugin-cer-app create-cer-app my-app
-```
-
-The interactive prompt asks for a project name and rendering mode:
-
-```
-Welcome to create-cer-app!
-
-Project name: my-app
-Select app mode:
-  1. spa  — Single-Page App (client-side rendering)
-  2. ssr  — Server-Side Rendering
-  3. ssg  — Static Site Generation
-Mode [1/2/3]: 1
-
-Creating SPA project: my-app
-  Directory: /path/to/my-app
-
-Project created! To get started:
-
-  cd my-app
-  npm install
-  npm run dev
-```
-
-You can also skip the prompts with flags:
-
-```sh
-npx --package @jasonshimmy/vite-plugin-cer-app create-cer-app my-app --mode ssr
-```
-
----
-
-## Option B — Add to an existing Vite project
-
-### 1. Install
-
-```sh
-npm install -D @jasonshimmy/vite-plugin-cer-app
-npm install @jasonshimmy/custom-elements-runtime
-```
-
-### 2. Configure Vite
-
-```ts
-// vite.config.ts
-import { defineConfig } from 'vite'
-import { cerApp } from '@jasonshimmy/vite-plugin-cer-app'
-
-export default defineConfig({
-  plugins: [cerApp()],
-})
-```
-
-Or use a separate `cer.config.ts` (picked up automatically by the CLI, and passed manually to `cerApp()` if using `vite.config.ts`):
-
-```ts
-// cer.config.ts
-import { defineConfig } from '@jasonshimmy/vite-plugin-cer-app'
-
-export default defineConfig({
-  mode: 'spa',
-})
-```
-
-```ts
-// vite.config.ts (when using cer.config.ts)
-import { defineConfig } from 'vite'
-import { cerApp } from '@jasonshimmy/vite-plugin-cer-app'
-import cerConfig from './cer.config.ts'
-
-export default defineConfig({
-  plugins: [cerApp(cerConfig)],
-})
-```
-
-### 3. Create the app structure
-
-```sh
-mkdir -p app/pages app/layouts app/components app/composables app/plugins app/middleware
-mkdir -p server/api server/middleware
-```
-
-### 4. Write your first page
-
-```ts
-// app/pages/index.ts
-// No imports needed — component, html are auto-injected
-component('page-index', () => {
-  return html`<h1>Hello, World!</h1>`
-})
-```
-
-### 5. Write a layout
-
-```ts
-// app/layouts/default.ts
-component('layout-default', () => {
-  return html`
-    <header><h1>My App</h1></header>
-    <main><slot></slot></main>
-  `
-})
-```
-
-### 6. Create `index.html`
-
-```html
-<!DOCTYPE html>
-<html lang="en">
-  <head>
-    <meta charset="UTF-8" />
-    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
-    <title>My App</title>
-  </head>
-  <body>
-    <cer-layout-view></cer-layout-view>
-    <script type="module" src="/.cer/app.ts"></script>
-  </body>
-</html>
-```
-
-> **Note:** The framework bootstrap lives in `.cer/app.ts` and is regenerated automatically on every dev server start and build. You never edit or own this file — updates to the plugin propagate to it immediately, just like Nuxt's `.nuxt/` directory.
-
----
-
-## TypeScript path aliases
-
-The framework automatically generates `.cer/tsconfig.json` with `~/` path aliases on every dev server start and build. To enable IDE autocomplete and type-checking for these aliases, extend it from your project `tsconfig.json`:
-
-```json
-// tsconfig.json
-{
-  "extends": "./.cer/tsconfig.json"
-}
-```
-
-The generated aliases map:
-
-| Alias | Resolves to |
-|---|---|
-| `~/*` | `app/*` |
-| `~/pages/*` | `app/pages/*` |
-| `~/layouts/*` | `app/layouts/*` |
-| `~/components/*` | `app/components/*` |
-| `~/composables/*` | `app/composables/*` |
-| `~/plugins/*` | `app/plugins/*` |
-| `~/middleware/*` | `app/middleware/*` |
-| `~/assets/*` | `app/assets/*` |
-
-```ts
-// Before — relative import
-import { useTheme } from '../../composables/useTheme'
-
-// After — alias import
-import { useTheme } from '~/composables/useTheme'
-```
-
-> `.cer/tsconfig.json` is auto-generated — do not edit or commit it. It is regenerated on every `cer-app dev` and `cer-app build`. Add `.cer/` to `.gitignore`.
-
----
-
-## Running the dev server
-
-```sh
-# Using the CLI (reads cer.config.ts automatically)
-npx cer-app dev
-
-# Or via npm scripts (after scaffolding)
-npm run dev
-```
-
-The dev server starts on `http://localhost:3000` by default.
-
----
-
-## Building for production
-
-```sh
-# SPA build
-npx cer-app build
-
-# SSR build (dual client + server bundles)
-npx cer-app build --mode ssr
-
-# SSG build (renders all routes to static HTML at build time)
-npx cer-app build --mode ssg
-# or equivalently:
-npx cer-app generate
-```
-
-### Build outputs
-
-| Mode | Output |
-|---|---|
-| `spa` | `dist/` — standard Vite client bundle |
-| `ssr` | `dist/client/` + `dist/server/server.js` |
-| `ssg` | `dist/<route>/index.html` per page + `dist/ssg-manifest.json` |
-
----
-
-## Previewing the build
-
-```sh
-# SPA / SSG (static file server)
-npx cer-app preview
-
-# SSR (loads dist/server/server.js as the request handler)
-npx cer-app preview --ssr
-```
-
-Preview runs on `http://localhost:4173` by default.
-
----
-
-## Scaffolded project scripts
-
-All three modes produce a `package.json` with these scripts:
-
-| Mode | `dev` | `build` | `preview` | `generate` |
-|---|---|---|---|---|
-| SPA | `cer-app dev` | `cer-app build` | `cer-app preview` | — |
-| SSR | `cer-app dev` | `cer-app build` | `cer-app preview --ssr` | — |
-| SSG | `cer-app dev` | `cer-app build` | `cer-app preview` | `cer-app generate` |