# Foldkit

> Foldkit is a TypeScript frontend framework built on Effect-TS that uses The Elm Architecture: a single Model, pure update, and side effects confined to Commands.

This index lists every page on the Foldkit documentation site with a short description. Every page is also available as Markdown by appending `.md` to its URL (e.g. https://foldkit.dev/get-started/getting-started.md). A single-file concatenation of every page is available at https://foldkit.dev/llms-full.txt.

## Docs

- [Coming from React](https://foldkit.dev/react/coming-from-react): Moving from React to a principled architecture? Foldkit replaces hooks, useEffect, and component state with The Elm Architecture: one Model, one update function, explicit effects. Built on Effect-TS.
- [Coming from TanStack Query](https://foldkit.dev/react/coming-from-tanstack-query): Coming from TanStack Query? Foldkit has no useQuery. Caching, background refetch, deduplication, and out-of-order response handling are not features here, they are ordinary Model state and a pure update function. Includes the latest-request-wins pattern for response races.
- [Example Apps](https://foldkit.dev/example-apps): Working Foldkit example apps: counter, forms, routing, auth, websocket chat, and more. Each demonstrates Effect-TS and Elm Architecture patterns.
- [Field Validation](https://foldkit.dev/core/field-validation): Per-field form validation in Foldkit using a four-state discriminated union. Built-in validation rules, Effect-TS powered, no impossible states.
- [Getting Started](https://foldkit.dev/get-started/getting-started): Set up your first Foldkit application in minutes. Install, scaffold with create-foldkit-app, and build a TypeScript frontend with Effect-TS.
- [Manifesto](https://foldkit.dev/get-started/manifesto): Why Foldkit exists and the principles behind its design.
- [Project Organization](https://foldkit.dev/patterns/project-organization): How to structure a Foldkit project for maintainability.
- [Roadmap](https://foldkit.dev/roadmap): Where Foldkit is headed: the blocks of work that gate a production-ready 1.0, the directions under exploration after it, and the stances that will not change.
- [Routing and Navigation](https://foldkit.dev/core/routing-and-navigation): Type-safe routing with bidirectional parser combinators in Foldkit. URLs parse into typed routes and build back. No string matching, built on Effect-TS.
- [Testing](https://foldkit.dev/testing): Test Foldkit programs with Story and Scene. Story simulates the update loop. Scene tests features through the rendered view with accessible locators.

## Guides

- [Foldkit vs Elm: Side by Side](https://foldkit.dev/elm/foldkit-vs-elm-side-by-side): A side-by-side comparison of the same pixel art editor built in both Foldkit and Elm. Same architecture, different host: ports vs Commands, decoders vs Schema, and what each side gives up.
- [Foldkit vs React: Side by Side](https://foldkit.dev/react/foldkit-vs-react-side-by-side): A side-by-side comparison of the same pixel art editor built in both Foldkit and React. Covers state management, side effects, testing, performance, and architectural tradeoffs.

## Core Concepts

- [Architecture](https://foldkit.dev/core/architecture): How Foldkit implements The Elm Architecture (TEA) with Effect-TS: Model, update, view, Commands, and Subscriptions.
- [Canvas](https://foldkit.dev/core/canvas): Declarative 2D rendering with a Schema-defined Shape AST and pointer events translated to canvas-local coordinates.
- [Commands](https://foldkit.dev/core/commands): Model side effects as values returned from update. Commands replace useEffect with explicit, testable Effect-TS operations.
- [Counter Example](https://foldkit.dev/core/counter-example): A minimal Foldkit application explained step by step.
- [Crash View](https://foldkit.dev/core/crash-view): A fallback UI and crash reporting for unrecoverable runtime errors.
- [CustomElement](https://foldkit.dev/core/custom-element): Bind native web components to Foldkit with CustomElement.define. Declare properties and events with Schema once and get a typed builder back.
- [DevTools](https://foldkit.dev/core/devtools): A built-in overlay for inspecting Messages and Model state.
- [Dom](https://foldkit.dev/core/dom): Effects for common DOM operations like focus, scroll, dialog open/close, scroll lock, and inert isolation.
- [Embedding](https://foldkit.dev/core/embedding): Run a Foldkit app inside a host application with a typed lifecycle handle and Ports.
- [File](https://foldkit.dev/core/file): Read and select files from the browser using an opaque File type and event attributes for inputs and drop zones.
- [Freeze Model](https://foldkit.dev/core/freeze-model): Catch accidental Model mutations at the write site in development.
- [Init & Flags](https://foldkit.dev/core/init-and-flags): Set up the initial Model, pass external data via flags, and run startup Commands.
- [Managed Resources](https://foldkit.dev/core/managed-resources): Resources that activate and release based on Model state.
- [Messages](https://foldkit.dev/core/messages): Type-safe events that drive state changes in Foldkit. Messages replace React event handlers with a declarative, traceable pattern.
- [Model](https://foldkit.dev/core/model): Define your entire application state as a single Effect-TS Schema. Learn how Foldkit's Model replaces useState, Redux, and Zustand.
- [Mount](https://foldkit.dev/core/mount): OnMount: the single mount-time DOM hook for integrating third-party libraries with paired cleanup. Keeps imperative work confined to the seam where the virtual DOM meets the real one.
- [Render](https://foldkit.dev/core/render): Primitives for synchronizing with the browser render cycle so DOM reads and CSS transitions land on the right frame.
- [Resources](https://foldkit.dev/core/resources): Long-lived browser singletons shared across Commands.
- [Runtime](https://foldkit.dev/core/runtime): Mount and run a Foldkit application in the browser.
- [Slow View](https://foldkit.dev/core/slow-view): Performance monitoring for view render times.
- [Submodel](https://foldkit.dev/core/submodel): Compose applications from independent, encapsulated modules.
- [Subscriptions](https://foldkit.dev/core/subscriptions): Declarative streams that start and stop based on Model state, with built-in helpers like Subscription.animationFrame for requestAnimationFrame-driven motion. Foldkit Subscriptions replace useEffect cleanup patterns with automatic lifecycle management.
- [Update](https://foldkit.dev/core/update): Pure functions that transform the Model and return Commands in response to Messages. Foldkit's update replaces useReducer and useEffect with a single, exhaustive pattern match.
- [View](https://foldkit.dev/core/view): Render your UI as a pure function of the Model. Foldkit views are plain TypeScript functions. No JSX, no hooks, no component lifecycle.
- [View Memoization](https://foldkit.dev/core/view-memoization): Optimize rendering performance with memoized views.

## Best Practices

- [Immutability](https://foldkit.dev/best-practices/immutability): Immutable model updates with evo for predictable state transitions.
- [Keying](https://foldkit.dev/best-practices/keying): Key branch points to prevent stale DOM when views switch between different trees.
- [Messages](https://foldkit.dev/best-practices/messages): Name messages as past-tense events, not imperative commands.
- [Side Effects & Purity](https://foldkit.dev/best-practices/side-effects-and-purity): Why Foldkit programs should have zero side effects outside of Commands.

## Patterns

- [Informing Submodels](https://foldkit.dev/patterns/informing-submodels): Relay a change a Submodel does not own (a URL, a server push, an auth change) through a helper it exposes, so it can update its own state in response.
- [Subscription Organization](https://foldkit.dev/patterns/subscription-organization): Canonical layout for subscription wiring across nested submodels.

## FAQ

- [Performance](https://foldkit.dev/faq/performance): How Foldkit performs and why: the rendering cost model, TodoMVC benchmark numbers against React, Elm, Svelte, Solid, and Lustre, what development mode costs that production does not, and the optimization toolkit.
- [What about SSR?](https://foldkit.dev/faq/what-about-ssr): Foldkit is client-first by design. What server rendering actually buys you, the kind of app Foldkit is for, the tradeoff, and how the Foldkit website pre-renders every route at build time using the runtime in headless Chromium.
- [Why no JSX?](https://foldkit.dev/faq/why-no-jsx): Why Foldkit uses a typed function-call DSL instead of JSX, with side-by-side comparisons of buttons, inputs, and conditional rendering.

## Foldkit UI

- [Animation](https://foldkit.dev/ui/animation): Coordinates CSS enter/leave animations via a state machine and data attributes. Works with both CSS transitions and keyframe animations.
- [Button](https://foldkit.dev/ui/button): A thin wrapper around the native button with accessibility attributes and styling hooks.
- [Calendar](https://foldkit.dev/ui/calendar): Accessible inline calendar grid with 2D keyboard navigation, locale-aware headers, and min/max/disabled-date constraints.
- [Checkbox](https://foldkit.dev/ui/checkbox): Accessible checkbox with indeterminate state support.
- [Combobox](https://foldkit.dev/ui/combobox): Accessible autocomplete input with filtering and selection.
- [Date Picker](https://foldkit.dev/ui/date-picker): Accessible date picker that wraps Calendar in a Popover. Focus choreography, click-outside dismissal, and hidden form input for native form submission.
- [Dialog](https://foldkit.dev/ui/dialog): A modal dialog backed by the native dialog element with focus trapping and scroll locking.
- [Disclosure](https://foldkit.dev/ui/disclosure): An accessible show/hide foundation for toggleable content sections.
- [Drag and Drop](https://foldkit.dev/ui/drag-and-drop): Accessible drag and drop with keyboard support, auto-scrolling, and screen reader announcements.
- [Fieldset](https://foldkit.dev/ui/fieldset): Group related form fields with accessible labeling.
- [File Drop](https://foldkit.dev/ui/file-drop): Headless file drop zone that accepts drag-and-drop plus click-to-browse via a hidden native file input.
- [Foldkit UI](https://foldkit.dev/ui/overview): Headless, accessible UI components for Foldkit: dialog, menu, tabs, listbox, and more. Built for The Elm Architecture with Effect-TS.
- [Input](https://foldkit.dev/ui/input): A thin wrapper around the native input with ARIA linking and styling hooks.
- [Listbox](https://foldkit.dev/ui/listbox): Accessible list selection with single and multi-select modes.
- [Menu](https://foldkit.dev/ui/menu): Accessible dropdown menu with keyboard navigation.
- [Popover](https://foldkit.dev/ui/popover): Floating content panels anchored to trigger elements.
- [Radio Group](https://foldkit.dev/ui/radio-group): Accessible radio button group with keyboard navigation.
- [Select](https://foldkit.dev/ui/select): A thin wrapper around the native select with ARIA linking and styling hooks.
- [Selection Submodels](https://foldkit.dev/ui/selection-submodels): How Foldkit UI components expose create<Item>() factories that pair view and update behind one type parameter so Item types cannot drift between the rendered list and the selection handler.
- [Slider](https://foldkit.dev/ui/slider): Accessible slider for numeric range input. Pointer drag, keyboard navigation, ARIA slider semantics.
- [Switch](https://foldkit.dev/ui/switch): Accessible toggle switch for boolean settings.
- [Tabs](https://foldkit.dev/ui/tabs): Accessible tabbed interface with keyboard navigation.
- [Textarea](https://foldkit.dev/ui/textarea): A thin wrapper around the native textarea with ARIA linking and styling hooks.
- [Toast](https://foldkit.dev/ui/toast): Stack of transient notifications anchored to a corner of the viewport with per-entry enter/leave animations and auto-dismiss.
- [Tooltip](https://foldkit.dev/ui/tooltip): Non-interactive floating label that appears on hover or focus and hides on leave, blur, or Escape.
- [Virtual List](https://foldkit.dev/ui/virtual-list): Virtualization primitive for large lists. Only items inside the viewport plus an overscan buffer are mounted; spacers above and below keep the scrollbar physically correct.

## Testing

- [Scene](https://foldkit.dev/testing/scene): Test features through the rendered view with Scene. Click buttons, type into inputs, and assert on the HTML using accessible locators.
- [Story](https://foldkit.dev/testing/story): Test the state machine with Story. Send Messages, resolve Commands inline, and assert on the Model. Pure, deterministic, fast.

## Examples

- [API Cache](https://foldkit.dev/example-apps/api-cache): Query caching without a query client. Demonstrates stale-while-revalidate, request deduplication, invalidation, and interval refetching.
- [Auth](https://foldkit.dev/example-apps/auth): Authentication flow with Submodels, OutMessage, protected routes, and session management.
- [Canvas Art](https://foldkit.dev/example-apps/canvas-art): Click the canvas to spawn bouncing balls. Demonstrates declarative 2D rendering with Canvas.view, animation-frame Subscriptions, and pointer events translated to canvas-local coordinates.
- [Counter](https://foldkit.dev/example-apps/counter): The classic counter example. Increment, decrement, and reset a number.
- [Counters](https://foldkit.dev/example-apps/counters): A dynamic list of Counter Submodels. Add and remove rows; each row is an independent Submodel embedded via h.submodel, with per-instance routing via a wrapper Message.
- [Crash View](https://foldkit.dev/example-apps/crash-view): Custom crash fallback UI. Demonstrates crash.view and crash.report with a crash button and reload.
- [Embedding](https://foldkit.dev/example-apps/embedding): A Foldkit widget embedded in a plain TypeScript host page through Runtime.embed. The host seeds initial state with Flags, pushes a step value in through an inbound Port, mirrors the count the widget emits through an outbound Port, and mounts and unmounts the widget with dispose. All communication crosses one Schema-typed handle; the host never touches the Model.
- [Form](https://foldkit.dev/example-apps/form): Form handling with field validation, error states, and async submission.
- [Generative Art](https://foldkit.dev/example-apps/generative-art): Move the mouse to stir a Perlin-noise flow field, click to bloom prismatic particle bursts. Demonstrates Canvas.view with hundreds of evolving Path strokes per frame, Effect Random for spawning, and tunable simulation knobs wired through Messages.
- [Job Application](https://foldkit.dev/example-apps/job-application): Multi-step form with async email validation, cross-field date constraints, file uploads, and per-step error indicators.
- [Kanban](https://foldkit.dev/example-apps/kanban): Drag-and-drop kanban board with cross-column reordering, keyboard navigation, fractional indexing, and screen reader announcements.
- [Map](https://foldkit.dev/example-apps/map): Interactive MapLibre GL map with locations, search, and "find my location". Demonstrates OnMount integration with a third-party DOM library, plus a Subscription bridging map move and marker click events back to the Model.
- [Pixel Art](https://foldkit.dev/example-apps/pixel-art): Pixel art editor showcasing undo/redo with immutable snapshots, time-travel history, UI components (RadioGroup, Switch, Listbox, Dialog, Button), createLazy view optimization, Subscriptions, Commands with error handling, and localStorage persistence via Flags.
- [Query Sync](https://foldkit.dev/example-apps/query-sync): Filterable dinosaur table where every control syncs to URL query parameters. Schema transforms enforce valid states. Invalid params gracefully fall back.
- [Routing](https://foldkit.dev/example-apps/routing): Client-side routing with URL parameters, nested routes, rest segments, and navigation.
- [Shopping Cart](https://foldkit.dev/example-apps/shopping-cart): E-commerce app with product listing, cart management, and checkout flow.
- [Snake](https://foldkit.dev/example-apps/snake): The classic snake game. Keyboard input, game loop, and collision detection.
- [Stopwatch](https://foldkit.dev/example-apps/stopwatch): A stopwatch with start, stop, and reset. Demonstrates time-based subscriptions.
- [Todo](https://foldkit.dev/example-apps/todo): A todo list with local storage persistence. Add, complete, and delete tasks.
- [Typing Terminal](https://foldkit.dev/example-apps/typing-terminal): A production real-time multiplayer typing speed game. Full-stack Effect app with an RPC backend, streaming room subscriptions, and a Foldkit frontend that share schemas across the wire.
- [UI Showcase](https://foldkit.dev/example-apps/ui-showcase): Interactive showcase of every Foldkit UI component with styled examples, routing, and component state management.
- [Weather](https://foldkit.dev/example-apps/weather): Look up weather by zip code. Demonstrates HTTP requests and loading states.
- [Web Components](https://foldkit.dev/example-apps/web-components): QR code designer wiring two real third-party web components into Foldkit with CustomElement.define. A hex color picker from vanilla-colorful emits color-changed CustomEvents that flow back as Messages, and the sl-qr-code element from Shoelace accepts typed properties. The picker and the QR never touch each other directly; they share state through the Model.
- [WebSocket Chat](https://foldkit.dev/example-apps/websocket-chat): Managed resources with WebSocket integration. Connection lifecycle, reconnection, and message streaming.

## AI

- [AI](https://foldkit.dev/ai/overview): Why Foldkit’s architecture makes AI-assisted development uniquely effective.
- [DevTools MCP](https://foldkit.dev/ai/mcp): Expose a running Foldkit app to AI agents over the Model Context Protocol.
- [Skills](https://foldkit.dev/ai/skills): Agent skills for generating, scaffolding, and auditing Foldkit programs.

## API Reference

- [Calendar](https://foldkit.dev/api-reference/calendar): API documentation for the Calendar module.
- [Canvas](https://foldkit.dev/api-reference/canvas): API documentation for the Canvas module.
- [Command](https://foldkit.dev/api-reference/command): API documentation for the Command module.
- [CustomElement](https://foldkit.dev/api-reference/custom-element): API documentation for the CustomElement module.
- [Dom](https://foldkit.dev/api-reference/dom): API documentation for the Dom module.
- [FieldValidation](https://foldkit.dev/api-reference/field-validation): API documentation for the FieldValidation module.
- [FieldValidationRule](https://foldkit.dev/api-reference/field-validation-rule): API documentation for the FieldValidationRule module.
- [File](https://foldkit.dev/api-reference/file): API documentation for the File module.
- [Html](https://foldkit.dev/api-reference/html): API documentation for the Html module.
- [ManagedResource](https://foldkit.dev/api-reference/managed-resource): API documentation for the ManagedResource module.
- [Message](https://foldkit.dev/api-reference/message): API documentation for the Message module.
- [Mount](https://foldkit.dev/api-reference/mount): API documentation for the Mount module.
- [Navigation](https://foldkit.dev/api-reference/navigation): API documentation for the Navigation module.
- [Port](https://foldkit.dev/api-reference/port): API documentation for the Port module.
- [Render](https://foldkit.dev/api-reference/render): API documentation for the Render module.
- [Route](https://foldkit.dev/api-reference/route): API documentation for the Route module.
- [Runtime](https://foldkit.dev/api-reference/runtime): API documentation for the Runtime module.
- [Scene](https://foldkit.dev/api-reference/scene): API documentation for the Scene module.
- [Schema](https://foldkit.dev/api-reference/schema): API documentation for the Schema module.
- [Story](https://foldkit.dev/api-reference/story): API documentation for the Story module.
- [Struct](https://foldkit.dev/api-reference/struct): API documentation for the Struct module.
- [Submodel](https://foldkit.dev/api-reference/submodel): API documentation for the Submodel module.
- [Subscription](https://foldkit.dev/api-reference/subscription): API documentation for the Subscription module.
- [Url](https://foldkit.dev/api-reference/url): API documentation for the Url module.

## Tooling

- [Oxlint Plugin](https://foldkit.dev/tooling/oxlint-plugin): Use the Foldkit oxlint plugin to enforce Foldkit-specific naming and message conventions, with examples for each custom rule.