@barefootjs/cli 0.1.0

package/dist/docs/core/core-concepts/how-it-works.md

@@ -0,0 +1,147 @@
+---
+title: How It Works
+description: Two-phase compilation and hydration markers
+---
+
+# How It Works
+
+## Two-Phase Compilation
+
+One JSX source file produces two outputs:
+
+```
+JSX Source
+    ↓
+[Phase 1] Analyze + Transform → IR (Intermediate Representation)
+    ↓
+[Phase 2a] IR → Marked Template  (server)
+[Phase 2b] IR → Client JS        (browser)
+```
+
+**Phase 1** produces a JSON IR tree — component structure, reactive expressions, event handlers, type information. Backend-independent.
+
+**Phase 2** generates:
+
+- **Marked Template** — HTML with `bf-*` attributes marking interactive elements. The adapter determines the format.
+- **Client JS** — Creates signals, wires effects, binds event handlers to marked elements.
+
+### Counter Example
+
+Source:
+
+```tsx
+"use client"
+import { createSignal } from '@barefootjs/client'
+
+export function Counter() {
+  const [count, setCount] = createSignal(0)
+
+  return (
+    <button onClick={() => setCount(n => n + 1)}>
+      Count: {count()}
+    </button>
+  )
+}
+```
+
+The IR records:
+- Signal `count` with initial value `0`
+- Reactive text expression `count()` → slot `s0`
+- Click handler on button → slot `s1`
+
+Marked template (Phase 2a):
+
+<!-- tabs:adapter -->
+<!-- tab:Hono -->
+```tsx
+export function Counter({ __instanceId, ... }) {
+  const __scopeId = __instanceId || `Counter_${Math.random().toString(36).slice(2, 8)}`
+  const count = () => 0   // server-side stub
+
+  return (
+    <button bf-s={__scopeId} bf="s1">
+      Count: {bfText("s0")}{count()}{bfTextEnd()}
+    </button>
+  )
+}
+```
+<!-- tab:Go Template -->
+```go-template
+{{define "Counter"}}
+<button bf-s="{{bfScopeAttr .}}" bf="s1">
+  Count: {{bfTextStart "s0"}}{{.Count}}{{bfTextEnd}}
+</button>
+{{end}}
+```
+<!-- /tabs -->
+
+Client JS (Phase 2b):
+
+```js
+import { $, $t, createEffect, createSignal, hydrate } from '@barefootjs/client'
+
+export function initCounter(__scope, _p = {}) {
+  if (!__scope) return
+
+  const [count, setCount] = createSignal(0)
+
+  const [_s1] = $(__scope, 's1')       // element lookup
+  const [_s0] = $t(__scope, 's0')      // text node lookup
+
+  createEffect(() => {
+    const __val = count()
+    if (_s0) _s0.nodeValue = String(__val ?? '')
+  })
+
+  if (_s1) _s1.addEventListener('click', () => { setCount(n => n + 1) })
+}
+
+hydrate('Counter', {
+  init: initCounter,
+  template: (_p) => `<button bf="s1"> Count: <!--bf:s0-->${(0)}<!--/--></button>`
+})
+```
+
+See [Compiler Internals](../advanced/compiler-internals.md) and [IR Schema Reference](../advanced/ir-schema.md).
+
+## Hydration
+
+Marker-driven hydration attaches behavior to server-rendered HTML.
+
+### Markers
+
+`bf-*` attributes in the marked template tell client JS where to attach:
+
+| Marker | Purpose | Example |
+|--------|---------|---------|
+| `bf-s` | Component scope boundary (`~` = child) | `<div bf-s="Counter_a1b2">` |
+| `bf` | Interactive element (slot) | `<p bf="s0">` |
+| `bf-p` | Serialized props JSON | `<div bf-p='{"initial":5}'>` |
+| `bf-c` | Conditional block | `<div bf-c="s2">` |
+| `bf-po` | Portal owner scope ID | `<div bf-po="Dialog_a1b2">` |
+| `bf-pi` | Portal container ID | `<div bf-pi="bf-portal-1">` |
+| `bf-pp` | Portal placeholder | `<template bf-pp="bf-portal-1">` |
+| `bf-i` | List item marker | `<li bf-i>` |
+
+### Flow
+
+1. Server renders HTML with markers, embeds props in `bf-p`
+2. Browser loads client JS
+3. `hydrate()` finds uninitialized `bf-s` elements
+4. Init function runs per scope — signals, effects, handlers
+5. Runtime tracks scopes to prevent double initialization
+
+### Scoped Queries
+
+`$()` and `$t()` search within a scope, excluding child component scopes:
+
+```html
+<div bf-s="TodoApp_x1">
+  <h1 bf="s0">Todo</h1>
+  <div bf-s="~TodoItem_y1">
+    <span bf="s0">Buy milk</span>
+  </div>
+</div>
+```
+
+`$(__scope, 's0')` in TodoApp finds `<h1>`, not the `<span>` inside TodoItem. The `~` prefix marks a child scope excluded from parent queries.

