SvelteKit Setup

This guide installs Auth (self-hosted user & organization management) in a SvelteKit + Convex app.
All UI code is copied into your project (shadcn-style) from @mmailaender/auth, so you own every line.

Use it for a fresh project or an existing app:

• Fresh project: follow all steps in order (start with Prerequisites).
• Existing project: skim Prerequisites and apply only what’s missing.

Prerequisites

Use these to either set up a new project or validate your existing setup.

1. Create a SvelteKit app

Note

When answering the interactive prompts in the SvelteKit scaffolder, the following choices are required to avoid styling/integration issues later:

• Step 3: select Tailwind CSS
• Step 5: select Forms (tailwindcss)

For existing projects, you can skip this section if your project already uses Tailwind and the Tailwind Forms plugin.

2. Add node types

3. Create convex.json

SvelteKit does not allow importing code from outside src/ by default. To keep Convex functions inside src/, create a convex.json next to your package.json and point the functions directory to src/convex.

4. Update svelte.config.js

Create a $convex alias so you can import Convex functions cleanly. Keep your existing config as-is and only add the alias key if it’s missing.

Setup Design System

1. Update src/app.css

2. Add data-theme="auth" to src/app.html

Setup Auth

1. Install and run the CLI

The CLI scaffolds the necessary auth files and keeps them up to date. During jsrepo init @auth/svelte, add default path to ./src and skip (press enter) the category paths questions (default paths will be set). During jsrepo add, select all files from @auth/svelte.

2. Add types

To avoid seeing type errors add the following types to src/app.d.ts

3. Add middleware

4. Update src/routes/+layout.svelte

Setup services

1. Set up a Convex dev deployment

Next, run npx convex dev. This will prompt you to log in to Convex, create a project, and save your production and deployment URLs. The dev command will then continue running to sync your functions with your dev deployment in the cloud.

2. Add Convex environment variables

Generate a secret for encryption and generating hashes. Use the command below if you have openssl installed, or generate your own however you like.

Add SITE_URL to Convex as an env variable and set the value to http://localhost:5173 for your dev environment (Vite default port).

Add the following environment variables to the .env.local file created by npx convex dev. Your dev server will pick these up automatically.

Next, choose which auth features you want to enable (email verification, organizations, etc.) and follow the corresponding guides in this docs section.