svelte-kit-template

An opinionated SvelteKit template for agent-assisted development — best practices are documented and demonstrated in working code.

Features

• AGENTS.md — plus CLAUDE.md and .mcp.json for Claude Code
• Audit logs — all writes, opt-in reads, query blocking on failure
• Database procedures — TypeScript functions, not SQL triggers
• Custom auth — database sessions, immediate revocation, onboarding flows
• Unit, E2E tests — procedures, audit logs, session cookies

Stack

• Svelte 5 — runes, createContext, await in markup
• SvelteKit 3 — remote functions (query, form, prerender)
• Drizzle ORM 1 — Relational Queries v2, node:sqlite driver
• Vite+ — version manager (Node.js, pnpm), Oxfmt, Vitest
• Tailwind CSS, Sentry, ESLint, Playwright (E2E), and more

Development Setup

Important

This project uses vp commands — install Vite+ globally.

Note

Run scripts with vpr <script> (alias for vp run) — vp lint runs built-in Oxlint, not ESLint.

Update the toolchain and dependencies. Rerun these periodically.

Warning

The server runs every app on PM2's Node.js, which may differ in major version from the one pinned. Rerun vp env pin node@lts and test before running update-runtime — see Update Node.js and PM2.

vp upgrade                  # upgrades global to the latest version
vp migrate --no-interactive # upgrades the project to that global version

vp env pin node@lts
vp env pin pnpm@latest

vp update

Configure the environment:

• Review .env and replace placeholder values
• Create .env.development.local based on .env.[mode].local.example

Generate and apply the database migrations:

vpr db:app:generate

# Purge `drizzle/app` to reset the schema.
# Commit the migrations once you're ready to deploy.

vpr db:app:migrate:dev
vpr dev

Production Setup

• VPS guide — deployment with HTTPS
• Sentry guide — error monitoring, tracing, and alerts

Migration

Each release has a Git tag, so you can diff any two tags to see what changed and port it into your project.

You can also paste the following section into a coding agent to run the upgrade for you.

Tip

To upgrade a project based on this template, find the current version in package.json, then diff it against the target version.

# Clone the template outside the project.
git clone https://github.com/hyunbinseo/svelte-kit-template /tmp/svelte-kit-template

# List the available versions.
git -C /tmp/svelte-kit-template tag --sort=v:refname

# Diff the current version against the target.
# Tags are prefixed with `v` (e.g. `v0.0.1`).
git -C /tmp/svelte-kit-template diff <old-tag> <new-tag>

Read AGENTS.md from the cloned upstream repo first — it documents the new conventions to follow. Update the local AGENTS.md to match, and apply the relevant changes. Ask before skipping a diverged file, or before leaving existing code on an old convention — note any such exception in AGENTS.md.

Commit the result as chore: sync with svelte-kit-template@<new-version>