SvelteKit Starter Template

A highly opinionated, production-ready starter template for SvelteKit applications, focusing on Developer Experience (DX), code quality, and modern tooling.

Philosophy & Motivation

Starting a new project often involves a repetitive "setup phase" — configuring linting, setting up authentication, wiring up a database, and ensuring type safety. This template aims to eliminate that friction.

The philosophy behind this starter is "Strict Default, Modern Stack". We believe that enforcing consistent code styles, commit conventions, and strict type checking from day one leads to more maintainable and scalable software. We've chosen a stack that combines the reliability of established tools (PostgreSQL) with the performance and developer joy of modern frameworks (Svelte 5, Tailwind 4, Bun). It's designed to let you hit the ground running with features you actually need, without the bloat you don't.

Features

This template comes pre-configured with a robust suite of tools:

🚀 Core Stack

• SvelteKit: The meta-framework for Svelte, providing a blazing fast app experience.
• Svelte 5: The latest version of Svelte with Runes for a simpler, more powerful reactivity model.
• Tailwind CSS v4: Utility-first CSS framework for rapid UI development.
• Bun: A fast all-in-one JavaScript runtime and package manager.

💾 Data & Authentication

• Drizzle ORM: A lightweight, type-safe TypeScript ORM.
• PostgreSQL: The world's most advanced open-source relational database (running in Docker).
• Clerk: Complete user management and authentication logic (via svelte-clerk).

🎨 UI & Components

• Shadcn UI: A collection of re-usable components built with Radix UI and Tailwind CSS.
• Lucide Icons: Beautiful & consistent icons.
• Dark Mode: Built-in support with mode-watcher.

🛠️ Developer Experience & Quality

• Lefthook: Fast and powerful Git hooks manager.
• Commitlint: Enforces conventional commit messages.
• ESLint & Prettier: Configured for strict linting and consistent formatting (including import sorting).
• Docker Compose: Pre-configured compose.yaml for spinning up a local PostgreSQL instance.
• Dev Container: It also provides a fully functional and pre-configured devcontainer, which is the recommended way to develop.
• VSCode Settings: Recommended extensions and workspace settings for a unified team experience.

Prerequisites

Before you start, you need to ensure you have the necessary tools installed and services configured.

1. Install Docker

You need Docker installed to run the local database and the Dev Container.

• Windows/Linux: Install Docker Desktop or Docker Engine.
• macOS: We strongly recommend using OrbStack instead of Docker Desktop for better performance and battery life.

2. Configure Clerk Authentication

You need to set up a project in Clerk for authentication.

1. Sign up/Login: Go to Clerk.com and sign in.
2. Create Application: Click on "Create Application" in the dashboard.
3. Configure Sign-in: Choose your preferred sign-in methods (e.g., Email, Google, GitHub).
4. Get API Keys: Once created, go to the API Keys section in the sidebar. You will need the Publishable key and Secret key.

Getting Started

1. Create your Repository

Click the "Use this template" button at the top of the GitHub repository to create a new repository based on this template.

2. Choose your Environment

You can develop either using a pre-configured Dev Container (recommended) or manually on your local machine.

Option A: Dev Container (Recommended)

This approach provides a fully configured environment with all dependencies and tools ready to go.

1. Open in Dev Container: Open the repository in GitHub Codespaces or VS Code with the "Dev Containers" extension.

2. Environment Setup: Create a .env file in the root.

   # .env
   # Note: 'db' is the hostname of the database service within the container network
   DATABASE_URL="postgres://root:mysecretpassword@db:5432/local"
   
   # Clerk Authentication Keys
   PUBLIC_CLERK_PUBLISHABLE_KEY=pk_test_...
   CLERK_SECRET_KEY=sk_test_...

3. Push Database Schema:

   bun db:push

4. Start Developing:

   bun dev

Option B: Local Setup

1. Clone and Install:

   git clone https://github.com/your-username/your-new-repo.git
   cd your-new-repo
   bun install

2. Environment Setup: Create a .env file in the root.

   # .env
   DATABASE_URL="postgres://root:mysecretpassword@localhost:5432/local"
   
   # Clerk Authentication Keys
   PUBLIC_CLERK_PUBLISHABLE_KEY=pk_test_...
   CLERK_SECRET_KEY=sk_test_...

3. Start the Database:

   bun stack:start

4. Push Database Schema:

   bun db:push

5. Start Developing:

   bun dev

Your app should now be running at http://localhost:5173.

Tools & Scripts

For a detailed explanation of all available scripts (development, testing, database management, etc.), please refer to the Tools Documentation.

build with ❤️ in ruhrgebiet