πΈ Rybbit - open-source and privacy-friendly alternative to Google Analytics that is 10x more intuitive.
Contributing to Rybbit
First off, thank you for taking the time to contribute! π
Whether it's a bug report, feature idea, or code contribution, all forms of help are appreciated.
Got an Idea or a Question?
Please start a Discussion if your contribution is not a bug report:
- Ideas β Share new features, suggestions, or improvements.
- Q&A β Ask questions about how things work.
- General β Anything else not covered by the above.
Use the appropriate category when opening a new discussion.
Found a Bug?
If something isn't working as expected, please open an Issue.
When filing an issue, make sure to:
- Include clear steps to reproduce the problem
- Describe what you expected to happen and what actually happened
- Attach logs, screenshots, or examples where applicable
- Use the correct issue template (if one is available)
This helps us investigate and resolve the issue faster.
Want to Submit a Pull Request?
Pull requests are welcome! Please keep in mind:
- Try to keep PRs focused and scoped to a single change.
- Follow any coding style guidelines or formatting rules (if specified).
- Include relevant context or links to issues/discussions.
- PRs will be reviewed and merged by the maintainers once they meet quality standards and align with the project direction.
Local development
The application is a pnpm workspace containing client/, server/, and shared/.
The docs app and React Native SDK are separate projects and keep their own tooling.
Use Node.js 24 (nvm use) and the pnpm version pinned in the root package.json:
corepack enable
pnpm install --frozen-lockfile
pnpm dev
Before starting the app, run the databases and point both apps at them:
Start only Postgres, ClickHouse, and Redis from the root
docker-compose.yml. They listen on localhost with the compose defaults (Postgres user and passwordfrog, ClickHouse passwordfrog, Redis passwordchangeme):docker compose up -d postgres clickhouse redisCopy
server/.env.exampletoserver/.envand set these values to match the compose defaults:CLICKHOUSE_PASSWORD=frog POSTGRES_USER=frog POSTGRES_PASSWORD=frog REDIS_PASSWORD=changeme BETTER_AUTH_SECRET=<output of openssl rand -hex 32>Create
client/.env.localwith the backend URL:NEXT_PUBLIC_BACKEND_URL=http://localhost:3001Create the Postgres tables (the Docker image does this on start; local dev does not):
pnpm --filter rybbit-backend db:migrate
The client runs on port 3002 and the backend on port 3001.
pnpm dev builds shared code first, then starts its TypeScript watcher alongside
both apps. The backend's existing dev command compiles once; restart it after
backend changes.
Run these commands from the repository root:
| Command | Purpose |
|---|---|
pnpm dev:client |
Start the client and shared-code watcher |
pnpm dev:server |
Start the backend and shared-code watcher |
pnpm build |
Build shared code, then both apps |
pnpm build:client |
Build shared code and the client |
pnpm build:server |
Build shared code and the backend, including the tracker |
pnpm test |
Build shared code and run both test suites once |
pnpm typecheck |
Build shared code and type-check both apps |
pnpm lint |
Run the client's ESLint command (currently a no-op, since client/eslint.config.mjs is commented out; use pnpm typecheck) |
The root test command runs one package at a time with four workers to bound the memory used by the backend's in-memory Postgres tests.
Package scripts also work inside their respective directories. Build shared
first with pnpm --filter @rybbit/shared build when running a package directly
from a fresh checkout. Add dependencies to the package that uses them, for example
pnpm --filter client add <package> or pnpm --filter rybbit-backend add <package>.
Commit the root pnpm-lock.yaml; do not generate npm lockfiles for these packages.
Dependency overrides and allowed dependency build scripts live in
pnpm-workspace.yaml.
Both Dockerfiles use the repository root as their build context and require BuildKit (enabled by default in current Docker versions):
docker build -f client/Dockerfile \
--build-arg NEXT_PUBLIC_BACKEND_URL=https://analytics.example.com \
-t rybbit-client .
docker build -f server/Dockerfile -t rybbit-backend .
Use your deployment's public backend URL. Docker Compose supplies this build
argument from BASE_URL; local .env files are excluded from Docker images.
The client image uses Next.js standalone output. The backend image uses
pnpm deploy --legacy --prod to create a portable package while keeping normal
workspace symlinks for local development. Its production dependencies include
Drizzle Kit because container startup applies migrations. Database commands are
explicit operations; installs, builds, and tests do not apply migrations.
Join Our Community
Youβre also welcome to join the Rybbit Discord to chat with the community and the team:
π https://discord.gg/DEhGb4hYBj
Thank you again for helping make Rybbit better!
β The Rybbit Team