# Using opencode with SvelteKit: A Developer’s Practical Guide

URL: https://agentvera.dev/en/blog/opencode-for-sveltekit/ · Published: 2026-11-01

Learn how to run opencode on a SvelteKit project: configure AGENTS.md, plan small tasks, run Vitest and Playwright, and avoid SvelteKit-specific agent pitfalls.

**In short:**

- opencode works well in a SvelteKit repo when AGENTS.md pins down build, lint, and test commands plus SvelteKit file rules.
- Keep tasks small and review diffs after every step; SvelteKit routing and load function changes need extra scrutiny.
- Use Vitest for server logic and Playwright for end-to-end flows, and let opencode run them before you merge.

[opencode](/en/agents/opencode/) is a terminal coding agent that can work directly inside an existing SvelteKit project. Once you start it with `opencode` in the project folder and point it at a clear AGENTS.md, it can add routes, refactor load functions, fix TypeScript errors, and run your test suite. This guide covers a repeatable workflow for SvelteKit teams that want the agent to produce reviewable, tested changes.

## Concrete strengths of opencode in SvelteKit projects

SvelteKit gives every route a small set of files with a predictable contract: `+page.svelte`, `+page.server.ts`, `+page.ts`, `+layout.server.ts`, and `+server.ts`. opencode reads those files and their imports, so it can make coherent changes across the route boundary instead of editing a single file in isolation. It also understands TypeScript well enough to adjust the generated `$types` imports and load return types that SvelteKit adds when you run `npm run check`. Because opencode can execute shell commands, it can run the SvelteKit compiler, Vitest, and Playwright itself and then react to failures, which keeps the loop inside one terminal instead of bouncing between an editor, a test runner, and a browser. That does not remove the need for review, but it does make the agent useful for the mechanical, multi-file edits that SvelteKit projects require.

## Prepare the repo with a tight AGENTS.md

opencode reads project instructions from AGENTS.md in the repo root. For SvelteKit work, keep that file short and specific: list the exact commands, the route conventions, and the server/client rules that the agent must respect. Do not rely on the model remembering SvelteKit defaults. For a typical project with Vitest and Playwright already installed, the file can look like this:

```markdown
# AGENTS.md

## Commands
- Install: `npm install`
- Dev: `npm run dev -- --open`
- Lint: `npm run lint`
- Typecheck: `npm run check`
- Unit tests: `npm run test:unit`
- E2E tests: `npm run test:e2e`
- Build: `npm run build`

## SvelteKit rules
- Routes live under `src/routes/`. Use `+page.svelte` for UI, `+page.server.ts` for server load and form actions, and `+page.ts` for universal load.
- Never import `$env/dynamic/private` or other server-only modules into client files.
- Use `$lib` for shared code. Do not create new top-level folders unless asked.
- Mutations go through form actions, not GET endpoints.
- Keep load functions explicit about return types and let SvelteKit generate `$types`; run `npm run check` after type changes.

## Conventions
- Prefer Svelte 5 runes (`$state`, `$derived`, `$effect`) over legacy stores.
- Use TypeScript interfaces for `PageData` when adding a load function.
- Follow existing formatting; do not reorder imports unless needed.
```

Putting the commands in AGENTS.md lets opencode run `npm run check` after a route change without being told every time. The SvelteKit-specific rules prevent the two most common agent mistakes: importing server-only code into `+page.svelte` and turning a simple mutation into a GET endpoint. A short file is better than a long one; opencode reads the whole file, but very long AGENTS.md files dilute the instructions. For a more detailed walkthrough of opencode itself, see [How to use opencode: a step-by-step guide](/en/blog/how-to-use-opencode/).

## A reliable loop for SvelteKit changes

The most reliable loop is: plan the change, ask opencode for a small diff, run the relevant checks, review the diff, and only then move to the next step. For SvelteKit, this usually means one route or one data function at a time. Avoid prompts like 'add all auth and dashboard pages'; instead, split them into route-level tasks. After each task, run `npm run check` or the targeted Vitest/Playwright command and inspect the changes with git diff.

Typical prompts that work well in this loop:
- 'Add a protected route at /dashboard with a `+page.server.ts` load that checks the session and redirects to /login if missing. Use the existing `requireUser` helper from `$lib/server/auth.ts`.'
- 'Refactor the profile form to use SvelteKit form actions with progressive enhancement and return `fail` for invalid input. Update the existing Playwright test to cover a failed submit.'
- 'Add a Vitest unit test for `parseInvoice` in `$lib/server/invoices.ts` and run `npm run test:unit`.'
- 'Create an API endpoint at `src/routes/api/health/+server.ts` that returns JSON `{ status: 'ok' }` and add a Playwright smoke test for it.'
- 'Run `npm run check` and fix all TypeScript errors, then run the full test suite. Do not change any UI text unless it is needed to fix a test.'

Each prompt includes the exact file path or command and the expected behavior. That is what makes opencode fast on SvelteKit: the route files are small and the contract is visible, but the agent still needs the exact path and the specific helper to reuse. After the agent finishes, review the diff with `git diff -- src/routes` before accepting it.

