Velodex

Velodex is an open-source fixed gear platform for documenting bikes, parts, riders, and clubs.

The app is built around structured bike builds: frame details, components, photos, likes, profiles, and lightweight club activity. The goal is to make fixed gear setups easier to save, browse, compare, and share.

Features

• Explore public builds by search, city, frame material, component, and popularity
• Add bikes with photos and structured component lists
• View bike detail pages with component match discovery
• Create rider profiles with public garages
• Create clubs, manage members, and post updates
• Upload bike, profile, club, and club-post images through Supabase storage

Tech Stack

• Next.js 16 App Router
• React 19
• Clerk auth
• Supabase Postgres
• Drizzle ORM
• Supabase storage
• Zod validation
• Playwright smoke tests

Local Setup

Install dependencies:

npm install

Start Supabase locally:

supabase start

Copy the example environment file:

cp .env.example .env.local

Fill in your own Clerk development keys, then copy the local Supabase values from:

supabase status -o env

Map the Supabase output into .env.local like this:

API_URL -> SUPABASE_URL
ANON_KEY / Publishable key -> SUPABASE_PUBLISHABLE_KEY
SERVICE_ROLE_KEY / Secret key -> SUPABASE_SECRET_KEY
DB_URL -> DATABASE_URL

Reset the local database from the checked-in migrations:

supabase db reset

Start the app:

npm run dev

Open http://localhost:3000.

Environment

Required values:

NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY=
CLERK_SECRET_KEY=
SUPABASE_URL=http://127.0.0.1:54321
SUPABASE_PUBLISHABLE_KEY=
SUPABASE_SECRET_KEY=
DATABASE_URL=postgresql://postgres:postgres@127.0.0.1:54322/postgres

Optional values are documented in .env.example.

Sample Data

After the local schema is ready, seed sample builds and clubs with:

npm run seed-data

Common Commands

npm run dev
npm run build
npm run lint
npm run typecheck
npm run test:smoke
supabase start
supabase stop
supabase status
supabase db reset

Database Changes

Supabase SQL migrations are the source of truth for schema changes.

Create a migration:

supabase migration new describe_change

Verify the full local schema:

supabase db reset

Apply committed migrations to a linked Supabase project:

supabase link --project-ref <project-ref>
supabase db push

Contributing

Use your own Clerk and Supabase development resources. Do not depend on maintainer production infrastructure.

Before opening a pull request, run the relevant checks:

npm run lint
npm run typecheck
npm run build