Skip to main content

​
Quickstart

This guide walks you through setting up folksbase on your local machine.

​
Prerequisites

Before you start, make sure you have: Optional services (features degrade gracefully without them):
  • Upstash Redis — caching and rate limiting
  • Vercel Blob — CSV file storage
  • Inngest — background job processing
  • Anthropic API key — AI-powered CSV column mapping

​
1. Clone and Install

git clone https://github.com/joselito/folksbase.git
cd folksbase
pnpm install

​
2. Configure Environment Variables

Copy the example files and fill in your values: 
cp apps/api/.env.example apps/api/.env
cp apps/web/.env.example apps/web/.env
At minimum, you need these values to get started: apps/api/.env — backend configuration:
VariableDescription
DATABASE_URLNeon Postgres connection string
SUPABASE_URLYour Supabase project URL
SUPABASE_PUBLISHABLE_KEYSupabase anon/public key
SUPABASE_SECRET_KEYSupabase service role key
ENCRYPTION_KEY64-char hex string for AES-256-GCM encryption
Generate an encryption key with: 
node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"
apps/web/.env — frontend configuration:
VariableDescription
NEXT_PUBLIC_API_URLhttp://localhost:3001/api
NEXT_PUBLIC_SUPABASE_URLYour Supabase project URL
NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEYSupabase anon/public key
See the Environment Variables page for the full list of configuration options.

​
3. Set Up the Database

Push the Drizzle schema to your Neon database: 
pnpm --filter @folksbase/db db:push
Optionally, seed the database with sample data: 
pnpm --filter @folksbase/db seed

​
4. Start Development

Run all apps in dev mode with a single command: 
pnpm dev
This starts:
AppURL
Web (Next.js)http://localhost:3000
API (Hono)http://localhost:3001

​
5. Verify It Works

  1. Open http://localhost:3000 in your browser
  2. Sign up or log in through Supabase Auth
  3. Try importing a CSV file or creating a contact manually
  4. Check the dashboard for stats and recent activity
You can also verify the API is running: 
curl http://localhost:3001/health
You should see a response like: 
{ "status": "ok", "checks": { "db": "ok", "redis": "ok" } }

​
Useful Commands

pnpm dev                # Run all apps in dev mode
pnpm build              # Build everything
pnpm typecheck          # Typecheck all packages
pnpm lint               # Lint with Biome
pnpm test               # Run unit tests

​
What’s Next?

Architecture Overview

Understand how the monorepo is structured and why.

Contributing Setup

Detailed development environment setup for contributors.