WebApp Template

Monorepo template for creating a modern web application.

Tech Stack

• Frontend: Svelte 5 + SvelteKit + TypeScript + Tailwind CSS 4 + shadcn-svelte + Lucide Svelte + Superforms + Valibot
• API: Supabase (PostgreSQL, Auth, Realtime, Storage)
• Build System: Turborepo + Bun + Vite
• Quality Tools: ESLint 9, Prettier, CSpell, markuplint
• Development: VS Code extensions, lint-staged, husky, GitHub Actions

Apps and Packages

apps/

• api - Supabase Local Development PostgreSQL database, authentication, and API services
• web [Demo] - SvelteKit Frontend Modern web application with page-based component organization, class-based design patterns, and comprehensive Supabase integration
• pages [Demo] - Static Site Publishing High-quality static websites with URL validation, accessibility checks, and SEO optimization

packages/

• shared - Shared components, styles, types, constants, and utilities
  • UI Components: shadcn-svelte components and custom components
  • Styles: app.css - Base Tailwind CSS styles
  • Shared logic: Types, constants, and utility functions
• eslint-config - Centralized ESLint 9 configuration with Flat Config
  • Pre-configured setups: root, web (Svelte), pages (Vanilla JS)
  • eslint-config-prettier - Prettier integration
  • eslint-plugin-svelte - Svelte linting
  • eslint-plugin-simple-import-sort - Import sorting
  • eslint-plugin-jsdoc - JSDoc validation
  • eslint-plugin-unused-imports - Unused import cleanup

Architecture Overview

graph TB
    subgraph "Monorepo Structure"
        subgraph "apps/"
            web["web<br/>SvelteKit App"]
            pages["pages<br/>Static Site"]
            api["api<br/>Supabase"]
        end

        subgraph "packages/"
            shared["shared<br/>Components & Utils"]
            eslint["eslint-config<br/>Linting Rules"]
        end

        web --> shared
        web --> api
        web --> eslint
        pages --> eslint
        shared --> eslint
    end

    subgraph "External Services"
        supabase["Supabase Cloud<br/>Production DB"]
    end

    api -.-> supabase

Loading

Quick Start

Prerequisites

• Bun
• Docker (for local database)

Starting Development

# Install dependencies (.env file is created automatically)
bun install

# For static site development
bun --filter pages dev

# For web app development
bun --filter api start    # Start Supabase API
bun --filter api generate # Generate TypeScript types (only when schema changes)
bun --filter web dev      # Start web development server

Note: TypeScript types are committed to the repository, so you only need to run generate when the database schema changes.

Environment Configuration

After running bun install, a .env file is automatically created from .env.example. Fill in the required values:

For local development:

• PUBLIC_SUPABASE_URL - http://127.0.0.1:54321
• PUBLIC_SUPABASE_ANON_KEY - Copy the anon key displayed when running bun --filter api start

For production deployment:

• PUBLIC_SUPABASE_URL - https://[project-id].supabase.co
• PUBLIC_SUPABASE_ANON_KEY - Get from Supabase Dashboard > Project Settings > API Keys

Optional (for advanced operations):

• DATABASE_URL - Enables bun --filter api push/pull to target production database
• SUPABASE_SERVICE_ROLE_KEY - Server-side admin access for Edge Functions, Webhooks (never use in browser!)

VS Code Extensions (Recommended)

• Svelte for VS Code
• ESLint
• Prettier
• Tailwind CSS IntelliSense
• EditorConfig

Available Commands

Root Level Commands

Run across every app and package from the repo root:

bun install      # Install dependencies (.env file is created automatically)
bun run dev      # Start all development servers
bun run build    # Build all apps and packages
bun run check    # Type-check all apps
bun run lint     # Lint all apps and packages
bun run format   # Format all apps and packages
bun run test     # Run all tests

Use bun run <script>, not bare bun <script> — names like build and test would otherwise launch Bun's built-in bundler and test runner instead of the package script.

Run a package's own script directly with Bun's filter — use this for most day-to-day package commands:

bun --filter api start       # Start Supabase API (port 54321)
bun --filter api generate    # Regenerate API types after schema changes
bun --filter web dev         # Start the web app only (port 5173)
bun --filter pages dev       # Start the static site only (port 3000)
bun --filter pages deploy    # Deploy the static site

