Go + SvelteKit Starter Kit

A comprehensive mono-repo starter kit for rapid full-stack development, featuring a Go backend with SvelteKit frontend. Optimized for scalability, maintainability, and developer productivity.

🚀 Features

Backend (Go)

• Go 1.24.3 - Latest Go version with modern features
• Standard Library Focus - Minimal dependencies, maximum performance
• PostgreSQL + pgx/v5 - Type-safe database operations
• sqlc - Generate type-safe Go code from SQL
• Structured Logging - Using Go's built-in slog package
• Clean Architecture - Feature-based folder structure
• Repository Pattern - Abstracted data access layer
• Docker Ready - Complete containerization setup
• Integration Tests - Comprehensive test suite
• Hot Reload - Development with Air

Frontend (SvelteKit)

• SvelteKit - Modern web framework with SSR/SPA capabilities
• TypeScript - Full type safety across the frontend
• UnoCSS - Instant atomic CSS engine with Tailwind-compatible utilities
• Custom Shortcuts - Predefined component classes and design system
• pnpm - Fast, efficient package manager
• npx bio - Fast linter and formatter (replaces ESLint/Prettier)
• CORS Handling - Seamless API communication
• Hot Reload - Instant development feedback

DevOps & Tooling

• Docker Compose - Complete development environment
• Makefile - Streamlined build processes
• Database Migrations - Version-controlled schema changes
• Health Checks - API and service monitoring
• Caddy2 Ready - Production reverse proxy configuration
• CI/CD Ready - Production deployment configuration

🌐 Port Configuration

The starter kit uses the following default ports:

Service	Development no Docker	Docker	Description
Backend API	8090	8090	Go server with REST API
Frontend	5173	8092	SvelteKit application
Database	5432	5432	PostgreSQL database
Redis	6379	6379	Redis cache (optional)
Adminer	8091	8091	Database admin UI (dev only)

🏃‍♂️ Quick Start

Prerequisites

• Go 1.24.3+
• Node.js 20+
• pnpm 8+
• Docker & Docker Compose
• PostgreSQL 17 (or use Docker)

1. Clone & Setup

# Clone the repository
git clone <repo-url>
cd go-svelte-starter

# One-command setup
make setup

2. Run Development Environment

Using docker:

make docker-up
# or
make docker-up-dev

or without docker

make dev

🗄 Database Management

Migrations

Database migrations use golang-migrate and are located in backend/internal/db/migrations/.

# Create a new migration
cd backend
make migrate-create NAME=migration_name

# Run migrations
make migrate-up

# Rollback migrations
make migrate-down

# Check status
make migrate-status

sqlc Code Generation

SQL queries in backend/internal/db/queries/ are compiled to type-safe Go code:

# Generate Go code from SQL
make sqlc-generate

Generated code appears in backend/internal/db/sqlc/.

🏗 Adding New Features

Backend Feature

Use the profiles feature as a template:

# Copy the profiles feature
cp -r backend/internal/profiles backend/internal/yourfeature

# Update:
# 1. Package names and imports
# 2. Struct names and types
# 3. Database table names in repository
# 4. Add routes to cmd/server/main.go

Frontend Pages

# Create a new route
mkdir frontend/src/routes/yourfeature
touch frontend/src/routes/yourfeature/+page.svelte

# Add API calls to lib/api.ts
# Create reusable components in src/lib/components/

🐳 Docker Deployment

Development Environment

# Start all services for development
make docker-up-dev

# Services available:
# - Frontend:  http://localhost:8092
# - Backend:   http://localhost:8090
# - Database:  localhost:5432
# - Redis:     localhost:6379
# - Adminer:   http://localhost:8091

Production Deployment

# Build and start production services
make docker-up

# Or step by step:
make docker-build   # Build images
make docker-up      # Start services

Production Build Configuration

The Go backend supports optimized production builds through Docker build arguments. Configure these in your .env files:

Backend .env:

# Go Build Configuration (for Docker builds)
CGO_ENABLED=0
GOOS=linux
GOARCH=amd64
GOAMD64=v3

📚 For detailed deployment instructions, see backend/docs/deployment.md

🌍 Caddy2 Integration

The starter kit is ready for Caddy2 reverse proxy. Use the provided Caddyfile.example:

Subdomain Configuration

# Main domain → Frontend
your-domain.com {
    reverse_proxy localhost:8092
}

# API subdomain → Backend
api.your-domain.com {
    reverse_proxy localhost:8090
}

# Admin subdomain → Adminer (dev only)
admin.your-domain.com {
    reverse_proxy localhost:8091
}

Single Domain Configuration

your-domain.com {
    # Frontend for root paths
    reverse_proxy localhost:8092

    # API routes
    handle /api/* {
        reverse_proxy localhost:8090
    }
}

🧪 Testing

Backend Tests

# Unit tests
make test

# Integration tests (automatically starts test database)
make test-integration

# Coverage report
make test-coverage

API Testing

Test the API endpoints:

# Health check
curl http://localhost:8090/health

# Profile endpoints (when running)
curl http://localhost:8090/api/profiles
curl -X POST http://localhost:8090/api/profiles \
  -H "Content-Type: application/json" \
  -d '{"email":"test@example.com","role":"Client","name":"Test User"}'

Production Checklist

• Use production environment: make env-prod
• Update database credentials in env/.env.prod
• Set secure JWT secrets
• Configure proper CORS origins
• Set up SSL certificates with Caddy2
• Configure log levels (warn/error)
• Set up monitoring and health checks
• Configure backup strategies
• Set up CI/CD pipelines
• Review all secrets and passwords in production config

🔧 Configuration Files

File	Purpose
docker-compose.yml	Container orchestration
Caddyfile.example	Reverse proxy configuration
backend/sqlc.yaml	Database code generation
backend/Makefile	Backend build automation
frontend/vite.config.ts	Build tool configuration
frontend/uno.config.ts	CSS framework configuration

🚨 Troubleshooting

Common Issues

Port conflicts:

# Check what's using ports
lsof -i :8090  # Backend
lsof -i :8092  # Frontend
lsof -i :5432  # Database

# Or change ports in .env files

Database connection issues:

# Check if PostgreSQL is running
make status

# Reset database
make db-reset

# View logs
docker-compose logs -f postgres

Frontend build issues:

# Clean and reinstall
cd frontend
rm -rf node_modules .svelte-kit
pnpm install
pnpm build

Environment configuration issues:

# Check current environment
make env-info

# Reset to development environment
make env-dev

# Copy fresh environment files
make env-copy

Go module issues:

cd backend
go mod tidy
go mod download

📝 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• SvelteKit - The web framework
• UnoCSS - The atomic CSS engine
• sqlc - SQL code generation
• pgx - PostgreSQL driver
• Caddy - The web server