Developer Getting Started Guide

Welcome to the Refresh App Web project! This guide will help you get up and running with your local development environment.

Prerequisites

Before you begin, ensure you have the following installed:

Required Tools

• Node.js 22.16+ - Download

• pnpm 9.10+ - Install via npm install -g pnpm

• Git - Download

• AWS CLI - Installation Guide

Optional Tools

• Wrangler CLI - Cloudflare Workers CLI (installed via pnpm)

• VS Code - Recommended IDE with Svelte extension

Account Access

You need access to:

• GitHub Repository: refresh-os/app-web (for code and CI/CD)

• AWS Account: Development account (469718319213) for SSM parameters

• Neon Database: Dev database connection

• Cloudflare Account: For Workers and Pages deployments

Required Credentials

1. AWS Profile: ref-dev configured via aws configure sso

2. Neon Database URL: Development Postgres connection string

3. OAuth Credentials: Google and Microsoft OAuth client IDs/secrets

4. Cloudflare API Token: For deployments

---

Day 1: Initial Setup

Step 1: Clone the Repository

git clone https://github.com/refresh-os/app-web.git
cd app-web

Step 2: Install Dependencies

pnpm install

This command will:

1. Install all Node.js dependencies

2. Set up Svelte, SvelteKit, and related tools

3. Install development tools (TypeScript, ESLint, Prettier)

Expected output:

Progress: resolved 1234, reused 1200, downloaded 34, added 1234, done
✓ Dependencies installed successfully

Step 3: Configure AWS SSO

Configure AWS CLI for the development account:

aws configure sso

Follow the prompts:

• SSO start URL: https://refresh.awsapps.com/start

• SSO Region: us-east-1

• Choose the dev account: 469718319213

• Default output format: json

• Profile name: ref-dev

Step 4: Fetch Environment Variables

Download environment variables from AWS SSM:

chmod +x scripts/fetch-ssm-params-local.sh
./scripts/fetch-ssm-params-local.sh dev .dev.vars

This fetches all secrets and configuration from AWS SSM Parameter Store.

Step 5: Create .env File

mv .dev.vars .env

See Reference: Configuration for required variables.

Step 6: Run Database Migrations

Apply database migrations to your local development database:

pnpm drizzle-kit migrate

Expected output:

Migrations applied:
  ✓ 0000_initial_schema.sql
  ✓ 0001_add_tenants.sql
  ✓ 0002_add_rls_policies.sql
All migrations applied successfully

Step 7: Start Development Server

pnpm dev

The app will be available at:

• HTTP: http://localhost:5173

• HTTPS (if certs exist): https://localhost:5173

Expected output:

VITE v6.3.6  ready in 1234 ms

➜  Local:   http://localhost:5173/
➜  Network: use --host to expose
➜  press h + enter to show help

Step 8: Verify Setup

1. Open http://localhost:5173 in your browser

2. You should see the login page

3. Click "Sign in with Google"

4. Complete OAuth flow

5. You should be redirected to the dashboard

If you see the dashboard, your setup is complete! 🎉

---

Day 2: First Code Change

Step 1: Create a Feature Branch

git checkout -b feature/my-first-change

Step 2: Make a Simple Change

Edit src/routes/(authenticated)/app/+page.svelte:

<script lang="ts">
	const { data } = $props();
</script>

<h1>Welcome to Refresh, {data.sessionUser.name}!</h1>
<!-- Add your name here -->
<p>Modified by: Your Name</p>

Save the file. The dev server will automatically reload.

Step 3: Run Tests

pnpm test

Ensure all tests pass before committing.

Step 4: Format and Lint

pnpm format
pnpm lint

This will:

1. Format code with Prettier

2. Run ESLint checks

3. Fix auto-fixable issues

Step 5: Commit Your Changes

git add .
git commit -m "docs: add developer name to dashboard"
git push origin feature/my-first-change

Step 6: Create a Pull Request

1. Go to GitHub repository

2. Click "New Pull Request"

3. Select your branch

4. Add description of changes

