Monorepo template for creating a modern web application.

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

• 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

• 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

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

• Bun
• Docker (for local database)

# 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.

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!)

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

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

# Development Workflow

# Start development servers
bun --filter api start          # Start Supabase API (port 54321)
bun dev                         # Start all development servers
# Or specific apps:
bun --filter web dev            # Start web app only (port 5173)
bun --filter pages dev          # Start static site only (port 3000)

# Build and generate
bun --filter api generate       # Generate TypeScript types from Supabase
bun --filter web build          # Build web application
bun --filter pages build        # Build static site

# Quality assurance
bun lint                        # Run linting across all apps
bun --filter web test           # Test web app
bun --filter pages test         # Test static site

# Code formatting
bun format                      # Format code across all apps

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

cd apps/web
bun dev              # Start development server (port 5173)
bun build            # Build for production
bun preview          # Preview production build
bun test             # Run Vitest tests
bun lint             # Run linting

cd apps/pages
bun dev              # Start development server (port 3000)
bun build            # Build static site with Tailwind CSS
bun test             # Validate links, images, and accessibility (Note: Delete tests/external-links.txt before bun test to update URL tracking)
bun lint             # Run HTML validation with markuplint
bun run deploy       # Deploy to server (rsync)

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

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 generate to update types

Common components and types are available through the @repo/shared package:

// Import UI components
import { Button } from '@repo/shared/components/ui/button';
import * as Card from '@repo/shared/components/ui/card';

// Import shared types
import type { UserProfile } from '@repo/shared/types/user';

// Import constants
import { DEFAULT_EASE } from '@repo/shared/constants/easing';

You can easily switch between development and production environments:

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

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

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
PUBLIC_GA4_MEASUREMENT_ID=G-XXXXXXXXXX  # Optional

• 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

• Use bun run deploy command in apps/pages
• Configure server details in deployment script
• Direct file transfer to your server

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

• Package Manager Migration:
  • Migrated from pnpm to Bun as the primary package manager
  • All pnpm commands must be replaced with bun equivalents
  • Replaced pnpm-lock.yaml with bun.lock
• Build System Updates:
  • Updated Turborepo filter syntax for GitHub Actions
  • Fixed Vercel deployment configurations for bun compatibility
  • Added generic build task to turbo.json

• Shared Package Introduction:
  • Created @repo/shared package for common components, types, and utilities
  • Moved all UI components from apps/web/src/lib/components/ui/ to packages/shared/
  • Migrated shared types (UserProfile) and constants (easing) to shared package
  • Updated all imports to use @repo/shared package instead of local paths
  • Centralized Tailwind CSS configuration and base styles in shared package
  • Applications now import shared CSS using @source directive

• Database Schema Changes:
  • Reset and restructured Supabase database schema with improved type definitions
  • Added updated_at columns to profiles and comments tables
  • Enhanced RLS policies with more granular permissions
  • Updated TypeScript types to reflect new schema structure
• Project Structure Optimization:
  • Removed deprecated apps/backend directory completely
  • Streamlined development workflow with automatic .env file generation
  • Updated all references and documentation to use apps/api consistently
• Application Structure:
  • Renamed apps/mockup to apps/pages for better clarity and purpose alignment
  • Removed deprecated commands/use-mockup.js script and related references
  • Updated all import paths and package references to use the new naming convention
• Deployment Configuration:
  • Separated Vercel deployment configurations for independent app deployment
  • Moved root-level vercel.json to apps/web/vercel.json
  • Added separate apps/pages/vercel.json for static site deployment
  • Each application now deploys independently with its own configuration
• Configuration Updates:
  • Enhanced Supabase configuration with comprehensive settings
  • Updated Turbo configuration to include all necessary environment variables
  • Improved Prettier and linting configurations for new structure
• Environment Setup:
  • Updated .env.example with comprehensive Supabase environment variables
  • Enhanced environment configuration documentation with clearer setup instructions
  • Improved local and production environment switching guidance

• Directory Structure:
  • Renamed apps/backend to apps/api for better semantic clarity
  • Updated all references in documentation, scripts, and configuration files

• Infrastructure Requirements:
  • Node.js v22 is now required (added .node-version file)
• Supabase Integration:
  • Restructured Supabase type flow: Direct import from apps/api/$generated/ instead of apps/web/src/lib/$generated/
  • Enhanced database schema with complete type generation
• Build System:
  • Updated Vercel deployment configuration with new build commands
  • Replaced concurrently with npm-run-all2 for better performance
• Development Tools:
  • Enhanced ESLint configuration with modular structure
  • Restructured shared packages with proper TypeScript builds

• Update Framework/Library Versions:
  • Switch to Svelte 5 (integrated with TypeScript and using the Rune)
  • Update to Tailwind CSS 4 (removed tailwind.config.js)
  • Upgrade to ESLint 9 and implement Flat Config
• API Change:
  • Replace Nhost with Supabase for API services

• Language Reversion and Documentation:
  • Reverted codebase from TypeScript back to JavaScript, supplementing with JSDoc for documentation

• Frontend Framework Change:
  • Switched from Next.js to SvelteKit for the frontend framework in apps/web
• Repository Rebranding:
  • Renamed nextjs-template repository to webapp-template

• API Services Integration:
  • Replaced individual Firebase and Hasura applications with a unified Nhost application in apps/nhost