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: install, tsc --noEmit, pnpm lint, then pnpm build.

Only the build is a gate. The typecheck and lint steps are continue-on-error because the repo carries a backlog of pre-existing failures, and next.config.mjs sets both typescript.ignoreBuildErrors and eslint.ignoreDuringBuilds, so next build catches neither. That means a type error can reach main — run pnpm exec tsc --noEmit on your own changes and do not add to the pile.

Tests

End-to-end (Playwright) is the suite that carries real weight. 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	Health and configuration endpoints
api-endpoints	api-endpoints.spec.ts	API route contracts
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 a placeholder serial.

Unit (Jest) is in a rough state. There are co-located tests under src/ (cimian-version.test.ts, eventLinks.test.ts, eventPayloadDetails.test.ts, installs/status.test.ts, modules/installs-last-run.test.ts), but jest.config.js declares a projects array whose three entries all match <rootDir>/__tests__/..., a directory that does not exist in the repo. Those project patterns take precedence over the top-level testMatch, so pnpm test does not run the co-located tests. The config also spells the mapper key moduleNameMapping rather than moduleNameMapper, so the @/ aliases are not applied. Fix the config before trusting a green pnpm test.

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 still describe a monorepo layout (apps/www, database) that this repository no longer has, and deploy.md documents deployment scripts that are not in the tree. src/lib/prisma.ts and src/api/** are leftovers with no live callers.