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

# Development Setup

> Get folksbase running locally in a few minutes.

## 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](https://neon.tech), [Supabase](https://supabase.com), [Upstash](https://upstash.com), and [Vercel](https://vercel.com) (free tiers work fine)

## Step-by-Step Setup

### 1. Clone and Install

```bash theme={"dark"}
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:

```bash theme={"dark"}
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](/deployment/environment) page for a full reference of every variable.

<Tip>
  Generate an encryption key for the API with:

  ```bash theme={"dark"}
  node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"
  ```
</Tip>

### 3. Set Up the Database

Push the Drizzle schema to your Neon database:

```bash theme={"dark"}
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):

```bash theme={"dark"}
pnpm dev
```

Or start individual apps:

```bash theme={"dark"}
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](http://localhost:3000) — you should see the login page
* Open [http://localhost:3001/api/docs](http://localhost:3001/api/docs) — the Scalar API reference should load
* Run the test suite to confirm everything is wired up:

```bash theme={"dark"}
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](/contributing/code-style) guide before writing code
* Check the [Testing](/contributing/testing) page for how to write and run tests
* See [Git Conventions](/contributing/git) for commit format and PR rules