Skip to content

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

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}