Skip to content

🐸 Rybbit - open-source and privacy-friendly alternative to Google Analytics that is 10x more intuitive.

5.5 KB
Raw Blame

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:

  1. Start only Postgres, ClickHouse, and Redis from the root docker-compose.yml. They listen on localhost with the compose defaults (Postgres user and password frog, ClickHouse password frog, Redis password changeme):

    docker compose up -d postgres clickhouse redis
    
  2. Copy server/.env.example to server/.env and 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>
    
  3. Create client/.env.local with the backend URL:

    NEXT_PUBLIC_BACKEND_URL=http://localhost:3001
    
  4. Create 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