Local Setup

This guide walks you through setting up Pixelflare for local development. The setup script handles most of this automatically, but this page explains what each step does and how to troubleshoot if something goes wrong.

Prerequisites

Before you start, you'll need these tools installed:

Node.js 20+

The project requires Node.js 20 or higher (22 recommended). Check your version:

node --version

If you need to install or update Node.js, grab it from nodejs.org or use a version manager like nvm or fnm.

pnpm 9+

I use pnpm for package management. It's faster than npm and handles the monorepo workspace well. Check if you have it:

pnpm --version

If not, install it:

npm install -g pnpm

Or see the pnpm installation docs for other options.

Wrangler (installed automatically)

Wrangler is Cloudflare's CLI for Workers development. It's included as a dev dependency, so you don't need to install it globally - it gets installed when you run pnpm install.

Quick Setup

The fastest way to get running:

git clone https://github.com/lissy93/pixelflare.git
cd pixelflare
pnpm install
pnpm setup:local
pnpm dev

Then open http://localhost:5173.

What the Setup Script Does

The scripts/setup-local.sh script (run via pnpm setup:local) handles these steps:

1. Checks required tools

Verifies that node, pnpm, and npx are available. If any are missing, it tells you what to install.

2. Creates environment files

Copies /.env.example to /.env and packages/frontend/.env.example to packages/frontend/.env. These contain sensible defaults for local development - you don't need to change anything to get started.

3. Creates worker secrets file

Creates /.dev.vars with local development secrets:

TURNSTILE_SECRET_KEY=1x0000000000000000000000000000000AA
API_HASH_SECRET=local-dev-secret-change-in-production

The Turnstile key is Cloudflare's test key that always passes verification. The hash secret is just for local dev.

4. Installs dependencies

Runs pnpm install if node_modules doesn't exist yet.

5. Applies database migrations

Runs the D1 migrations to set up your local SQLite database. The migrations live in packages/database/migrations/ and create all the tables for users, images, albums, tags, etc.

6. Creates the dev user

Inserts a dev-user record into the users table. This is needed because other tables have foreign key constraints referencing the users table. Without this user, you can't create albums, upload images, etc.

Running the Dev Server

Once setup is complete:

pnpm dev

This starts three processes concurrently:

Service	URL	Description
API	localhost:8787	Cloudflare Worker running the backend
Frontend	localhost:5173	SvelteKit app
i18n	-	Watches translation files for changes

The terminal output is color-coded: blue for API, green for frontend, yellow for i18n.

Project Structure

The repo is a pnpm monorepo with these packages:

Package	Description
packages/api	Hono-based API running on Cloudflare Workers
packages/frontend	SvelteKit frontend
packages/shared	Shared types and utilities
packages/config	Shared configuration constants
packages/database	Database migrations and schema
packages/i18n	Internationalization strings
packages/gateway	CDN gateway worker
packages/docs	This documentation site
packages/tooling	Shared ESLint, Prettier, TypeScript configs

Authentication in Dev Mode

By default, local development runs in "no-auth" mode. Every request is automatically authenticated as dev-user. You don't need to log in or set up OAuth.

This is controlled by CF_ACCESS_AUD = "dev" in packages/api/wrangler.dev.toml. If you want to test with different users, you can switch to mock auth mode - see the comments in that file.

Common Issues

Database writes fail with foreign key errors

If you see errors like FOREIGN KEY constraint failed when creating albums or uploading images, the dev user probably doesn't exist. Run:

pnpm setup:local

Or manually insert the user:

npx wrangler d1 execute pixflare-db-local --local \
  --config packages/api/wrangler.dev.toml \
  --command "INSERT INTO users (owner, display_name, created_at, updated_at) VALUES ('dev-user', 'Dev User', datetime('now'), datetime('now'));"

Port already in use

If port 8787 or 5173 is taken, you'll see an error. Find and kill the process using it, or check if you already have a dev server running in another terminal.

Migrations fail

If migrations fail, your local database might be in a weird state. The nuclear option is to delete it and start fresh:

rm -rf .wrangler/state/
pnpm setup:local

Changes not showing up

The dev server has hot reload, but sometimes you need to restart it. Try stopping (Ctrl+C) and running pnpm dev again. If you changed shared packages (@pixflare/config, @pixflare/shared), you might need to rebuild them first:

pnpm build
pnpm dev

Useful Commands

pnpm dev              # Start all dev servers
pnpm build            # Build all packages
pnpm test             # Run tests
pnpm lint             # Run linters
pnpm type-check       # TypeScript type checking
pnpm setup:local      # Re-run local setup
pnpm migrate:d1:local # Apply database migrations

Next Steps

• Architecture - understand how the system fits together
• Testing - run and write tests
• Contributing - guidelines for contributing