Scope a graph task to one package with Turbo when you specifically want dependency-aware execution and caching. Always use turbo run <task> (the bare turbo <task> shorthand clashes with built-in commands like generate):

bun turbo run build --filter web      # Build only web (and its dependencies)
bun turbo run check --filter web      # Type-check only web
bun turbo run generate --filter api   # Regenerate API types with Turbo caching

App-Specific Commands

API (Supabase)

cd apps/api
bun run start        # Start Supabase locally
bun run stop         # Stop Supabase
bun run status       # Show Supabase service status
bun run reset        # Reset database and regenerate types
bun run generate     # Generate TypeScript types
bun run test         # Run Supabase tests
bun run lint         # Run linting
bun run format       # Format code

Web App

cd apps/web
bun run dev          # Start development server (port 5173)
bun run build        # Build for production
bun run preview      # Preview production build
bun run check        # Run type checking with svelte-check
bun run check:watch  # Type checking in watch mode
bun run test         # Run tests
bun run test:watch   # Run tests in watch mode
bun run lint         # Run linting
bun run format       # Format code

Pages (Static Site Publishing)

cd apps/pages
bun run dev              # Start development server (port 3000)
bun run build            # Build static site with Tailwind CSS
bun run test             # Validate links, images, and accessibility
bun run test:watch       # Run tests in watch mode
bun run test:update      # Update test snapshots such as tests/external-links.txt
bun run lint             # Run HTML validation with markuplint
bun run format           # Format with Prettier
bun run deploy           # Deploy public/ to DEPLOY_TARGET with rsync

# Optimization Utilities
bun run add-size-to-img       # Add width/height to <img> tags for better performance
bun run clean-images          # Remove unused images from project
bun run clean-images --dry-run # Preview unused image removals

Port Configuration

Service	Port	Description
Supabase API	54321	REST API, GraphQL, Storage
Supabase DB	54322	PostgreSQL database
Supabase Studio	54323	Admin dashboard
Supabase Inbucket	54324	Email testing
Web App	5173	SvelteKit development server
Pages	3000	Static site with BrowserSync

Type Safety and Environment Switching

Supabase Type Generation

TypeScript types are automatically generated from your Supabase database schema:

1. Local Development: Types are generated to apps/api/$generated/types.ts
2. Frontend Usage: Types are imported from the api package (e.g., import type { Database } from 'api/types')
3. After Schema Changes: Run bun --filter api generate to update types

Shared Components and Types

Common components, types, and constants are imported from the @repo/shared package. See packages/shared for the available exports and usage examples.

Environment Switching

You can easily switch between development and production environments:

1. For Development: Use local Supabase (started with bun --filter api start)
2. For Production Testing: Update .env with production Supabase credentials
3. Type Safety: Types are committed to repository for CI/CD compatibility

Deployment

Vercel Deployment

The project supports deploying both apps as separate Vercel projects. Each app includes its own vercel.json configuration file.

Web App (SvelteKit)

Configuration:

• Framework Preset: SvelteKit
• Root Directory: apps/web
• Build Command: Automatically configured via apps/web/vercel.json
• Install Command: Automatically configured via apps/web/vercel.json

Environment Variables: Set the following environment variables in your Vercel project settings:

PUBLIC_SUPABASE_URL=https://your-project.supabase.co
PUBLIC_SUPABASE_ANON_KEY=your-anon-key

Static Pages

Option 1: Vercel Deployment

• Framework Preset: Other
• Root Directory: apps/pages
• Build Command: Automatically configured via apps/pages/vercel.json
• Install Command: Automatically configured via apps/pages/vercel.json
• Output Directory: public

Option 2: Server Deployment (rsync)

• Use bun run deploy command in apps/pages
• Configure DEPLOY_TARGET in apps/pages/commands/deploy.js
• Ensure SSH access and rsync are available for your target server
• Direct file transfer to your server

Setup Instructions

1. Create two separate Vercel projects from the same GitHub repository
2. Set different Root Directory for each project:
   • Web App: apps/web
   • Static Pages: apps/pages
3. Each project will use its respective vercel.json configuration
4. Configure environment variables for the web app project

Changelog

See CHANGELOG.md for highlights of notable and breaking changes. For the complete history, see the GitHub Releases.