@barefootjs/cli 0.35.4 → 0.35.5

package/dist/docs/core/adapters/hono-adapter.md

@@ -126,7 +126,7 @@ export function Counter(__allProps: { initial?: number } & { __instanceId?: stri
 A build-time post-processing step injects `useRequestContext()` calls into generated templates. `BfScripts` renders the collected `<script>` tags:
 
 ```tsx
-import { BfScripts } from '@barefootjs/hono'
+import { BfScripts } from '@barefootjs/hono/scripts'
 
 export function Layout({ children }) {
   return (
@@ -212,3 +212,158 @@ export default defineConfig({
   }),
 })
 ```
+
+## Adding to an Existing Project
+
+`npm create barefootjs@latest` scaffolds the layout above from scratch; this section retrofits it onto an existing Hono + Cloudflare Workers app that already renders with `hono/jsx-renderer` and deploys with `wrangler deploy`. The end state is the same as the scaffold's, so a freshly scaffolded project is a valid reference to diff against when something doesn't line up.
+
+### What changes
+
+`barefoot()` compiles **individual components** — each `.tsx` under `components` becomes an SSR template under `templates` plus hydration JS under `build.outDir`. It never bundles the server app into a single file. For a project that currently does that with a whole-app Vite bundler (e.g. `@hono/vite-build`), the consequence is:
+
+| | Before | After |
+|---|---|---|
+| Server build | Bundler plugin emits a single-file SSR bundle | Step removed; nothing replaces it |
+| `wrangler.jsonc` `main` | The pre-bundled output | The uncompiled entry file — wrangler's own esbuild bundles it at dev/deploy time |
+| `vite build` | Produces the server bundle | Produces compiled templates + hydration JS only |
+
+`barefoot()` takes the bundler plugin's place in `vite.config.ts`, and any `package.json` script or CI step that referenced the old bundle path goes with it.
+
+**Paths in this section are the scaffold's** (`components/`, `dist/components`, `public/components`, `server.tsx`, `renderer.tsx`). Substitute your own. Two that are easy to copy literally by mistake:
+
+- `wrangler.jsonc` `main` must be your app's actual Hono entry file (e.g. `src/index.tsx`). Copying `server.tsx` as-is fails immediately with `The entry-point file at "server.tsx" was not found`.
+- `import { renderer } from './renderer'` assumes `jsxRenderer` lives in its own module, as in the scaffold. If yours is defined inline in the entry file, edit it there and skip the import — there's no need to split it out.
+
+### 1. Install
+
+```sh
+npm install @barefootjs/client @barefootjs/hono @barefootjs/jsx @barefootjs/shared
+npm install -D @barefootjs/vite
+```
+
+> **Peer dependencies.** `@barefootjs/hono` peer-depends on `vite ^6.0.0` and `@barefootjs/jsx` on `typescript ^5.0.0`. A project already on a newer major of either (e.g. `vite@8`, `typescript@7`) fails `npm install` with an `ERESOLVE` error. Either install with `--legacy-peer-deps` or pin `typescript` to `^5`. The `typescript` range is the one that matters: a newer `vite` alone works in practice, but a newer `typescript` makes `vite build` crash at config-load time with `TypeError: ts.createPrinter is not a function` — an opaque runtime error, not a version check — because `@barefootjs/vite` calls the `typescript` package's compiler API directly.
+
+### 2. Config files
+
+#### `tsconfig.json`
+
+```json
+{
+  "compilerOptions": {
+    "jsx": "react-jsx",
+    "jsxImportSource": "@barefootjs/hono/jsx",
+    "baseUrl": ".",
+    "paths": {
+      "@/components/*": ["./dist/components/*", "./components/*"]
+    }
+  },
+  "exclude": ["node_modules", "dist/components"]
+}
+```
+
+`@/components/*` has two targets, tried in order by both TypeScript and wrangler: the compiled SSR template under `dist/components/` (carrying the hydration markers from Output Format above) whenever it exists, otherwise the raw source under `components/` so editor tooling and type-checking resolve before the first build. Excluding `dist/components` keeps the compiled copy out of type-checking. Everything else already in `compilerOptions` (`types`, `strict`, …) stays as it is.
+
+#### `vite.config.ts`
+
+```ts
+// vite.config.ts
+import { dirname, resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { defineConfig } from 'vite'
+import { barefoot } from '@barefootjs/hono/vite'
+
+const HERE = dirname(fileURLToPath(import.meta.url))
+
+export default defineConfig({
+  // Public URL prefix of the client build. Must match the path Workers
+  // Assets serves `build.outDir` under (wrangler.jsonc below).
+  base: '/components/',
+  resolve: {
+    // Required, not optional: Vite's dev-server dependency pre-scan runs
+    // before this plugin's `transform` hook and ignores tsconfig `paths`.
+    // Points at the SOURCE tree, never at `dist/components`.
+    alias: {
+      '@/components': resolve(HERE, 'components'),
+    },
+  },
+  // `build.outDir` sits inside `public/`, which Workers Assets already
+  // serves as-is. Vite's default `publicDir` would copy the rest of
+  // `public/` into `public/components` on every build for nothing.
+  publicDir: false,
+  build: {
+    outDir: 'public/components',   // hydration JS → served by Workers Assets
+    emptyOutDir: true,
+  },
+  plugins: barefoot({
+    components: ['components'],    // .tsx source directories to compile
+    templates: 'dist/components',  // compiled SSR templates → imported by the server, never served
+  }),
+})
+```
+
+Everything not shown (hashing, chunking, minification, dev server) is stock Vite. `adapterOptions`, `assets`, and `assetsOutputFile` (see Options above) are not needed for a retrofit.
+
+#### `wrangler.jsonc`
+
+```jsonc
+{
+  "$schema": "node_modules/wrangler/config-schema.json",
+  "name": "my-app",
+  // Your existing uncompiled Hono entry (see "Paths" above). Wrangler
+  // bundles it and follows the tsconfig `paths` mapping into dist/components/.
+  "main": "server.tsx",
+  "compatibility_date": "2025-01-01",
+  // Must cover `build.outDir` from vite.config.ts and must not include
+  // `templates` — see Deploying to Cloudflare Workers above.
+  "assets": {
+    "directory": "./public"
+  }
+}
+```
+
+### 3. Wire the app
+
+**Render `<BfScripts />` once** (from `@barefootjs/hono/scripts`) in the layout your `jsxRenderer` already defines — not inside individual components. It emits the `<script>` tags loading each compiled component's hydration JS exactly once per page, however many instances are rendered (see Script Collection above). Existing `ContextRenderer` augmentation and stylesheet links stay as they are.
+
+```tsx
+import { jsxRenderer } from 'hono/jsx-renderer'
+import { BfScripts } from '@barefootjs/hono/scripts'
+
+export const renderer = jsxRenderer(({ children, title }) => (
+  <html lang="en">
+    <head>
+      <meta charset="UTF-8" />
+      <title>{title ?? 'My app'}</title>
+    </head>
+    <body>
+      {children}
+      <BfScripts />
+    </body>
+  </html>
+))
+```
+
+**Import components through the alias**, not a relative path into the source tree, so the dist-first resolution from `tsconfig.json` applies:
+
+```tsx
+// server.tsx
+import { Hono } from 'hono'
+import { renderer } from './renderer'
+import { Counter } from '@/components/Counter'
+
+const app = new Hono()
+app.use('*', renderer)
+app.get('/', (c) => c.render(<main><Counter /></main>, { title: 'My app' }))
+export default app
+```
+
+Existing plain Hono JSX components can stay put and move under `components/` one at a time — only files under a configured `components` directory are compiled.
+
+### 4. Build and verify
+
+```sh
+npx vite build      # writes dist/components/ (templates) and public/components/ (hydration JS)
+npx wrangler dev    # or: npx wrangler deploy
+```
+
+Load a page that renders a converted `"use client"` component: its element carries a `bf` marker attribute (see Output Format above) and it responds to interaction. During development, run `vite dev` alongside `wrangler dev` so `dist/components/` keeps regenerating on change.

package/dist/docs/core/adapters.md

@@ -18,16 +18,20 @@ JSX Source
 
 ## Available Adapters
 
-| Adapter | Output | Backend | Package |
-|---------|--------|---------|---------|
-| [`HonoAdapter`](./adapters/hono-adapter.md) | `.tsx` | Hono / JSX-based servers | `@barefootjs/hono` |
-| [`GoTemplateAdapter`](./adapters/go-template-adapter.md) | `.tmpl` + `_types.go` | Go `html/template` | `@barefootjs/go-template` |
-| [Perl](./adapters/perl-adapter.md) | `.ep` / `.tx` | Mojolicious, Text::Xslate (PSGI/Plack) | `@barefootjs/mojolicious`, `@barefootjs/xslate` |
-| [Ruby](./adapters/ruby-adapter.md) | `.erb` | stdlib ERB (any Rack app — Sinatra, Rails) | `@barefootjs/erb` |
-| [Python](./adapters/python-adapter.md) | `.jinja` | Jinja2 (Flask, Django, bare WSGI) | `@barefootjs/jinja` |
-| [PHP](./adapters/php-adapter.md) | `.twig` / `.blade.php` | Twig (Slim, plain PHP), Laravel Blade (`illuminate/view` standalone) | `@barefootjs/twig`, `@barefootjs/blade` |
-| [Rust](./adapters/rust-adapter.md) | `.j2` | minijinja (axum, actix-web, warp) | `@barefootjs/rust` |
-| [CSR](./adapters/csr.md) | — (client-rendered) | None (browser-only) | `@barefootjs/client` |
+<!-- ADAPTER-TABLE:START (auto-generated by scripts/generate-adapter-docs.ts — do not edit by hand) -->
+| Language | Backend | Package |
+|----------|---------|---------|
+| TypeScript | [Hono](./adapters/hono-adapter.md) | `@barefootjs/hono` |
+| Go | [html/template](./adapters/go-template-adapter.md) | `@barefootjs/go-template` |
+| Perl | [Mojolicious](./adapters/perl-adapter.md) | `@barefootjs/mojolicious` |
+| Perl | [Text::Xslate](./adapters/perl-adapter.md) | `@barefootjs/xslate` |
+| Ruby | [ERB](./adapters/ruby-adapter.md) | `@barefootjs/erb` |
+| Python | [Jinja2](./adapters/python-adapter.md) | `@barefootjs/jinja` |
+| PHP | [Twig](./adapters/php-adapter.md) | `@barefootjs/twig` |
+| PHP | [Laravel Blade](./adapters/php-adapter.md) | `@barefootjs/blade` |
+| Rust | [minijinja](./adapters/rust-adapter.md) | `@barefootjs/rust` |
+| — | [CSR (browser only)](./adapters/csr.md) | `@barefootjs/client` |
+<!-- ADAPTER-TABLE:END -->
 
 > CSR is not an IR→template adapter. It renders components directly in the browser using client-side template functions — use it when the server can't (or shouldn't) emit the initial HTML.
 

package/dist/docs/core/core-concepts/backend-freedom.md

@@ -13,19 +13,21 @@ BarefootJS compiles JSX at build time into your backend's native template format
 JSX → IR (backend-agnostic) → Adapter → Template
 ```
 
-| Language | Adapter | Notes |
-|----------|---------|-------|
-| TypeScript | [HonoAdapter](../adapters/hono-adapter.md) | Hono / JSX-based TS servers |
-| TypeScript | [TestAdapter](https://github.com/piconic-ai/barefootjs/tree/main/packages/test) | IR-based component testing |
-| Go | [GoTemplateAdapter](../adapters/go-template-adapter.md) | `html/template` |
-| Perl | [MojoliciousAdapter](https://github.com/piconic-ai/barefootjs/tree/main/packages/adapter-mojolicious) | Mojolicious EP templates |
-
-### Planned
-
-| Language | Adapter |
-|----------|---------|
-| Rust | (TBD) |
-| Python | Jinja2Adapter |
-| Ruby | ERBAdapter |
+<!-- ADAPTER-TABLE:START (auto-generated by scripts/generate-adapter-docs.ts — do not edit by hand) -->
+| Language | Backend | Package |
+|----------|---------|---------|
+| TypeScript | [Hono](../adapters/hono-adapter.md) | `@barefootjs/hono` |
+| Go | [html/template](../adapters/go-template-adapter.md) | `@barefootjs/go-template` |
+| Perl | [Mojolicious](../adapters/perl-adapter.md) | `@barefootjs/mojolicious` |
+| Perl | [Text::Xslate](../adapters/perl-adapter.md) | `@barefootjs/xslate` |
+| Ruby | [ERB](../adapters/ruby-adapter.md) | `@barefootjs/erb` |
+| Python | [Jinja2](../adapters/python-adapter.md) | `@barefootjs/jinja` |
+| PHP | [Twig](../adapters/php-adapter.md) | `@barefootjs/twig` |
+| PHP | [Laravel Blade](../adapters/php-adapter.md) | `@barefootjs/blade` |
+| Rust | [minijinja](../adapters/rust-adapter.md) | `@barefootjs/rust` |
+| — | [CSR (browser only)](../adapters/csr.md) | `@barefootjs/client` |
+<!-- ADAPTER-TABLE:END -->
+
+TypeScript also has an [IR-based `TestAdapter`](https://github.com/piconic-ai/barefootjs/tree/main/packages/test) for browser-free component testing — it isn't a serving-time backend, so it's outside the table above. See [Adapters](../adapters.md) for the full picture, including which adapters share one engine-agnostic runtime.
 
 The IR contract is stable. You can [write a custom adapter](../adapters/custom-adapter.md) for any backend.