TurboStarter
Installation
For the complete documentation index, see llms.txt. Prefer markdown by appending .md to documentation URLs or sending Accept: 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 to src/ (e.g. @/lib/log, @/modules/billing/...). There is no other alias.
  • Env config: env.config.ts lives outside src/, so import it by relative path with the .ts extension.
  • Cloudflare bindings: import env from cloudflare:workers.
  • i18n: keep the .js extension 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 createServerFn handlers, usually in *.functions.ts.
  • Files named *.server.ts read 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 const maps), no any.
  • Prefer interface for object shapes and type for 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.json and messages/es.json in 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 fmt block sets quotes, width, import order, and Tailwind class order.
  • Oxlint is an ESLint-compatible linter. The lint block is type-aware, so pnpm lint doubles 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:

  • tests runs vp check (format, lint, and types) and then the Vitest suite on every pull request.
  • e2e runs Playwright against Chrome, Firefox, and Safari (WebKit). On pull requests it only runs when the PR has the e2e label.
  • publish-web runs the tests, then deploys the Worker with pnpm 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:

.vite-hooks/pre-commit
vp staged

vp 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

On this page

Ship globally on the edge. In minutes.Try Edge Kit