GitHub Copilot Instructions

This document provides context and guidelines for GitHub Copilot when working with the SvelteKit Starter Project.

Project Overview

This is a SvelteKit 5 Starter Template designed for fast-tracking modern web application development with authentication, database integration, and a complete UI component system.

Technology Stack

Frontend: SvelteKit 5 with TypeScript
ORM: Drizzle ORM with type-safe operations
Database: PostgreSQL (configured for Supabase)
Authentication: Better-Auth with email OTP
UI: Tailwind CSS + bits-ui components (shadcn-svelte style)
Email: Brevo (formerly Sendinblue) SMTP integration
Package Manager: pnpm
Animations: tw-animate-css
Icons: Lucide Svelte

Key Architectural Patterns

Database Schema

Better-Auth Integration: Complete user management with sessions and accounts
User Table: Email-based authentication with verification status
Session Management: Secure session storage with expiration
Account Linking: Support for OAuth providers (extensible)
Application Schema: Extensible structure in
```
src/lib/server/db/schema.ts
```
Type Safety: Full TypeScript integration with Drizzle generated types

Route Structure

```
(auth)/
```
: Authentication flows (sign-in, email verification)
```
/
```
: Public home page

File-based routing with

+page.svelte

+page.server.ts

+layout.svelte

Server hooks for session management in
```
hooks.server.ts
```

State Management

Svelte 5 runes (
```
$state
```
,
```
$derived
```
,
```
$effect
```
)
Better-Auth session management via server locals
Form validation with
```
sveltekit-superforms
```
+ Zod
Global app state via
```
app.d.ts
```
type definitions

Code Conventions

File Naming

Components:

kebab-case.svelte

(e.g.,

artist-create-form.svelte

)

Types:
```
PascalCase
```
interfaces/types
Constants:
```
UPPER_SNAKE_CASE
```
exports
Database fields:
```
snake_case
```
(Drizzle schema)

Import Patterns

// SvelteKit imports
import { goto } from '$app/navigation';
import { page } from '$app/stores'; // Standard SvelteKit store

// Better-Auth imports
import { auth } from '$lib/auth';

// Library imports
import * as Card from '$lib/components/ui/card/index.js';
import { Button } from '$lib/components/ui/button';
import { Input } from '$lib/components/ui/input';

// Database imports
import { db } from '$lib/server/db/';
import { user, session } from '$lib/server/db/schema';

// Form handling
import { superForm } from 'sveltekit-superforms';
import { zodClient } from 'sveltekit-superforms/adapters';
import { emailSchema } from '$lib/zod-schemas';

Component Structure

<script lang="ts">
	// Imports
	import { Button } from '$lib/components/ui/button';

	// Props using Svelte 5 syntax
	interface Props {
		title: string;
		optional?: boolean;
	}

	let { title, optional = false }: Props = $props();

	// State using Svelte 5 runes
	let isLoading = $state(false);

	// Derived values
	let displayTitle = $derived(title.toUpperCase());

	// Functions/event handlers
	function handleClick() {
		isLoading = true;
		// ... logic
	}
</script>

<!-- Markup with Tailwind classes and OKLCH colors -->
<div class="bg-background text-foreground">
	<Button onclick={handleClick} disabled={isLoading}>
		{displayTitle}
	</Button>
</div>

<style>
	/* Minimal custom styles - prefer Tailwind utilities */
</style>

Key Business Logic

Authentication Flow

Email-based authentication using Better-Auth
OTP verification via Brevo SMTP
Session management stored in database
Route protection via server hooks
User state available in
```
event.locals.user
```

Database Operations

Drizzle ORM with PostgreSQL adapter
Type-safe queries with generated schemas
Migration system with
```
drizzle-kit
```
Development tools including Drizzle Studio

Common Patterns

Form Handling

// Use superforms with Zod validation
import { superForm } from 'sveltekit-superforms';
import { zodClient } from 'sveltekit-superforms/adapters';
import { emailSchema } from '$lib/zod-schemas';

// In component
let { form, errors, enhance } = superForm(data.form, {
	validators: zodClient(emailSchema)
});

Authentication Actions

// Sign in with email (triggers OTP)
const response = await auth.api.signInEmail({
	body: { email }
});

// Verify OTP
const response = await auth.api.verifyEmail({
	body: { email, otp }
});

Database Queries

Use Drizzle with proper error handling and type safety

import { db } from '$lib/server/db/';
import { user } from '$lib/server/db/schema';
import { eq } from 'drizzle-orm';

// Query with type safety
const foundUser = await db.select().from(user).where(eq(user.email, email)).limit(1);

