Get started

Install, run locally, and check the starter in a few commands.

Prerequisites

Node 24 and Bun 1.3.9.
Docker, for the bundled local PostgreSQL and zero-cache. Deployed stages get Amazon RDS from the SST stack by default (Deployment). Any other PostgreSQL works, locally or deployed, if it has logical replication and a direct connection for zero-cache; see Database.
Xcode or the Android SDK only when you build the native apps.

Run locally

bun install --frozen-lockfile
bun run setup
bun run db:up
bun run db:migrate
bun run dev

db:up starts PostgreSQL and zero-cache, the sync service every CRM screen reads and writes through; zero-cache retries until db:migrate has created the publication it replicates. bun run dev checks the database can feed it, uses the running zero-cache, or starts one itself from node_modules when none is running (for a managed database, for example). It prints the fix when the database is not ready, instead of leaving you with empty screens.

Open http://localhost:8081 and sign in with any email address from the sign-in screen: the kit is passwordless, so it emails a six-digit code and the first code creates the account. setup writes an ignored .env with a random auth secret and the console email provider, and never overwrites an existing file. With managed PostgreSQL, set DATABASE_URL in .env and skip db:up.

The home page, appearance settings, these docs, and the production build work without a running database. Signing in and editing an account need the database and the auth environment values; CRM screens also need zero-cache. With the console email provider, the sign-in code — and any confirmation or reset link — prints in the terminal running bun run dev. Set EMAIL_PROVIDER=file and EMAIL_OUTBOX=.onekit/outbox.jsonl instead to read them back from a file.

Make it yours

Choice	Where
Name, scheme, native identifiers, default appearance, accent	`src/config/app.ts`
Tokens, fonts, breakpoints, Tamagui settings	`src/tamagui/config.ts`
Database URL, auth secret, OAuth credentials, email provider	`.env` locally; SST secrets when deployed
Session lifetime, password policy, trusted origins	`src/server/auth.ts`
Email copy	`src/server/email.ts`
Plans and prices	`src/config/billing.ts`; Stripe keys in `.env`
Schema and migrations	`src/server/db/schema.ts`, `drizzle/`
AWS region, service size, scaling, OAuth and email toggles	`infra/config.ts`
Native development, preview, production builds	`app.config.ts`, `eas.json`
These docs	`src/docs/*.mdx`, `src/docs/routes.ts`

The Configuration guide covers each of these in detail.

Native development

Set ONE_PUBLIC_SERVER_URL in .env to a server reachable from your device. Physical phones need your computer’s LAN address; the Android emulator usually uses 10.0.2.2. Keep BETTER_AUTH_URL and ONE_SERVER_URL on the same origin during development. Then:

bun run native:prebuild
bun run ios       # Xcode required
# or
bun run android   # Android SDK required

Use the development build; Expo Go is not part of the supported setup. Replace the sh.onekit.app identifiers (Onekit’s own) before distribution. EAS profiles are provided, but you link your own Expo project and set its public server URL.

Check the starter

bun run check
bun run test:auth
bun run build
bunx playwright install chromium
bun run test:e2e

Auth tests use an isolated in-memory PostgreSQL engine, apply the real migrations, and capture outgoing email in memory. They need neither Docker nor credentials. Browser tests run against the production build on port 4180.

bun run dev is local. sst dev and sst deploy connect to your AWS account and can create billable infrastructure; see Deployment.

Onekit / A little less setup.Web · iOS · Android