## Where opencode shines and where to review closely

opencode handles route additions, form actions, server endpoints, TypeScript fixes, and small refactors in `$lib` well. It can also update Vitest mocks and Playwright selectors when the tests are in the repo. Where it needs close review is the SvelteKit boundary between server and client.

Watch for these specifics:
- The agent may import `$env/dynamic/private`, Prisma, or other server-only modules into `+page.svelte` or `+page.ts`. That breaks the build, but opencode may not notice until you run `npm run build` or `npm run check`.
- Universal load functions and server load functions have different rules. An agent may place `cookies.get()` or a database call in `+page.ts` instead of `+page.server.ts`.
- Form actions need the `fail` return type and `use:enhance` on the client. The agent may add a `<form method="POST">` but skip `use:enhance`, so the page does a full reload.
- SvelteKit’s generated `$types` change when you add or rename load functions. The agent may not run `npm run check` and leave stale `PageData` or `ActionData` types.
- If the project uses Svelte 5 runes, the agent may still generate old `onMount` or store-based snippets. Tell it in AGENTS.md to use runes and review the diff for legacy patterns.

Most of these are caught by `npm run check` or `npm run build`, so the rule is simple: never accept a route-level change without running the compiler and looking at the generated types.

## Verifying SvelteKit changes with Vitest and Playwright

Let opencode run the checks, but verify the results against the right command. Vitest is the natural fit for unit testing universal load functions, form actions, and `$lib/server` helpers because those modules are plain TypeScript once you mock `cookies`, `fetch`, and `locals`. Playwright covers the real browser flows: navigation, form submissions, and redirects after login.

A useful verification table for a SvelteKit change:

| Check | Command | What to look for |
| --- | --- | --- |
| Typecheck and generated types | `npm run check` | No TS errors in route files, `$types` updated |
| Unit tests | `npm run test:unit` | Vitest passes for load functions, actions, helpers |
| E2E smoke | `npm run test:e2e` | Playwright passes for critical user flows |
| Production build | `npm run build` | Adapter output completes, no server-only import leaks |

Ask opencode to run the narrowest command that covers the change. For a `+server.ts` endpoint, run a Playwright API test or the relevant Vitest test; do not start a full e2e run for every small diff. When an agent fixes a test, require it to run that test again before you review the diff. If Playwright is configured with a local dev server, opencode may need to start `npm run dev` first; mention that in the prompt or add it to AGENTS.md.

## Running parallel agents with AgentVera

When one opencode instance is not enough, AgentVera runs real coding agent CLIs, including opencode, side by side in separate terminal panels. For SvelteKit work, the most useful features are per-agent git worktrees so parallel agents do not overwrite the same route files, automatic code review with file:line links after each turn to catch client/server boundary mistakes, and token budgets per agent, turn, and day so multiple agents do not burn through the whole account. Together those make a multi-agent setup safer for a file-based framework like SvelteKit. See [Best tools to run AI coding agents in parallel (2026)](/en/blog/best-tools-parallel-ai-coding-agents/) for more context.

## Keep the loop small and review the boundary

opencode is most productive on SvelteKit when you treat it as a fast junior engineer with good typing skills and a short memory. Put the commands and file rules in AGENTS.md, ask for one route or one data change at a time, run the compiler and tests before you review, and watch the server/client boundary. When you need more throughput, use isolated worktrees and a review step rather than letting several agents edit the same `src/routes` tree.

## Frequently asked questions

**How do I set up opencode for a SvelteKit project?** Start opencode in the project root and add an AGENTS.md with the build, lint, check, unit test, and e2e commands. Include rules for SvelteKit file conventions and the server/client boundary. Then ask for one small route change at a time.

**Can opencode create SvelteKit routes and form actions?** Yes. It can add +page.svelte, +page.server.ts, and +server.ts files, plus form actions with fail and use:enhance. Review the generated code for server-only imports and run npm run check.

**Does opencode run Vitest and Playwright tests automatically?** It runs the commands you specify in AGENTS.md or the prompt. Ask it to run npm run test:unit for Vitest and npm run test:e2e for Playwright after changes. It can inspect failures and adjust tests or code.

**How do I stop opencode from breaking SvelteKit load functions and SSR?** Put explicit rules in AGENTS.md: server-only code belongs in +page.server.ts, not +page.ts or +page.svelte; mutations go through form actions; run npm run check after changes. Review every diff that touches route files.

---

**About AgentVera.** AgentVera is a desktop app for macOS, Windows and Linux, built by Solviera Teknoloji. It runs 18 AI coding agents (Claude Code, Codex, Gemini CLI, Copilot, Cursor, Antigravity, opencode, Hermes, Qwen Code, Kimi Code, Kiro, Amp, Droid, Goose, Vibe, Crush, Aider, Cline) side by side, per project, in real terminals with the user's own CLI installs and logins. The free plan has unlimited agents. Download: https://agentvera.dev/en/download/ · Pricing: https://agentvera.dev/en/pricing/