Development
Local Setup
Prerequisites#
| Requirement | Version | Notes |
|---|---|---|
| Node.js | ≥ 20 | Use nvm or fnm for version management. |
| npm | ≥ 11 | Comes with Node.js. Verify: npm --version |
| Wrangler CLI | ≥ 4 | npm install -g wrangler. Cloudflare Workers local dev. |
| Neon account | — | Create a free project at neon.tech. Grab the pooled connection string. |
| Clerk account | — | Create an application at clerk.com. Copy publishable + secret keys. |
| Git | ≥ 2.30 | Standard. Verify: git --version |
Clone & install#
- 1
Clone the repository
bashgit clone <repo-url> commodity-management-platform cd commodity-management-platform - 2
Install all workspace dependencies
bashnpm install - 3
Set up environment variables
Copy the example env file and fill in your values. Each app has its own
.env.localfile. - 4
Run database migrations
bashnpm run db:migrate:sms-settings npm run db:migrate:farmer-registry npm run db:migrate:farm-mapping npm run db:migrate:deforestation-risk npm run db:migrate:sustainability-programs npm run db:migrate:surveys npm run db:migrate:eudr-compliance - 5
Start all dev servers
bashnpm run dev
Dev servers#
| App | URL | Start command |
|---|---|---|
| Product frontend | http://localhost:3000 | Turborepo starts it via npm run dev |
| Hono API | http://localhost:8788 | Turborepo starts it via npm run dev |
| This docs site | http://localhost:3001 | Turborepo starts it via npm run dev |
Turborepo starts all three
Running
npm run dev from the root starts all three apps in parallel via Turborepo. You do not need to start them individually.Environment variables#
| Variable | Required | Notes |
|---|---|---|
DATABASE_URL | Required | Neon PostgreSQL connection string. Use the pooled connection URL. |
AUTH_DEV_BYPASS | Optional | Set to "true" to bypass Clerk JWT verification locally. Never set in production. |
DEV_AUTH_EMAIL | Optional | Simulated user email when AUTH_DEV_BYPASS=true. |
DEV_AUTH_ROLE | Optional | Simulated role: org:admin | org:manager | org:officer |
DEV_AUTH_TENANT_ID | Optional | Simulated Clerk org ID (org_...). |
DEV_AUTH_USER_ID | Optional | Simulated Clerk user ID (user_...). |
NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY | Required | From Clerk dashboard → API Keys. |
CLERK_SECRET_KEY | Required | From Clerk dashboard → API Keys. Keep this secret. |
NEXT_PUBLIC_API_URL | Required | API base URL. Locally: http://localhost:8788 |
AUTH_DEV_BYPASS
AUTH_DEV_BYPASS=true bypasses Clerk JWT verification entirely — it is only for local development with Wrangler. Never deploy with this set. Use DEV_AUTH_ROLE=org:admin and DEV_AUTH_TENANT_ID=org_test alongside it to simulate a specific user.Common commands#
| Command | What it does |
|---|---|
| npm run dev | Start all dev servers in parallel. |
| npm run build | Build all apps and packages in dependency order. |
| npm run lint | ESLint across all workspaces (--max-warnings 0). |
| npm run typecheck | TypeScript type check across all workspaces. |
| npm run check-types | Alias for typecheck. |
| npm run test | Vitest across all workspaces. |
| npm run format | Prettier format all files. |
| npm run clean | Remove .next, .turbo build caches. |
Running commands in a single workspace#
bash
# Typecheck only the docs app
npm run typecheck --workspace=docs
# Run tests for the farmer-registry backend package
npm run test --workspace=feature-farmer-registry
# Lint only the web app
npm run lint --workspace=webDatabase migrations#
Each backend feature package manages its own Drizzle migrations. Migrations are stored in be-packages/feature-*/src/db/migrations/ and are checked into git.
bash
# Run migrations for a specific feature
npm run db:migrate:farmer-registry
# Generate a new migration after schema changes
npm run db:generate:farmer-registry