Frontend Development (cred-web-commercial)

Prerequisites

Node.js 20.19+ or 22.12+ (see engines in package.json)
Bun ≥1.2 — this is the package manager (packageManager: bun@1.2.23)
Access to the .env secrets in 1Password

Quick Start

1. Clone Repository

git clone https://github.com/credinvest/cred-web-commercial.git
cd cred-web-commercial

2. Install Dependencies

bun install

Use Bun, not Yarn or npm

This repo uses Bun as its package manager. Running yarn install or npm install will create incorrect lockfiles.

3. Environment Setup

Copy the example env and fill in the secrets:

cp .env.example .env

The .env.example is pre-configured to point at the remote dev API (api-dev.credplatform.com). Fill in the Firebase, PostHog, and other keys from 1Password.

For local federation (local backend + Apollo Router), see Run Modes below.

4. Start Development Server

bun run dev

The app starts on http://localhost:8002 and connects to the remote dev API.

Project Structure

This is a Turborepo monorepo with the following layout:

cred-web-commercial/
├── apps/
│   └── web-commercial/        # Main Next.js 16 app (Pages Router)
├── libs/
│   ├── cred-ui/               # Shared UI component library
│   └── cred-ui-charts/        # Chart components
├── package.json               # Root scripts and workspace config
├── .env                       # Remote dev API (default)
├── .env.local.local           # Local federation (localhost:4000)
└── turbo.json                 # Turborepo pipeline config

Run Modes

Command	Env file	Connects to	When to use
`bun run dev`	`.env`	Remote dev API	Day-to-day frontend work
`bun run dev:local`	`.env.local.local`	Local federation gateway (`localhost:4000`)	Testing backend changes locally
`bun run dev:staging`	`.env.staging.local`	Staging API	Testing against staging data
`bun run dev:prod`	`.env.production.local`	Production API	Debugging production issues

When switching between modes, clear the Next.js cache to avoid stale env vars:

rm -rf apps/web-commercial/.next
bun run dev:local    # or whichever mode

For local federation setup (running the backend locally), see the API Development guide.

GraphQL Codegen

Frontend types are generated from the federated GraphQL schema. After backend schema changes or when updating .gql query files:

bun run gql              # regenerate types from remote dev schema
bun run gql:local        # regenerate from local federation (restarts router)

Generated files are protected

Never hand-edit schema.graphql, schemas.tsx, operations.tsx, or hooks.tsx — these are regenerated by codegen.

Testing

Unit Tests

bun run test
bun run test:watch       # watch mode
bun run test:coverage    # with coverage report

Visual Tests (Playwright)

bun run test:visual              # headless
bun run test:visual:headed       # with browser UI
bun run test:visual:debug        # debug mode
bun run test:visual:update       # update snapshots
bun run test:visual:report       # view report

E2E Tests (Playwright)

bun run test:e2e                 # headless
bun run test:e2e:headed          # with browser UI
bun run test:e2e:debug           # debug mode
bun run test:e2e:report          # view report

Performance Tests (Playwright)

bun run test:performance         # headless
bun run test:performance:headed  # with browser UI
bun run test:performance:report  # view report

Useful Commands

Command	Description
`bun run dev`	Start dev server (port 8002)
`bun run dev:local`	Start with local federation backend
`bun run build`	Production build
`bun run lint`	Run ESLint
`bun run lint:fix`	Auto-fix lint issues
`bun run typecheck`	Run TypeScript type checking
`bun run gql`	Regenerate GraphQL types
`bun run test`	Run unit tests
`bun run test:e2e`	Run E2E tests
`bun run storybook:cred-ui`	Start Storybook for cred-ui

Vercel Preview Deployments (Review Apps)

Frontend preview deployments are hosted on Vercel. To reduce costs, not all PR branches auto-deploy.

What Auto-Deploys

Branch / Author	Auto-Deploy?
`main`	Always
`develop`	Always
`staging`	Always
Commits by `jcarrharris`	Always
All other PR branches	Only when explicitly triggered

How to Trigger a Preview Deploy

There are three ways to trigger a Vercel preview build:

Option 1: deploy-preview PR label (recommended)

Add the deploy-preview label to your PR — the vercel-deploy-on-label workflow will trigger a Vercel preview deployment via the Vercel API. No dummy commit required.

Every subsequent push to a labeled PR will also trigger a build automatically (via the Vercel ignoreCommand).

Option 2: [deploy] in commit message

Add [deploy] anywhere in your commit message for a one-off build:

git commit -m "feat: my changes [deploy]"

Option 3: /deploy-preview Claude command

In the cred-web-commercial repo, run the /deploy-preview slash command in Claude Code. It creates an empty commit with [deploy] in the message and pushes it — useful when the agent just opened a PR and you want a preview without adding the label manually.

Before Pushing

Always pull the latest from develop before pushing to avoid stale previews:

git pull --rebase origin develop

Preview URLs

Preview deployments are available at:

https://cred-web-commercial-git-<branch>-credai.vercel.app

These are covered by the same Vercel firewall rules as all other environments (see Deployment Guide — Vercel Firewall).

Code Standards

Follow the Coding Standards guide
Use ESLint and Prettier for formatting (bun run lint:fix)
Write tests for new features
Run bun run lint && bun run typecheck before pushing
Never hand-edit generated GraphQL files — use bun run gql
PR title format: {Linear ticket id}: {Linear ticket title}