# SvelteKit + PostgreSQL

> SvelteKit full-stack framework with PostgreSQL database.

- Category: Full Web Stacks
- Difficulty: intermediate
- Components: sveltekit, postgres
- Tags: sveltekit, svelte, postgres, full-stack
- Source: https://docker.recipes/full-stacks/sveltekit-postgres

## Overview

SvelteKit is a modern full-stack framework built on Svelte that provides server-side rendering, static site generation, and single-page application capabilities with file-based routing and built-in performance optimizations. Born from the Svelte ecosystem, SvelteKit offers a compile-time approach that eliminates virtual DOM overhead while providing a complete application framework with TypeScript support, form actions, and universal load functions for data fetching.

This stack combines SvelteKit's lightning-fast frontend compilation and flexible rendering modes with PostgreSQL's robust ACID-compliant database engine, creating a powerful foundation for data-driven applications. PostgreSQL's advanced JSON support complements SvelteKit's modern JavaScript architecture, while its mature transaction system ensures data integrity for complex business logic handled through SvelteKit's server-side form actions and API routes.

Developers building modern web applications that require both high performance and data reliability should consider this stack, particularly when handling complex relational data, user authentication systems, or applications requiring real-time features with PostgreSQL's LISTEN/NOTIFY functionality alongside SvelteKit's WebSocket support.

## Features

- File-based routing system with automatic code splitting and lazy loading
- Server-side rendering with hydration and static site generation capabilities
- Form actions for type-safe server-side mutations without JavaScript
- Universal load functions for data fetching with automatic serialization
- PostgreSQL ACID compliance with advanced transaction support for data integrity
- JSON/JSONB support for hybrid relational-document data models
- Full-text search with ranking and highlighting capabilities
- Hot module replacement in development with instant page updates

## Use cases

- E-commerce platforms requiring complex product catalogs with inventory management
- Content management systems with hierarchical data and full-text search
- SaaS applications needing multi-tenant data isolation and user management
- Real-time dashboards combining PostgreSQL analytics with SvelteKit's reactive updates
- Progressive web applications requiring offline-first capabilities with database sync
- API-driven applications with server-side form validation and database persistence
- Documentation sites with dynamic content pulled from PostgreSQL CMS backends

## Prerequisites

- Docker and Docker Compose installed with at least 1GB RAM available
- Node.js knowledge for SvelteKit development and package management
- Basic SQL understanding for PostgreSQL database schema design
- Port 3000 available for SvelteKit development server access
- Understanding of environment variables for database connection configuration
- Familiarity with either Prisma, Drizzle, or Kysely for database ORM integration

## docker-compose.yml

```yaml
services:
  sveltekit:
    build: .
    container_name: sveltekit
    environment:
      DATABASE_URL: postgresql://${DB_USER}:${DB_PASSWORD}@postgres:5432/${DB_NAME}
    ports:
      - "3000:3000"
    depends_on:
      - postgres
    networks:
      - svelte-network

  postgres:
    image: postgres:16-alpine
    environment:
      POSTGRES_DB: ${DB_NAME}
      POSTGRES_USER: ${DB_USER}
      POSTGRES_PASSWORD: ${DB_PASSWORD}
    volumes:
      - postgres_data:/var/lib/postgresql/data
    networks:
      - svelte-network

volumes:
  postgres_data:

networks:
  svelte-network:
    driver: bridge
```

## .env

```bash
DB_NAME=sveltekit
DB_USER=sveltekit
DB_PASSWORD=changeme
```

## Usage notes

- Docs: https://kit.svelte.dev/docs
- Access at http://localhost:3000
- File-based routing in src/routes/
- SSR, SSG, SPA modes available
- Form actions for server-side mutations
- Use Prisma, Drizzle, or Kysely for database

## Troubleshooting

- SvelteKit build fails with memory errors: Increase Docker container memory limits or add NODE_OPTIONS='--max-old-space-size=4096' environment variable
- Database connection refused on startup: Ensure PostgreSQL container starts before SvelteKit by adding health checks to depends_on configuration
- Form actions return 403 CSRF errors: Configure SvelteKit's CSRF protection settings in app.html or disable for development with csrf.disable option
- Hot reload not working in development: Mount src directory as volume and ensure file watchers work with Docker using CHOKIDAR_USEPOLLING=true
- PostgreSQL data persists after container removal: Remove postgres_data volume explicitly with docker-compose down -v command
- SvelteKit adapter errors in production: Configure appropriate adapter for deployment target in svelte.config.js and rebuild container

