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

package/docs/server-api.md

@@ -1,253 +0,0 @@
-# Server API Routes
-
-Files in `server/api/` define HTTP endpoint handlers. The same file-to-path rules used for pages apply here, with an `/api/` prefix prepended to every route.
-
----
-
-## Defining handlers
-
-Export one function per HTTP method. Method names must be uppercase:
-
-```ts
-// server/api/users/index.ts  →  GET /api/users, POST /api/users
-import type { ApiHandler } from '@jasonshimmy/vite-plugin-cer-app/types'
-
-export const GET: ApiHandler = async (req, res) => {
-  const users = await db.user.findAll()
-  res.json(users)
-}
-
-export const POST: ApiHandler = async (req, res) => {
-  const user = await db.user.create(req.body)
-  res.status(201).json(user)
-}
-```
-
-```ts
-// server/api/users/[id].ts  →  GET/PUT/DELETE /api/users/:id
-export const GET: ApiHandler = async (req, res) => {
-  const user = await db.user.findById(req.params.id)
-  if (!user) return res.status(404).json({ error: 'Not found' })
-  res.json(user)
-}
-
-export const PUT: ApiHandler = async (req, res) => {
-  const updated = await db.user.update(req.params.id, req.body)
-  res.json(updated)
-}
-
-export const DELETE: ApiHandler = async (req, res) => {
-  await db.user.delete(req.params.id)
-  res.status(204).end()
-}
-```
-
----
-
-## File → path mapping
-
-| File | API path |
-|---|---|
-| `server/api/health.ts` | `/api/health` |
-| `server/api/users/index.ts` | `/api/users` |
-| `server/api/users/[id].ts` | `/api/users/:id` |
-| `server/api/posts/[postId]/comments.ts` | `/api/posts/:postId/comments` |
-
-The same transformation rules as page routing apply: `[param]` → `:param`, `index.ts` → strip segment.
-
----
-
-## `ApiHandler` signature
-
-```ts
-type ApiHandler = (req: ApiRequest, res: ApiResponse) => void | Promise<void>
-```
-
-### `ApiRequest` (extends `IncomingMessage`)
-
-```ts
-interface ApiRequest extends IncomingMessage {
-  params: Record<string, string>   // URL path params, e.g. { id: '42' }
-  query: Record<string, string>    // Parsed query string, e.g. { page: '1' }
-  body: unknown                    // Parsed JSON body (POST/PUT/PATCH only)
-}
-```
-
-### `ApiResponse` (extends `ServerResponse`)
-
-```ts
-interface ApiResponse extends ServerResponse {
-  json(data: unknown): void         // Set Content-Type: application/json and send
-  status(code: number): ApiResponse // Set status code, chainable
-}
-```
-
----
-
-## Error handling
-
-Unhandled errors thrown inside a handler are caught and return a 500 JSON response:
-
-```json
-{ "error": "Internal Server Error" }
-```
-
-For custom error responses, handle errors yourself:
-
-```ts
-export const GET: ApiHandler = async (req, res) => {
-  try {
-    const result = await riskyOperation()
-    res.json(result)
-  } catch (err) {
-    res.status(503).json({ error: 'Service unavailable', message: String(err) })
-  }
-}
-```
-
----
-
-## Reading the request body
-
-For `POST`, `PUT`, and `PATCH` requests with `Content-Type: application/json`, the body is automatically parsed and available as `req.body`:
-
-```ts
-export const POST: ApiHandler = async (req, res) => {
-  const { name, email } = req.body as { name: string; email: string }
-  // ...
-}
-```
-
-For other content types, `req.body` is the raw `Buffer`.
-
----
-
-## Query parameters
-
-Query string parameters are parsed and available as `req.query`:
-
-```ts
-// GET /api/users?page=2&limit=10
-export const GET: ApiHandler = async (req, res) => {
-  const page = parseInt(req.query.page ?? '1')
-  const limit = parseInt(req.query.limit ?? '20')
-  // ...
-}
-```
-
----
-
-## Default handler (method-agnostic)
-
-Export a `default` function to handle any HTTP method that does not have a named handler:
-
-```ts
-// server/api/webhook.ts
-export default async function handler(req, res) {
-  // Handles any method not explicitly exported
-  res.json({ received: true })
-}
-```
-
----
-
-## Where API routes are registered
-
-| Environment | Registration |
-|---|---|
-| **Dev** | Vite `configureServer` middleware — active immediately, hot-reloaded |
-| **SSR production** | Exported from `dist/server/server.js` alongside the SSR handler |
-| **SPA production** | Not included — deploy API routes separately or use a proxy |
-| **SSG production** | Optionally called at build time for data; otherwise deployed separately |
-
-### SPA mode — by design
-
-In SPA mode (`mode: 'spa'`) the build output is a pure client bundle with no server component. API routes defined in `server/api/` are **only active during development** (Vite dev server middleware). At runtime the SPA has no server to serve them from.
-
-Options for SPA + API:
-- **Separate API server** — deploy a Node.js/Express server alongside the SPA that mounts the same `server/api/` handlers.
-- **Reverse proxy** — proxy `/api/*` requests from your CDN or web server to a backend service.
-- **Switch to SSR mode** — `mode: 'ssr'` gives you a full Node.js server that serves both the SSR pages and the API routes from a single process.
-
----
-
-## Using composables in API handlers
-
-Files in `server/api/` are **not** covered by the auto-import transform (unlike `app/pages/`, `app/layouts/`, etc.). To use framework composables such as `useCookie` or `useSession`, import them explicitly:
-
-```ts
-// server/api/session.ts
-import { useSession } from '@jasonshimmy/vite-plugin-cer-app/composables'
-
-export const GET: ApiHandler = async (_req, res) => {
-  const session = useSession<{ userId: string }>()
-  const data = await session.get()
-  res.json({ userId: data?.userId ?? null })
-}
-
-export const POST: ApiHandler = async (_req, res) => {
-  const session = useSession<{ userId: string }>()
-  await session.set({ userId: 'user-123' })
-  res.json({ ok: true })
-}
-```
-
-```ts
-// server/api/prefs.ts
-import { useCookie } from '@jasonshimmy/vite-plugin-cer-app/composables'
-
-export const POST: ApiHandler = async (_req, res) => {
-  const theme = useCookie('theme')
-  theme.set('dark', { path: '/', maxAge: 31536000 })
-  res.json({ ok: true })
-}
-```
-
-`useCookie` and `useSession` read and write HTTP headers through the per-request `AsyncLocalStorage` context, which the framework sets up automatically before calling each API handler.
-
----
-
-## Custom server integration
-
-When integrating the server bundle with a custom Node.js server (Express, Fastify, Hono, etc.) instead of the built-in adapters, wrap each API handler call with `runWithRequestContext` so that composables like `useCookie` and `useSession` have access to the current `req`/`res`:
-
-```ts
-// Express custom server
-import express from 'express'
-import { handler, apiRoutes, runWithRequestContext } from './dist/server/server.js'
-
-const app = express()
-
-app.all('/api/*', async (req, res) => {
-  for (const route of apiRoutes) {
-    const params = matchApiPattern(route.path, req.path)
-    if (params) {
-      req.params = params
-      const fn = route.handlers[req.method.toLowerCase()] ?? route.handlers.default
-      if (fn) {
-        await runWithRequestContext(req, res, () => fn(req, res))
-        return
-      }
-    }
-  }
-  res.status(404).send('Not Found')
-})
-
-app.use((req, res) => handler(req, res))
-app.listen(3000)
-```
-
-`runWithRequestContext(req, res, fn)` runs `fn` inside the per-request `AsyncLocalStorage` context. Without it, `useCookie`, `useSession`, and other server-side composables cannot access the current request or response.
-
-> The built-in preview server and all platform adapters (Vercel, Netlify, Cloudflare) call `runWithRequestContext` automatically — you only need this when building a custom integration.
-
----
-
-## Virtual module
-
-The route map is available via `virtual:cer-server-api`:
-
-```ts
-import apiRoutes from 'virtual:cer-server-api'
-// [{ path: '/api/users', handlers: { get: [Function], post: [Function] } }, ...]
-```

