Local Development Guide

This guide covers running the Refresh App Web locally, debugging techniques, hot reload, and working with Wrangler for Cloudflare Workers development.

Running Locally

Standard Vite Development Server

The default development workflow uses Vite's dev server with hot module replacement (HMR):

pnpm dev

This starts the app at http://localhost:5173 with:

• ✅ Hot Module Replacement (HMR)

• ✅ Fast refresh

• ✅ Source maps for debugging

• ✅ TypeScript checking

• ✅ HTTPS support (if certs exist)

When to use: Regular feature development, UI work, component development

Wrangler Development Server

For testing Cloudflare Workers-specific features:

pnpm wrangler:dev

This runs your app in a local Workers environment with:

• ✅ R2 bucket access (local simulation)

• ✅ Environment variables from .dev.vars

• ✅ Workers runtime behavior

• ⚠️ Slower reload than Vite

When to use: Testing R2 uploads, Workers bindings, production-like environment

HTTPS Development

For testing OAuth flows (requires HTTPS redirect URIs):

1. Generate self-signed certificates:

mkdir -p certs
cd certs

# Generate key and certificate
openssl req -x509 -newkey rsa:4096 -keyout key.pem -out cert.pem -days 365 -nodes

1. Vite will auto-detect certs:

Vite config automatically looks for certs/key.pem and certs/cert.pem:

// vite.config.ts
if (command === 'serve') {
	const certsPath = path.join(__dirname, 'certs');
	if (fs.existsSync(certsPath)) {
		config.server.https = {
			key: fs.readFileSync(path.join(certsPath, 'key.pem')),
			cert: fs.readFileSync(path.join(certsPath, 'cert.pem'))
		};
	}
}

1. Start dev server:

pnpm dev

Access at https://localhost:5173 (accept self-signed cert warning)

---

Hot Module Replacement (HMR)

How HMR Works

Vite's HMR preserves application state while updating code:

1. You save a file

2. Vite detects the change

3. Only the changed module is reloaded

4. Page updates without full refresh

5. Component state is preserved (when possible)

HMR-Friendly Code

✅ Good - State preserved:

<script>
	let count = $state(0);
</script>

<button onclick={() => count++}>
	Count: {count}
</button>

When you edit this file and save, count value is preserved.

⚠️ Tricky - State may reset:

<script>
	import { browser } from '$app/environment';

	let data = $state([]);

	if (browser) {
		fetch('/api/data')
			.then((r) => r.json())
			.then((d) => (data = d));
	}
</script>

Side effects in module scope may re-run on HMR.

✅ Better - Use $effect:

<script>
	let data = $state([]);

	$effect(() => {
		fetch('/api/data')
			.then((r) => r.json())
			.then((d) => (data = d));
	});
</script>

Disabling HMR for a File

If HMR causes issues, force full reload:

// +page.server.ts
if (import.meta.hot) {
	import.meta.hot.decline();
}

---

Debugging

Browser DevTools

Chrome/Edge DevTools:

1. Open DevTools (F12)

2. Go to Sources tab

3. Find your file in src/

4. Set breakpoints

5. Reload page or trigger code path

Source Maps: Vite generates source maps automatically in dev mode, so you see original TypeScript/Svelte code.

VS Code Debugging

Create .vscode/launch.json:

{
	"version": "0.2.0",
	"configurations": [
		{
			"type": "chrome",
			"request": "launch",
			"name": "Launch Chrome against localhost",
			"url": "http://localhost:5173",
			"webRoot": "${workspaceFolder}/src",
			"sourceMaps": true
		}
	]
}

Usage:

1. Start dev server: pnpm dev

2. Press F5 in VS Code

3. Chrome opens with debugger attached

4. Set breakpoints in VS Code

5. Debug in VS Code instead of browser

Server-Side Debugging

Console Logging:

// +page.server.ts
export const load: PageServerLoad = async ({ locals }) => {
	const session = await locals.auth();
	console.log('Session:', session); // Appears in terminal

	return { data: session };
};

Node Debugger:

