Skip to main content
Foldkit
On this pageCreate a Project

Get Started

Built on Effect. Architected like Elm. Written in TypeScript. Let’s get your first application running.

Create a Project

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:

Create a Foldkit project
npx create-foldkit-app@latest

The 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:

Enter the project directory
cd your-project

  • pnpm: pnpm dev

  • npm: npm run dev

  • Yarn: yarn dev

  • Bun: bun dev

Vite prints a local URL when the server is ready. Open it in your browser, and your first Foldkit application is running.

Find Your Way Around

The exact files depend on the rendering mode and starter example. A small browser-only SPA such as Counter begins with these pieces:

  • src/main.ts: pure application definitions

  • src/entry.ts: runtime bootstrap referenced by index.html

  • src/styles.css: Tailwind CSS entry point

  • index.html: HTML entry point

  • vite.config.ts: Vite configuration with @foldkit/vite-plugin

  • tsconfig.json: TypeScript configuration

  • .oxlintrc.json: Oxlint configuration

  • .oxfmtrc.json: Oxfmt configuration

  • AGENTS.md: your instructions for AI coding assistants working on the project

  • FOLDKIT.md: Foldkit's own conventions for those assistants, replaced from the current template when you upgrade Foldkit

In a small starter, src/main.ts holds the Model, Messages, update, init, and view. Larger examples move those definitions into focused modules as the application grows.

For the Counter starter, src/entry.ts imports the application definitions and starts the runtime with Runtime.makeApplication and Runtime.run. Other starters may compose the application from several modules or start a different host, but they keep runtime startup separate from the pure definitions. That separation lets tests import the application without starting a runtime as a side effect.

The generated project also includes lint and format scripts. Run them with your selected package manager. For example: pnpm lint and pnpm format. See Oxlint Plugin for the Foldkit-specific rules.

Add Foldkit to an Existing Project

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:

Install Foldkit and Effect
npm install foldkit effect@4.0.0 @effect/platform-browser@4.0.0

Where to Go Next