@barefootjs/cli 0.6.1 → 0.8.0

package/dist/docs/core/README.mdx

@@ -52,6 +52,7 @@
 - [Adapter Architecture](./adapters/adapter-architecture.md) — How adapters work, the `TemplateAdapter` interface, and the IR contract
 - [Hono Adapter](./adapters/hono-adapter.md) — Configuration and output format for Hono / JSX-based servers
 - [Go Template Adapter](./adapters/go-template-adapter.md) — Configuration and output format for Go `html/template`
+- [Perl Adapter](./adapters/perl-adapter.md) — Mojolicious and Text::Xslate (PSGI/Plack) backends, sharing one runtime
 - [CSR (Client-Side Rendering)](./adapters/csr.md) — Static-hosting renderer: emit client JS only, no SSR template
 - [Writing a Custom Adapter](./adapters/custom-adapter.md) — Step-by-step guide to implementing your own adapter
 

package/dist/docs/core/adapters/go-template-adapter.md

@@ -12,6 +12,27 @@ npm install @barefootjs/go-template
 ```
 
 
+## Server integration
+
+The adapter is **web-framework-agnostic** — it emits plain Go `html/template`
+files plus a small runtime (`FuncMap`, `Renderer`), so any server that can
+parse and execute `html/template` can render the output. The scaffolder
+(`npm create barefootjs@latest -- --adapter <name>`) ships runnable starters
+for four Go servers, all built on this adapter:
+
+| `--adapter` | Framework | Router |
+|-------------|-----------|--------|
+| `echo` | [Echo](https://echo.labstack.com/) | `echo.Renderer` |
+| `gin` | [Gin](https://gin-gonic.com/) | `gin.Engine` |
+| `chi` | [Chi](https://go-chi.io/) | `chi.Router` (net/http) |
+| `nethttp` | Go standard library | `http.ServeMux` |
+
+Each scaffold loads the generated `.tmpl` files into a `template.Template`
+with `bf.FuncMap()`, then renders a component through `bf.NewRenderer(...)`.
+Runnable end-to-end examples for all four live under
+[`integrations/`](https://github.com/piconic-ai/barefootjs/tree/main/integrations).
+
+
 ## Basic Usage
 
 ```typescript