NODE_OPTIONS='--inspect' pnpm dev

Then in Chrome, go to chrome://inspect and click "inspect" on your Node process.

Wrangler Tail (Production Logs)

Stream real-time logs: npx wrangler tail --env production. See Reference: CLI Commands.

---

Database Development

Drizzle Studio

Visual database editor:

pnpm db:studio

Opens at https://local.drizzle.studio with:

• Browse all tables

• Edit data directly

• Run queries

• View relationships

Making Schema Changes

Workflow:

1. Edit schema file:

// src/lib/server/db/schema/users.ts
export const users = pgTable('users', {
	id: text('id').primaryKey(),
	name: text('name').notNull(),
	// Add new field
	phoneNumber: text('phone_number')
});

1. Generate migration:

pnpm db:generate

Creates a new file in drizzle/migrations/.

1. Review migration SQL:

-- drizzle/migrations/0012_add_phone_number.sql
ALTER TABLE "users" ADD COLUMN "phone_number" text;

1. Apply migration:

pnpm db:migrate

1. Verify in Drizzle Studio:

pnpm db:studio

1. Commit migration file:

git add drizzle/migrations/0012_add_phone_number.sql
git commit -m "db: add phone_number to users table"

Development Database Resets

Reset entire database:

# Drop all tables (DESTRUCTIVE)
psql $WRITE_DATABASE_URL -c "DROP SCHEMA public CASCADE; CREATE SCHEMA public;"

# Re-apply all migrations
pnpm db:migrate

Seed development data:

Create scripts/seed-dev-data.ts:

import { db } from './src/lib/server/db';
import { users, tenants } from './src/lib/server/db/schema';

async function seed() {
	// Insert test tenant
	await db.insert(tenants).values({
		tenantName: 'Test Org',
		description: 'Development test organization'
	});

	console.log('Seed complete');
}

seed();

Run: tsx scripts/seed-dev-data.ts

---

Environment Variables

Loading Environment Variables

Priority (highest to lowest):

1. .env.local (git-ignored, local overrides)

2. .env (git-ignored, main config)

3. .env.example (git-tracked, template)

Fetching from AWS SSM

# Fetch dev environment variables
./scripts/fetch-ssm-params-local.sh dev .dev.vars

# Move to .env
mv .dev.vars .env

Managing Secrets Locally

Never commit secrets to git:

# .gitignore already includes:
.env
.env.*
!.env.example

Add new secret:

1. Add to AWS SSM:

aws ssm put-parameter \
  --profile ref-dev \
  --name "/app-web/dev/NEW_SECRET" \
  --value "secret-value" \
  --type "SecureString"

1. Re-fetch environment variables:

./scripts/fetch-ssm-params-local.sh dev .dev.vars
mv .dev.vars .env

1. Restart dev server

---

Testing Locally

Unit Tests

# Run all tests
pnpm test

# Run tests in watch mode
pnpm test:unit

# Run specific test file
pnpm test src/lib/components/Button.test.ts

Type Checking

# One-time check
pnpm check

# Watch mode
pnpm check:watch

Linting and Formatting

# Format all files
pnpm format

# Run linter
pnpm lint

# Auto-fix linting issues
pnpm lint --fix

---

Working with Cloudflare Workers

Local R2 Bucket Access

Using Wrangler Dev:

pnpm wrangler:dev

Wrangler simulates R2 buckets locally. Upload/download works, but data is ephemeral.

Accessing R2 in Code:

// +page.server.ts
export const load: PageServerLoad = async ({ platform }) => {
	const bucket = platform?.env?.IMAGES_BUCKET;

	if (!bucket) {
		console.warn('R2 bucket not available (use wrangler:dev)');
		return { images: [] };
	}

	const list = await bucket.list();
	return { images: list.objects };
};

Testing Bindings

Environment Variables:

// Access via $env/static/private
import { PRIVATE_JWK_JSON } from '$env/static/private';

R2 Buckets:

// Access via platform.env
const bucket = platform?.env?.IMAGES_BUCKET;

KV Stores (if used):

