foldkit

The frontend framework for correctness.

Documentation · Manifesto · Examples · Getting Started · Discord

Foldkit is a TypeScript frontend framework built on Effect. It gives your entire application one architecture: a Schema-defined Model as the single source of truth, fact-named Messages, an exhaustive update function, and explicit Commands for side effects. Routing, server rendering, UI components, Submodels, and browser lifecycles all use that same Model and Message flow.

Foldkit uses The Elm Architecture instead of component-owned state and hook lifecycles. That discipline is a real commitment. Foldkit works best when the team wants shared conventions across the application and is ready to build on Effect throughout. If your backend already uses Effect, Foldkit carries the same tools and patterns into the browser: Schema, services, Streams, and scoped resources.

A Foldkit program can own the whole page or run as a widget inside an existing application, React included, through Runtime.embed. The same program can render on the server at build time or per request, then hydrate in place. Coming from React? Start here, or compare the same pixel-art editor built in both frameworks.

[!NOTE] Foldkit is in beta and under active development. The core API is stable, but breaking changes may occur in minor releases. See the changelog for details.

Get Started

create-foldkit-app scaffolds a complete setup with Tailwind, TypeScript, Oxlint, Prettier, and the Vite plugin for state-preserving HMR. Pick a rendering mode (browser-only SPA, static generation, or server rendering) and, for a SPA, the example to start from.

npx create-foldkit-app@latest

Counter

A complete Foldkit program. State lives in a single Model, events become Messages, and a pure function handles every transition. main.ts defines the program and entry.ts boots the Runtime, so main.ts stays importable from tests without booting a Runtime as a side effect.

// src/main.ts
import { Match as M, Schema as S } from 'effect'
import { Command, Runtime } from 'foldkit'
import { Document, HtmlBuilder } from 'foldkit/html'
import { m } from 'foldkit/message'
import { evo } from 'foldkit/struct'

// MODEL

export const Model = S.Struct({ count: S.Number })
export type Model = typeof Model.Type

// MESSAGE

const ClickedDecrement = m('ClickedDecrement')
const ClickedIncrement = m('ClickedIncrement')
const ClickedReset = m('ClickedReset')

export const Message = S.Union([
  ClickedDecrement,
  ClickedIncrement,
  ClickedReset,
])
export type Message = typeof Message.Type

// UPDATE

export const update = (
  model: Model,
  message: Message,
): readonly [Model, ReadonlyArray<Command.Command<Message>>] =>
  M.value(message).pipe(
    M.withReturnType<
      readonly [Model, ReadonlyArray<Command.Command<Message>>]
    >(),
    M.tagsExhaustive({
      ClickedDecrement: () => [evo(model, { count: count => count - 1 }), []],
      ClickedIncrement: () => [evo(model, { count: count => count + 1 }), []],
      ClickedReset: () => [evo(model, { count: () => 0 }), []],
    }),
  )

// INIT

export const init: Runtime.ApplicationInit<Model, Message> = () => [
  { count: 0 },
  [],
]

// VIEW

export const view = (model: Model, h: HtmlBuilder<Message>): Document => ({
  title: `Counter: ${model.count}`,
  body: h.div(
    [],
    [
      h.p([], [model.count.toString()]),
      h.button([h.OnClick(ClickedDecrement())], ['-']),
      h.button([h.OnClick(ClickedReset())], ['Reset']),
      h.button([h.OnClick(ClickedIncrement())], ['+']),
    ],
  ),
})

// src/entry.ts
import { Runtime } from 'foldkit'

import { Model, init, update, view } from './main'

const application = Runtime.makeApplication({
  Model,
  init,
  update,
  view,
  container: document.getElementById('root'),
})

Runtime.run(application)

Source: examples/counter.

What Ships With Foldkit

Routing, server rendering, UI components, composition, and browser lifecycles all use the same Model and Message flow. The pieces below ship as one system and are documented in depth at foldkit.dev.

• Commands: Side effects as named Effects that return Messages and are run by the Runtime.
• Routing: Type-safe bidirectional routing from parser combinators. URLs parse to Routes, Routes build URLs.
• Subscriptions: External event streams declared as a function of the Model.
• Managed Resources: Model-driven lifecycle for WebSockets, AudioContext, and other long-lived handles.
• Mount: The seam where view code hands a real DOM element to a third-party library that owns its own DOM.
• Submodels: A self-contained Model, update, and view that a parent embeds, wrapping child Messages in a Got* envelope.
• OutMessage: A typed channel for a child Submodel to emit domain events up to its parent.
• Embedding: Run a Foldkit program inside a host app through Schema-typed Ports with Runtime.embed.
• UI Components: Accessible, keyboard-friendly primitives in the @foldkit/ui package.
• Field Validation: Per-field validation state modeled as a discriminated union.
• Virtual DOM: Declarative views with lazy memoization and keyed diffing, powered by Snabbdom.
• Server Rendering: The same program rendered to HTML at build time (SSG) or per request (SSR), then hydrated in place.
• DevTools: In-browser overlay for inspecting Messages, Model, and Commands, with time-travel.
• DevTools MCP: Expose a running app to AI agents over the Model Context Protocol.
• Crash View and Reporting: A custom fallback UI when the update loop throws, plus a report callback.
• Story Testing: Exercise the update function directly, resolving Commands inline. No mocks, no fake timers.
• Scene Testing: Drive your real view the way a user does, with accessible locators. No browser required.
• Slow Warnings: Development warnings when update, view, patch, or Subscription extraction exceeds its budget.
• HMR: Vite plugin with state-preserving hot module replacement. Change your view, keep your state.

AI-Assisted Development

Every feature has the same visible structure: a Schema-defined Model, fact-named Messages, exhaustive update, and explicit Commands. AI-generated changes follow code paths a person can inspect and test. Foldkit DevTools and its MCP server expose the same Model and Message history while the application runs.

Examples

Some of what you can build with Foldkit. See all example apps on foldkit.dev.

• Counter: Increment/decrement with reset
• Todo: CRUD operations with localStorage persistence
• Form: Form validation with async email checking
• Job Application: Multi-step form with cross-field validation, file uploads, and per-step error indicators
• Weather: HTTP requests with async state handling
• API Cache: Query caching with stale-while-revalidate, request deduplication, and interval refetching
• Routing: URL routing with parser combinators
• Route Transitions: Live transition log with entry, exit, and stayed navigation policies
• Query Sync: URL query parameter sync with filtering and sorting
• Snake: Classic game built with Subscriptions
• Auth: Authentication flow with Submodels and OutMessage
• Shopping Cart: Nested models and complex state
• WebSocket Chat: Managed Resources with WebSocket integration
• Kanban: Drag-and-drop kanban board with cross-column reordering and keyboard navigation
• Pixel Art: Grid-based pixel editor with painting, erasing, and palette selection
• UI Showcase: Interactive showcase of every Foldkit UI component
• Static Site Generation: Build-time prerendering with client hydration
• Server-Side Rendering: Per-request rendering on an Effect HttpServer with cookie-derived Flags
• Typing Game: Multiplayer typing game with Effect RPC backend (play it live)

License

MIT