// Insert with validation
const newUser = await db
	.insert(user)
	.values({
		email: email.toLowerCase(),
		name: displayName,
		emailVerified: false
	})
	.returning();

Environment Variables

# Database (PostgreSQL)
DATABASE_URL="postgres://user:password@host:port/db-name"

# App Configuration
BETTER_AUTH_SECRET="The Secret Code"
BETTER_AUTH_URL="http://localhost:5173" # Base URL of your app

# Brevo (formerly Sendinblue) Email Configuration
BREVO_SMTP_HOST="smtp-relay.brevo.com"
BREVO_SMTP_PORT="587"
BREVO_SMTP_USER="your-brevo-smtp-login"
BREVO_SMTP_PASSWORD="your-brevo-smtp-password"
BREVO_FROM_EMAIL="[email protected]"

Development Guidelines

Available Scripts

```
pnpm dev
```
- Start development server
```
pnpm build
```
- Build for production
```
pnpm preview
```
- Preview production build
```
pnpm db:generate
```
- Generate Drizzle migrations
```
pnpm db:push
```
- Push schema to database
```
pnpm db:migrate
```
- Run database migrations
```
pnpm db:studio
```
- Open Drizzle Studio
```
pnpm lint
```
- Run ESLint and Prettier
```
pnpm format
```
- Format code with Prettier

Project Structure

src/
├── lib/
│   ├── components/
│   │   ├── auth/           # Auth-specific components
│   │   └── ui/             # shadcn-svelte UI components
│   ├── server/db/          # Database schema and client
│   ├── auth.ts             # Better-Auth configuration
│   ├── client.ts           # Database client setup
│   ├── utils.ts            # Utility functions
│   └── zod-schemas.ts      # Validation schemas
├── routes/
│   ├── (auth)/             # Authentication routes
│   ├── +layout.svelte      # Root layout
│   ├── +layout.server.ts   # Server layout logic
│   └── +page.svelte        # Home page
├── app.d.ts                # TypeScript app definitions
├── app.html                # HTML template
└── hooks.server.ts         # Server hooks (session handling)

When suggesting code:

Use TypeScript - Full type safety with Drizzle-generated types
Follow Svelte 5 - Use runes (
```
$state
```
,
```
$derived
```
,
```
$effect
```
), not legacy reactivity
Props with interfaces - Use
```
interface Props
```
with destructuring assignment
Error handling - Always wrap database calls in try/catch
Validation - Use Zod schemas from
```
$lib/zod-schemas
```
Authentication - Check
```
event.locals.user
```
for auth state
Styling - Use Tailwind utilities with OKLCH color system
Accessibility - Include proper ARIA labels and semantic HTML
Responsive - Mobile-first Tailwind classes
Better-Auth patterns - Use proper API calls for auth operations

Avoid:

Legacy Svelte 4 patterns (
```
let:
```
,
```
export let
```
)
Direct DOM manipulation (use Svelte reactivity)
Inline styles (use Tailwind utilities)
Hardcoded strings (use proper validation)
Missing error boundaries
Non-accessible components
Supabase-specific auth patterns (this uses Better-Auth)

Testing Patterns

Database Testing

Use
```
pnpm db:push
```
for development schema changes
Use
```
pnpm db:generate
```
to create migration files
Use
```
pnpm db:studio
```
for visual data inspection
Test with proper environment variables

Authentication Testing

Test email OTP flow with Brevo integration
Verify session persistence across requests
Test route protection via
```
hooks.server.ts
```
Test user state in
```
event.locals
```

Common Debugging

Database Issues

Check Drizzle schema matches actual database
Verify PostgreSQL connection string
Use
```
pnpm db:studio
```
for visual data inspection
Use
```
pnpm db:push
```
for development schema updates
Check migration files in
```
/drizzle
```
directory

Authentication Issues

Verify Better-Auth configuration in
```
src/lib/auth.ts
```
Check Brevo SMTP credentials and settings
Test email OTP delivery and verification
Verify session handling in
```
hooks.server.ts
```
Check user state in browser dev tools

Styling Issues

Verify OKLCH color variables in
```
layout.css
```
Check Tailwind class conflicts
Test responsive breakpoints
Verify shadcn-svelte component imports

Starter Template Usage

This is a starter template designed to be cloned and customized. When helping with development:

Understand it's a foundation - The code provides authentication, database, and UI foundations
Expect customization - Help adapt the starter for specific use cases
Maintain patterns - Keep the established patterns for consistency
Extend thoughtfully - Add features that complement the existing architecture

When implementing new features, follow the established patterns for database schema, authentication flows, and component structure. The starter is designed to be production-ready while remaining flexible for customization.

GitHub Copilot Instructions

Related Skills

Nano Banana Pro

Markdown Converter

1password