Contributing

How to contribute to Rustrak.

Setup

Prerequisites

• Rust, current stable
• Node.js 22+
• pnpm 10+
• Docker, optional: only for PostgreSQL or to build images

Clone and install

git clone https://github.com/rustrak/rustrak.git
cd rustrak
pnpm install

Start development

# Run the server on :8080, with SQLite. The .env keeps the database and
# source maps inside the checkout instead of /data.
cd apps/server && cp .env.example .env && cargo run
 
# Run the dashboard on :3000, proxying the API to :8080 (separate terminal)
cd apps/dashboard && pnpm dev

The server uses SQLite unless told otherwise. To work against PostgreSQL:

docker compose -f docker-compose.dev.yml up -d postgres
cd apps/server && DATABASE_URL=postgres://rustrak:rustrak@localhost:5432/rustrak \
  cargo run --no-default-features --features postgres

To have the server itself serve the dashboard, as it does in production, run pnpm build --filter=@rustrak/server from the root: it builds the dashboard, copies it to apps/server/static with scripts/bundle-dashboard.sh, and builds the server.

Project structure

rustrak/
├── apps/
│   ├── server/         # Rust server: API, ingest, and the dashboard from static/
│   ├── dashboard/      # React SPA, compiled into apps/server/static
│   └── docs/           # Documentation site
├── packages/
│   ├── ui/             # Design system
│   ├── client/         # TypeScript API client
│   ├── mcp/            # MCP server over the client
│   ├── test-sentry/    # CLI that sends test events
│   └── benchmarks/     # Load and throughput benchmarks
├── scripts/
│   └── bundle-dashboard.sh   # copies the dashboard build into apps/server/static
└── docker-compose.yml

Workflow

Branches

• main – Stable release
• feat/* – New features
• fix/* – Bug fixes

Commits

Use conventional commits:

feat: Add issue muting
fix: Correct rate limit calculation
docs: Update deployment guide

Pull requests

1. Create feature branch
2. Make changes
3. Run tests
4. Submit PR
5. Address feedback

Server (Rust)

Tests

cd apps/server
cargo test

Style

cargo fmt
cargo clippy

Migrations

sqlx migrate add description
sqlx migrate run

Dashboard

React 19, TanStack Router and Vite. It compiles to static files that the Rust server hands out, so there is no Node process in production: pnpm dev runs Vite on :3000 and proxies the API prefixes to the server, which is the same one-origin arrangement production has.

Tests

cd apps/dashboard
pnpm test
pnpm lint

Strings and translations

Every user-facing sentence lives in src/shared/i18n/messages/, one JSON dictionary per locale, and nowhere else. A new string goes into all five dictionaries, and is read through a translator rather than written inline.

Dates, numbers and percentages are never formatted by hand. toLocaleString() and a bare Intl formatter use the browser’s locale rather than the one the reader chose in Rustrak. Use use-intl’s useFormatter with one of the named formats in src/shared/i18n/config.ts. The architecture suites fail the build on all of this.

Adding a language

The server needs no change: it accepts any well-formed language tag, so a locale is added entirely in the dashboard.

1. Copy src/shared/i18n/messages/en.json to your locale’s tag, for example fr.json, and translate the values. Keep every key: a missing one renders as the raw key, not as English
2. Add the tag to LOCALES in src/shared/i18n/routing.ts
3. Add the dictionary to OTHER_LOCALES in src/__tests__/architecture/message-keys.test.ts, which holds every locale to the same keys as English
4. Run pnpm test

Documentation

Run locally

cd apps/docs
pnpm dev

Add pages

1. Create .mdx in content/
2. Add to _meta.js
3. Link from related pages

Getting help

• Issues: Report bugs
• Discussions: Ask questions
• Docs: Check documentation first

Thanks for contributing!