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

package/docs/middleware.md

@@ -1,234 +0,0 @@
-# Middleware
-
-The framework has two kinds of middleware:
-
-1. **Route middleware** — runs in the browser before navigation (auth guards, redirects)
-2. **Server middleware** — runs on the server for every HTTP request (CORS, logging)
-
----
-
-## Route middleware
-
-### Defining middleware
-
-Create a file in `app/middleware/`. Export a default `MiddlewareFn` using `defineMiddleware`:
-
-```ts
-// app/middleware/auth.ts
-export default defineMiddleware(async (to, from) => {
-  const session = await getSession()
-  if (!session) return '/login'  // redirect
-  return true                    // allow navigation
-})
-```
-
-`defineMiddleware` is a no-op identity helper — it just provides TypeScript types without
-any runtime overhead. It is auto-imported, so you don't need to import it manually.
-
-### `MiddlewareFn` signature
-
-```ts
-type GuardResult = boolean | string | Promise<boolean | string>
-
-type MiddlewareFn = (
-  to: RouteState,
-  from: RouteState | null,
-  next: () => Promise<void>,
-) => GuardResult | void
-```
-
-| Return value | Effect |
-|---|---|
-| `true` | Allow navigation |
-| `false` | Block navigation (stay on current route) |
-| `string` | Redirect to that path |
-| `void` / no return | Allow navigation (same as `true`) |
-
----
-
-### `next()` chaining — wrapper middleware
-
-The third parameter `next` lets you build **wrapper middleware** that executes logic both _before_ and _after_ the remaining middleware chain runs. This is useful for logging, timing, and instrumentation.
-
-When you call `next()`, the remaining middleware in the chain runs before `next()` resolves. If you do **not** call `next()`, you take full control of the guard result via your return value.
-
-```ts
-// app/middleware/logger.ts
-export default defineMiddleware(async (to, from, next) => {
-  console.log('[nav] start:', to.path)
-  const start = Date.now()
-
-  await next()  // run the rest of the middleware chain
-
-  console.log('[nav] done:', to.path, `(${Date.now() - start}ms)`)
-  // No return value — navigation proceeds based on the downstream result
-})
-```
-
-```ts
-// app/pages/admin.ts
-export const meta = {
-  middleware: ['logger', 'auth'],
-  // Execution: logger (before) → auth (guard) → logger (after)
-}
-```
-
-**Key rules:**
-
-- If you call `next()` and return no value, the chain result from downstream middleware wins.
-- If you call `next()` but also return `false` or a redirect string, your return value takes precedence.
-- If you do **not** call `next()`, the remaining middleware in the chain is skipped. Your return value controls navigation as normal.
-- If a middleware throws, navigation is blocked (`false`) and the chain stops.
-
----
-
-### Assigning middleware to a specific page
-
-Set `meta.middleware` to an array of middleware names. The name is the filename without the extension:
-
-```ts
-// app/pages/dashboard.ts
-export const meta = {
-  middleware: ['auth'],   // runs app/middleware/auth.ts before this page
-}
-```
-
----
-
-### Multiple middleware
-
-Middleware runs in the order listed. The first non-`true` result wins:
-
-```ts
-// app/pages/admin.ts
-export const meta = {
-  middleware: ['auth', 'admin-role'],
-  // Runs: auth → admin-role → page render
-}
-```
-
----
-
-### Execution order within a navigation
-
-1. Route middleware runs for the matched route — all declared middleware executes in order
-2. Route state updates (component renders)
-3. Post-navigation hooks fire (analytics, logging)
-
-Redirect loop protection: the router stops after 10 consecutive redirects.
-
----
-
-### Error handling
-
-If a middleware function throws (synchronously or asynchronously), navigation is **blocked** — the framework catches the error, logs it, and returns `false` to keep the user on the current route:
-
-```
-[cer-app] Middleware "auth" threw an error: Error: session store unavailable
-```
-
-This means a crashing middleware is always safe: the user stays put rather than landing on a broken page or being incorrectly redirected. Subsequent middleware in the same chain does not run.
-
----
-
-### TypeScript types
-
-`MiddlewareFn` and `GuardResult` are exported from the package if you need them outside of auto-imported files:
-
-```ts
-import type { MiddlewareFn, GuardResult } from '@jasonshimmy/vite-plugin-cer-app/types'
-```
-
----
-
-### All middleware files
-
-All files in `app/middleware/` are registered and available by name. They are exported from `virtual:cer-middleware`:
-
-```ts
-import { middleware } from 'virtual:cer-middleware'
-// { auth: [Function], 'admin-role': [Function], ... }
-```
-
----
-
-## Server middleware
-
-Server middleware runs on the HTTP level — before API routes and before SSR rendering. Place files in `server/middleware/`.
-
-```ts
-// server/middleware/cors.ts
-// defineServerMiddleware is auto-imported — no import statement needed
-export default defineServerMiddleware((req, res, next) => {
-  res.setHeader('Access-Control-Allow-Origin', '*')
-  res.setHeader('Access-Control-Allow-Methods', 'GET, POST, PUT, DELETE, OPTIONS')
-  res.setHeader('Access-Control-Allow-Headers', 'Content-Type, Authorization')
-
-  if (req.method === 'OPTIONS') {
-    res.statusCode = 204
-    res.end()
-    return  // do NOT call next() — response is complete
-  }
-
-  next()
-})
-```
-
-If you need it outside `server/middleware/` files, import explicitly:
-
-```ts
-import { defineServerMiddleware } from '@jasonshimmy/vite-plugin-cer-app/composables'
-```
-
-### `ServerMiddleware` signature
-
-```ts
-type ServerMiddleware = (
-  req: IncomingMessage,
-  res: ServerResponse,
-  next: (err?: unknown) => void,
-) => void | Promise<void>
-```
-
-- Call `next()` to pass the request to the next handler.
-- Call `next(err)` with an error to short-circuit the chain. The response status defaults to `500`; attach a numeric `.status` to the error object to send a different status code.
-- Throw (synchronously or via a rejected Promise) to produce the same result as `next(err)`.
-- If you do not call `next()` at all (e.g. you called `res.end()`), the chain stops and subsequent handlers (API routes, SSR) will not run.
-
-**Custom status codes in server middleware**
-
-Throw (or reject) with an object that has a numeric `.status` property to control the HTTP response status:
-
-```ts
-// server/middleware/auth.ts
-export default defineServerMiddleware(async (req, _res, next) => {
-  const token = req.headers['authorization']
-  if (!token) {
-    const err = new Error('Unauthorized') as Error & { status: number }
-    err.status = 401
-    throw err
-  }
-  next()
-})
-```
-
-The framework extracts `err.status` and uses it as `res.statusCode`. If the value is non-numeric or missing, it falls back to `500`. This replaces the old behavior of always returning `500` for all middleware errors.
-
----
-
-### Dev server behavior
-
-Server middleware is applied in dev via Vite's `configureServer` middleware hook, before API routes and before the SSR HTML renderer.
-
-In production (SSR mode), server middleware is exported from the server bundle and applied in the same order.
-
----
-
-### Execution order
-
-For each request, the order is:
-
-1. Server middleware (from `server/middleware/`, in scan order)
-2. API route handlers (from `server/api/`)
-3. SSR HTML renderer (if `mode === 'ssr'` and the request accepts `text/html`)
-4. Vite dev server (dev only — serves assets and handles HMR)

