Start here

What is kitr

The mental model for kitr in five minutes: platforms, packages, kits and providers, what it is built on and what works today.

kitr is a TypeScript framework for apps that run in a browser, on a server, and (as previews) on the desktop and on phones. You write one app/ folder in React and TypeScript. A project file called kitrrc.ts says where it runs and which capabilities it has, and one CLI (kitr add, kitr dev, kitr build) sets everything up. Each capability is a small package that wraps a library you may already know, such as TanStack Router, TanStack Query, React Hook Form or h3. It is for teams who want one set of conventions instead of choosing and wiring twenty libraries, and for coding agents, which can read the same conventions from AGENTS.md.

Pre-release. kitr is version 0.1 and is not on npm yet. See Getting started for how to run it from a checkout.

The four words you need

Platform. A platform is where the app runs: a website, an API server, a desktop window, a phone. You list platforms in kitrrc.ts, each with a name and options, for example site: web({ mode: 'ssr' }). kitr dev site runs one, and kitr build builds all of them into dist/<name>/. Platforms are packages too (@kitr/web, @kitr/server).

Package. A package is one capability: routing, data fetching, forms, auth, mail. It is published as @kitr/<name>, and you import from @kitr/<name>. The import gives you the upstream library unchanged, plus a few helpers. kitr add forms installs the package, wires it into the project, writes its config file and adds lines to AGENTS.md.

Kit. A kit is a starting set of platforms, packages and files for kitr new. app is a web app on an existing API, fullstack adds server rendering and its own backend, server is an API with no React. A kit is only a shortcut: afterwards you add and remove packages like any other project. Kits lists them all.

Provider. A provider is how a package takes part in app startup. It is a small object with hooks that run in order: register, boot, ready, shutdown, plus wrap for packages that need to wrap the React tree. kitrrc.ts lists the providers as lazy imports, so you can read your project's startup in one file.

One app, several platforms

The same app/ can run in more than one place. This kitrrc.ts has a website and an API:

// kitrrc.ts
import { defineKitrConfig } from 'kitr/app'
import { server } from '@kitr/server'
import { web } from '@kitr/web'

export default defineKitrConfig({
  packages: ['@kitr/router', '@kitr/query'],
  providers: [
    () => import('@kitr/router/provider'),
    () => import('@kitr/query/provider'),
  ],
  platforms: {
    site: web({ mode: 'ssr' }),
    api: server({ runtime: 'node' }),
  },
})

kitr dev site api runs both. kitr build writes dist/site/ and dist/api/. Options live in config/<package>.ts, and kitr config site port 4000 edits one with validation. The exact shape of kitrrc.ts is on Configuration.

What is built on what

kitr does not re-implement the libraries below. It re-exports them and adds a thin layer: one import path, one data contract and one startup order.

kitr piece Upstream library What kitr adds
@kitr/router TanStack Router A route table in app/routes.ts, requireAuth(), can()
@kitr/query TanStack Query Contracts and cache effects
@kitr/forms React Hook Form Schema validation, server errors mapped to fields
@kitr/table TanStack Table Sorting and paging kept in the URL
@kitr/state Zustand Stores that are safe with server rendering
@kitr/http ky An auth header, one refresh retry, one error shape
@kitr/web Vite and TanStack Start The web() platform: static, spa, ssr and pwa modes
@kitr/server h3 and srvx The server() platform, request context
@kitr/tailwind, @kitr/theme Tailwind, cva Tokens, dark mode, components you copy into your app

What works today

Part Status
web() platform (static, spa, ssr, pwa) Ready
server() platform (h3 on srvx) Ready
Packages in the app, fullstack and server kits Ready
desktop() (Electron), tauri(), mobile() (Capacitor) Preview
Device packages (platform, files, notifications, native, secure-storage, updater) Preview
Install from npm Not yet: run an example from a checkout

Previews exist in the repository but are refused by kitr new and kitr add unless you pass --preview. The native shells are web views around your app, not React Native. kitr has no auth server of its own: the auth package connects to the one you have.

Glossary

Term Meaning
Platform Where an app runs: web, server, desktop, mobile. Named in kitrrc.ts
Package One capability, published as @kitr/<name> and added with kitr add
Kit A starting set of platforms, packages and files for kitr new
Preset A kit with real pages, controllers and tests: saas, site, realtime
Provider A package's startup hooks: register, boot, ready, shutdown, wrap
Entry point An import path such as @kitr/router that exposes a package
Route table The list of pages in app/routes.ts, one .page() per URL
Contract The one shape for queries, mutations and subscriptions, whatever serves them
Effects Cache changes a mutation declares: invalidate, set, remove
kitrrc.ts The project file that lists packages, providers and platforms
config/ One options file per package, typed by the package
AGENTS.md Conventions for coding assistants, kept up to date by kitr add

Where next