Development

Development

Working on the dashboard: the scripts, what CI enforces, and the state of the test suites.

Setup

pnpm install

pnpm dev

pnpm dev runs Next with --max-old-space-size=4096; some of the report pages are large enough that the default heap is tight. Use pnpm dev:profile to run the dev server under the Node inspector.

In development, requests to localhost, 127.0.0.1 and 0.0.0.0 bypass authentication in the middleware, so you can work against a real API without any identity provider configured. Only API_BASE_URL and a credential are needed — see Configuration.

Scripts

Command	What it does
pnpm dev	Dev server on port 3000
pnpm build	Production build, standalone output
pnpm start	Serve a production build
pnpm lint	ESLint with --max-warnings=0
pnpm test	Jest
pnpm test:e2e	Full Playwright run
pnpm test:routes	Playwright, page smoke tests only
pnpm test:api-health	Playwright, health checks only
pnpm test:api-endpoints	Playwright, API contract checks only
pnpm test:api-prod / pnpm test:all-prod	The same with TEST_ENV=production
pnpm generate-icons	Regenerate favicons and PWA icons from the logo

Continuous integration

.github/workflows/ci.yml runs on pushes and pull requests to main, on Node 20 with pnpm 9: pnpm install --frozen-lockfile, then four blocking steps in order.

pnpm exec tsc --noEmit

pnpm lint

pnpm test

pnpm build

Typecheck, lint (warnings included) and unit tests are real gates because next build checks neither types nor lint: next.config.mjs sets typescript.ignoreBuildErrors and eslint.ignoreDuringBuilds. Run the first three locally before pushing.

.github/workflows/ghcr-publish.yml publishes the container image on a tag; see Deployment.

Tests

Unit (Jest) runs every src/**/*.{test,spec}.{ts,tsx} file in a jsdom environment, with @/ mapped to src/. The suites cover the installs status and system-problem helpers, device status (including Storage), Cimian version parsing, the installs last-run verdict, event links and payload details, installed-update search and KB coverage, the platform filter provider, and a render test of the managed-installs table.

End-to-end (Playwright) has four projects in e2e/:

Project	Spec	Checks
frontend-routes	frontend-routes.spec.ts	Every page returns under 500, and the legacy /devices/<module> redirects land on /<module>
api-health	api-health.spec.ts	Calls reportmate-api directly at API_BASE_URL (required) with API_INTERNAL_SECRET or REPORTMATE_PASSPHRASE: health, devices, events, and that an anonymous negotiate call is refused
api-endpoints	api-endpoints.spec.ts	The dashboard's own route handlers (/api/healthz, /api/version and the proxies)
dashboard	dashboard.spec.ts	Dashboard behaviour

Locally, Playwright starts pnpm dev for you and reuses an existing server on port 3000. With TEST_ENV=production it skips that and uses E2E_BASE_URL. Device routes use TEST_DEVICE_SERIAL, defaulting to TESTSERIAL0001. CI does not run the Playwright suites.

Conventions

• TypeScript strict, path alias @/* mapped to the repo root in tsconfig.json.
• ESLint extends next/core-web-vitals and next/typescript. Unused variables prefixed with _ are allowed; src/lib/modules/** is ignored.
• Follow URL_STATE_CONVENTIONS.md when adding filters or list state — see Theming and UI.
• New per-module normalization goes in src/lib/data-processing/modules/, one file per module.
• A new data path is a route handler in app/api/** using getInternalApiHeaders(), never a browser fetch to the API.

Contributing

Branch off origin/main as <type>/<slug> where type is one of feature, fix, chore, ci, docs. Commit subjects are plain imperative prose. Work is tracked as GitHub issues in this repository; close them from a pull request body with Closes #<n>. Never push main directly. Say in the pull request what you built and ran, including pre-existing failures you did not cause.

Stale files to be aware of

docker-compose.yml and pnpm-workspace.yaml describe a monorepo layout (apps/www, database) that this repository does not have, and deploy.md documents deployment scripts that are not in the tree. src/api/** has no live callers.