Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.folksbase.joselito.dev/llms.txt

Use this file to discover all available pages before exploring further.

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:
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.