<!-- Canonical: https://programkit.dev/docs/guides/local-development -->
<!-- Markdown: https://programkit.dev/docs/guides/local-development.md -->

# Local development

This guide gets a fresh checkout to the working sample without external accounts or secrets. If
you only want your own hosted copy, skip local setup and use the
[Deploy to Cloudflare button](/docs/self-hosting/cloudflare.md#path-a-deploy-to-cloudflare-button).

## Prerequisites

- Node.js 24 or newer
- Git

The repository pins Node 24 in `.node-version` for version managers and Cloudflare builds. The npm
commands below fetch the exact pnpm version recorded in `package.json`; no global pnpm or Corepack
installation is required.

## Start the application

```bash
npm run setup
npm start
```

Open `http://localhost:4173`. The development command starts Vite, the React application, the
Cloudflare Worker, and local Durable Object storage in one process.

No Airtable, Cloudflare login, email provider, or API key is required. The first request creates a
deterministic AIE NYC workspace with proposals, reviewers, speakers, tasks, sessions, and a
published agenda.

## Exercise the main workflow

1. Open `/forms` and inspect the call-for-proposals form and conditional workshop field.
2. Open `/submit/aie-nyc-2026-cfp` and submit a proposal.
3. Open `/submissions`, select that proposal, and make a decision.
4. Open `/reviews`, then use a reviewer's **Open portal** link to inspect the exact assigned queue
   and scorecard workspace.
5. Open `/portal/par_003` to complete accepted-speaker requirements.
6. Open `/schedule`, change the draft, run preflight, and publish a release.
7. Open `/agenda` to verify that the public program reads the immutable release.

The sample submitter and participant identities are intentionally route-derived. Reviewer links
also carry a per-reviewer capability, matching the links an organizer copies from `/reviews`.

## Reset local state

Stop the development server, then remove only the local Wrangler state directories:

```bash
rm -rf .wrangler apps/cloudflare/.wrangler
```

The next `npm start` starts from the deterministic seed again. Never use this command against a
directory other than a ProgramKit checkout.

## Run the complete gate

```bash
npm run verify
```

Use the narrower commands while iterating:

```bash
npm test
npm run lint
npm run format:check
```

Contributors who already use pnpm can continue to run `pnpm dev`, `pnpm check`, and the other
scripts directly.

## Optional services

Local ProgramKit is complete without optional services. Add them only for the workflow you are
testing:

- Airtable OAuth or a scoped personal token: [Airtable integration](/docs/integrations/airtable.md)
- Cloudflare mail bindings: [Email integration](/docs/integrations/email.md)
- Remote Workers deployment: [Deployment](https://forge.smol.ai/andheller/programkit/blob/main/DEPLOYMENT.md)

Copy `apps/cloudflare/.dev.vars.example` to the ignored root `.dev.vars` only when an integration
needs secrets. Never commit `.dev.vars`.