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.

Build Chirp, a Twitter clone, from an empty folder to a deploy: Entity, Guard, signing in, the database tables, Remote, forms, Crud, Site, the components and optimistic updates. Under four minutes, music only.

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 update already 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.

Read the guide →

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') }),
  ),
)

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.

Read the guide →

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.

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.

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.