Gemini CLI and SvelteKit: Practical Workflow Guide

Gemini CLI is a terminal coding agent that can scaffold, edit, and verify SvelteKit code when you run gemini in the project root. With a focused GEMINI.md, it respects SvelteKit conventions around +page.svelte, +page.server.ts, load functions, and form actions. This guide covers a practical setup and working loop for daily SvelteKit development.

Why Gemini CLI fits SvelteKit

SvelteKit’s file-based routing gives the agent a clear map of the application. A page at src/routes/products/[slug]/+page.svelte pairs with +page.server.ts for server-only loading and with a universal +page.ts when data needs to be shared with the client. Gemini CLI can read those files, trace the data flow, and make small, coherent changes. This is very different from a framework where state and routing are scattered across a component tree.

Because SvelteKit uses explicit server and client boundaries, the agent can be told to keep server-only imports inside +page.server.ts and +server.ts. That rule, written in GEMINI.md, prevents the most common SvelteKit build failure: importing $lib/server/db or a private environment variable into client-bundled code. The agent also benefits from TypeScript strict mode; type errors become immediate signals for incorrect route params, load return types, and form action signatures.

The practical guide How to use Gemini CLI: a step-by-step guide covers the general loop. For SvelteKit, the loop is most productive when each prompt names a route, load function, endpoint, or form action rather than describing a page in general terms.

Configuring GEMINI.md for SvelteKit

Create a GEMINI.md file in the repository root. Gemini CLI reads it on every run, so keep it concise and only include rules that prevent real mistakes. A useful SvelteKit GEMINI.md lists the build, test, and lint commands, explains the folder conventions, and states the server/client boundary rules.

Here is a short, realistic example:

# GEMINI.md

## Commands
- Install: npm install
- Dev server: npm run dev
- Build: npm run build
- Lint: npm run lint
- Check svelte: npm run check
- Unit tests: npm run test:unit
- E2E tests: npx playwright test

## Conventions
- Routes live in src/routes.
- Server-only code goes in +page.server.ts, +page.server.js, or +server.ts.
- Client code must not import from $lib/server.
- Load functions must return serializable data only; no Svelte stores, components, or Date objects.
- Form actions use return fail() for validation errors and redirect() only after success.
- Use $lib aliases for imports from src/lib.
- Keep styles scoped in <style> tags; do not edit app.html unless asked.

Do not leave ambiguity about the test commands. If npm run test:unit runs Vitest and npm run test runs Playwright, write both names exactly as they appear in package.json. If the project uses a monorepo, state the workspace package as well. The more precise the commands, the less likely the agent is to invent a script or run the wrong suite.

A day-to-day working loop

Use a plan, small steps, test, and review diff loop. Start by describing the desired behavior in terms of route files or form actions, not a vague feature request. After each agent turn, read the diff before accepting it. SvelteKit changes often touch two or three files at once, so a quick review of the .svelte template, the server load, and the imported types prevents subtle serialization or import errors.

Typical prompts for SvelteKit tasks:

1. Add a protected route at /account that checks the session in a load function and redirects unauthenticated users to /login.
2. Create a form action on the login page that validates email and password, sets a session cookie, and returns field errors with fail().
3. Add a +server.ts endpoint for POST /api/webhooks that verifies the signature and stores the event in the local database.
4. Convert the dashboard page to use universal load and add an await block for the loading state.
5. Add a Playwright test for the checkout flow and a Vitest unit test for the cart store.

After each step, run the relevant test or build command and share the failure output with Gemini CLI. If the failure is a Svelte compiler warning rather than a test failure, paste that output too; the agent can often find the exact template line.

Common SvelteKit tasks and pitfalls

Gemini CLI handles many SvelteKit tasks well: creating route files with matching page and server code, updating load functions to fetch and type data, writing form actions with progressive enhancement, adding API endpoints, and generating Vitest or Playwright tests.

The table below shows common files and useful prompts.

Watch the agent closely around SvelteKit’s client/server boundary. The most common failure is importing server-only modules or private environment variables into a +page.svelte or a universal +page.ts file. SvelteKit will then fail during client bundling, and the error may point to the wrong line. Another recurring issue is returning non-serializable data such as Date, Map, or a Svelte store from a load function; this may pass in development but break with a serialization error during build. Also check form actions that call redirect() after fail() or forget to preserve use:enhance semantics. The agent may also edit generated files under .svelte-kit or create conflicting routes with overlapping parameter names.

When the agent modifies a load function, verify that server-only imports remain in +page.server.ts and are not copied into +page.ts. That single review habit catches most SvelteKit-specific agent mistakes.

Testing and verification with Vitest and Playwright

Use a test-driven loop. For SvelteKit, run npm run test:unit for Vitest tests of stores, utilities, and load functions where possible. Use npx playwright test for end-to-end flows that involve form actions, redirects, and client-side navigation. If the project has npm run check, run it after route changes to catch svelte-check errors in templates and types.

When an agent changes +page.server.ts or +server.ts, ask it to write a unit test that imports the load function or endpoint handler directly and passes a mock event. This works well for pure validation or data-mapping logic. For UI changes, a Playwright test that asserts the rendered result is more reliable than reading the diff alone. Always review test failures with the agent; do not accept a change that only makes a test pass by weakening the assertion.

A good verification prompt is: Add a Vitest test for the login form action that covers missing email, missing password, and invalid credentials. Then run the test suite and share the errors. This keeps the agent grounded in the actual behavior of the SvelteKit form action.

Parallel agents with AgentVera

AgentVera is a desktop app for running coding agents; for SvelteKit, the key benefits are git worktrees, automatic code review, checkpoints, and token budgets. Agents work in separate worktrees so one can add a route while another updates a shared store without overwriting files. Automatic code review after each turn catches server/client boundary mistakes and links findings to file:line, exactly where +page.server.ts issues appear. Checkpoints let you undo a bad route or form action in one click. Token budgets prevent long unattended runs. For orchestration patterns, see AI agent orchestration for coding: 5 patterns and tools.

Wrap-up

Use Gemini CLI with SvelteKit as a rigorous pair programmer: keep GEMINI.md specific, work in small testable steps, review every diff, and lean on Vitest and Playwright for verification. The agent’s value comes from respecting SvelteKit’s file conventions and server/client boundaries; if those are encoded in the project instructions, most daily SvelteKit tasks become straightforward. For larger changes, parallel agents in git worktrees with review and checkpoints avoid route conflicts and make the work easier to track.