const kv = platform?.env?.MY_KV_NAMESPACE;
await kv.get('key');

---

Performance Profiling

Vite Build Analysis

Generate bundle size visualization:

pnpm build

Opens dist/bundle-analysis.html showing:

• Chunk sizes

• Dependencies per chunk

• Treemap visualization

Lighthouse Testing

1. Build production version:

pnpm build
pnpm preview

1. Open http://localhost:4173

2. Run Lighthouse in Chrome DevTools

3. Review performance, accessibility, SEO scores

Monitoring HMR Performance

Check Vite HMR speed:

pnpm dev

In console, look for:

[vite] hmr update /src/routes/app/+page.svelte in 45ms

If HMR is slow (>500ms), check for:

• Large dependency graphs

• Too many components

• Slow imports

---

Common Workflows

Adding a New Page

1. Create route file:

mkdir -p src/routes/(authenticated)/app/new-feature
touch src/routes/(authenticated)/app/new-feature/+page.svelte
touch src/routes/(authenticated)/app/new-feature/+page.server.ts

1. Add server load function:

// +page.server.ts
import type { PageServerLoad } from './$types';

export const load: PageServerLoad = async ({ locals }) => {
	const session = await locals.auth();

	return {
		title: 'New Feature'
	};
};

1. Create component:

<!-- +page.svelte -->
<script lang="ts">
	const { data } = $props();
</script>

<h1>{data.title}</h1>

1. Test locally:

Navigate to http://localhost:5173/app/new-feature

Adding a Component

1. Create component file:

touch src/lib/components/MyComponent.svelte

1. Implement component:

<script lang="ts">
	interface Props {
		title: string;
		onSave?: () => void;
	}

	let { title, onSave }: Props = $props();
</script>

<div class="my-component">
	<h2>{title}</h2>
	{#if onSave}
		<button onclick={onSave}>Save</button>
	{/if}
</div>

1. Use in page:

<script>
	import MyComponent from '$lib/components/MyComponent.svelte';
</script>

<MyComponent title="Hello" onSave={() => console.log('Saved')} />

Making an API Endpoint

1. Create endpoint:

mkdir -p src/routes/api/my-endpoint
touch src/routes/api/my-endpoint/+server.ts

1. Implement handler:

import { json } from '@sveltejs/kit';
import type { RequestHandler } from './$types';

export const GET: RequestHandler = async ({ locals }) => {
	const session = await locals.auth();

	if (!session?.user) {
		return json({ error: 'Unauthorized' }, { status: 401 });
	}

	return json({ data: 'Hello World' });
};

1. Test endpoint:

curl http://localhost:5173/api/my-endpoint

---

Troubleshooting

Port Already in Use

# Find process on port 5173
lsof -ti:5173

# Kill it
lsof -ti:5173 | xargs kill -9

# Or use different port
PORT=5174 pnpm dev

HMR Not Working

1. Check file watcher limits (Linux):

# Increase limit
echo fs.inotify.max_user_watches=524288 | sudo tee -a /etc/sysctl.conf
sudo sysctl -p

1. Clear Vite cache:

rm -rf node_modules/.vite
pnpm dev

TypeScript Errors

# Regenerate types
pnpm prepare

# Check for errors
pnpm check

Database Connection Issues

1. Check DATABASE_URL in .env

2. Verify Neon database is accessible

3. Test connection:

psql $WRITE_DATABASE_URL -c "SELECT 1"

---

Best Practices

1. Use HMR-friendly patterns - Avoid side effects in module scope

2. Test with Wrangler before deploying - Catch Workers-specific issues early

3. Keep .env in sync - Re-fetch from SSM when parameters change

4. Run tests before committing - pnpm test && pnpm check

5. Use TypeScript strictly - Catch errors at compile time

6. Profile performance regularly - Use Lighthouse and bundle analysis

---

Related Documentation

• Getting Started - Initial setup

• Authentication - Auth.js implementation

• Database - Drizzle ORM and migrations

• Testing - Testing strategies

• Code Standards - Team conventions

---

Last updated: October 2025