weifuwu 0.19.8 → 0.19.10

package/README.md

@@ -15,11 +15,9 @@ serve((req, ctx) => new Response('Hello, World!'), { port: 3000 })
 ```
 
 ```ts
-import { serve, Router, preferences, ssr, rootLayout } from 'weifuwu'
+import { serve, Router, ssr } from 'weifuwu'
 const app = new Router()
-app.use(preferences({ dir: './locales' }))
-app.use(rootLayout('./ui'))
-app.get('/', ssr('./ui/pages/home.tsx'))
+app.use('/', ssr({ dir: './ui' }))
 serve(app.handler(), { port: 3000, websocket: app.websocketHandler() })
 ```
 
@@ -119,14 +117,14 @@ The `ctx` object accumulates properties as it passes through the middleware chai
 | `queue` | `queue()` | `Queue` | Job queue |
 | `prefs` | `preferences()` | `{ locale, theme }` | User preferences (locale, theme) |
 | `deploy` | `deploy()` | `{ appName? }` | Deploy gateway info |
-| `layoutStack` | `rootLayout()` / `layout()` | `LayoutEntry[]` | React layout component stack |
+| `layoutStack` | `ssr()` internal | `LayoutEntry[]` | React layout component stack |
 | `loaderData` | User middleware | `Record<string, unknown>` | SSR data passed to client |
 | `user` | `auth()` / `user().middleware()` | `{ id?: string }` | Authenticated user |
 | `parsed` | `validate()` / `upload()` | `{ body, query, params, headers, files }` | Validated/parsed request data |
 | `t` | `preferences()` | `(key) => string` | Translation function |
 | `setPref` | `preferences()` | `(key, val) => Response` | Set preference cookie + redirect |
-| `compiledTailwindCss` | `tailwind()` | `string` | Compiled CSS content (internal) |
-| `tailwindCssUrl` | `tailwind()` | `string` | Compiled CSS route URL (internal) |
+| `compiledTailwindCss` | `ssr()` internal | `string` | Compiled CSS content (internal) |
+| `tailwindCssUrl` | `ssr()` internal | `string` | Compiled CSS route URL (internal) |
 
 ---
 
@@ -137,7 +135,7 @@ All modules follow one of **2 patterns** — learn these and you know every modu
 | Pattern | How to mount | Example |
 |---------|-------------|---------|
 | `[α]` | `app.use(mod())` | `compress()`, `preferences()`, `postgres()` |
-| `[β]` | `app.use('/path', mod())` | `health()`, `graphql(handler)`, `user()` |
+| `[β]` | `app.use('/path', mod())` | `health()`, `ssr({dir})`, `graphql(handler)`, `user()` |
 
 ### Pattern α — Middleware
 
@@ -398,23 +396,7 @@ Restart=always
 | `buildCommand` | — | Build command |
 | `ports` | — | `[port, port+1]` for blue-green |
 
-### errorBoundary(path) [β]
 
-Wraps child routes in an error boundary. If a page or middleware throws, the error component is rendered via SSR with head injection (CSS, theme, context) and layout wrapping.
-
-```ts
-app.use('/blog', errorBoundary('./blog-error.tsx'))
-```
-
-The error component receives `{ error, reset }` as props (`reset` is a no-op on the server):
-
-```tsx
-export default function BlogError({ error, reset }: { error: Error; reset: () => void }) {
-  return <div><h2>Error</h2><p>{error.message}</p></div>
-}
-```
-
-Error boundaries nest — the nearest one up the middleware chain catches the error.
 
 ### health [β]
 
@@ -483,16 +465,7 @@ await engine.trigger({ function_id: 'orders::create', payload: { items: ['apple'
 | `.migrate()` | DB setup |
 | `.shutdown()` | Clean shutdown |
 
-### layout(path) [β]
-
-Compiles a `.tsx` file and returns middleware that pushes the layout component onto `ctx.layoutStack`. Pages rendered by `ssr()` consume this stack. Use after `rootLayout()` to extend a shared structure.
-
-```ts
-app.use(rootLayout('./ui'))
-app.use(layout('./extra.tsx'))   // appended after rootLayout
-```
 
-Layout components receive `{ children }` (the child page or nested layout). Multiple layouts wrap from outer to inner in `use()` order.
 
 ### logdb [β]
 
@@ -566,17 +539,7 @@ await msg.send(channelId, 'System message', { sender_type: 'system', sender_id:
 | `.send(channel, content, opts?)` | Send message to channel |
 | `.close()` | Cleanup |
 
-### notFound(path) [β]
 
-Returns a catch-all handler for 404 pages. When a path is given, the component is rendered via SSR with layout support. Falls back to plain text if compilation fails or no path given.
-
-```ts
-// No path — plain text
-app.all('/*', notFound())
-
-// Path to a .tsx component — renders via SSR
-app.all('/*', notFound('./not-found.tsx'))
-```
 
 ### opencode [β]
 
@@ -825,20 +788,7 @@ app.use(requestId({ header: 'X-Request-Id', generator: () => crypto.randomUUID()
 | `header` | `string` | `'X-Request-ID'` | Header name to read/write |
 | `generator` | `() => string` | `crypto.randomUUID()` | ID generator |
 
-### rootLayout(dir) [α]
-
-One-stop middleware for a page structure. Compiles `layout.tsx` and `app.css` from the given directory, and in dev mode registers vendor bundle, HMR WebSocket, and file watcher.
-
-```ts
-app.use(rootLayout('./ui'))
-// Scans ./ui/layout.tsx → layout component
-// Scans ./ui/app.css → tailwind CSS at /{mountPath}/__wfw/style/{hash}.css
-// Dev: vendor bundle + HMR WS + file watcher
-```
 
-- Sets `ctx.layoutStack` (consumed by `ssr()`)
-- Registers CSS route at `/__wfw/style/:hash.css` — Tailwind CSS compiled via `@tailwindcss/postcss` if `app.css` exists in the dir. Hash is content-based, ensuring cache invalidation on changes.
-- Each `rootLayout` instance is independent — sub-routes can define their own
 
 ### seo [β] + seoMiddleware [α]
 
@@ -858,21 +808,64 @@ Also exports `seoTags(config)` for generating meta/og/twitter tags as an HTML st
 | `sitemap` | `SitemapConfig` | — | Sitemap configuration (urls, resolve, cacheTTL) |
 | `headers` | `SeoHeadersConfig` | — | Response headers (e.g. `X-Robots-Tag`) |
 
-### ssr(path) [β]
+### ssr({ dir }) [β]
+
+One-stop Server-Side Rendering. Accepts a directory and returns a Router that handles all SSR routes, tailwind CSS, hydration bundles, and livereload — using Next.js-style file conventions.
 
-Compiles a `.tsx` file and returns a Router handler that renders the React component to HTML with streaming, client bundle injection, and context serialization.
+```ts
+import { Router, ssr } from 'weifuwu'
+const app = new Router()
+app.use('/', ssr({ dir: './ui' }))
+```
+
+**Directory conventions (Next.js-style):**
+
+```
+./ui/
+├── app/                 ← only this directory affects routing
+│   ├── globals.css      ← tailwind CSS + CSS variables (optional)
+│   ├── layout.tsx       → root layout (wraps all pages)
+│   ├── page.tsx         → GET /
+│   ├── not-found.tsx    → 404 page (optional)
+│   ├── error.tsx        → error boundary (optional)
+│   ├── about/
+│   │   ├── page.tsx     → GET /about
+│   │   └── layout.tsx   → group layout
+│   └── posts/
+│       ├── page.tsx     → GET /posts
+│       └── [id]/
+│           └── page.tsx → GET /posts/:id
+├── components/          ← shared components (does not affect routing)
+└── lib/                 ← utilities (does not affect routing)
+```
+
+| Location | Route |
+|----------|-------|
+| `app/page.tsx` | `GET /` |
+| `app/[param]/page.tsx` | `GET /:param` |
+| `app/layout.tsx` | Root layout (wraps all pages in its subtree) |
+| `app/not-found.tsx` | 404 fallback for that subtree |
+| `app/error.tsx` | Error boundary for that subtree |
+| `app/globals.css` | Tailwind CSS entry (compiled via `@tailwindcss/postcss`) |
+
+**How it works:**
+
+- Each page is lazy-resolved on first request — only the `page.tsx` and its layout chain are compiled
+- Hydration bundle generated per-page at `/__ssr/{hash}.js`
+- Tailwind CSS served at `/__wfw/style/{hash}.css` (cached, content-hashed)
+- Dev mode: vendor bundle, HMR WebSocket, file watcher — all automatic
+- Page components and layouts are compiled via esbuild at runtime — no build step needed
 
 ```ts
