SvelteKit Base Template

This repository serves as a production-ready base template for SvelteKit projects, providing a structured starting point for building full-stack web applications with SvelteKit, PostgreSQL, and modern tooling.

Features

• SvelteKit with TypeScript
• TailwindCSS for styling
• PostgreSQL database with Docker Compose
• Graphile Migrate for database migrations
• Kysely for type-safe database queries
• Kysely Codegen for automatic type generation
• Zod for schema validation

Quick Start

1. Use This Template

Click "Use this template" on GitHub or clone this repository:

git clone <your-repo-url>
cd <your-project-name>

2. Essential Configuration Changes

Before starting development, you should update the following:

Update Project Directory

1. project/: Rename the project directory to match your project name.

   mv project your-project-name
   

Update Project Name

1. package.json: Change the name field in /project/package.json:

   {
     "name": "your-project-name"
   }
   

Update Docker Compose Configuration

2. docker-compose.yml: Update container names and database names:

   services:
     postgres:
       container_name: your-project-name_postgresql
       environment:
         POSTGRES_DB: your-project-name
         POSTGRES_USER: postgres
         POSTGRES_PASSWORD: your-secure-password
   
     pgweb:
       container_name: your-project-name_pgweb
       environment:
         DATABASE_URL: postgres://postgres:your-secure-password@postgres:5432/your-project-name?sslmode=disable
   

Set Up Environment Variables

3. Environment files: Copy and configure environment variables:

   cd project
   cp .env.example .env.development
   cp .env.example .env.production  # if needed
   

4. Update database URLs in your environment files:

   # .env.development
   DATABASE_URL=postgresql://postgres:your-secure-password@localhost:5432/your-project-name
   SHADOW_DATABASE_URL=postgresql://postgres:your-secure-password@localhost:5432/your-project-name_shadow
   ROOT_DATABASE_URL=postgresql://postgres:your-secure-password@localhost:5432/postgres
   

3. Install Dependencies

cd project
npm install

4. Start Development

# This will start Docker services, watch for current migrations, and start the dev server
npm run dev

# Or start services individually:
npm run docker:up     # Start PostgreSQL and pgweb
npm run dev:sveltekit # Start only the SvelteKit dev server

5. Database Setup

The template includes migration tooling. To set up your database schema:

1. Write your first migration in /project/migrations/current.sql
2. Run migrations:

   npm run gm:dev commit
   

3. Generate type-safe database schema:

   npm run kysely-codegen:db   # Generate Kysely types
   npm run kysely-codegen:zod  # Generate Zod schemas
   

If running npm run dev, the current migration will automatically be watched and applied, and the codegen tasks will run after every current migration.

Available Scripts

From the /project directory:

• npm run dev - Start development with Docker services
• npm run dev:sveltekit - Start only SvelteKit dev server
• npm run build - Build for production
• npm run preview - Preview production build
• npm run docker:up - Start Docker services
• npm run docker:down - Stop Docker services
• npm run gm:dev - Run Graphile Migrate commands
• npm run kysely-codegen:db - Generate database types
• npm run kysely-codegen:zod - Generate Zod schemas

Services

When running npm run dev or npm run docker:up:

• SvelteKit app: http://localhost:5173
• pgweb (database admin): http://localhost:8081
• PostgreSQL: localhost:5432

Project Structure

project/
├── src/
│   ├── lib/
│   │   ├── generated/     # Auto-generated DB types and Zod schemas
│   │   └── server/        # Server-side utilities
│   └── routes/            # SvelteKit routes
├── migrations/            # Database migrations
├── static/               # Static assets
└── scripts/              # Utility scripts

Additional Configuration

Customize Database Schema Generation

• Edit .kysely-codegenrc.ts for Kysely type generation
• Edit .kysely-zod-codegenrc.ts for Zod schema generation

Environment-Specific Settings

Create additional environment files as needed:

• .env.development - Development settings
• .env.staging - Staging settings
• .env.production - Production settings