aMaDrOfSvelte

SvelteKit template with authentication, database, UI components, and PWA support.

Features

• SvelteKit - Full-stack web framework with Svelte 5 runes
• Tailwind CSS 4 - Utility-first CSS framework
• shadcn-svelte - UI component library
• Better Auth - Authentication with GitHub OAuth
• Drizzle ORM - Type-safe database queries
• Turso - SQLite edge database
• TypeScript - Type safety throughout
• PWA - Progressive web app with offline support

Tech Stack

Project Structure

src/
├── lib/
│   ├── components/
│   │   └── ui/           # shadcn-svelte components
│   ├── server/
│   │   ├── auth.ts       # Better Auth configuration
│   │   └── db/           # Database setup and schema
│   ├── auth-client.ts    # Client-side auth helpers
│   ├── utils.ts          # Utility functions
│   └── pwa.ts            # PWA initialization
├── routes/
│   ├── api/
│   │   └── auth/         # Auth API endpoints
│   ├── auth/             # Authentication pages
│   ├── dashboard/        # Protected dashboard
│   └── +layout.svelte    # Root layout
└── app.css               # Global styles with Tailwind

Quick Start

Prerequisites

• Node.js 18+ or Bun
• A GitHub OAuth app
• A Turso database

1. Clone and Install

git clone <repository-url>
cd aMaDrOfSvelte
bun install  # or npm install

2. Environment Setup

Copy the example environment file:

cp .env.example .env

Configure your environment variables:

# Database (Turso)
DATABASE_URL="libsql://your-database-name.turso.io"
DATABASE_AUTH_TOKEN="your-turso-auth-token"

# Authentication
BETTER_AUTH_SECRET="your-super-secret-key-min-32-chars"
BETTER_AUTH_URL="http://localhost:5173"

# GitHub OAuth
GITHUB_CLIENT_ID="your-github-client-id"
GITHUB_CLIENT_SECRET="your-github-client-secret"

# Environment
NODE_ENV="development"

3. Database Setup

Create and push your database schema:

bun run db:generate  # Generate migrations
bun run db:push      # Apply to database

Optional: Open Drizzle Studio to view your database:

bun run db:studio

4. GitHub OAuth Setup

1. Go to GitHub Developer Settings
2. Create a new OAuth App with:
   • Application name: Your app name
   • Homepage URL: http://localhost:5173
   • Authorization callback URL: http://localhost:5173/api/auth/callback/github
3. Copy the Client ID and Client Secret to your .env file

5. Start Development

bun run dev  # or npm run dev

Visit http://localhost:5173 to see your app!

Database Setup

Using Turso (Recommended)

1. Install Turso CLI:

curl -sSfL https://get.tur.so/install.sh | bash

2. Create a database:

turso db create amadrofsvelte

3. Get your database URL and create a token:

turso db show amadrofsvelte  # Get the URL
turso db tokens create amadrofsvelte  # Create auth token

4. Add the URL and token to your .env file

Alternative: Local SQLite

For local development, you can use a local SQLite file:

DATABASE_URL="file:./local.db"
# Remove or leave empty: DATABASE_AUTH_TOKEN=""

Authentication

Authentication flow:

1. Public Pages - Home page accessible to everyone
2. Protected Routes - Dashboard requires authentication
3. Auth Redirect - Unauthenticated users redirected to sign-in
4. Session Management - Persistent sessions with Better Auth
5. Sign Out - Clean session termination

Adding More OAuth Providers

Better Auth supports many providers. To add more:

1. Update src/lib/server/auth.ts:

socialProviders: {
  github: { /* existing config */ },
  google: {
    clientId: env.GOOGLE_CLIENT_ID || '',
    clientSecret: env.GOOGLE_CLIENT_SECRET || ''
  }
}

2. Add environment variables to .env
3. Update the sign-in UI in /auth page

Progressive Web App

The template includes PWA functionality with:

• Service Worker - Workbox for caching and offline support
• Web Manifest - App metadata and icon configuration
• Install Prompt - Native install prompts for supported browsers
• Offline Support - Basic caching for static assets

PWA Configuration

The PWA is configured through:

• static/manifest.json - App manifest with icons and metadata
• src/pwa.ts - Service worker registration and management
• src/lib/components/PWAInstallPrompt.svelte - Install prompt component

Customizing PWA Settings

Update static/manifest.json for app metadata:

{
    "name": "Your App Name",
    "short_name": "AppName",
    "description": "App description",
    "theme_color": "#your-color",
    "background_color": "#your-bg-color"
}

UI Components

Included components:

• Button - Multiple variants and sizes
• Card - Content containers
• Input - Form inputs
• Label - Form labels
• Alert - Status messages
• Badge - Status indicators
• Tabs - Tabbed interfaces
• Select - Dropdown selections
• Switch - Toggle controls
• Textarea - Multi-line inputs
• Separator - Visual dividers
• PWA Install Prompt - Native app installation

Adding More Components

Use the shadcn-svelte CLI or copy components manually:

npx shadcn-svelte add dialog
npx shadcn-svelte add toast

Tailwind CSS 4

Features:

• Vite Plugin: No PostCSS configuration needed
• OKLCH Colors: Modern color space support
• Custom Properties: CSS custom properties for theming
• Dark Mode: Built-in dark mode support
• Modern Features: @theme directive and more

Color System

Color system:

:root {
    --color-background: oklch(1 0 0);
    --color-foreground: oklch(0.129 0.042 264.695);
    --color-primary: oklch(0.208 0.042 265.755);
    /* ... more colors */
}

Scripts

Deployment

Vercel (Recommended)

1. Push your code to GitHub
2. Connect your repository to Vercel
3. Add environment variables in Vercel dashboard
4. Update BETTER_AUTH_URL to your production domain
5. Update GitHub OAuth callback URL

Other Platforms

Works on any Node.js platform. Update the adapter in svelte.config.js:

import adapter from '@sveltejs/adapter-node'; // or adapter-vercel, etc.

Customization

Changing the Theme

Modify colors in src/app.css:

:root {
    --color-primary: oklch(0.5 0.2 250); /* Custom blue */
    /* Update other colors as needed */
}

Adding Database Tables

1. Add tables to src/lib/server/db/schema.ts
2. Generate migrations: bun run db:generate
3. Apply changes: bun run db:push

Custom Components

Create new components in src/lib/components/:

<!-- src/lib/components/CustomButton.svelte -->
<script lang="ts">
    import { Button } from './ui/button';

    let { children, ...props } = $props();
</script>

<Button {...props}>
    {@render children?.()}
</Button>

Contributing

1. Fork the repository
2. Create a feature branch: git checkout -b feature-name
3. Make your changes
4. Run tests: bun run check
5. Commit: git commit -m 'Add feature'
6. Push: git push origin feature-name
7. Open a Pull Request

License

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

Acknowledgments

• SvelteKit for the amazing framework
• shadcn/ui for component design inspiration
• Better Auth for secure authentication
• Drizzle for type-safe database queries
• Turso for edge database hosting

Documentation

• SvelteKit
• Svelte 5 Runes
• Tailwind CSS 4
• Better Auth
• Drizzle ORM

Built for developers who want to ship fast.