5. Request review from team member

Your PR will trigger:

• CI/CD checks (linting, type checking, tests)

• PR sandbox deployment to Cloudflare

• Code review from team

---

Common Tasks

Running the App Locally

pnpm dev                 # Development server with hot reload
pnpm build              # Production build
pnpm preview            # Preview production build

Database Tasks

pnpm db:generate        # Generate migration from schema changes
pnpm db:migrate         # Apply migrations
pnpm db:push            # Push schema changes directly (dev only)
pnpm db:studio          # Open Drizzle Studio (DB GUI)

Testing

pnpm test               # Run all tests
pnpm test:unit          # Run unit tests with watch mode
pnpm check              # TypeScript type checking
pnpm check:watch        # Type checking in watch mode

Code Quality

pnpm format             # Format code with Prettier
pnpm lint               # Run ESLint

Wrangler (Cloudflare)

pnpm wrangler:login     # Login to Cloudflare
pnpm wrangler:dev       # Run with Wrangler dev server
pnpm wrangler:deploy    # Deploy to Cloudflare

---

Project Structure

src/
├── routes/           # SvelteKit routes
│   ├── (authenticated)/  # Authenticated routes
│   ├── api/          # API endpoints
│   └── auth/         # Auth pages
├── lib/
│   ├── components/   # Reusable components
│   ├── server/       # Server-only code (auth, db, api)
│   └── types/        # TypeScript types
└── hooks.server.ts   # Server hooks (middleware)

---

Daily Workflow

1. Create branch: git checkout -b feature/my-feature

2. Make changes, test: pnpm dev, pnpm test, pnpm check

3. Commit: git commit -m "feat: add feature"

4. Push and create PR

5. After approval → Merge → Auto-deploy to dev

See Code Standards and Local Development for details.

---

Troubleshooting

Environment Variables Not Loading

Problem: App fails to start with missing environment variables

Solution:

1. Ensure .env file exists in project root

2. Re-fetch from SSM: ./scripts/fetch-ssm-params-local.sh dev .dev.vars

3. Verify AWS credentials: aws sso login --profile ref-dev

Database Connection Failed

Problem: Cannot connect to Neon database

Solution:

1. Check WRITE_DATABASE_URL in .env

2. Verify Neon database is running

3. Check your IP is whitelisted in Neon console

4. Test connection: psql $WRITE_DATABASE_URL

Port Already in Use

Problem: Error: Port 5173 is already in use

Solution:

# Find and kill process using port 5173
lsof -ti:5173 | xargs kill -9

# Or use a different port
PORT=5174 pnpm dev

TypeScript Errors

Problem: Type checking fails

Solution:

# Regenerate SvelteKit types
pnpm prepare

# Run type checker
pnpm check

Build Fails

Problem: pnpm build fails with errors

Solution:

1. Clear .svelte-kit directory: rm -rf .svelte-kit

2. Reinstall dependencies: rm -rf node_modules && pnpm install

3. Check for TypeScript errors: pnpm check

4. Review build logs for specific errors

---

Next Steps

Now that you're set up, explore:

1. Local Development Guide - Learn about hot reload, debugging, and Wrangler

2. Authentication Guide - Understand Auth.js and JWT implementation

3. Database Guide - Work with Drizzle ORM and RLS

4. Testing Guide - Write tests with Vitest

5. Code Standards - Follow team coding conventions

---

Getting Help

• Documentation Issues: Create an issue in the GitHub repository

• Technical Questions: Ask in the #dev-app-web Slack channel

• Bug Reports: Create a GitHub issue with reproduction steps

• Feature Requests: Discuss with the team before implementing

---

Onboarding Checklist

• Install required tools (Node.js, pnpm, AWS CLI)

• Clone repository

• Configure AWS SSO

• Install dependencies

• Fetch environment variables

• Run database migrations

• Start development server

• Make first code change

• Run tests and linting

• Create first pull request

• Review architecture documentation

• Join team Slack channels

• Schedule onboarding meeting with team lead

---

Last updated: October 2025