package/docs/plugins.md

@@ -1,170 +0,0 @@
-# App Plugins
-
-Plugins are loaded once before the app renders. They receive an `app` context with `provide` for dependency injection and `router` for registering global navigation guards.
-
----
-
-## Creating a plugin
-
-```ts
-// app/plugins/01.store.ts
-import type { AppPlugin } from '@jasonshimmy/vite-plugin-cer-app/types'
-import { createStore } from '@jasonshimmy/custom-elements-runtime/store'
-
-export default {
-  name: 'app-store',
-  setup(app) {
-    const store = createStore({ user: null, theme: 'light' })
-    app.provide('store', store)
-  },
-} satisfies AppPlugin
-```
-
----
-
-## Plugin interface
-
-```ts
-interface AppPlugin {
-  name: string
-  setup(app: AppContext): void | Promise<void>
-}
-
-interface AppContext {
-  provide(key: PropertyKey, value: unknown): void
-  router: Router
-  config: CerAppConfig  // always {} (empty object) at runtime
-}
-```
-
----
-
-## Load order
-
-Plugins are loaded in filename order. Use a numeric prefix to control sequencing:
-
-```
-app/plugins/
-  01.store.ts      ← loaded first
-  02.auth.ts       ← loaded second
-  03.analytics.ts  ← loaded third
-  errorHandler.ts  ← loaded after all numbered plugins (alphabetical)
-```
-
-- Numbered files (e.g. `01.store.ts`) come before unnumbered files.
-- Within the same tier, files are sorted alphabetically.
-- The number is stripped; the actual filename is the plugin name by convention.
-
----
-
-## Dependency injection
-
-Use `app.provide` in the plugin's `setup` to make values available to all components via `inject`:
-
-```ts
-// app/plugins/01.store.ts
-export default {
-  name: 'app-store',
-  setup(app) {
-    const store = createStore({ count: 0 })
-    app.provide('store', store)
-  },
-}
-```
-
-```ts
-// app/pages/index.ts
-component('page-index', () => {
-  const store = useInject<Store>('store')
-  const count = computed(() => store?.state.count ?? 0)
-
-  return html`<p>Count: ${count}</p>`
-})
-```
-
----
-
-## Async plugins
-
-Plugins can be async. All plugins are awaited in sequence before the app renders:
-
-```ts
-// app/plugins/02.auth.ts
-export default {
-  name: 'auth',
-  async setup(app) {
-    const session = await fetchSession()
-    app.provide('session', session)
-  },
-}
-```
-
----
-
-## Router guards in plugins
-
-Register global navigation guards via `app.router`:
-
-```ts
-// app/plugins/03.analytics.ts
-export default {
-  name: 'analytics',
-  setup(app) {
-    app.router.subscribe((to) => {
-      trackPageView(to.path)
-    })
-  },
-}
-```
-
----
-
-## Reading provided values with `useInject`
-
-To read values provided by a plugin, use `useInject` instead of the raw `inject()` from the runtime. `useInject` works correctly in **all three modes** — SPA, SSR, and SSG:
-
-```ts
-// app/pages/dashboard.ts
-component('page-dashboard', () => {
-  const store = useInject<Store>('store')
-
-  if (!store) return html`<p>Loading…</p>`
-
-  return html`<p>Count: ${store.state.count}</p>`
-})
-```
-
-`useInject` is auto-imported in `app/pages/`, `app/layouts/`, and `app/components/` — no explicit import needed.
-
-**Why not raw `inject()`?** In SSR and SSG modes the server renders the component tree directly, without `<cer-layout-view>` establishing the Vue-style provide context. `useInject` bridges this gap:
-
-| Mode | How the value is resolved |
-|------|--------------------------|
-| SPA / client | `inject()` walks the component tree (provided by `<cer-layout-view>`) |
-| SSR (dev & prod) | reads from `globalThis.__cerPluginProvides` (set by the server entry at startup) |
-| SSG | same as SSR |
-
-If you need `useInject` outside of auto-imported directories, import it explicitly:
-
-```ts
-import { useInject } from '@jasonshimmy/vite-plugin-cer-app/composables'
-```
-
----
-
-## Virtual module
-
-The sorted plugin list is available via `virtual:cer-plugins`:
-
-```ts
-import plugins from 'virtual:cer-plugins'
-// plugins is an array of AppPlugin objects in load order
-```
-
-In `.cer/app.ts` (the auto-generated framework entry), plugins are executed sequentially before the router initializes:
-
-```ts
-for (const plugin of plugins) {
-  await plugin.setup(appContext)
-}
-```