weifuwu 0.9.2 → 0.9.3

package/README.md

@@ -34,11 +34,42 @@ Everything follows the same `(req, ctx) => Response` contract. The Router handle
 
 ## Quick start
 
+### Hello World
+
 ```ts
 import { serve } from 'weifuwu'
 serve((req, ctx) => new Response('Hello, World!'), { port: 3000 })
 ```
 
+### React + Tailwind
+
+```bash
+npm install weifuwu
+mkdir -p ui/pages
+```
+
+```ts
+// app.ts
+import { serve, Router } from 'weifuwu'
+
+const app = new Router()
+app.use('/', await tsx({ dir: './ui/' }))
+serve(app.handler(), { port: 3000, websocket: app.websocketHandler() })
+```
+
+```tsx
+// ui/pages/page.tsx
+export default function Home() {
+  return <h1 className="text-3xl font-bold text-blue-600">Hello</h1>
+}
+```
+
+```bash
+node app.ts
+```
+
+Open http://localhost:3000 — Tailwind CSS is compiled automatically, pages hot-reload on save.
+
 ## Router
 
 ```ts
@@ -851,44 +882,134 @@ import { serve, Router } from 'weifuwu'
 import { tsx } from 'weifuwu/tsx'
 
 const app = new Router()
-app.use('/', await tsx({ dir: './pages/' }))
+app.use('/', await tsx({ dir: './ui/' }))
 
 serve(app.handler(), { port: 3000, websocket: app.websocketHandler() })
 ```
 
-### Development mode
+### Directory structure
 
-`tsx()` automatically runs in development mode (`NODE_ENV !== 'production'`):
+```
+ui/
+├── pages/              ← 页面文件
+│   ├── page.tsx        → GET /           (React component, default export)
+│   ├── layout.tsx      → root layout     (HTML shell, receives req/ctx, NOT hydrated)
+│   ├── not-found.tsx   → 404 error page  (rendered for unmatched routes, wrapped in layout)
+│   ├── about/page.tsx  → GET /about
+│   ├── blog/[slug]/
+│   │   ├── page.tsx    → GET /blog/:slug
+│   │   ├── load.ts     → data fetching   (server-only, default export)
+│   │   └── route.ts    → POST /blog/:slug (API, named exports POST/PUT/DELETE/...)
+│   ├── blog/layout.tsx → /blog/* layout  (UI structure, receives children, hydrated)
+│   └── api/search/
+│       └── route.ts    → GET /api/search (standalone API, no page.tsx needed)
+└── components/         ← 组件文件（会被热更自动感知）
+    └── button.tsx
+```
+
+### Development mode
 
-- **File watching** — editing a `.tsx`/`.ts` file triggers recompilation and the browser auto-refreshes via WebSocket
-- **Tailwind CSS** — if an `app.css` or `globals.css` file is found, Tailwind CSS is processed automatically. Write `className` directly.
-- **`@` aliases** — if `tsconfig.json` or `jsconfig.json` has `compilerOptions.paths`, the `@` alias is passed to esbuild automatically (works with shadcn/ui)
-- **Process state preserved** — DB connections, WebSockets, in-memory caches are not lost
+tsx() runs in development mode automatically when `NODE_ENV !== 'production'`:
 
-Production mode (`NODE_ENV=production`) disables file watching and live reload. All other features work the same.
+- **File watching** — chokidar watches the `dir` directory for `.tsx`/`.ts` changes
+  - Page files in `pages/` → single-file recompilation + registry update
+  - Component files in `components/` → full rebuild of all pages
+  - New files are detected automatically
+- **Live reload** — Compiled via esbuild `write: false` + `vm.Script.runInContext` (no disk writes, no `node --watch` conflict)
+- **WebSocket auto-refresh** — `/__weifuwu/livereload` endpoint pushes reload signals; browser refreshes automatically
+- **`node --watch` compatible** — External files (`app.ts`, `middleware/`) handled by `--watch` restart; `ui/` changes handled by tsx() without conflict
 
 ```bash
-node app.ts                # development
+node app.ts                # development (auto-reload + live refresh)
 NODE_ENV=production node app.ts   # production
 ```
 
-### File conventions
+### Tailwind CSS
 
+tsx() includes built-in Tailwind CSS v4 support. If an `app.css` file exists in the `dir` directory, it is compiled automatically through PostCSS + `@tailwindcss/postcss`. If no `app.css` is found, one is created automatically:
+
+```css
+@import "tailwindcss";
 ```
