Web Frontend¶

The commands below are tested on Linux only.

cd web-frontend
bun install
bun run dev

The development, build, start, and E2E build commands disable Next.js anonymous telemetry with NEXT_TELEMETRY_DISABLED=1 on every run.

Run frontend unit/component tests:

cd web-frontend
bun run test

Run frontend coverage:

cd web-frontend
bun run test:coverage

Run frontend browser integration tests:

The chat rendering comparison runs the current Python exporter. Install the core runtime dependencies first. On a host, activate the core environment or set AI_EXPORT_PYTHON to its Python executable. The development container already includes these dependencies.

cd web-frontend
bunx playwright install-deps chromium
bunx playwright install chromium
bun run test:e2e
# or in interactive UI mode:
bun run test:e2e:ui

On Linux, install fonts-dejavu-core if fc-match system-ui does not report DejaVu Sans. The Ubuntu CI runner renders page text with DejaVu Sans, which is wider than most fallback fonts. Without it, layout tests can pass locally and fail in CI.

When using the repository docker/Dockerfile.dev, Chromium is preinstalled in the image at build time using the frontend's locked Playwright version. If you rebuild the image after Playwright version changes, bun run test:e2e and bun run test:e2e:ui should not require rerunning bunx playwright install chromium inside each new docker run --rm container.

In GitHub Actions, frontend browser integration tests run after frontend unit/coverage tests. The workflow uploads Playwright reports as build artifacts so failed CI runs keep browser traces and reports for debugging.

e2e/experimental-ai-rendering.spec.ts compares the live transcript and fresh export HTML from the same conversation events. It checks content, disclosure states, and screenshots at desktop and phone widths, including after reload. Comparison HTML, screenshots, and visual differences are saved under the repository-root artifacts/chat-rendering/ directory and uploaded by CI.

Generate a separate browser-flow coverage report from Playwright:

cd web-frontend
bun run test:e2e:coverage
bun run coverage:e2e:report

This writes a separate report under web-frontend/coverage-e2e/ and does not replace the main Vitest coverage report under web-frontend/coverage/.

For building static site, run:

cd web-frontend
bun run build

Hosting on Netlify¶

Netlify starts with a blobless clone. The build downloads missing historical objects before calculating the frontend version, while preserving the selected commit. Every build runs the fetch, while cached builds reuse existing objects. This makes Git version hash lengths align with the backend's full clone.

The root netlify.toml builds the static frontend into web-frontend/out and publishes the documentation under /docs. After linking the repository to a Netlify project, open Project configuration → Environment variables and configure these variables with the Builds scope:

Variable	Value	Sensitive
`NEXT_PUBLIC_SENTRY_DSN`	Public DSN for the frontend Sentry project.	No
`SENTRY_ENVIRONMENT`	`production` for the production deploy context. Use a distinct value such as `staging` for branch deploys.	No
`SENTRY_PROJECT`	Slug of the frontend Sentry project.	No
`SENTRY_AUTH_TOKEN`	Sentry organization auth token allowed to create releases and upload source maps for the frontend project.	Yes

Mark SENTRY_AUTH_TOKEN as Contains secret values in Netlify. Never prefix it with NEXT_PUBLIC_, put it in netlify.toml, or commit it to an environment file. The Next.js Sentry build plugin reads it only while building, then uploads the release and source maps. Without it, the site still builds and browser events still reach Sentry through NEXT_PUBLIC_SENTRY_DSN, but production stack traces may remain minified.

To create the token:

Follow Sentry's auth-token instructions to create an organization token through an internal integration.
Grant org:ci for release and source-map operations. Ensure the integration can access the team that owns SENTRY_PROJECT.
Copy the generated token into Netlify as SENTRY_AUTH_TOKEN, select the Builds scope, and mark it as Contains secret values.

Trigger a new deploy after changing any build environment variable. Configure different SENTRY_ENVIRONMENT values per Netlify deploy context when production and branch deploys share the same frontend Sentry project.

For linting, run:

cd web-frontend
bun run lint -- --fix

bun can be replaced directly with npm for the basic Next.js workflow, but the documented project scripts assume Bun.