-app.get('/about', ssr('./ui/pages/about.tsx'))
+// Multiple independent SSR directories
+app.use('/',      ssr({ dir: './www' }))
+app.use('/admin', ssr({ dir: './admin' }))
+
+// API routes coexist normally
+app.get('/api/ping', () => Response.json({ pong: true }))
 ```
 
-- Compiles via esbuild at runtime (no build step)
-- Reads `ctx.layoutStack` (set by `rootLayout()` or `layout()`) and wraps the component from outer to inner
-- Injects hydration script pointing to the auto-generated client bundle at `/__ssr/{entryId}.js`
-- Injects `<link>` for tailwind CSS from `ctx.tailwindCssUrl` (set by `rootLayout()`)
-- Serializes middleware-injected `ctx` data to `window.__WEIFUWU_CTX` for client-side hydration
-- **Dev mode:** uses `createRoot` instead of `hydrateRoot` — all hooks (`useState`, `useEffect`) work correctly; SSR content is still streamed for fast first paint
-- **Prod mode:** uses `hydrateRoot` for full SSR hydration
+Layout components receive `{ children }` and wrap from outer to inner:
 
 ### tenant [β]
 
@@ -1084,9 +1077,9 @@ function Toast() {
 
 ### Dev mode
 
-Auto-detected when `NODE_ENV !== 'production'`. `rootLayout(dir)` automatically registers vendor bundle, HMR WebSocket, and file watcher. No explicit setup needed.
+Auto-detected when `NODE_ENV !== 'production'`. `ssr({dir})` automatically registers vendor bundle, HMR WebSocket, and file watcher. No explicit setup needed.
 
-When a `.tsx` or `.css` file changes under the `rootLayout` dir, the browser hot-updates without refreshing — `useState` values are preserved. Layout changes trigger a full page reload.
+When a `.tsx` or `.css` file changes under the `ssr` dir, the browser hot-updates without refreshing — `useState` values are preserved. Layout changes trigger a full page reload.
 
 ---
 
@@ -1125,7 +1118,7 @@ Every public symbol can be imported from `'weifuwu'`:
 ### Core
 
 ```ts
