For the complete documentation index, see llms.txt. Prefer markdown by appending.mdto documentation URLs or sendingAccept: text/markdown.
Conventions
Follow Edge Kit's conventions for module layout, typed imports, server boundaries, localized copy, and the lint checks that enforce them.
You're not required to follow these conventions; they're simply a standard set of practices used in Edge Kit. If you like them, we encourage you to keep them during your usage of the kit so you have a consistent code style that you and your teammates understand.
Single package
Edge Kit is one package, so there's no decision about where shared code goes. Keep infrastructure adapters in src/lib, product features in src/modules, and let src/routes only compose them. See Project structure.
Imports and paths
- From the app: use the
@/alias, which maps tosrc/(e.g.@/lib/log,@/modules/billing/...). There is no other alias. - Env config:
env.config.tslives outsidesrc/, so import it by relative path with the.tsextension. - Cloudflare bindings: import
envfromcloudflare:workers. - i18n: keep the
.jsextension in imports from@/lib/i18n.
import env from "../../env.config.ts"; // typed secrets (envin + Zod)
import { env as bindings } from "cloudflare:workers"; // env.DB, env.KV, ...
import { m } from "@/lib/i18n/messages.js";Client and server code
- UI talks to the server through
createServerFnhandlers, usually in*.functions.ts. - Files named
*.server.tsread D1, secrets, and bindings. Never import them from client components. - TanStack Query options live in
*.queries.ts. - Link targets come from
src/config/paths.ts, not inline string literals.
Use paths configuration for shared route constants and server functions for the client/server boundary.
TypeScript
- Functional and declarative. No classes, no enums (use
as constmaps), noany. - Prefer
interfacefor object shapes andtypefor unions and derived types. - Validate with Zod 4.
- Use guard clauses and early returns over nested conditionals.
Internationalization
All user-facing copy goes through Paraglide. The lint rules require translated strings in JSX.
- Short reusable labels are unprefixed:
save,email,home. - View-specific copy uses a dotted prefix:
auth.login.title. - Every segment is camelCase.
- Keep
messages/en.jsonandmessages/es.jsonin sync.
UI
- Kumo components are imported by subpath (
@cloudflare/kumo/components/button), never from the package root, to keep the bundle small. - Icons come from
@phosphor-icons/react. - Shared app-level UI lives in
src/modules/common. - Use Tailwind CSS utilities, no inline styles.
Tooling
We don't enforce complex rules that aren't relevant to the project, giving you more freedom to customize things. Vite+ runs the tools that keep the conventions in place. Their settings live in vite.config.ts:
- Oxfmt is a Prettier-compatible formatter. The
fmtblock sets quotes, width, import order, and Tailwind class order. - Oxlint is an ESLint-compatible linter. The
lintblock is type-aware, sopnpm lintdoubles as the type check. - TypeScript is the language the app and those checks are written in.
Code health
GitHub Actions
By default, Edge Kit sets up GitHub Actions in .github/workflows:
testsrunsvp check(format, lint, and types) and then the Vitest suite on every pull request.e2eruns Playwright against Chrome, Firefox, and Safari (WebKit). On pull requests it only runs when the PR has thee2elabel.publish-webruns the tests, then deploys the Worker withpnpm run deploy(manual trigger).
Git hooks
pnpm install runs vp config, which points Git at Vite+ commit hooks in .vite-hooks. The pre-commit script checks the files you are about to commit:
vp stagedvp staged reads the staged block in vite.config.ts and runs vp check --fix on staged source, JSON, CSS, and Markdown. That applies formatting and lint fixes, including the type-aware lint pass.
Edit .vite-hooks/pre-commit if you want a different check before each commit. vp hooks disable turns hooks off in the current clone, and vp hooks enable turns them back on.
How is this guide?
Last updated on
AI-assisted development
Use Cursor, Claude Code, ChatGPT Codex, or Antigravity with Edge Kit. Rules, skills, and workflows for TanStack Start on Cloudflare Workers.
Common commands
Common pnpm, Wrangler, and D1 commands for daily Edge Kit work. Dev server, builds, linting, migrations, tests, and deploys.