Quickstart

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

Prerequisites

Before you start, make sure you have:

Node.js 24+ — download here
pnpm 10+ — install with npm install -g pnpm
A Neon Postgres database — create one
A Supabase project — create one (for authentication)

You’ll also need these services (or compatible alternatives):

Upstash Redis — caching and rate limiting
Vercel Blob — CSV file storage
Inngest — background job processing
Anthropic API key — AI-powered CSV column mapping

The app degrades gracefully if any of these are missing, but all four are required for full functionality.

1. Clone and Install

git clone https://github.com/breakzplatform/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:

Variable	Description
`DATABASE_URL`	Neon Postgres connection string
`SUPABASE_URL`	Your Supabase project URL
`SUPABASE_PUBLISHABLE_KEY`	Supabase anon/public key
`SUPABASE_SECRET_KEY`	Supabase service role key
`ENCRYPTION_KEY`	64-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:

Variable	Description
`NEXT_PUBLIC_API_URL`	`http://localhost:3001/api`
`NEXT_PUBLIC_SUPABASE_URL`	Your Supabase project URL
`NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY`	Supabase 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:

App	URL
Web (Next.js)	http://localhost:3000
API (Hono)	http://localhost:3001

5. Verify It Works

Open http://localhost:3000 in your browser
Sign up or log in through Supabase Auth
Try importing a CSV file or creating a contact manually
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

Getting Started

Features

Architecture

Background Jobs

API

Deployment

Contributing

Prerequisites

1. Clone and Install

2. Configure Environment Variables

3. Set Up the Database

4. Start Development

5. Verify It Works

Useful Commands

What’s Next?

Architecture Overview

Contributing Setup

​Prerequisites

​1. Clone and Install

​2. Configure Environment Variables

​3. Set Up the Database

​4. Start Development

​5. Verify It Works

​Useful Commands

​What’s Next?

Architecture Overview

Contributing Setup

Prerequisites

1. Clone and Install

2. Configure Environment Variables

3. Set Up the Database

4. Start Development

5. Verify It Works

Useful Commands

What’s Next?