Development Workflow

This page describes the developer workflow for changing Workbase safely.

1. Setup

pnpm install
cp .env.example .env
pnpm prisma:generate
pnpm exec prisma migrate deploy

If you seed demo data:

pnpm prisma:seed

Run locally on port 3030:

pnpm dev

Set NEXTAUTH_URL=http://localhost:3030 for local auth consistency.

2. Core checks

pnpm typecheck
pnpm lint
pnpm test

Current pnpm test runs tests/price-preview.test.ts.

3. Database workflow

• Update prisma/schema.prisma.

• Create migration in dev:

  pnpm prisma:migrate
  

• Apply in shared/prod-like envs:

  pnpm exec prisma migrate deploy
  

4. API and OpenAPI workflow

When changing /api/v1 route behavior:

1. update route logic (app/api/v1/**)
2. update request/response schemas (src/lib/validation/**)
3. update scripts/generate-openapi.ts
4. regenerate and validate:

pnpm generate:openapi
pnpm validate:openapi

5. Module-aware changes

If a change belongs to an optional module:

• verify module id is registered in src/modules/registry.ts
• ensure enable/disable behavior is safe (module-lifecycle.ts)
• verify company scoping
• document operational caveats in docs/modularity.mdx

6. Common gotchas

• Session-authenticated mutating API calls need x-csrf-token.
• Many endpoints require companyId; missing company context returns 403.
• /api/v1 CORS and rate limiting are controlled in proxy.ts.
• Storefront product/category sources can switch between local DB and MoySklad using feature flags and module state.