Thank you for helping improve Roamarr. This project is a self-hosted SvelteKit and MongrelDB Kit travel organizer. Changes should be small, tested, and aligned with the existing route, server-helper, and UI patterns.
-
Fork the repository on GitHub.
-
Clone your fork:
git clone https://github.com/<you>/roamarr.git cd roamarr
-
Create a focused branch:
git checkout -b fix-trip-reminder
-
Install dependencies:
npm ci
-
Make the smallest change that fully solves the issue.
-
Add or update tests and documentation.
-
Run the local checks that match the change:
npm run check npm test -
Push your branch and open a pull request against
master.
Pull requests should include a clear summary, the tests you ran, and screenshots when the change affects the UI.
src/routes/contains SvelteKit pages, layouts, and route actions. Keep route files thin and delegate business logic tosrc/lib/server/.src/lib/server/contains auth, settings, scheduler, sharing, ownership, travel-domain logic, import/export, notifications, expenses, and admin operations.src/lib/server/db/contains the MongrelDB Kit schema, database singleton, migrations, and compatibility gate. Repositories live undersrc/lib/server/repositories/.src/lib/components/,src/lib/icons.ts, andsrc/app.csscontain shared UI components, icon names, Tailwind v4 tokens, and reusable app classes.tests/helpers.tsandtests/eventHelpers.tscontain shared database and SvelteKit event fixtures.
Prefer existing helpers, shared fixtures, and app classes over new one-off patterns.
Roamarr requires Node.js 24 or newer.
npm ci
export ROAMARR_SECRET="$(openssl rand -base64 32)"
export DATABASE_PATH="./roamarr-db"
npm run devOpen http://localhost:5173/setup on first boot.
Useful commands:
npm run dev # Vite dev server
npm run check # Svelte + TypeScript check
npm test # Vitest suite once
npm run test:e2e:install # install Playwright Chromium
npm run test:e2e # reset the port-3002 container and run Playwright
npm run build # production build to ./build
npm run credits:generate # regenerate bundled license and credits data
npm run db:compat-fixture # intentionally refresh the sample database fixtureThe end-to-end wrapper requires Podman and the maintainer-local, gitignored
compose.local.yml. Public clones do not include that file. Use the Vitest and
build gates unless you provide an equivalent local compose configuration.
Do not commit real .env files, local databases, logs, generated build output,
Playwright output, screenshots, dependencies, or machine-local state.
- Use TypeScript ES modules and the existing Svelte 5 patterns.
- Prefer
$lib/server/*aliases over deep relative imports. - Keep route actions thin: validate input, enforce ownership or authorization,
call server modules, and return SvelteKit
fail,redirect, orerrorresponses. - Prefer repository helpers and kit query builders over raw SQL.
- Use explicit transactions for atomic multi-step mutations.
- Use Luxon for timezone and datetime math.
- Reuse validators from
src/lib/server/validation.ts, action helpers fromsrc/lib/server/actions.ts, and parameter parsers fromsrc/lib/server/params.ts. - Use shared UI components and classes before adding one-off Svelte markup or CSS.
- Add concise comments only when the reason is not obvious from the code.
- Avoid unrelated formatting, broad refactors, and speculative abstractions.
Roamarr stores sensitive travel data. Do not weaken security invariants without an explicit design decision.
- Passwords must use argon2id.
- Session cookies must contain only random tokens; the database stores only token hashes.
- Encrypted-at-rest fields must remain encrypted.
- Public shares and calendar feeds must expose only the reduced viewer projection.
- Reads must use sharing checks, and mutations with client-supplied foreign IDs must enforce ownership.
- Security-relevant mutations must write audit log entries.
- Notifications, emails, webhooks, and public projections must not leak private document numbers, policy numbers, confirmation numbers, card details, or notes.
Follow the disclosure policy in docs/SECURITY.md. Do not report vulnerabilities through public issues or pull requests.
Match test coverage to the risk of the change:
- Server logic should have focused Vitest coverage near the source file.
- Route actions should test validation, authorization, and mutation behavior.
- Schema changes should update
mongrelSchema.tsand include tests for affected behavior. MongrelDB/Kit upgrades are also gated bysrc/lib/server/db/mongrelCompat.test.tsagainsttests/fixtures/mongreldb/; only regenerate that fixture after intentional storage-format breaks (npm run db:compat-fixture). - Security-sensitive changes should cover negative authorization and validation paths.
- UI changes should at least pass
npm run check; add browser or component coverage when behavior is non-trivial.
Run the broader gate before opening substantial pull requests:
npm run check
npm testUpdate documentation in the same pull request when behavior, setup, deployment, environment variables, or user-facing workflows change.
- Setup and usage belong in README.md.
- The complete public manual is indexed at docs/README.md.
- Security disclosure and threat model details belong in docs/SECURITY.md.
- Dependency changes should run
npm run credits:generateso the About license and credits pages stay current.
UI text is moving into Paraglide JS message catalogs.
English is the base locale and the only one so far. The locale comes from the
browser's Accept-Language header and falls back to English; there are no
locale URL prefixes or cookies.
- Add or change English text in
messages/en.json, then use it asm.key()from$lib/paraglide/messages. Keys arearea_purpose, for examplelogin_submit. src/lib/paraglide/is generated by the Vite plugin duringnpm run dev,npm run buildandnpm test, and bynpm run i18n:compile(whichnpm run checkruns first). It is git-ignored; never edit it. Compiler options are inproject.inlang/paraglide.config.js.- MCP tool descriptions, JSON API error messages and seeded default data stay English: clients and agents read them, not people.
- Compiling loads the inlang message-format plugin from
node_modules(@inlang/plugin-message-format, an exact-pinned devDependency referenced inproject.inlang/settings.json), so it is covered by the lockfile and works offline. Upgrade it like any other dependency.
Roamarr is GPL-3.0-only. New dependencies must be compatible with the project license and should be added only when they clearly reduce complexity or provide well-tested domain behavior that should not be maintained locally.
When changing dependencies:
- Update
package.jsonandpackage-lock.json. - Run
npm run credits:generate. - Verify the About license and credits pages still render.
A good pull request:
- Has one clear purpose.
- Describes user-visible behavior changes.
- Calls out migrations, deployment changes, or compatibility risks.
- Includes tests, or explains why tests are not practical.
- Updates docs when behavior changes.
- Passes the relevant local checks.
- Avoids unrelated formatting or refactoring churn.