Codex works well with SvelteKit when you treat it as a pair programmer that respects a project-specific AGENTS.md. Run codex from the SvelteKit root, keep changes small, and verify through Vitest, Playwright, and svelte-check. This guide covers setup, prompts, pitfalls, and verification for maintainable SvelteKit work.
Why Codex fits SvelteKit projects well
Codex is useful because SvelteKit has a clear file structure: route folders with +page.svelte, +page.server.ts, +page.ts, and +server.ts. The agent can navigate these conventions and generate TypeScript that respects the server/client split. In practice, Codex does well when it has a concise AGENTS.md and a specific task, but it needs your review because SvelteKit encourages colocated files and server-only boundaries that are easy to cross. The more you treat it like a developer who has read the docs but has not seen your project, the better the output.
Prepare your SvelteKit project with a focused AGENTS.md
The most important setup step is to create an AGENTS.md in the project root. Codex reads this file and uses it as persistent project instructions. For a SvelteKit project, include exact commands, folder conventions, and rules that prevent common mistakes. Avoid making it a generic README; keep it specific enough that an experienced contractor could start working immediately. For CLI basics outside this article, see this step-by-step guide.
# AGENTS.md
## Commands
- Install: `pnpm install`
- Dev: `pnpm dev`
- Build: `pnpm build`
- Typecheck: `pnpm check` (runs `svelte-check --tsconfig ./tsconfig.json`)
- Lint: `pnpm lint`
- Format: `pnpm format`
- Unit tests: `pnpm test:unit` (Vitest)
- E2E tests: `pnpm test:e2e` (Playwright)
## Layout and conventions
- Routes live under `src/routes/`. Use `+page.svelte`, `+page.server.ts`, `+page.ts`, `+layout.svelte`, `+layout.server.ts`, and `+server.ts` as appropriate.
- Server-only code belongs in `src/lib/server/`. Never import server-only modules into client code.
- Reusable UI goes in `src/lib/components/` and is imported as `$lib/components/...`.
- Types live in `src/lib/types.ts`.
## SvelteKit rules
- Put data loading in `+page.server.ts` or `+page.ts` load functions, not in `+page.svelte`.
- Use form actions in `+page.server.ts` for mutations; add a `+server.ts` endpoint only for external APIs.
- In `+server.ts`, export named functions like `GET`, `POST`, `PUT`, `DELETE`.
- Validate form action input with Zod before touching the database.
- Never import `$env/static/private` into client files.
- Use `browser` from `$app/environment` for client-only guards.Keep the file short; Codex reads it on every turn, so a 200-line policy document dilutes the useful rules.
Run a tight Codex loop on SvelteKit tasks
Run codex in the project root and give it a small, concrete task. Start with an instruction that asks for a plan, not a full implementation. After each change, run the relevant verification commands, review the diff, and paste any failure back into Codex. If a task involves multiple routes or shared modules, split it into one route or one function at a time.
Example prompts:
Read AGENTS.md and summarize the project's route structure, then plan the files you would change to add a +server.ts health endpoint under /api/health.Add a +page.server.ts load function for /dashboard that reads locals.user, redirects to /login if missing, and returns typed user data.Add a default form action in /settings/+page.server.ts that validates display name and email with Zod and returns fail(400, { errors }) on invalid input.Write a Vitest test for the /settings form action, mocking the database layer and asserting both success and validation failure.Run pnpm check, pnpm lint, and pnpm test:unit; fix only the issues caused by your last change.
Where Codex excels and where you must review closely
Codex is strong at boilerplate like load functions, form actions, and simple +server.ts endpoints. It can also write Vitest and Playwright tests, refactor types, and explain existing route flows. The main risk is SvelteKit-specific boundaries: server-only code leaking into the client, form actions that return the wrong response shape, and load function dependencies that trigger unnecessary waterfalls.
| Task | Good prompt | SvelteKit-specific watchpoint |
|---|---|---|
| Load data for a page | Create a load function for /dashboard that uses locals.user and throws redirect(307, '/login') if not authenticated. | It may put the logic in +page.ts instead of +page.server.ts, leaking server imports. |
| Add a mutation | Add a default form action in /account/+page.server.ts that validates with Zod and uses fail to return field errors. | It may import Zod in +page.svelte or forget to return the form data on failure. |
| Add an API route | Add src/routes/api/items/+server.ts with GET returning a typed list from the database. | It may confuse +server.ts with +page.server.ts or omit the json() helper. |
| Refactor nested layouts | Merge the two layout load functions into one using the sequence helper and remove duplicate user fetching. | It may call parent() eagerly in +page.server.ts and create waterfalls, or break the group layout structure. |
Watch also for missing await before parent(), incorrect depends() invalidation, and unsafe cookies access. These are often caught by pnpm check or a failing test, but a quick manual review catches them earlier.
Verify Codex changes with tests and checks
Never trust Codex’s claim that a test passes. Run the commands yourself and paste the output into the next prompt if something fails. For unit logic, pnpm test:unit with Vitest is fast and usually enough for form action validation. For end-to-end flows, pnpm test:e2e runs Playwright; ensure the dev server is started by the Playwright webServer config or run it separately. Always run pnpm check to catch type errors in generated SvelteKit code, and pnpm build before merging to catch SSR-only failures. Review the diff with git diff after every task; Codex sometimes edits a shared file to fix one route and introduces an unrelated regression. Automated review can help here; AI code review describes how a second model can check what the agent writes.
Scale SvelteKit work with AgentVera and parallel agents
AgentVera is a desktop app that runs coding agents’ real command line tools side by side in one window, each in its own real terminal panel. For SvelteKit work, run several Codex sessions in parallel, but give each one its own git worktree so route and server changes do not collide. When an agent finishes, automatic code review checks for SvelteKit-specific issues like server-only imports leaking into client code. Checkpoint snapshots let you undo a bad refactor or replay a turn step by step, and token budgets stop a long svelte-check loop from burning the entire day.
Keep the loop tight
Codex fits a SvelteKit workflow when the project instructions are explicit, the tasks are small, and the verification loop is strict. Keep AGENTS.md focused on commands, route conventions, and server/client boundaries. Use Codex for boilerplate and refactoring, but run the tests and type checks yourself. With that discipline, Codex becomes a reliable part of SvelteKit development.