-serve, createTestServer, Router,
+serve, createTestServer, Router, ssr,
 Context, Handler, Middleware, ErrorHandler, ServeOptions, Server,
 loadEnv
 ```
@@ -1172,7 +1165,7 @@ openai, createOpenAI
 ### Other modules
 
 ```ts
-health, analytics, seo, seoMiddleware, seoTags,
+preferences, health, analytics, seo, seoMiddleware, seoTags,
 user, mailer, graphql, aiStream, runWorkflow,
 logdb, messager, agent, iii, createWorker, registerWorker,
 opencode, deploy, defineConfig,

package/cli/template/app.ts

@@ -1,12 +1,8 @@
-import { join } from 'node:path'
-import { Router, ssr, rootLayout, preferences } from '../../index.ts'
-
-const _ui = join(import.meta.dirname, 'ui')
-const _loc = join(import.meta.dirname, 'locales')
+import { Router, ssr, preferences } from '../../index.ts'
 
 export const app = new Router()
-app.use(rootLayout(_ui))
-app.use(preferences({ dir: _loc, locale: { default: 'en' }, theme: { default: 'system' } }))
+app.use('/', ssr({ dir: './ui' }))
+app.use(preferences({ dir: './locales', locale: { default: 'en' }, theme: { default: 'system' } }))
 app.use(async (req, ctx, next) => {
   ctx.loaderData = {
     features: [
@@ -17,6 +13,5 @@ app.use(async (req, ctx, next) => {
   }
   return next(req, ctx)
 })
-app.get('/', ssr(join(_ui, 'page.tsx')))
 app.get('/api/ping', () => Response.json({ pong: true, time: new Date().toISOString() }))
 app.ws('/ws/echo', { message(ws, _ctx, data) { ws.send(`echo: ${data}`) } })

package/cli/template/ui/{page.tsx → app/page.tsx}

@@ -1,6 +1,6 @@
 import { useState } from 'react'
-import { useWebsocket, useLoaderData, useLocale, useTheme } from '../../../react.ts'
-import Greeting from './components/Greeting.tsx'
+import { useWebsocket, useLoaderData, useLocale, useTheme } from '../../../../react.ts'
+import Greeting from '../components/Greeting.tsx'
 
 export default function Home() {
   const [input, setInput] = useState('')

package/cli/template/ui/components/Greeting.tsx

@@ -1,3 +1,3 @@
 export default function Greeting({ name }: { name: string }) {
-  return <span className="text-green-500 font-bold">{name}!</span>
+  return <span className="text-red-500 font-bold">{name}!</span>
 }

package/cli.ts

@@ -36,19 +36,12 @@ async function cmdInit(name: string) {
   await cp(templateDir, targetDir, { recursive: true })
 
   // Rewrite local imports → package imports for the copied project
-  for (const file of ['app.ts', 'index.ts', 'ui/page.tsx']) {
+  for (const file of ['app.ts', 'index.ts', 'ui/app/page.tsx']) {
     const fp = join(targetDir, file)
     let content = await readFile(fp, 'utf-8')
     content = content
       .replace(/from '\.\.\/\.\.\/index\.ts'/g, "from 'weifuwu'")
       .replace(/from '\.\.\/\.\.\/\.\.\/react\.ts'/g, "from 'weifuwu/react'")
-      .replace(/import \{ join \} from 'node:path'\n/gm, '')
-      .replace(/const _ui = join\(import\.meta\.dirname, 'ui'\)\n/gm, '')
-      .replace(/const _loc = join\(import\.meta\.dirname, 'locales'\)\n\n/, '')
-      .replace(/preferences\(\{ dir: _loc, locale: \{ default: 'en' \}, theme: \{ default: 'system' \} \}\)/g, "preferences({ dir: './locales' })")
-      .replace(/rootLayout\(_ui\)/g, "rootLayout('./ui')")
-      .replace(/ssr\(join\(_ui, 'page\.tsx'\)\)/g, "ssr('./ui/page.tsx')")
-      .replace(/join\(import\.meta\.dirname, 'ui'\)/g, "'./ui'")
     await writeFile(fp, content)
   }
 
@@ -57,8 +50,8 @@ async function cmdInit(name: string) {
     name,
     type: 'module',
     scripts: {
-      dev: 'node index.ts',
-      start: 'NODE_ENV=production node index.ts',
+      dev: 'NODE_ENV=development node index.ts',
+      start: 'node index.ts',
     },
     dependencies: {
       weifuwu: `^${v}`,
@@ -98,7 +91,7 @@ async function cmdInit(name: string) {
     '## Commands',
     '',
     '- `npm run dev` — start dev server with `--watch`',
-    '- `npm start` — start production server (NODE_ENV=production)',
+    '- `npm start` — start production server',
     '- `npm install` — install dependencies',
     '- `npx tsc --noEmit` — type-check without emitting',
     '',

package/dist/auth.d.ts

@@ -0,0 +1,8 @@
+import type { Middleware } from './types.ts';
+export interface AuthOptions {
+    token?: string;
+    verify?: (token: string, req: Request) => unknown | Promise<unknown>;
+    proxy?: string | URL;
+    header?: string;
+}
+export declare function auth(options: AuthOptions): Middleware;

package/dist/cli.js

@@ -28,18 +28,18 @@ async function cmdInit(name) {
   await mkdir(targetDir, { recursive: true });
   const templateDir = join(pkgRoot, "cli", "template");
   await cp(templateDir, targetDir, { recursive: true });
-  for (const file of ["app.ts", "index.ts", "ui/page.tsx"]) {
+  for (const file of ["app.ts", "index.ts", "ui/app/page.tsx"]) {
     const fp = join(targetDir, file);
     let content = await readFile(fp, "utf-8");
-    content = content.replace(/from '\.\.\/\.\.\/index\.ts'/g, "from 'weifuwu'").replace(/from '\.\.\/\.\.\/\.\.\/react\.ts'/g, "from 'weifuwu/react'").replace(/import \{ join \} from 'node:path'\n/gm, "").replace(/const _ui = join\(import\.meta\.dirname, 'ui'\)\n/gm, "").replace(/const _loc = join\(import\.meta\.dirname, 'locales'\)\n\n/, "").replace(/preferences\(\{ dir: _loc, locale: \{ default: 'en' \}, theme: \{ default: 'system' \} \}\)/g, "preferences({ dir: './locales' })").replace(/rootLayout\(_ui\)/g, "rootLayout('./ui')").replace(/ssr\(join\(_ui, 'page\.tsx'\)\)/g, "ssr('./ui/page.tsx')").replace(/join\(import\.meta\.dirname, 'ui'\)/g, "'./ui'");
+    content = content.replace(/from '\.\.\/\.\.\/index\.ts'/g, "from 'weifuwu'").replace(/from '\.\.\/\.\.\/\.\.\/react\.ts'/g, "from 'weifuwu/react'");
     await writeFile(fp, content);
   }
   await writeFile(join(targetDir, "package.json"), JSON.stringify({
     name,
     type: "module",
     scripts: {
-      dev: "node index.ts",
-      start: "NODE_ENV=production node index.ts"
+      dev: "NODE_ENV=development node index.ts",
+      start: "node index.ts"
     },
     dependencies: {
       weifuwu: `^${v}`
@@ -76,7 +76,7 @@ async function cmdInit(name) {
     "## Commands",
     "",
     "- `npm run dev` \u2014 start dev server with `--watch`",
-    "- `npm start` \u2014 start production server (NODE_ENV=production)",
+    "- `npm start` \u2014 start production server",
     "- `npm install` \u2014 install dependencies",
     "- `npx tsc --noEmit` \u2014 type-check without emitting",
     "",

package/dist/compile.d.ts

@@ -12,3 +12,5 @@ export declare function compileHotComponent(path: string): Promise<{
     hash: string;
     code: string;
 }>;
+/** Clean up esbuild's internal worker pool. Call when you're done compiling. */
+export declare function closeCompile(): Promise<void>;

package/dist/cors.d.ts

@@ -0,0 +1,10 @@
+import type { Middleware } from './types.ts';
+export interface CORSOptions {
+    origin?: string | string[] | ((origin: string) => string | boolean | undefined);
+    methods?: string[];
+    allowedHeaders?: string[];
+    exposedHeaders?: string[];
+    credentials?: boolean;
+    maxAge?: number;
+}
+export declare function cors(options?: CORSOptions): Middleware;

package/dist/env.d.ts

@@ -1 +1,3 @@
+/** Whether NODE_ENV is explicitly set to 'development' */
+export declare function isDev(): boolean;
 export declare function loadEnv(path?: string): void;

package/dist/html-shell.d.ts

@@ -0,0 +1 @@
+export declare function buildHtmlShell(title: string, bodyElement: any, layoutComponents: any[]): any;

package/dist/index.d.ts

@@ -1,12 +1,16 @@
 export type { Context, Handler, Middleware, ErrorHandler } from './types.ts';
-export { loadEnv } from './env.ts';
+export { loadEnv, isDev } from './env.ts';
 export { serve, createTestServer } from './serve.ts';
 export type { ServeOptions, Server } from './serve.ts';
 export { Router } from './router.ts';
 export type { WebSocketHandler } from './router.ts';
 export { TsxContext } from './tsx-context.ts';
-export { auth, cors, logger } from './middleware.ts';
-export type { AuthOptions, CORSOptions, LoggerOptions } from './middleware.ts';
+export { logger } from './logger.ts';
+export type { LoggerOptions } from './logger.ts';
+export { cors } from './cors.ts';
+export type { CORSOptions } from './cors.ts';
+export { auth } from './auth.ts';
+export type { AuthOptions } from './auth.ts';
 export { serveStatic } from './static.ts';
 export type { ServeStaticOptions } from './static.ts';
 export { validate } from './validate.ts';
@@ -68,10 +72,3 @@ export type { LogdbOptions, LogdbModule, LogEntry, LogEntryInput, } from './logd
 export { iii, createWorker, registerWorker } from './iii/index.ts';
 export type { IIIModule, IIIOptions, WorkerInfo, FunctionInfo, TriggerInfo, FunctionHandler, FunctionContext, TriggerInput, RemoteWorker, TriggerRequest, } from './iii/types.ts';
 export { ssr } from './ssr.ts';
-export { rootLayout } from './root-layout.ts';
-export { layout } from './layout.ts';
-export { notFound } from './not-found.ts';
-export { errorBoundary } from './error-boundary.ts';
-export { clearCompileCache } from './compile.ts';
-export { ssrEntries } from './ssr-entries.ts';
-export type { SsrEntry } from './ssr-entries.ts';