package/docs/testing.md

@@ -1,455 +0,0 @@
-# Manual Testing Guide
-
-This guide walks through how to manually test every major feature of the framework end-to-end.
-
----
-
-## Prerequisites
-
-Build the plugin first:
-
-```sh
-cd /path/to/@jasonshimmy/vite-plugin-cer-app
-npm install
-npm run build
-```
-
-All examples below assume the plugin is built and either globally installed or linked.
-
----
-
-## 1. Scaffold and verify all three modes
-
-### Create one app per mode
-
-```sh
-node dist/cli/create/index.js my-spa  --mode spa
-node dist/cli/create/index.js my-ssr  --mode ssr
-node dist/cli/create/index.js my-ssg  --mode ssg
-```
-
-In each directory, install dependencies and link the plugin:
-
-```sh
-cd my-spa && npm install && npm link /path/to/@jasonshimmy/vite-plugin-cer-app
-```
-
-### Start the dev server
-
-```sh
-npm run dev   # opens http://localhost:3000
-```
-
-**Expected:** Browser shows the scaffolded welcome page with the project name. No console errors.
-
-### Build and preview
-
-```sh
-npm run build
-npm run preview
-```
-
-| Mode | Preview URL | Expected |
-|---|---|---|
-| SPA | `http://localhost:4173` | Index page loads, client-side routing works |
-| SSR | `http://localhost:4173` | Full HTML in `view-source:` (no empty `<div>`) |
-| SSG | `http://localhost:4173` | Same as SSR; `dist/index.html` exists on disk |
-
----
-
-## 2. Test file-based routing
-
-In any scaffolded app, add pages incrementally and verify route registration.
-
-### Static route
-
-```sh
-echo "component('page-about', () => html\`<h1>About</h1>\`)" > app/pages/about.ts
-```
-
-1. While dev server is running, open `http://localhost:3000/about`
-2. **Expected:** Page renders. HMR full-reloads automatically when the file is created.
-
-### Dynamic route
-
-```sh
-mkdir -p app/pages/blog
-cat > app/pages/blog/[slug].ts << 'EOF'
-component('page-blog-slug', () => {
-  const props = useProps({ slug: '' })
-  return html`<h1>Post: ${props.slug}</h1>`
-})
-EOF
-```
-
-1. Navigate to `http://localhost:3000/blog/hello-world`
-2. **Expected:** Page renders with `Post: hello-world`
-
-### Catch-all / 404
-
-```sh
-echo "component('page-all', () => html\`<h1>404</h1>\`)" > app/pages/\[...all\].ts
-```
-
-1. Navigate to `http://localhost:3000/this-does-not-exist`
-2. **Expected:** 404 page renders
-
-### Route group
-
-```sh
-mkdir -p "app/pages/(auth)"
-echo "component('page-login', () => html\`<h1>Login</h1>\`)" > "app/pages/(auth)/login.ts"
-```
-
-1. Navigate to `http://localhost:3000/login` (not `/auth/login`)
-2. **Expected:** Login page renders at the correct URL
-
----
-
-## 3. Test layouts
-
-```sh
-cat > app/layouts/minimal.ts << 'EOF'
-component('layout-minimal', () => {
-  return html`<div class="minimal"><slot></slot></div>`
-})
-EOF
-```
-
-Add to a page:
-
-```ts
-// app/pages/about.ts
-component('page-about', () => html`<h1>About</h1>`)
-
-export const meta = { layout: 'minimal' }
-```
-
-**Expected:** The about page is wrapped in `.minimal` without the default header/footer.
-
-To verify layout switching works:
-1. Navigate between a page using `default` layout and one using `minimal`
-2. **Expected:** No full-page flash; only the `<slot>` content changes
-
----
-
-## 4. Test auto-imports
-
-Create a page that uses runtime identifiers without any import statement:
-
-```ts
-// app/pages/counter.ts
-component('page-counter', () => {
-  const count = ref(0)
-
-  return html`
-    <div>
-      <p>Count: ${count}</p>
-      <button @click="${() => count.value++}">+</button>
-    </div>
-  `
-})
-```
-
-**Expected:** Page works without any `import` statement at the top. The dev server transforms the file to inject imports automatically.
-
-To inspect the injection, check the network tab in DevTools — the transformed file will have `import { component, html, ref, ... }` prepended.
-
----
-
-## 5. Test components
-
-```sh
-cat > app/components/my-badge.ts << 'EOF'
-component('my-badge', () => {
-  const props = useProps({ text: '', color: 'blue' })
-  return html`<span style="background:${props.color};color:white;padding:2px 6px;border-radius:4px">${props.text}</span>`
-})
-EOF
-```
-
-Use it in any page (no import needed):
-
-```ts
-// app/pages/index.ts
-component('page-index', () => {
-  return html`<h1>Hello <my-badge text="World" color="green"></my-badge></h1>`
-})
-```
-
-**Expected:** Badge renders inline on the home page.
-
----
-
-## 6. Test composables
-
-```sh
-cat > app/composables/useGreeting.ts << 'EOF'
-export function useGreeting(name: string) {
-  return `Hello, ${name}!`
-}
-EOF
-```
-
-```ts
-// app/pages/index.ts
-// No import needed — useGreeting is auto-imported from virtual:cer-composables
-component('page-index', () => {
-  const greeting = useGreeting('World')
-  return html`<h1>${greeting}</h1>`
-})
-```
-
-**Expected:** Page shows "Hello, World!"
-
----
-
-## 7. Test plugins
-
-```sh
-cat > app/plugins/01.greeting.ts << 'EOF'
-export default {
-  name: 'greeting',
-  setup(app) {
-    app.provide('greeting', 'Hello from a plugin!')
-  },
-}
-EOF
-```
-
-Use in a page:
-
-```ts
-// app/pages/index.ts
-component('page-index', () => {
-  const greeting = useInject<string>('greeting')
-  return html`<p>${greeting}</p>`
-})
-```
-
-**Expected:** Page shows the injected string in all three modes (SPA, SSR, SSG). `useInject` is auto-imported — no explicit import needed.
-
----
-
-## 8. Test route middleware
-
-```sh
-cat > app/middleware/auth.ts << 'EOF'
-export default defineMiddleware((to, from) => {
-  const { loggedIn } = useAuth()
-  return loggedIn ? true : '/login'
-})
-EOF
-```
-
-Assign to a page:
-
-```ts
-// app/pages/dashboard.ts
-component('page-dashboard', () => html`<h1>Dashboard</h1>`)
-export const meta = { middleware: ['auth'] }
-```
-
-**Testing steps:**
-
-1. Navigate to `http://localhost:3000/dashboard` without a `token` in localStorage
-2. **Expected:** Redirected to `/login`
-3. In DevTools console: `localStorage.setItem('token', 'abc')`
-4. Navigate back to `/dashboard`
-5. **Expected:** Dashboard page renders
-
----
-
-## 9. Test server API routes
-
-```sh
-mkdir -p server/api
-cat > server/api/health.ts << 'EOF'
-export const GET = (req, res) => {
-  res.json({ status: 'ok', time: new Date().toISOString() })
-}
-EOF
-```
-
-1. Start the dev server: `npm run dev`
-2. Open `http://localhost:3000/api/health`
-3. **Expected:** `{"status":"ok","time":"..."}` in the browser
-
-Test a dynamic route:
-
-```sh
-cat > server/api/echo/[msg].ts << 'EOF'
-export const GET = (req, res) => {
-  res.json({ echo: req.params.msg, query: req.query })
-}
-EOF
-```
-
-1. Open `http://localhost:3000/api/echo/hello?foo=bar`
-2. **Expected:** `{"echo":"hello","query":{"foo":"bar"}}`
-
-Test a POST handler:
-
-```sh
-curl -X POST http://localhost:3000/api/health \
-  -H "Content-Type: application/json" \
-  -d '{"name":"test"}'
-```
-
-(If no POST handler is defined, nothing responds — add one to verify.)
-
----
-
-## 10. Test server middleware
-
-```sh
-cat > server/middleware/cors.ts << 'EOF'
-export default defineServerMiddleware((req, res, next) => {
-  res.setHeader('X-Test-Header', 'middleware-works')
-  next()
-})
-EOF
-```
-
-1. Make any request (e.g. `curl -i http://localhost:3000/api/health`)
-2. **Expected:** Response headers include `X-Test-Header: middleware-works`
-
----
-
-## 11. Test `useHead()`
-
-```ts
-// app/pages/about.ts
-component('page-about', () => {
-  useHead({
-    title: 'About — My App',
-    meta: [
-      { name: 'description', content: 'About page description' },
-    ],
-  })
-  return html`<h1>About</h1>`
-})
-```
-
-**Client mode (SPA/dev):**
-1. Navigate to `/about`
-2. **Expected:** Browser tab title changes to "About — My App"; DevTools → Elements → `<head>` contains the meta tag
-
-**SSR mode:**
-1. View source of the SSR response (`curl http://localhost:3000/about | head -30`)
-2. **Expected:** `<title>About — My App</title>` and `<meta name="description">` appear inside `<head>` in the raw HTML
-
----
-
-## 12. Test SSR mode end-to-end
-
-```sh
-cd my-ssr
-npm run build
-```
-
-Inspect the output:
-
-```sh
-ls dist/
-# client/  server/
-
-node -e "
-const { handler } = await import('./dist/server/server.js')
-const http = await import('node:http')
-http.createServer(handler).listen(3001, () => console.log('http://localhost:3001'))
-" --input-type=module
-```
-
-1. Open `http://localhost:3001`
-2. **Expected:** Full page HTML served (view-source shows rendered content, not empty shell)
-3. JavaScript hydrates client-side after load
-
----
-
-## 13. Test SSG mode
-
-```sh
-cd my-ssg
-npm run generate
-# or: npm run build (SSG mode)
-```
-
-Inspect output:
-
-```sh
-ls dist/
-# index.html  client/  server/  ssg-manifest.json
-
-cat dist/ssg-manifest.json
-# { "generatedAt": "...", "paths": ["/"], "errors": [] }
-
-cat dist/index.html | head -20
-# Full rendered HTML
-```
-
-Add a dynamic page with `ssg.paths`:
-
-```ts
-// app/pages/items/[id].ts
-component('page-items-id', () => {
-  const props = useProps({ id: '' })
-  return html`<h1>Item ${props.id}</h1>`
-})
-
-export const meta = {
-  ssg: {
-    paths: async () => [
-      { params: { id: '1' } },
-      { params: { id: '2' } },
-      { params: { id: '3' } },
-    ],
-  },
-}
-```
-
-Run `npm run generate` again:
-
-```sh
-ls dist/items/
-# 1/  2/  3/
-
-cat dist/items/1/index.html  # should contain "Item 1"
-```
-
----
-
-## 14. Run the automated test suite
-
-The framework ships with unit and integration tests. Run them with:
-
-```sh
-cd /path/to/@jasonshimmy/vite-plugin-cer-app
-npm test
-```
-
-Run with coverage report:
-
-```sh
-npm run test:coverage
-```
-
-Run in watch mode during development:
-
-```sh
-npm run test:watch
-```
-
----
-
-## Common issues
-
-| Symptom | Likely cause | Fix |
-|---|---|---|
-| `Cannot find module 'virtual:cer-routes'` | Plugin not in Vite config | Add `cerApp()` to `vite.config.ts` plugins |
-| Page not found after adding a file | HMR did not trigger | Save the file again or restart dev server |
-| `component is not defined` | Auto-import not running | Check `autoImports.runtime: true` in config; ensure file is in `app/pages/` |
-| SSR renders blank page | `entry-server.ts` not found | Ensure `app/entry-server.ts` exists or let the framework generate it |
-| API route returns 404 in dev | File not in `server/api/` | Confirm path is `server/api/` (at project root, not inside `app/`) |
-| SSG build skips dynamic routes | `meta.ssg.paths` not exported | Export `meta.ssg.paths` from the page file |
-| Layout not applied | `meta.layout` name mismatch | Ensure the value matches the layout filename without extension |