Skip to content
WeDanceDocs
Getting started

Quick start

Run WeDance on your own machine, against a local Postgres. Nothing here touches the production database.

Prerequisites

  • Git

    to clone the repository.

  • Bun

    the package manager and script runner (bun install, bun run …).

  • Node.js 20.19+ or 22.12+

    Nuxt 4 runs on it.

  • Docker

    for the local Postgres database.

1. Clone and install

bash
git clone https://github.com/razbakov/wedance-2026.git
cd wedance-2026
bun install

bun install also runs nuxt prepare, which generates the architecture docs data from the code.

2. Create your .env

Start from the example. For local work only the database needs a value.

bash
cp .env.example .env

Then set the database lines to the local database from the next step:

bash
# .env — local database through the dev proxy
DATABASE_URL=postgresql://dev:dev@localhost:5441/wedance
NEON_FETCH_ENDPOINT=http://localhost:4444/sql

The other keys can stay empty while you work locally: without Resend, sign-in magic links are printed to the terminal; without a Google Maps key, city search only finds cities already in the database; PostHog and Sentry do nothing without a key. Ticket checkout (Stripe) and photo uploads (Cloudinary) only work once you add your own test keys.

3. Start a local database

The app talks to Postgres through the Neon HTTP driver. Locally, a small proxy stands in for Neon, so the app runs against plain Postgres in Docker.

bash
docker run -d --name wedance-2026-dev-db \
  -e POSTGRES_USER=dev -e POSTGRES_PASSWORD=dev -e POSTGRES_DB=wedance \
  -p 5441:5432 postgres:17-alpine
bash
bun run db:push --force   # create the tables from server/database/schema.ts
bun run dev:db-proxy           # keep this running in its own terminal (port 4444)
bun run db:seed                # optional: a few sample festivals

The proxy (scripts/dev/neon-http-proxy.ts) connects to postgresql://dev:dev@localhost:5441/wedance by default; set LOCAL_PG_URL to use another database.

4. Run the app

bash
bun run dev   # http://localhost:3000

Open http://localhost:3000, and these docs at http://localhost:3000/docs. A fresh database is empty, so city and event pages show their empty states until you add data.

5. Run the tests

bash
bun run test          # unit + router tests (vitest), incl. design-system guardrails
bun run test:tokens   # only the design-token guardrails
bun run build         # production build — also regenerates the architecture docs

Tests that need a database skip themselves when none is configured. The Playwright suites (bun run test:e2e, bun run test:design) expect a running app; see docs/design-system.md.

Next

Read CONTRIBUTING.md before you open a pull request, then explore the design system and the architecture.