-pages/
-  page.tsx              → GET /           (React component, default export)
-  layout.tsx            → root layout     (HTML shell, receives req/ctx, NOT hydrated)
-  not-found.tsx         → 404 error page  (rendered for unmatched routes, wrapped in layout)
-  about/page.tsx        → GET /about
-  blog/[slug]/
-    page.tsx            → GET /blog/:slug
-    load.ts             → data fetching   (server-only, default export)
-    route.ts            → POST /blog/:slug (API, named exports POST/PUT/DELETE/...)
-  blog/layout.tsx       → /blog/* layout  (UI structure, receives children, hydrated)
-  api/search/
-    route.ts            → GET /api/search (standalone API, no page.tsx needed)
+
+Write `className` directly in your components — no CLI, no configuration:
+
+```tsx
+export default function Home() {
+  return <h1 className="text-3xl font-bold text-blue-600">Hello</h1>
+}
 ```
 
+In development mode, Tailwind is reprocessed whenever a `.tsx` file changes (new class names are picked up automatically).
+
+### `@` alias
+
+If your project has a `tsconfig.json` or `jsconfig.json` with `compilerOptions.paths`, tsx() reads it automatically and passes aliases to all esbuild builds (SSR compilation, hydration bundles, and hot reload):
+
+```json
+{
+  "compilerOptions": {
+    "paths": {
+      "@/*": ["./ui/*"]
+    }
+  }
+}
+```
+
+This enables imports like `@/components/button` or `@/lib/utils` in both server-rendered and client-hydrated code.
+
+### shadcn/ui
+
+tsx() works with [shadcn/ui](https://ui.shadcn.com) out of the box. The `@` alias and Tailwind CSS are handled automatically.
+
+```bash
+# 1. Install shadcn CLI and init (select "other" framework)
+npx shadcn@latest init
+
+# 2. When prompted, configure:
+#    - Style:            your preference
+#    - Base color:       your preference
+#    - CSS file path:    ui/app.css
+#    - Import alias:     @/  →  ./ui/
+#    - React hooks:      yes
+```
+
+```json
+// tsconfig.json (generated by shadcn init)
+{
+  "compilerOptions": {
+    "paths": {
+      "@/*": ["./ui/*"]
+    }
+  }
+}
+```
+
+Add components:
+
+```bash
+npx shadcn@latest add button card dialog
+```
+
+Use them in your pages:
+
+```tsx
+// ui/pages/page.tsx
+import { Button } from '@/components/ui/button'
+
+export default function Home() {
+  return <Button variant="outline">Click me</Button>
+}
+```
+
+```bash
+node app.ts
+```
+
+### Backward compatibility
+
+`tsx({ dir: './pages/' })` still works. When there is no `pages/` subdirectory under `dir`, the `dir` itself is used as the pages directory.
+
 ### page.tsx — page component
 
 ```tsx
@@ -967,7 +1088,7 @@ serve(app.handler(), { websocket: app.websocketHandler() })
 ```
 
 ```bash
-node app.ts                # development (auto-reload on changes)
+node app.ts                # development (auto-reload + live refresh)
 NODE_ENV=production node app.ts   # production
 ```
 
@@ -1110,18 +1231,19 @@ Returns `MessagerModule` — `{ migrate, router, wsHandler, send, close }`.
 
 | Option | Default | Description |
 |--------|---------|-------------|
-| `dir`  | —       | Pages directory path |
+| `dir` | — | UI directory path (containing `pages/` and optionally `components/`) |
 
 Returns `Promise<Router>`.
 
-Development features (auto-detected, no configuration needed):
+Auto-detected features (no configuration needed):
 
 | Feature | Behavior |
 |---------|----------|
-| **File watching** | Enabled when `NODE_ENV !== 'production'`. Watches pages directory, recompiles on change, sends live-reload signal via WebSocket |
-| **Tailwind CSS** | Auto-detected when `app.css` / `globals.css` exists. Processed through PostCSS + Tailwind plugin. Served at `/__wfw/style.css` and auto-injected into HTML `<head>` |
-| **`@` alias** | Read from `tsconfig.json` / `jsconfig.json` `compilerOptions.paths` and passed to esbuild |
+| **File watching** | Enabled in dev mode. Watches `dir` for changes, recompiles on the fly, sends reload via WebSocket |
 | **WebSocket live reload** | Endpoint at `/__weifuwu/livereload`. Browser auto-refreshes on file changes or server restart |
+| **Tailwind CSS** | Auto-detected when `app.css` exists. Compiled through PostCSS + `@tailwindcss/postcss`. Served at `/__wfw/style.css`, auto-injected into HTML `<head>` |
+| **`@` alias** | Read from `tsconfig.json` / `jsconfig.json` `compilerOptions.paths`. Passed to all esbuild builds |
+| **Process state** | Dev mode keeps the process alive on file changes. DB connections, WebSockets, in-memory caches persist |
 
 To use WebSocket features, pass `router.websocketHandler()` to `serve()`: