Development setup and tests
Set up
Section titled “Set up”You need Node.js 24 (the version continuous integration uses), Docker for PostgreSQL, and Yarn 4 through corepack.
cd assetscorepack enableyarn installThe --recursive flag fetches the artwork repositories under submodules/.
Start a database and the server:
yarn db:up # PostgreSQL in Dockeryarn server:dev # the server, with file watchingcd packages/ui && yarn dev # the interfaceyarn workspace server run setup does a full first-time setup in one command: it builds the images, starts the database, runs the migrations, seeds the database, runs a first collection and builds the provider orders.
To collect data into your database, see Collectors and Self-hosting: Collection.
Run the tests
Section titled “Run the tests”Tests use Vitest. The node --test runner is used only for a few older tests of provider sync order and database batching.
# Serveryarn workspace server run vitest run
# Interface (needs the jsdom environment from packages/ui/vitest.config.ts)yarn workspace ui run testRun the interface tests through the workspace. Never run them from the repository root, because they need the jsdom environment that packages/ui/vitest.config.ts sets up.
Keep a test file next to the source it tests:
- Server tests:
*.test.tsnext to the source inpackages/server/src/. - Interface tests:
*.test.tsor*.test.tsxnext to the source.
Coverage: 100 percent on every workspace
Section titled “Coverage: 100 percent on every workspace”Continuous integration gates on coverage. A passing test run does not imply a passing coverage run. Run the coverage variant for every workspace you touched before you call a change done.
yarn workspace server run vitest run --coverageyarn workspace ui run vitest run --coverageyarn workspace @gibs/sdk run vitest run --coverageyarn workspace @gibs/utils run vitest run --coverageyarn workspace @gibs/react run vitest run --coverageEvery workspace must reach 100 percent on all four metrics: statements, branches, functions and lines. The thresholds are set there. One untested line fails the build while every test still passes. At the time of writing, the server has 7469 statements, 3686 branches, 1385 functions and 6679 lines over 3281 tests. The interface has 2746, 1633, 714 and 2394 over 1845 tests. @gibs/sdk has 92 tests, @gibs/utils 95 and @gibs/react 41.
There is no margin under the floors. The old floors sat about 0.2 below the measured value, because this workspace once reported slightly lower on the continuous integration runner than on a laptop. At 100 there is nothing left to absorb that gap. A runner that measures lower is reporting a test that depends on its environment, and that is worth a red build.
When you find a new gap, you have three honest answers:
- Write a test that fails when the behaviour breaks.
- Delete the code, if nothing can reach it.
- Report the gap, with evidence.
Never lower a floor to make a run pass. Never invent a state that the application cannot produce just to execute a line.
Each workspace runs its own lint from its own directory. Continuous integration runs both.
cd packages/server && yarn lintcd packages/ui && yarn lintLint is Prettier plus ESLint. The project uses ESLint 10. It needs Node.js 20.19 or later, 22.13 or later, or 24. The configuration is packages/server/eslint.config.js (flat config), and packages/ui has its own. Unused arguments must start with an underscore (argsIgnorePattern: '^_').
ESLint 10 added three rules to eslint:recommended. no-useless-assignment and preserve-caught-error found real issues in packages/server/src/collect/ and packages/server/src/server/list/handlers.ts: dead variable initialisers, and two thrown errors that dropped their original cause. Both are fixed in the source, not suppressed. no-unassigned-vars found nothing.
Typecheck and build
Section titled “Typecheck and build”From the repository root:
# TypeScript 7, through the runner. A bare tsc is TypeScript 6.node scripts/tsc7.mjs --noEmit -p tsconfig.json
# Build everythingyarn run buildSee Continuous integration and TypeScript for why there are two versions.
yarn workspace ui run build is a bare vite build. It strips types without reading them, so a type error will not fail it. The typecheck job is the only thing between a type error and the main branch.
Smoke test a running instance
Section titled “Smoke test a running instance”yarn smoke # the project staging instanceyarn smoke:production # the public instance, gib.showThe smoke test calls every documented endpoint and also sends the inputs that should be refused. It exits with a non-zero status on any failure, so it can gate a deploy. It uses the project staging instance unless you pass a target.
Each request carries a random query parameter on purpose. Image responses are cached at the edge for a day, so a plain request after a deploy can be answered by a copy made before it. That looks like missing response headers rather than a stale body. The link and x-license headers are set unconditionally, so if either is absent, the response did not come from that code at all. Suspect the cache before the code.
Code conventions
Section titled “Code conventions”- Server source must stay strippable by Node.js. See Architecture.
- Every isolated unit needs tests, and the coverage rule above applies.
- Add a route and its
openapi.tsentry in the same change. See Continuous integration. - Pure logic that you extract from a component goes in
packages/ui/src/lib/utils/. See Front end.