klarbild-oss/CONTRIBUTING.md

Contributing

Thanks for looking. Klarbild is a small project with one maintainer, so the most useful contributions are the ones that arrive ready to merge: a clear problem, a minimal change, and a test where a test is possible.

Getting it running

npm install
cp .env.example .env     # DATABASE_URL, SESSION_SECRET, ENCRYPTION_KEY
npm run dev

You need a PostgreSQL to point DATABASE_URL at; docker compose up db gives you one. Migrations run themselves on the first request.

npm test          # 130 tests, no database needed
npx tsc --noEmit  # must be clean
npm run build

Both npm test and tsc run in CI and both must be green.

How the code is laid out

src/lib/print*.ts     the print engine — pure arithmetic, heavily tested
src/lib/paper.ts      86 image sizes, 19 paper formats, the size parser
src/lib/modules.ts    which optional modules are switched on
src/lib/i18n.ts       translation; the English sentence is the key
src/components/       React islands, one per screen
src/pages/            Astro pages and the API under src/pages/api/
migrations/           numbered SQL, forward-only, idempotent, run on boot
tests/                node:test, no framework

The rule that matters most: the browser preview and the server-side PDF use the same layout code. If you change how a sheet is laid out, change it in src/lib/printlayout.ts and both follow. Anything that recomputes geometry in a component is a bug waiting to happen.

House style

• Comments explain why, and carry the number that justifies the decision. "Measured: 440 MB of images peaked at 196 MB of memory" is worth more than "stream the files". Please keep that habit; it is most of what makes this codebase navigable.
• No new dependency without a reason in the pull request. There are 20 runtime dependencies and that is already plenty.
• Two-space indent, no semicolon crusade, no reformatting of files you did not otherwise touch.
• Metric units. English decimal point in English strings.

Translation

The English string in the source is the key. To add a language:

1. Copy src/locales/de.json to src/locales/<code>.json and translate the values.
2. Add the code to LOCALES and LOCALE_NAMES in src/lib/i18n.ts, and to DICTS in src/lib/i18n.server.ts.

A missing key falls back to English, so a partial translation is still useful. Never build a sentence by concatenation — use a named placeholder: t('{done} of {total} done', { done, total }).

Adding a module

Optional features live behind src/lib/modules.ts. A new one needs: an entry in MODULE_IDS and MODULE_INFO, a has('yours') guard on its navigation entry and its settings card, and if (!has('yours')) return moduleOff('yours') at the top of every API route it owns. The test is simple — with the module off, the instance should not hint that the feature exists.

Pull requests

One change per pull request. Say what breaks if it is wrong. If you found a bug you are not fixing, an issue with a reproduction is genuinely useful on its own.