Skip to main content

​
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/joselito/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

pnpm test

​
Useful Commands

CommandWhat it does
pnpm devStart all apps in dev mode
pnpm buildBuild everything
pnpm testRun all unit tests (Vitest)
pnpm lintCheck formatting and lint rules (Biome)
pnpm lint:fixAuto-fix lint and formatting issues
pnpm typecheckRun TypeScript type checking
pnpm --filter @folksbase/db db:studioOpen Drizzle Studio (database GUI)
pnpm --filter @folksbase/web storybookRun 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