package/dist/docs/core/core-concepts/mpa-style.md

@@ -0,0 +1,36 @@
+---
+title: MPA-style Development
+description: Server-rendering by default, with client JavaScript only where you need it
+---
+
+# MPA-style Development
+
+Add interactive components to server-rendered pages without changing your architecture.
+
+Existing options require trade-offs:
+
+- **jQuery / vanilla JS** — No component model. Hard to maintain at scale.
+- **SPA framework (Next.js, Nuxt)** — Even with server components, you adopt the framework's build pipeline, routing, and deployment model.
+- **Islands (Astro, Fresh)** — Server rendering with selective hydration, but your server must be Astro or Fresh.
+
+BarefootJS outputs templates for your existing server. The compiler is a build step — your routing and deployment don't change. `"use client"` marks the components that need interactivity; only those ship JavaScript:
+
+```tsx
+// ProductPage.tsx — server component
+import { AddToCart } from './AddToCart'    // "use client"
+import { ReviewStars } from './ReviewStars' // "use client"
+
+export function ProductPage({ product }) {
+  return (
+    <div>
+      <h1>{product.name}</h1>
+      <p>{product.description}</p>
+      <img src={product.image} />
+      <ReviewStars rating={product.rating} />
+      <AddToCart productId={product.id} />
+    </div>
+  )
+}
+```
+
+`h1`, `p`, `img` produce zero JS. Only `ReviewStars` and `AddToCart` ship client JavaScript. Server-rendered HTML is visible immediately; interactive components become functional after hydration.

package/dist/docs/core/core-concepts/reactivity.md

