Development Setup

Prerequisites

Before you start, make sure you have:

Node.js 24+ — check with node -v
pnpm 10+ — install with corepack enable or npm install -g pnpm
Accounts on Neon, Supabase, Upstash, and Vercel (free tiers work fine)

Step-by-Step Setup

1. Clone and Install

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

pnpm install also configures local git hooks automatically via pnpm prepare — you’ll get pre-commit linting and pre-push checks out of the box.

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

The API needs credentials for Neon (Postgres), Upstash (Redis), Supabase (auth), Vercel Blob (file storage), Inngest (background jobs), and Anthropic (AI). The web app needs the API URL and Supabase public keys. See the Environment Variables page for a full reference of every variable.

Generate an encryption key for the API with:

node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"

3. Set Up the Database

Push the Drizzle schema to your Neon database:

pnpm --filter @folksbase/db db:push

This compiles the TypeScript schema to JS first, then runs drizzle-kit push. Always use this command instead of running drizzle-kit directly.

4. Start Development

Run everything at once (web, API, email preview, Inngest dev server):

pnpm dev

Or start individual apps:

pnpm --filter @folksbase/web dev   # Frontend on http://localhost:3000
pnpm --filter @folksbase/api dev   # API on http://localhost:3001

5. Verify It Works

Open http://localhost:3000 — you should see the login page
Open http://localhost:3001/api/docs — the Scalar API reference should load
Run the test suite to confirm everything is wired up:

pnpm test

Useful Commands

Command	What it does
`pnpm dev`	Start all apps in dev mode
`pnpm build`	Build everything
`pnpm test`	Run all unit tests (Vitest)
`pnpm lint`	Check formatting and lint rules (Biome)
`pnpm lint:fix`	Auto-fix lint and formatting issues
`pnpm typecheck`	Run TypeScript type checking
`pnpm --filter @folksbase/db db:studio`	Open Drizzle Studio (database GUI)
`pnpm --filter @folksbase/web storybook`	Run Storybook on port 6006

Monorepo Structure

folksbase/
├── apps/
│   ├── web/        # Next.js 15 frontend (Vercel)
│   ├── api/        # Hono backend (Render)
│   └── docs/       # Mintlify documentation
├── packages/
│   ├── db/         # Drizzle schema + migrations
│   ├── emails/     # Email templates (Resend)
│   └── types/      # Shared TypeScript types

Shared code lives in packages/. The two apps (web and api) are independent deployments — never import directly between them.

Next Steps

Read the Code Style guide before writing code
Check the Testing page for how to write and run tests
See Git Conventions for commit format and PR rules

Getting Started

Features

Architecture

Background Jobs

API

Deployment

Contributing

Prerequisites

Step-by-Step Setup

1. Clone and Install

2. Configure Environment Variables

3. Set Up the Database

4. Start Development

5. Verify It Works

Useful Commands

Monorepo Structure

Next Steps

​Prerequisites

​Step-by-Step Setup

​1. Clone and Install

​2. Configure Environment Variables

​3. Set Up the Database

​4. Start Development

​5. Verify It Works

​Useful Commands

​Monorepo Structure

​Next Steps

Prerequisites

Step-by-Step Setup

1. Clone and Install

2. Configure Environment Variables

3. Set Up the Database

4. Start Development

5. Verify It Works

Useful Commands

Monorepo Structure

Next Steps