🚀 SvelteKit + Convex Starter

A modern, type-safe, full-stack starter template for building real-time web applications with incredible developer experience.

✨ Features

• ⚡️ SvelteKit - Modern full-stack framework with SSR, routing, and API routes
• 🎨 Svelte 5 - Revolutionary reactivity with runes ($state, $derived, $effect)
• 🗄️ Convex - Real-time database with automatic sync and type-safe queries
• 🔐 Better Auth - Flexible authentication (optional, add when needed)
• 🛠️ Runed - Powerful Svelte 5 utility library
• ⚠️ Neverthrow - Functional error handling with Result types
• 📦 Bun - Fast JavaScript runtime and package manager
• 🔒 End-to-end TypeScript - Full type safety from database to UI

🎯 Why This Stack?

• Real-time by Default: Convex automatically syncs data across clients via WebSockets
• Type-Safe Everywhere: Database schemas, API calls, and UI components are fully typed
• Developer Experience: Minimal boilerplate, maximum productivity with Svelte 5 runes
• Modern Patterns: Functional error handling, reactive utilities, and composable components
• Fast: Bun for lightning-fast installs and builds

🚀 Quick Start

Prerequisites

Install Bun:

curl -fsSL https://bun.sh/install | bash

Create a New Project

# Clone this template
git clone https://github.com/yourusername/svelte-convex-starter my-app
cd my-app

# Install dependencies
bun install

# Start development server
bun run dev

Visit http://localhost:5173 to see your app! 🎉

📦 Setup Convex (Optional)

If you want to use the real-time database:

# Install Convex
bun add convex convex-svelte

# Initialize Convex (creates convex/ directory)
bunx convex dev --once --configure=new

# Start Convex dev server (in a separate terminal)
bunx convex dev

🔐 Setup Authentication (Optional)

If you need authentication:

# Install Better Auth
bun add better-auth

# Follow the setup guide in .cursor/rules/001_quick_reference.mdc

📁 Project Structure

├── src/
│   ├── routes/          # SvelteKit routes (pages & API endpoints)
│   ├── lib/             # Shared components and utilities
│   └── app.html         # HTML template
├── convex/              # Convex backend (schemas, queries, mutations)
├── static/              # Static assets
├── .cursor/
│   └── rules/           # Comprehensive documentation for AI assistants
│       ├── 001_quick_reference.mdc
│       ├── 002_integration_example.mdc
│       └── 003_detailed_reference.mdc
└── svelte.config.js     # SvelteKit configuration

🛠️ Available Commands

# Development
bun run dev              # Start dev server
bun run dev -- --open    # Start dev server and open browser

# Building
bun run build            # Build for production
bun run preview          # Preview production build

# Code Quality
bun run check            # Type-check your code
bun run format           # Format code with Prettier
bun run lint             # Lint code

# Convex (if using)
bunx convex dev          # Start Convex dev server
bunx convex deploy       # Deploy Convex to production

📚 Documentation

This starter comes with comprehensive documentation optimized for AI assistants (Cursor, GitHub Copilot, etc.):

• Quick Reference - Essential patterns and syntax (auto-loaded)
• Integration Example - Complete full-stack todo app
• Detailed Reference - Advanced patterns and edge cases
• Tech Stack Overview - High-level overview

Key Concepts

Svelte 5 Runes

<script>
    // Reactive state
    let count = $state(0);

    // Computed values
    let doubled = $derived(count * 2);

    // Side effects
    $effect(() => {
        console.log('Count:', count);
    });
</script>

Convex Real-time Queries

<script>
    import { useQuery, useMutation } from 'convex-svelte';
    import { api } from '../convex/_generated/api';

    const posts = useQuery(api.posts.list, {});
    const createPost = useMutation(api.posts.create);
</script>

{#if $posts === undefined}
    <p>Loading...</p>
{:else}
    <ul>
        {#each $posts as post}
            <li>{post.title}</li>
        {/each}
    </ul>
{/if}

🎓 Learn More

• SvelteKit Documentation
• Svelte 5 Documentation
• Convex Documentation
• Better Auth Documentation
• Runed Documentation
• Bun Documentation

🚨 Important Notes

• Always use Bun, not npm or yarn
• Use Svelte 5 runes ($state, $derived, $effect), not Svelte 4 syntax
• Never share state on the server - causes data leakage between users
• Remote functions are enabled by default in svelte.config.js

🤝 Contributing

This is a personal starter template, but feel free to fork it and adapt it to your needs!

📝 License

MIT

Built with ❤️ using SvelteKit, Convex, and Bun