On this pageCreate a Project
Get Started
Built on Effect. Architected like Elm. Written in TypeScript. Let’s get your first application running.
Before you begin, install Node.js 22.22.2 or newer and make sure the package manager you want to use is available. The create-foldkit-app scaffolder is the recommended way to start.
Run the scaffolder:
npx create-foldkit-app@latestThe CLI asks for a project name, a rendering mode, and a package manager. If you choose a browser-only SPA, it also asks which example you want to start from. The other rendering modes create their own starter applications:
SPA: renders entirely in the browser.
Static generation: prerenders routes to static HTML, then hydrates them in the browser.
Server rendering: renders each request on a Node server, then hydrates it in the browser.
The scaffolder creates the project and installs its dependencies. Move into the new directory, then start the development server with the package manager you selected:
cd your-projectpnpm:
pnpm devnpm:
npm run devYarn:
yarn devBun:
bun dev
Vite prints a local URL when the server is ready. Open it in your browser, and your first Foldkit application is running.
The exact files depend on the rendering mode and starter example. The small browser-only Counter SPA shows the usual split.
The Counter starter begins with these files:
src/application.ts: the typed Application and its implementation piecessrc/entry.ts: runtime bootstrap referenced byindex.htmlsrc/styles.css: Tailwind CSS entry pointindex.html: HTML entry pointvite.config.ts: Vite configuration with@foldkit/vite-plugintsconfig.json: TypeScript configuration.oxlintrc.json: Oxlint configuration.oxlintrc.effect.json: Effect type-aware lint configuration.oxfmtrc.json: Oxfmt configurationAGENTS.md: your instructions for AI coding assistants working on the projectFOLDKIT.md: Foldkit's own conventions for those assistants, replaced from the current template when you upgrade Foldkit
In a small starter, src/application.ts calls Block.makeDefinition('Application', { Model, Message }), creates a named ApplicationComposition, and assembles ApplicationBlock. The Definition authors Commands, Steps, lifecycle behavior, and Bindings; the Composition owns init, update, and the primary view after its child and Mount graph is fixed. Commands, Subscriptions, Mounts, ManagedResources, and their handler recipes stay on the root Block. Larger examples move substantial pieces into focused files as the application grows.
For the Counter starter, src/entry.ts imports ApplicationBlock and passes it with the page container to Program.make. The returned lowercase program is a passive runtime input. A starter whose handlers need application Services defines ApplicationLayer in services.ts, then the entry calls program.provide(ApplicationLayer). Importing the Block, creating the Program, and providing a Layer remain passive; startup happens only when the Runtime starts the Program.
The generated project also includes lint and format scripts. Run them with your selected package manager. For example: pnpm lint and pnpm format. The lint script checks Foldkit conventions and Effect usage. See Oxlint Plugin for the Foldkit-specific rules.
Skip this section if you used create-foldkit-app. Scaffolded projects already receive compatible package versions.
Foldkit uses Effect 4 stable and pins its peer dependencies to exact versions: effect@4.0.0 and @effect/platform-browser@4.0.0. Install those versions together. When upgrading an existing app, update every Effect package to the same version. Use the stable import paths, such as effect/http and effect/persistence, in place of their effect/unstable paths.
Install Foldkit together with its pinned peer dependencies:
npm install foldkit effect@4.0.0 @effect/platform-browser@4.0.0Read Architecture to understand the Model, Message, update, and view loop.
If you know React, use Coming from React to map familiar ideas onto Foldkit. If you know Elm, compare the two in Foldkit vs Elm: Side by Side.
For AI-assisted development, follow the setup in AI.