@@ -0,0 +1,35 @@
+---
+title: Fine-grained Reactivity
+description: Signal-based reactivity — no virtual DOM, updates at the DOM node level
+---
+
+# Fine-grained Reactivity
+
+The compiler analyzes which DOM nodes depend on which signals and generates code that connects them at hydration. When state changes, only that DOM node updates — no virtual DOM, no component re-render.
+
+Inspired by [SolidJS](https://www.solidjs.com/). The key difference from React: **components run once**, not on every state change.
+
+## Signals, Effects, Memos
+
+```tsx
+const [count, setCount] = createSignal(0)     // reactive value
+const doubled = createMemo(() => count() * 2)  // cached derived value
+
+createEffect(() => {
+  console.log('Count is:', count())            // re-runs when count changes
+})
+
+setCount(1)  // triggers the effect, recomputes doubled
+```
+
+The getter is a function call — `count()`, not `count`. The runtime tracks which signals each effect reads. No dependency arrays.
+
+## How Updates Reach the DOM
+
+```
+setCount(1) → signal notifies subscribers → effect updates the DOM node
+```
+
+The compiler analyzed which DOM node depends on `count` and generated an effect that updates it directly. No tree diffing at runtime.
+
+For the full API, see [Reactivity](../reactivity.md).

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

@@ -0,0 +1,28 @@
+---
+title: Core Concepts
+description: The four design principles and a technical overview of how BarefootJS works
+---
+
+# Core Concepts
+
+BarefootJS compiles JSX into server templates and minimal client JS for any backend. No SPA framework, no Node.js lock-in.
+
+## Backend Freedom
+
+Server rendering with JSX usually means running Node.js. BarefootJS compiles JSX to native templates for Hono, Go `html/template`, or any custom adapter — no Node.js at serving time.
+
+## MPA-style Development
+
+Components render to static HTML by default. `"use client"` marks those that need interactivity — only they ship JavaScript. Your routing, data fetching, and templates don't change.
+
+## Fine-grained Reactivity
+
+The compiler analyzes which DOM nodes depend on which signals and generates code that connects them. When state changes, only the affected node updates — no virtual DOM, no component re-render.
+
+## AI-native Development
+
+`renderToTest()` verifies component structure, signals, and accessibility against the compiler's IR in milliseconds. E2E tests are still needed for real interactions, but structural issues are caught fast. The `bf` CLI provides discovery, scaffolding, and debugging for humans and AI agents.
+
+## How It Works
+
+Two-phase compilation and hydration markers — a technical deep-dive.

package/dist/docs/core/introduction.md

@@ -0,0 +1,87 @@
+---
+title: Introduction
+description: What is BarefootJS — JSX to server template + client JS compiler
+---
+
+# Introduction
+
+## What is BarefootJS?
+
+BarefootJS is a compiler that transforms JSX components into server-rendered templates and minimal client-side JavaScript.
+
+Write familiar JSX with fine-grained reactivity — the compiler splits it into a **marked template** for your backend and a **tiny hydration script** for the browser.
+
+```tsx
+"use client"
+import { createSignal } from '@barefootjs/client'
+
+export function Counter() {
+  const [count, setCount] = createSignal(0)
+
+  return (
+    <button onClick={() => setCount(n => n + 1)}>
+      Count: {count()}
+    </button>
+  )
+}
+```
+
+This single file compiles into two outputs:
+
+<!-- tabs:adapter -->
+<!-- tab:Hono -->
+**Marked template** — Renders static HTML with hydration markers:
+
+```tsx
+export function Counter({ __instanceId, ... }) {
+  const __scopeId = __instanceId || `Counter_${Math.random().toString(36).slice(2, 8)}`
+  const count = () => 0
+
+  return (
+    <button bf-s={__scopeId} bf="s1">
+      Count: {bfText("s0")}{count()}{bfTextEnd()}
+    </button>
+  )
+}
+```
+
+<!-- tab:Go Template -->
+**Marked template** — Go `html/template` with hydration markers:
+
+```go-template
+{{define "Counter"}}
+<button bf-s="{{bfScopeAttr .}}" bf="s1">
+  Count: {{bfTextStart "s0"}}{{.Count}}{{bfTextEnd}}
+</button>
+{{end}}
+```
+
+<!-- /tabs -->
+
+**Client script** — Wires up only the interactive parts:
+
+```js
+import { $, $t, createEffect, createSignal, hydrate } from '@barefootjs/client'
+
+export function initCounter(__scope, _p = {}) {
+  if (!__scope) return
+
+  const [count, setCount] = createSignal(0)
+
+  const [_s1] = $(__scope, 's1')       // find element with bf="s1"
+  const [_s0] = $t(__scope, 's0')      // find text node at <!--bf:s0-->
+
+  createEffect(() => {
+    const __val = count()
+    if (_s0) _s0.nodeValue = String(__val ?? '')
+  })
+
+  if (_s1) _s1.addEventListener('click', () => { setCount(n => n + 1) })
+}
+
+hydrate('Counter', {
+  init: initCounter,
+  template: (_p) => `<button bf="s1"> Count: <!--bf:s0-->${(0)}<!--/--></button>`
+})
+```
+

package/dist/docs/core/llms.txt

@@ -0,0 +1,53 @@
+# BarefootJS
+
+> JSX -> Marked Template + client JS compiler. Signal-based reactivity for any backend.
+
+## Core Concepts
+
+- [AI-native Development](https://barefootjs.dev/docs/core-concepts/ai-native.md): Millisecond IR tests and the bf CLI for human + agent workflows
+- [Backend Freedom](https://barefootjs.dev/docs/core-concepts/backend-freedom.md): How adapters let the same JSX run on any server — Hono, Go, and beyond
+- [How It Works](https://barefootjs.dev/docs/core-concepts/how-it-works.md): Two-phase compilation and hydration markers
+- [MPA-style Development](https://barefootjs.dev/docs/core-concepts/mpa-style.md): Server-rendering by default, with client JavaScript only where you need it
+- [Fine-grained Reactivity](https://barefootjs.dev/docs/core-concepts/reactivity.md): Signal-based reactivity — no virtual DOM, updates at the DOM node level
+
+## Reactivity
+
+- [createEffect](https://barefootjs.dev/docs/reactivity/create-effect.md): Runs a function and re-runs it whenever its tracked signal dependencies change.
+- [createMemo](https://barefootjs.dev/docs/reactivity/create-memo.md): Creates a cached derived value that recomputes only when its dependencies change.
+- [createSignal](https://barefootjs.dev/docs/reactivity/create-signal.md): Creates a reactive getter/setter pair for managing state.
+- [onCleanup](https://barefootjs.dev/docs/reactivity/on-cleanup.md): Registers a cleanup function that runs when the owning effect re-runs or the component is destroyed.
+- [onMount](https://barefootjs.dev/docs/reactivity/on-mount.md): Runs a callback once when the component initializes, without tracking signal dependencies.
+- [Props Reactivity](https://barefootjs.dev/docs/reactivity/props-reactivity.md): How prop access patterns determine whether reactive updates propagate in BarefootJS components.
+- [untrack](https://barefootjs.dev/docs/reactivity/untrack.md): Executes a function without tracking signal dependencies in the current reactive context.
+
+## Rendering
+
+- [/* @client */ Directive](https://barefootjs.dev/docs/rendering/client-directive.md): Mark JSX expressions for client-only evaluation when the compiler cannot translate them to server templates.
+- [Fragment](https://barefootjs.dev/docs/rendering/fragment.md): Using fragments to render children without a wrapper element, including transparent fragment behavior.
+- [JSX Compatibility](https://barefootjs.dev/docs/rendering/jsx-compatibility.md): Standard JSX syntax support in BarefootJS, including control flow and common patterns from React and SolidJS.
+
+## Components
+
+- [Children & Slots](https://barefootjs.dev/docs/components/children-slots.md): Accept nested JSX content via the children prop and enable polymorphic rendering with the Slot component.
+- [Component Authoring](https://barefootjs.dev/docs/components/component-authoring.md): Learn how to write server and client components in BarefootJS using JSX functions.
+- [Context API](https://barefootjs.dev/docs/components/context-api.md): Share state with deeply nested children without prop drilling using createContext and useContext.
+- [Portals](https://barefootjs.dev/docs/components/portals.md): Render elements outside their parent DOM hierarchy for overlays, modals, and tooltips.
+- [Props & Type Safety](https://barefootjs.dev/docs/components/props-type-safety.md): Type component props with TypeScript interfaces and preserve type information through compilation.
+- [Style Overrides](https://barefootjs.dev/docs/components/styling.md): How user-supplied classes override component base classes via CSS Cascade Layers
+
+## Adapters
+
+- [Adapter Architecture](https://barefootjs.dev/docs/adapters/adapter-architecture.md): How adapters convert the compiler's IR into server-renderable template formats.
+- [CSR (Client-Side Rendering)](https://barefootjs.dev/docs/adapters/csr.md): Render BarefootJS components directly in the browser without a server-rendered template.
+- [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.
+
+## Advanced
+
+- [Vendor code-splitting](https://barefootjs.dev/docs/advanced/code-splitting.md): Split large vendor libraries into separately-cached browser chunks via barefoot.config.ts externals
+- [Compiler Internals](https://barefootjs.dev/docs/advanced/compiler-internals.md): How the BarefootJS compiler transforms JSX into marked templates and client JavaScript.
+- [Error Codes Reference](https://barefootjs.dev/docs/advanced/error-codes.md): BF-prefixed compiler error codes with explanations and fixes.
+- [IR Schema Reference](https://barefootjs.dev/docs/advanced/ir-schema.md): JSON tree structure of the Intermediate Representation consumed by adapters and client-JS generation.
+- [Performance Optimization](https://barefootjs.dev/docs/advanced/performance.md): Strategies to minimize bundle size, reduce hydration cost, and optimize runtime reactivity
+- [xyflow browser bundle](https://barefootjs.dev/docs/advanced/xyflow-browser-bundle.md): How to serve @barefootjs/xyflow as a pre-built browser chunk via an importmap

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

@@ -0,0 +1,160 @@
+---
+title: Quick Start
+description: Scaffold a BarefootJS app in under five minutes — Counter component, dev server, deploy.
+---
+
+# Quick Start
+
+Scaffold a BarefootJS app, run it locally, and tour the generated project. About five minutes.
+
+## Prerequisites
+
+- **Node.js 22+** (or Bun).
+- The default scaffold targets [Cloudflare Workers](https://developers.cloudflare.com/workers/) via `wrangler dev` — runs locally, no account needed.
+
+## 1. Scaffold the project
+
+<PackageManagerTabs command="barefootjs@latest" mode="create" />
+
+Press Enter at the prompts to accept the defaults (Hono on Cloudflare Workers, UnoCSS).
+
+## 2. Install and run
+
+```bash
+cd my-app
+npm install
+npm run dev
+```
+
+`npm run dev` runs three processes in parallel:
+
+- `bf build --watch` — the BarefootJS compiler. Watches `components/` and emits marked templates plus client JS to `public/components/`.
+- `unocss --watch` — scans your JSX for utility classes and writes `public/uno.css`.
+- `wrangler dev --live-reload` — Cloudflare's local Workers runtime. Serves the app and reloads the browser on rebuilds.
+
+Open the URL Wrangler prints. You should see a counter card with **+1**, **-1**, and **Reset** buttons.
+
+## 3. Look at what was generated
+
+```
+my-app/
+├── server.tsx              # Hono routes — entry point
+├── renderer.tsx            # HTML shell (<head>, <body>, BfScripts)
+├── components/
+│   └── Counter.tsx         # The starter component
+├── components/ui/
+│   └── button/             # Pulled from the BarefootJS UI registry
+├── public/                 # Static assets served by Workers
+│   ├── tokens.css          # CSS design tokens
+│   ├── styles.css          # Counter + page styles
+│   └── components/         # Generated client JS (bf build writes here)
+├── barefoot.config.ts      # Compiler + paths config
+├── wrangler.jsonc          # Cloudflare Workers config
+└── uno.config.ts           # UnoCSS scan patterns
+```
+
+Open `components/Counter.tsx`:
+
+```tsx
+'use client'
+
+import { createSignal, createMemo } from '@barefootjs/client'
+import { Button } from '@/components/ui/button'
+
+interface CounterProps {
+  initial?: number
+}
+
+export function Counter(props: CounterProps) {
+  const [count, setCount] = createSignal(props.initial ?? 0)
+  const doubled = createMemo(() => count() * 2)
+
+  return (
+    <div className="counter">
+      <p className="counter-value">count: {count()}</p>
+      <p className="counter-doubled">doubled: {doubled()}</p>
+      <div className="counter-buttons">
+        <Button onClick={() => setCount(n => n + 1)}>+1</Button>
+        <Button onClick={() => setCount(n => n - 1)} variant="secondary">-1</Button>
+        <Button onClick={() => setCount(0)} variant="ghost">Reset</Button>
+      </div>
+    </div>
+  )
+}
+```
+
+See [Client Directive](./rendering/client-directive.md), [`createSignal`](./reactivity/create-signal.md), and [`createMemo`](./reactivity/create-memo.md) for what each piece does. Props are read via `props.initial`, not destructured — destructuring captures the value once and breaks reactivity, so the compiler emits warning [`BF043`](./advanced/error-codes.md) when it sees that form on a `"use client"` component. [Props Reactivity](./reactivity/props-reactivity.md) covers the full rule.
+
+The Counter is mounted in `server.tsx`:
+
+```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: 'BarefootJS app' },
+  ),
+)
+
+export default app
+```
+
+Same `Counter` import, two outputs: server renders HTML, client hydrates the buttons.
+
+## 4. Make a change
+
+With `npm run dev` still running, pass an initial value from the server. In `server.tsx`:
+
+```tsx
+app.get('/', (c) =>
+  c.render(
+    <main>
+      <Counter initial={5} />
+    </main>,
+    { title: 'BarefootJS app' },
+  ),
+)
+```
+
+Save. The browser reloads and the counter starts at **5**. The server rendered `5` into the HTML, and hydration picked it up on the client — the same JSX, evaluated in both places.
+
+Now add a new button to `Counter.tsx`:
+
+```tsx
+<Button onClick={() => setCount(n => n * 2)} variant="ghost">×2</Button>
+```
+
+Save and watch the browser update. No virtual DOM, no diff — the compiler generated an effect that updates only the `<p>` text node when `count` changes.
+
+## 5. Deploy (optional)
+
+When you're ready to ship:
+
+```bash
+npm run deploy
+```
+
+This runs `bf build`, generates the final `uno.css`, and calls `wrangler deploy`. The first deploy will prompt you to log into Cloudflare. After that, your app is live on `*.workers.dev`.
+
+## Next steps
+
+- **[Core Concepts](./core-concepts.md)** — the four design principles behind BarefootJS: backend freedom, MPA-style rendering, fine-grained reactivity, and AI-native workflows.
+- **[`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:
+
+  ```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.

package/dist/docs/core/reactivity/create-effect.md

@@ -0,0 +1,125 @@
+---
+title: createEffect
+description: Runs a function and re-runs it whenever its tracked signal dependencies change.
+---
+
+# createEffect
+
+Runs a function immediately and re-runs it whenever any signal read inside it changes.
+
+```tsx
+import { createEffect } from '@barefootjs/client'
+
+createEffect(fn: () => void | (() => void)): void
+```
+
+
+## Basic Usage
+
+```tsx
+const [count, setCount] = createSignal(0)
+
+createEffect(() => {
+  document.title = `Count: ${count()}`
+})
+
+setCount(1) // Effect re-runs, title becomes "Count: 1"
+```
+
+Dependencies are tracked automatically. No dependency array is needed.
+
+
+## Conditional Dependencies
+
+Dependencies change per run. If a branch skips a signal read, that signal is not tracked for that run:
+
+```tsx
+const [showName, setShowName] = createSignal(true)
+const [name, setName] = createSignal('Alice')
+const [count, setCount] = createSignal(0)
+
+createEffect(() => {
+  if (showName()) {
+    console.log(name())  // name is tracked
+  } else {
+    console.log(count()) // count is tracked instead
+  }
+})
+```
+
+
+## Cleanup
+
+Two ways to register cleanup for resources that need teardown before re-run.
+
+### Return a function
+
+```tsx
+createEffect(() => {
+  const timer = setInterval(() => console.log('tick'), 1000)
+  return () => clearInterval(timer)
+})
+```
+
+### `onCleanup`
+
+```tsx
+createEffect(() => {
+  const timer = setInterval(() => console.log('tick'), 1000)
+  onCleanup(() => clearInterval(timer))
+})
+```
+
+`onCleanup` can be called multiple times. Cleanups run in reverse order (last registered, first called). See [`onCleanup`](./on-cleanup.md) for details.
+
+
+## Common Patterns
+
+### localStorage sync
+
+```tsx
+const [theme, setTheme] = createSignal('light')
+
+createEffect(() => {
+  localStorage.setItem('theme', theme())
+})
+```
+
+### Data fetching
+
+```tsx
+const [query, setQuery] = createSignal('')
+
+createEffect(() => {
+  const q = query()
+  if (!q) return
+
+  const controller = new AbortController()
+  fetch(`/api/search?q=${q}`, { signal: controller.signal })
+    .then(r => r.json())
+    .then(setResults)
+
+  onCleanup(() => controller.abort())
+})
+```
+
+When `query` changes, the previous fetch is aborted before the new one starts.
+
+### Reactive attributes
+
+The compiler generates effects for reactive attributes.
+
+Source:
+
+```tsx
+<button disabled={loading()}>Submit</button>
+```
+
+Generated client JS:
+
+```js
+const [_s0] = $(__scope, 's0')
+createEffect(() => {
+  if (_s0) { _s0.disabled = !!(loading()) }
+})
+```