Packages for Foldkit · Effect 4 · MIT
Ready-made patterns for Foldkit. Less code to write, fewer tokens to spend.
Server data, offline sync, routing, forms, a CMS and AI agents, each a package you place instead of code you or your coding agent write by hand. None keeps state of its own: each reads your Model and sends Messages your update already handles.
Give this to your coding agent:
The docs and the agent skill ship inside the npm package, at the version of your code. npx foldkit-plus docs <query> reads them offline; npx foldkit-plus skill installs the matching skill.
One state machine.
A Foldkit application is a Schema-typed Model, a Message union naming everything that can happen, and one pure update that turns a Message into the next Model. That makes it easy to test and replay, until state starts living somewhere else: a cache in a hook, a store in the URL, an agent tool that changes data its own way. Every package here keeps it in the Model:
01
Agents
An agent can only send Messages
updatealready handles.02
Servers
Server data lives in the Model and is reduced by
update.03
Devices
Replicas replay the same Messages through the same
update.04
The URL
The URL and storage mirror a slice of the Model; they never own it.
05
Design systems
A design system styles a view from outside, without forking it.
Start with a Surface.
Start from the application you have. Surface.application wraps it without changing it, and App.surface declares what one feature may read and which Messages it may send. The other packages all take a Surface like this one.
app.ts
A todo list
Todos, a filter and a selection; four Messages; one update. The TodoList Surface sees the todos and the filter, and may toggle and filter.
import { Option, Schema } from 'effect'
import { defineMessageUnion } from 'foldkit/message'
import { modifyFields } from 'foldkit/struct'
import { Surface } from 'foldkit-surface'
const Todo = Schema.Struct({ id: Schema.String, title: Schema.String, done: Schema.Boolean })
export const Model = Schema.Struct({
todos: Schema.Array(Todo),
filter: Schema.Literals(['all', 'active', 'done']),
selected: Schema.Option(Schema.String),
})
export type Model = typeof Model.Type
export const Message = defineMessageUnion({
AddedTodo: { id: Schema.String, title: Schema.String },
ToggledTodo: { id: Schema.String },
ChangedFilter: { filter: Schema.Literals(['all', 'active', 'done']) },
SelectedTodo: { id: Schema.String },
})
export type Message = typeof Message.Type
// One Model, one Message union, one update: the whole application.
export const App = Surface.application({
Model,
Message,
initial: { todos: [], filter: 'all', selected: Option.none() },
update: (model, message) =>
Message.match(message, {
AddedTodo: ({ id, title }) => ({
model: modifyFields(model, { todos: todos => [...todos, { id, title, done: false }] }),
}),
ToggledTodo: ({ id }) => ({
model: modifyFields(model, {
todos: todos =>
todos.map(todo => (todo.id === id ? { ...todo, done: !todo.done } : todo)),
}),
}),
ChangedFilter: ({ filter }) => ({ model: modifyFields(model, { filter: () => filter }) }),
SelectedTodo: ({ id }) => ({
model: modifyFields(model, { selected: () => Option.some(id) }),
}),
}),
})
// A boundary: what the list may read, and the Messages it may send.
export const TodoList = App.surface('TodoList', {
model: ({ model }) => ({ todos: model.todos, filter: model.filter }),
messages: [Message.ToggledTodo, Message.ChangedFilter],
})Then connect it.
The same App, extended four ways. None adds a reducer, a store or a cache outside the Model.
view.ts
Draw it through slots
A view of the Surface reads only what the Surface exposes. A design system styles its slots from outside, with Style.attach.
import { Capability, Event, Slot, Slots, Style } from 'foldkit-mixins'
import { SurfaceView } from 'foldkit-mixins-surface'
import { Message, TodoList } from './app.js'
const ListSlots = Slots.define({
root: Slot.make({ capability: Capability.Container }),
toggle: Slot.make({ capability: Capability.Interactive, events: [Event.Click] }),
})
// The view reads only what the Surface projects, and sends only what it exposes.
export const TodoListView = SurfaceView.define(TodoList, ListSlots, (list, slots, h) =>
h.ul(
slots.root.attrs(),
list.todos.map(todo =>
h.li(
[],
[
h.button(slots.toggle.attrs([h.OnClick(Message.ToggledTodo({ id: todo.id }))]), [
todo.title,
]),
],
),
),
),
).pipe(
// Its look attaches from outside, to the slots it declared.
Style.attach(
Style.forSlots(ListSlots)({ root: Style.class('todos'), toggle: Style.class('todo') }),
),
)agent.ts
Hand it to an agent
An agent sees the todos and may add or toggle one, through tools over MCP, WebMCP, A2A or Agent Native. Each tool call is a Message through update.
import { Agent } from 'foldkit-agent'
import { Projection } from 'foldkit-surface'
import { App, Message } from './app.js'
const Todos = Agent.forApplication(App)
// An agent sees the todos and may send two Messages. Nothing else exists to it.
export const TodoAgent = Todos.make({
context: Projection.pick(App.model.todos),
messages: Todos.expose(Message, {
AddedTodo: 'Add a todo',
ToggledTodo: {
name: 'toggle_todo',
description: 'Mark a todo done, or not done',
available: model => model.todos.length > 0,
},
}),
})sync.ts
Take it offline
The todos replicate across tabs and devices. Adding and toggling are kept while offline and replayed through the same update on every device.
import { MessageSet, Projection } from 'foldkit-surface'
import { DocumentId, Sync } from 'foldkit-sync'
import { App, Message } from './app.js'
// The todos replicate; adding and toggling are the durable operations, replayed
// through the same update on every device. The filter stays on this one.
export const TodoSync = Sync.forApplication(App).make({
documentId: DocumentId.make('todos'),
shared: Projection.pick(App.model.todos),
durable: MessageSet.make(App, [Message.AddedTodo, Message.ToggledTodo]),
})mirror.ts
Put it in the URL
The filter is copied into the address, so a shared link restores it. The Model still owns it.
import { Mirror } from 'foldkit-mirror'
import { App } from './app.js'
// ?filter=active: the URL carries the filter, and a link restores it. The Model
// still owns it; the URL only mirrors it.
export const Filters = Mirror.url(App, {
name: 'filters',
fields: [App.model.filter],
})Server data, in the Model.
A server's data is cached in the Model, normalized by entity and changed only by update. A Surface says what it shows; Remote fetches it, keeps it live, and tells the view whether it has loaded.
remote.ts
Read a project
The domain is declared once with foldkit-entity. The same declaration maps to Drizzle tables on the server, and guards decide who may read it.
import { Schema } from 'effect'
import { defineMessageUnion } from 'foldkit/message'
import { Entity } from 'foldkit-entity'
import { Remote, RemoteData } from 'foldkit-remote'
import { Surface } from 'foldkit-surface'
// The domain, declared once: the client caches it, the server reads it.
const Project = Entity.define(
'Project',
Schema.Struct({ id: Schema.String, name: Schema.String, owner: Schema.String }),
)
const ProjectName = Entity.select(Project, { id: true, name: true })
// Server facts live in the Model, under one field, reduced by update.
const Model = Schema.Struct({ remote: Remote.Model })
const Message = defineMessageUnion({ ...Remote.messages })
const App = Surface.application({ Model, Message })
const Data = Remote.make({ model: App.model.remote, entities: [Project] })
// A Surface asks for what it shows; Remote fetches it. The read does no I/O.
export const ProjectPage = App.surface('ProjectPage', {
params: { id: Schema.String },
model: ({ params }) => ({ project: Data.get(ProjectName, params.id) }),
})
export const heading = (project: RemoteData<{ readonly name: string }>) =>
RemoteData.match(project, {
Initial: () => '',
Loading: () => 'Loading…',
Ready: ({ name }) => name,
Refreshing: ({ name }) => name,
Failed: error => error.message,
NotFound: () => 'No such project',
})Packages.
Choose by who owns the data. Each family has guides and an API reference.
Foundations
What every other package builds on: boundaries, placement and views.
Surface
What one feature may read, and which Messages it may send.
Owner: the application
foldkit-surface · foldkit-metadata
Bundle
A Submodel packaged once and placed anywhere, its update, view and subscriptions wired.
Owner: the parent Model
foldkit-bundle · foldkit-bundle-surface
Mixins
Typed slots a view exposes, styled from outside without forking it.
Owner: the view contract
foldkit-mixins · foldkit-mixins-surface · foldkit-mixins-ui
Primitives
Media queries, timers, sockets, undo history and more, as small Bundles.
Owner: the parent Model
foldkit-primitives
Data
Data owned outside the page: by a server, a log or the URL.
Entity
A domain declared once: fields, relations and derived members.
Owner: the domain declaration
foldkit-entity
Remote
Server data, normalized in the Model: queries, mutations and live updates.
Owner: the server
foldkit-remote · foldkit-remote-server · foldkit-remote-drizzle · foldkit-remote-domain
Sync
Edits that work offline and agree across devices, through a durable log.
Owner: the durable log
foldkit-sync · foldkit-durable
Guard
Who may read and change what, declared once and enforced on the server, in sync and for agents.
Owner: the domain declaration
foldkit-guard
Auth
Who is signed in: a Yielded Auth session as the principal a Remote server answers as.
Owner: Yielded Auth, through its session
foldkit-auth
Mirror
A slice of the Model kept in the URL or in storage, restored on load.
Owner: the local Model
foldkit-mirror
Screens
Forms, tables, content and editors.
Form
Drafts, validation and a decoded value, built from the Entity it writes.
Owner: the parent Model
foldkit-form · foldkit-mixins-form
CRUD
Create, edit and list screens, built from a form and a Remote operation.
Owner: Remote and the form
foldkit-crud · foldkit-mixins-crud
Data grid
Keyboard, selection, editing and virtualization over rows you own.
Owner: the grid; the application owns the rows
foldkit-data-grid · foldkit-mixins-data-grid
CMS
Drafts, revisions, scheduled publishing, and what visitors may see.
Owner: the application's tables
foldkit-cms · foldkit-cms-drizzle
Composition
Pages as data, made of Blocks, and the builder that edits them.
Owner: the Document, as a stored field
foldkit-composition · foldkit-builder · foldkit-mixins-builder
Rich text
A semantic document, the commands that edit it, and its editor.
Owner: the local Model
foldkit-richtext · foldkit-richtext-dom · foldkit-mixins-richtext · foldkit-richtext-markdown · foldkit-richtext-code · foldkit-richtext-code-shiki
Delivery
Server rendering, routing, images, AI agents and React.
SSR
Server rendering that hands the browser the Model instead of running init again.
Owner: the application, in a resume plan
foldkit-ssr · foldkit-host
Media
Responsive images as URLs to write, and icons as data.
Owner: the image's source; variants are a cache
foldkit-media
Site
Routes as data: addresses, titles, head metadata, links and prefetch.
Owner: the tree, as data
foldkit-site
Agent
What an AI agent may see and do, over MCP, WebMCP, A2A or Agent Native.
Owner: the application
foldkit-agent · foldkit-agent-mcp · foldkit-agent-webmcp · foldkit-agent-a2a · foldkit-agent-native
React
React components in a Foldkit view, and Foldkit programs inside React.
Owner: the Model, or the embedded program
foldkit-react · foldkit-react-codegen
Demos.
Examples from this repository, built as static sites. Where one needs a server, it runs in your browser, so nothing you do leaves your machine.
A blog studio and its site
Drafts beside the row, revisions, scheduled publishing and a page builder, with the public site rendered at build time.
foldkit-cms · foldkit-cms-drizzle · foldkit-remote · foldkit-crud · foldkit-form · foldkit-builder · foldkit-ssr
Two devices, one registry
Two devices edit 10,000 products in a data grid, offline and in conflict, and agree once both are back.
foldkit-data-grid · foldkit-mixins-data-grid · foldkit-remote · foldkit-sync · foldkit-durable
Pages two tabs edit at once
Rich text two people edit at the same time, online or not, converging through one journal.
foldkit-richtext · foldkit-richtext-dom · foldkit-mixins-richtext · foldkit-richtext-markdown · foldkit-sync · foldkit-durable
A rich text playground
One document with movable blocks, anchored discussions, images, tables, code, toggles and footnotes, every edit a transition of the Model.
foldkit-richtext · foldkit-richtext-dom · foldkit-mixins-richtext · foldkit-richtext-markdown · foldkit-richtext-code-shiki
A todo list an agent can use
One application definition drives the view, the tools an agent calls, the document replicas share, and the policy the server enforces.
foldkit-surface · foldkit-sync · foldkit-durable · foldkit-agent · foldkit-agent-webmcp · foldkit-mixins · foldkit-mirror
A Twitter clone, Chirp
Posts declared once as Entities, guarded on the server, served through Remote, posted and edited through forms built from the same input, and liked in one round trip.
foldkit-entity · foldkit-guard · foldkit-remote · foldkit-remote-drizzle · foldkit-form · foldkit-crud · foldkit-site · foldkit-mixins-ui
A data grid over 100,000 rows
A grid that owns focus, selection, columns and the open editor, while the application owns every row.
foldkit-data-grid · foldkit-mixins-data-grid · foldkit-bundle
Eight widgets from shared primitives
Once the capabilities exist, a family of widgets gets cheap: each one is a Bundle placement plus Behaviors on a shared Collection description, with no bespoke state machine.
Status.
Every package is 0.x and may break between minor versions; the changelog says how to upgrade, and the blog tell the story of the larger releases. They target Foldkit 0.170 and Effect 4. Some are marked early or experimental; the release matrix lists every version.