Skip to main content

Frontend Setup

Prerequisites​

  • Node.js 20.19+ and npm
  • Backend running on http://localhost:8080 (for API calls during development)

Installation​

cd frontend
npm install

Development Commands​

CommandDescription
npm run devStart the Vite dev server on port 5173 with hot module replacement
npm run buildProduction build to dist/ directory
npm run lintRun ESLint checks across all source files
npm run format:checkRun Prettier to verify formatting (no writes)
npm testRun the Vitest test suite
npm run generate:typesRegenerate TypeScript types from swagger spec

Type Generation​

After changing backend swagger annotations, regenerate frontend types:

make swagger && make generate-types

This runs swagger2openapi (Swagger 2.0 → OpenAPI 3.0) then openapi-typescript to produce src/types/generated.ts. Adapter files in src/types/ re-export generated types with clean names and correct nullability. See the Frontend Overview for details on the adapter pattern.

Running the Dev Server​

npm run dev

The development server starts at http://localhost:5173 and proxies API requests to the backend at http://localhost:8080. Changes to source files trigger instant hot module replacement.

Production Build​

npm run build

This produces optimized static assets in the dist/ directory, ready to be served by nginx or any static file server.

Testing​

The frontend uses Vitest as the test runner with React Testing Library for component testing. Code coverage is measured using the v8 coverage provider.

Running Tests​

npm test

Test Utilities​

Custom test utilities are located at src/test/test-utils.tsx. This module provides a custom render function that wraps components in the necessary providers:

  • MemoryRouter — Provides routing context for components that use React Router
  • SidebarProvider — Provides sidebar state context for layout components

Usage:

import { render, screen } from "@/test/test-utils";
import { MyComponent } from "./MyComponent";

test("renders correctly", () => {
  render(<MyComponent />);
  expect(screen.getByText("Expected text")).toBeInTheDocument();
});

Mock Data Factories​

Mock data factories are available at src/test/mocks.ts. These factories produce realistic test data that matches backend API response shapes, making it easy to write tests without manually constructing large data objects.

Test Setup​

The test setup file at src/test/setup.ts includes polyfills required by the jsdom environment:

  • window.matchMedia — jsdom does not provide a native implementation; required by sidebar/mobile detection
  • ResizeObserver — jsdom does not provide a native implementation; required by Recharts ResponsiveContainer