@@ -221,6 +242,14 @@ export function TodoList({ items }: { items: TodoItem[] }) {
 }
 ```
 
+Child component props carry a `ScopeID` used for hydration. You don't have to
+mint these by hand: `bf.Renderer.Render` backfills a unique
+`<Component>_<random>` id for any child (in a slice or a single field) whose
+`ScopeID` is empty — the same shape the generated `New{Component}Props()`
+constructor uses. Build child props with just the data they need (e.g.
+`TodoItemProps{Todo: t}`) and the runtime fills in the rest. Setting `ScopeID`
+explicitly still works and is preserved when you need a stable id.
+
 ## Conditional Rendering
 
 Ternaries become `{{if}}...{{else}}...{{end}}`:

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

@@ -0,0 +1,171 @@
+---
+title: Perl Adapter
+description: Render BarefootJS components from Perl — one engine-agnostic runtime with Mojolicious and Text::Xslate (PSGI/Plack) backends.
+---
+
+# Perl Adapter
+
+Run the same JSX components on a Perl backend. BarefootJS compiles your JSX into
+a **marked template** plus **client JS**; on the server, a small Perl runtime
+renders those templates. The runtime is deliberately **template-engine- and
+web-framework-agnostic**, so one implementation drives multiple stacks.
+
+```
+JSX → IR → marked template (.ep / .tx) + Component.client.js
+                 │
+                 ▼
+   BarefootJS runtime  ──delegates──▶  pluggable backend
+   (@barefootjs/perl)                  (Mojolicious | Text::Xslate)
+```
+
+## Two backends, one runtime
+
+| Backend | Template syntax | Compile-time package | Runtime | Where it runs |
+|---------|-----------------|----------------------|---------|---------------|
+| Mojolicious | EP (`<%= %>`) | `@barefootjs/mojolicious` | `Mojolicious::Plugin::BarefootJS` + `BarefootJS::Backend::Mojo` | Mojolicious apps |
+| Text::Xslate | Kolon (`<: :>`) | `@barefootjs/xslate` | `BarefootJS::Backend::Xslate` | **any PSGI / Plack app** (no framework) |
+
+Both compile-time packages emit per-component template files and the shared
+client JS, and both render through the same engine-agnostic Perl runtime
+(`BarefootJS`, shipped by `@barefootjs/perl`). The only thing that differs is
+the **backend**: a tiny object that implements the four operations the runtime
+delegates to.
+
+### The backend contract
+
+Everything that depends on *how* a template renders — JSON marshalling,
+raw-string marking, JSX-children materialisation, and named-template
+rendering — lives behind a `backend` object with four methods:
+
+| Method | Purpose |
+|--------|---------|
+| `encode_json($data)` | Serialize a value for `bf-p` props / inline JSON |
+| `mark_raw($str)` | Mark already-safe HTML so the engine won't re-escape it |
+| `materialize($value)` | Resolve captured JSX children to a string |
+| `render_named($name, $bf, \%vars)` | Render a child component's template |
+
+Because that is the *only* engine-specific surface, the EP→Kolon mapping is
+mechanical and the runtime is reused unchanged:
+
+| Mojolicious EP | Text::Xslate Kolon |
+|----------------|--------------------|
+| `<%= EXPR %>` (escaped) | `<: EXPR :>` (Kolon auto-escapes) |
+| `<%== EXPR %>` (raw) | `<: EXPR \| mark_raw :>` |
+| `bf->method(args)` | `$bf.method(args)` |
+| `% if (C) { … % }` | `: if (C) { … : }` |
+
+## Mojolicious
+
+```
+npm install @barefootjs/mojolicious
+```
+
+Scaffold a runnable starter:
+
+```
+npm create barefootjs@latest -- --adapter mojo
+```
+
+Configure the build (`barefoot.config.ts`):
+
+```typescript
+import { createConfig } from '@barefootjs/mojolicious/build'
+
+export default createConfig({
+  components: ['./components'],
+  outDir: 'dist',
+})
+```
+
+In your app, load the plugin — it registers a `bf` helper that gives each
+request a `BarefootJS` runtime backed by `BarefootJS::Backend::Mojo`:
+
+```perl
+use Mojolicious::Lite -signatures;
+
+plugin 'BarefootJS';
+
+get '/counter' => sub ($c) {
+    $c->render(template => 'Counter', layout => 'default');
+};
+
+app->start;
+```
+
+The generated `.html.ep` templates call the runtime through the `bf` helper
+(`<%== bf->scope_attr %>`, `<%= bf->json($data) %>`, …).
+
+## Text::Xslate (PSGI / Plack)
+
+```
+npm install @barefootjs/xslate
+```
+
+```typescript
+import { createConfig } from '@barefootjs/xslate/build'
+
+export default createConfig({
+  components: ['./components'],
+  outDir: 'dist',
+})
+```
+
+The build emits Kolon `.tx` templates. The backend is just a plain
+`Text::Xslate` instance, so it runs under **any PSGI/Plack app** — no
+Mojolicious required:
+
+```perl
+use BarefootJS;
+use BarefootJS::Backend::Xslate;
+
+my $backend = BarefootJS::Backend::Xslate->new(path => ['dist/templates']);
+
+my $app = sub {
+    my $env = shift;
+    my $bf  = BarefootJS->new(undef, { backend => $backend });
+    $bf->_scope_id('Counter_' . int(rand(1e6)));
+    my $body = $backend->render_named('Counter', $bf, { count => 0 });
+    my $html = "<!doctype html><body>$body" . $bf->scripts . '</body>';
+    return [200, ['Content-Type' => 'text/html; charset=utf-8'], [$html]];
+};
+```
+
+The generated Kolon templates call the runtime as a `bf` object
+(`<: $bf.scope_attr() :>`, `<: $bf.json($data) :>`, …). Kolon auto-escapes
+`<: … :>` interpolations; helpers that emit markup return `mark_raw` values.
+
+## CPAN distributions
+
+The Perl side is packaged as standalone CPAN distributions (built with
+[Minilla](https://metacpan.org/pod/Minilla)), so a Perl app can depend on them
+without the JS toolchain at runtime:
+
+| Distribution | Main module | Depends on |
+|--------------|-------------|------------|
+| `BarefootJS` | `BarefootJS` | core Perl only |
+| `BarefootJS-Backend-Xslate` | `BarefootJS::Backend::Xslate` | `BarefootJS`, `Text::Xslate` |
+| `Mojolicious-Plugin-BarefootJS` | `Mojolicious::Plugin::BarefootJS` | `BarefootJS`, `Mojolicious` |
+
+## Dev auto-reload
+
+`barefoot build --watch` writes a sentinel after each rebuild; the browser can
+subscribe to a small SSE endpoint and reload automatically. The logic is
+framework-agnostic (`BarefootJS::DevReload`):
+
+- **Mojolicious:** `plugin 'BarefootJS::DevReload'`, then emit `%== bf_dev_snippet` before `</body>`.
+- **PSGI / Plack:** mount `BarefootJS::DevReload->to_app(dist_dir => 'dist')` at the SSE endpoint, and emit `BarefootJS::DevReload->snippet($endpoint)` in your layout. Run under a prefork server (Starman / Starlet) in dev.
+
+Both are no-ops in production.
+
+## Examples
+
+Runnable end-to-end apps that render the same shared components on a Perl
+backend live under
+[`integrations/`](https://github.com/piconic-ai/barefootjs/tree/main/integrations) —
+including SSR, fine-grained reactivity, a REST todo API, and SSE streaming.
+
+## See also
+
+- [Adapter Architecture](./adapter-architecture.md) — the `TemplateAdapter` interface and IR contract
+- [Backend Freedom](../core-concepts/backend-freedom.md) — why the same JSX runs on any stack
+- [Writing a Custom Adapter](./custom-adapter.md)

package/dist/docs/core/adapters.md

@@ -22,10 +22,15 @@ JSX Source
 |---------|--------|---------|---------|
 | [`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` |
 | [CSR](./adapters/csr.md) | — (client-rendered) | None (browser-only) | `@barefootjs/client` |
 
 > 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.
 
+The `GoTemplateAdapter` is web-framework-agnostic: its `html/template` output runs on any Go server. `npm create barefootjs@latest` ships scaffolds for Echo, Gin, Chi, and net/http (via `--adapter`) — see [Go Template Adapter → Server integration](./adapters/go-template-adapter.md#server-integration).
+
+The Perl adapters share one engine-agnostic runtime (`BarefootJS`): `@barefootjs/mojolicious` targets Mojolicious EP, and `@barefootjs/xslate` targets Text::Xslate (Kolon) and runs under any PSGI/Plack app. See the [Perl Adapter](./adapters/perl-adapter.md) page.
+
 ## Pages
 
 | Topic | Description |
@@ -33,5 +38,6 @@ JSX Source
 | [Adapter Architecture](./adapters/adapter-architecture.md) | How adapters work, the `TemplateAdapter` interface, and the IR contract |
 | [Hono Adapter](./adapters/hono-adapter.md) | Configuration and output format for Hono / JSX-based servers |
 | [Go Template Adapter](./adapters/go-template-adapter.md) | Configuration and output format for Go `html/template` |
+| [Perl Adapter](./adapters/perl-adapter.md) | Mojolicious and Text::Xslate (PSGI/Plack) backends, sharing one runtime |
 | [CSR](./adapters/csr.md) | Client-side rendering without a server-rendered template |
 | [Writing a Custom Adapter](./adapters/custom-adapter.md) | Step-by-step guide to implementing your own adapter |

package/dist/docs/core/llms.txt

@@ -44,6 +44,7 @@
 - [Writing a Custom Adapter](https://barefootjs.dev/docs/adapters/custom-adapter.md): Step-by-step guide to building a custom adapter using the TestAdapter as a reference.
 - [Go Template Adapter](https://barefootjs.dev/docs/adapters/go-template-adapter.md): Generate Go html/template files and type definitions from the compiler's IR.
 - [Hono Adapter](https://barefootjs.dev/docs/adapters/hono-adapter.md): Generate Hono JSX templates from the compiler's IR for Hono-based servers.
+- [Perl Adapter](https://barefootjs.dev/docs/adapters/perl-adapter.md): Render BarefootJS components from Perl — one engine-agnostic runtime with Mojolicious and Text::Xslate (PSGI/Plack) backends.
 
 ## Advanced
 

package/dist/docs/core/quick-start.mdx

@@ -152,10 +152,10 @@ This runs `bf build`, generates the final `uno.css`, and calls `wrangler deploy`
 - **[`createSignal`](./reactivity/create-signal.md)** and **[`createMemo`](./reactivity/create-memo.md)** — the reactivity primitives you just used.
 - **[Client Directive](./rendering/client-directive.md)** — exactly what `"use client"` does and when to reach for it.
 - **[Hono Adapter](./adapters/hono-adapter.md)** — adapter-specific configuration and output details.
-- Pick a different backend by passing `--adapter` to the scaffolder. Supported values today: `hono` (default — Cloudflare Workers), `hono-node`, `echo` (Go / Echo), `mojo` (Mojolicious / Perl), `csr` (no backend — pure client render). For example:
+- Pick a different backend by passing `--adapter` to the scaffolder. Supported values today: `hono` (default — Cloudflare Workers), `hono-node`, `echo` (Go / Echo), `gin` (Go / Gin), `chi` (Go / Chi), `nethttp` (Go / net/http stdlib), `mojo` (Mojolicious / Perl), `csr` (no backend — pure client render). For example:
 
   ```bash
   npm create barefootjs@latest -- --adapter hono-node
   ```
 
-  See [Adapter Architecture](./adapters/adapter-architecture.md) for the architectural overview, and the per-adapter pages under [`docs/core/adapters/`](./adapters/) for output details. The `@barefootjs/go-template` package is a compile-time adapter API for generating Go `html/template` files — it does not have a `bf init` scaffold; see [Go Template Adapter](./adapters/go-template-adapter.md) for the programmatic usage.
+  See [Adapter Architecture](./adapters/adapter-architecture.md) for the architectural overview, and the per-adapter pages under [`docs/core/adapters/`](./adapters/) for output details. The four Go scaffolds (`echo`, `gin`, `chi`, `nethttp`) all build on the `@barefootjs/go-template` adapter, which generates Go `html/template` files; see [Go Template Adapter](./adapters/go-template-adapter.md) for its programmatic API.