Cursor Agent SvelteKit: A Practical Guide

Cursor Agent works well in SvelteKit projects for adding routes, load functions, form actions, and tests. Run it from the project root with cursor-agent and give it project-specific instructions through AGENTS.md or .cursor/rules. This guide covers setup, prompts, pitfalls, and verification for SvelteKit.

Why Cursor Agent fits SvelteKit development

SvelteKit tasks usually span several files that must stay consistent: a +page.svelte component, a +page.ts or +page.server.ts load function, and often a +server.ts endpoint or form action. Cursor Agent can open those files together, plan the change, and edit them in one pass while respecting the route structure. Because it runs from the terminal, it can execute pnpm check, pnpm test:unit, or pnpm build immediately and react to compiler output instead of guessing. That loop is especially useful for SvelteKit’s server/client boundary, where one wrong import can break a production build. For a command line workflow overview, see How to use Cursor CLI: a step-by-step guide.

Preparing AGENTS.md for a SvelteKit project

Create an AGENTS.md file in the project root or add rules under .cursor/rules. The file should be short and command-first: how to install, develop, build, lint, check, and test. Then state SvelteKit-specific conventions so the agent does not guess whether you use Svelte 5 runes or legacy syntax, where server-only code belongs, and what belongs in load functions versus form actions.

# SvelteKit project instructions

## Commands
- Install: pnpm install
- Dev: pnpm dev
- Build: pnpm build
- Lint: pnpm lint
- Check: pnpm check
- Unit tests: pnpm test:unit
- E2E tests: pnpm test:e2e

## Conventions
- Routes live in src/routes. Use +page.svelte, +page.ts, +page.server.ts, and +server.ts.
- Put private data access in +page.server.ts or +server.ts, never in +page.ts or components.
- Load functions return plain serializable objects only. No Dates, class instances, or functions.
- Mutations go through form actions in +page.server.ts, not GET or POST endpoints, unless the endpoint is an external API.
- Use Svelte 5 runes ($state, $derived, $effect). Do not use legacy stores or `$:` syntax.
- Shared imports come from $lib, for example `$lib/components/Button.svelte`.
- Keep server-only modules under src/lib/server.
- Never edit svelte.config.js, vite.config.ts, or package.json unless the task explicitly asks for it.

Keep the file factual; Cursor Agent reads the AGENTS.md at the start of a session. If you have a Svelte 4 project, change the runes line accordingly. The goal is to remove ambiguity about file placement, return types, and commands.

A practical SvelteKit workflow: plan, code, verify

Start each task by asking for a plan before code. A good first prompt is: ‘Inspect the current /dashboard route and propose a plan to add a settings form; do not edit files yet.’ Once you agree, tell the agent to make the change in small steps and run the relevant command after each step. After each turn, run pnpm check, pnpm test:unit, and pnpm test:e2e yourself, then review the diff with git diff -- src/routes. If the diff touches more files than expected or changes generated config, ask the agent to undo and redo the work with a narrower scope.

Example prompts for typical SvelteKit tasks:

• ‘Add a /dashboard route with a +page.server.ts load function that reads locals.user and returns only { id, email }. In +page.svelte, show the email and handle the case where user is null by redirecting to /login.’
• ‘Create login and logout form actions in /account/+page.server.ts. Validate the email format and password length, use fail(400, { message }) for invalid input, set an httpOnly session cookie on success, and use redirect(303, '/'). Update +page.svelte to use use:enhance.’
• ‘Add a +server.ts endpoint at /api/items with GET returning a list and POST parsing JSON. Return 400 for malformed input, 401 for unauthenticated, and 201 on success. Do not use a database; return a fixed in-memory list for now.’
• ‘Write Vitest tests for src/lib/utils/date.ts and for the load function in /dashboard/+page.server.ts. Mock locals and fetch; use vi.fn() where needed.’
• ‘Run pnpm check and fix all type and a11y warnings in the routes under /settings that I changed in the last commit.’

What Cursor Agent does well and SvelteKit pitfalls to watch

Cursor Agent handles CRUD routes, form actions, endpoint stubs, refactors from legacy syntax to runes, and test generation well. The table shows good prompts and common failure points.

Watch the server/client boundary closely. SvelteKit compiles +page.ts for the browser, so any import from src/lib/server or any use of locals there fails or leaks. Load functions must return serializable data; SvelteKit serializes the output for the client and drops functions or Date instances unexpectedly. Form actions are another frequent issue: a success redirect must be thrown, not returned, and failed validation should return fail(400, data) so use:enhance can show errors. With Svelte 5, the agent sometimes mixes $: reactivity or onMount from legacy examples; keep your AGENTS.md explicit about the version.

Testing SvelteKit changes with Cursor Agent

Make verification part of the prompt. Ask the agent to run pnpm check after code changes; svelte-check catches prop mismatches, missing imports, and some unused variables. Run pnpm lint for style and correctness. Unit tests use Vitest; for load functions, export them and invoke with a mock event object containing locals, params, url, and fetch. Have the agent write tests alongside changes for new util functions and server logic. For end-to-end coverage, Playwright tests live in the e2e folder and run against a dev server. When a route changes, ask the agent to update the affected Playwright spec and run pnpm test:e2e. Always review the diff before accepting; git diff -- src/routes is the fastest way to see whether unrelated files were touched. If the agent changes svelte.config.js or package.json, ask why before proceeding.

Parallel SvelteKit work with AgentVera

AgentVera is a desktop app that runs Cursor Agent and other CLI coding tools side by side in real terminal panels. For SvelteKit work, the most useful features are parallel agents in separate git worktrees, automatic code review with file:line findings, and checkpoints that let you undo a whole turn. You can have one agent add a route while another writes tests without them overwriting each other. The review step catches server/client boundary mistakes, and checkpoints make it safe to try a risky Svelte 5 conversion. See Best tools to run AI coding agents in parallel (2026) for the broader workflow.

Final recommendations

Cursor Agent is a practical fit for SvelteKit when you give it a short, explicit AGENTS.md and keep changes small. Plan first, run the check and test commands after every turn, and review diffs around routes, load functions, and form actions. With those habits, the agent can handle substantial SvelteKit work without turning your project into a mess.