BarefootJS Documentation

#Table of Contents

#1. [Introduction](./introduction.md)

• What is BarefootJS?
• Why BarefootJS?
• Design Philosophy

#2. Getting Started

• Installation
• Quick Start (5-minute tutorial)
• Project Structure

#3. [Core Concepts](./core-concepts.md)

• Two-Phase Compilation
• Signal-Based Reactivity
• Hydration Model
• The "use client" Directive

#4. [Reactivity](./reactivity.md)

• createSignal — Create a reactive value
• createEffect — Run side effects when dependencies change
• createMemo — Create a cached derived value
• onMount — Run once on component initialization
• onCleanup — Register cleanup for effects and lifecycle
• untrack — Read signals without tracking dependencies
• Props Reactivity — Gotchas with destructuring

#5. [Templates & Rendering](./rendering.md)

• JSX Compatibility — What works, what doesn't, and what differs
• Fragment — Fragment support and hydration behavior
• /* @client */ Directive — Skip server evaluation for client-only expressions

#6. [Components](./components.md)

• Component Authoring — Server components, client components, and the compilation model
• Props & Type Safety — Typing props, defaults, and rest spreading
• Children & Slots — Children prop, the Slot component, and the asChild pattern
• Context API — Sharing state with createContext / useContext
• Portals — Rendering elements outside their parent DOM hierarchy

#7. [Adapters](./adapters.md)

• Adapter Architecture — How adapters work, the TemplateAdapter interface, and the IR contract
• Hono Adapter — Configuration and output format for Hono / JSX-based servers
• Go Template Adapter — Configuration and output format for Go html/template
• Writing a Custom Adapter — Step-by-step guide to implementing your own adapter

#8. [Advanced](./advanced.md)

• IR Schema Reference — Node types, metadata, hydration markers
• Compiler Internals — Pipeline phases, reactivity analysis, code generation
• Error Codes Reference — All BF001–BF043 errors with solutions
• Performance Optimization — Minimal client JS, fast hydration, efficient reactivity

---

#Documentation Conventions

Throughout this documentation, code examples use switchable tabs for the following:

Adapter — Examples show output for your selected adapter:

• Hono (default)
• Go Template

Package Manager — Install commands match your toolchain:

• npm (default)
• bun
• pnpm
• yarn

These preferences persist across pages.

Note for non-JavaScript developers: Sections marked with 💡 provide brief explanations of JSX and TypeScript concepts for developers coming from Go, Python, or other backend languages.