Checkmate
DocumentationGetting started

Contributing to Checkmate

Set up a development environment, find an issue and open a pull request. Code, docs and translations are all welcome.

Thanks for your interest in contributing. Checkmate is an open-source project that welcomes code, ideas, translations and documentation. Reading the section that matches what you want to do helps us review and accept your contribution faster.

Note

We work closely with contributors on Discord. You'll find maintainers, community members and first-time contributors helping each other there.

New to contributing?

  1. Pick a good first issue.
  2. Comment on it to say you'd like to work on it.
  3. Follow the local setup below.
  4. Ask on Discord if you get stuck.

Get help or ask a question

Ask on Discord or in GitHub Discussions. The core contributors are active in both.

Report a bug

  1. Search the existing issues.
  2. If it isn't listed, open a new issue.
  3. Describe what happened, what you expected and the steps to reproduce it. Logs and screenshots help.

Suggest a feature

  1. Open a new issue with the feature request template.
  2. Explain your use case and why it would help.
  3. If you plan to build it, discuss it on Discord before you write code.

Before suggesting a feature, check that it isn't already covered by a configuration option and search the issues for an existing request. If there is one, add a comment there instead of opening a new issue. Features that help most users are more likely to be accepted than ones that serve a small subset.

Set up Checkmate locally

Prerequisites

  • Node.js 24 or newer, with npm 11 or newer
  • Docker, for the MongoDB container
  • Git
node --version
npm --version
docker --version
git --version

1. Clone the repository

git clone https://github.com/bluewave-labs/Checkmate.git
cd Checkmate

2. Start MongoDB

docker run -d -p 27017:27017 -v uptime_mongo_data:/data/db --name uptime_database_mongo mongo:8.0

3. Set up the server

cd server
npm install

Create a .env file in the server directory with the minimum configuration:

CLIENT_HOST="http://localhost:5173"
JWT_SECRET="my_secret_key_change_this"
DB_CONNECTION_STRING="mongodb://localhost:27017/uptime_db"
TOKEN_TTL="99d"
ORIGIN="localhost"
LOG_LEVEL="debug"
  • CLIENT_HOST: the frontend URL
  • JWT_SECRET: the secret used to sign login tokens. Change it to something random
  • DB_CONNECTION_STRING: the MongoDB connection URL
  • TOKEN_TTL: how long a login token lasts, in vercel/ms format
  • ORIGIN: the origin used for CORS
  • LOG_LEVEL: debug, info, warn or error

The full list of server variables is in the installation guide.

Start the server with hot reload:

npm run dev

The server runs at http://localhost:52345.

4. Set up the client

In a new terminal, from the repository root:

cd client
npm install

Create a .env file in the client directory:

VITE_APP_API_BASE_URL="http://localhost:52345/api/v1"
VITE_APP_LOG_LEVEL="debug"
  • VITE_APP_API_BASE_URL: the server's API URL
  • VITE_APP_LOG_LEVEL: debug, info, warn or error

Start the client:

npm run dev

5. Open the app

Manage the MongoDB container

docker stop uptime_database_mongo
docker start uptime_database_mongo
docker rm uptime_database_mongo

Troubleshooting

Port already in use. Check whether another service uses port 5173, 52345 or 27017. Stop it or change the port in the .env files.

MongoDB connection errors. Check that the container is running with docker ps and read its logs with docker logs uptime_database_mongo.

Module not found errors. Run npm install in both client and server.

If you're still stuck, ask on Discord.

Contribute code

  1. Pick or open an issue. Look at good first issue first.
  2. For a deeper look at the architecture, read the Checkmate overview on DeepWiki (optional).
  3. Ask to be assigned. If someone is already assigned and there has been no activity for 7 days, you can ask to take it over.
  4. Create a branch from develop.
  5. Write your code, then run and test it locally.
  6. Open a pull request against develop.
Note

New to Git? The Bluewave team maintains a Git quick start guide.

Improve the documentation

Documentation fixes are valuable contributions, from a typo to a missing example.

  • This documentation site: open an issue describing the change or mention it on Discord.
  • The README: small edits (typos, wording, formatting) can go straight to a pull request against develop. For larger changes, such as restructuring a section, open an issue first so we can agree on the scope. Screenshots help when you document UI behaviour.
  • README translations: they live in docs/translations/. If you add a new language, also add its flag and link to the language bar in the root README.md and in every translated README so they stay in sync.

Help with translations

The app uses i18next with one JSON file per language in client/src/locales/. en.json is the source of truth. The other languages started as machine translations that anyone can refine.

To improve an existing language:

  1. Edit client/src/locales/<code>.json.
  2. Keep the key structure identical to en.json and translate only the values.
  3. Open a pull request against develop. No language selector changes are needed.

To add a new language:

  1. Add client/src/locales/<code>.json with the same key structure as en.json. If you can't translate every key, leave those strings in English instead of removing the keys.
  2. Add the language's display name to languageNames in client/src/Components/inputs/LanguageSelector.tsx, for example it: "Italiano". The selector picks up the new file automatically.
  3. Open a pull request against develop.

If translating a whole file is more than you want to take on, open an issue asking for the language. We'll generate a machine-translated starting file that you or others can refine.

Warning

Translations are no longer managed in POEditor. Edit the JSON files in client/src/locales/ directly.

Submit a pull request

A pull request should:

  • address one issue or topic
  • be tested locally
  • follow the code and translation guidelines below
  • reference the related issue, for example Fixes #123
  • target the develop branch

Smaller pull requests get faster and better reviews. The maintainers explain why in the importance of small pull requests.

Code guidelines

  • Run npm run lint and npm run format-check in both client and server. If format-check reports problems, fix them with npm run format before you commit.
  • Use camelCase for variables, PascalCase for components and UPPER_CASE for constants.
  • Put every user-facing string through the translation function, t("your.key").
  • Style with the shared theme and components. Avoid magic numbers and inline styles.
  • Follow the structure and patterns already used in the codebase. The repository's coding conventions list the rules reviewers check.

Pull request checklist

Before you open a pull request, confirm that:

  • you tested the app locally and your change works
  • you reviewed your code and removed debug logs and leftover code
  • the GitHub issue is assigned to you
  • the description includes the related issue number, for example Fixes #123
  • all user-facing text uses t("key")
  • there are no hardcoded URLs, config values or secrets
  • styling uses the shared theme
  • the pull request covers a single issue or topic
  • UI changes include screenshots or a video
  • npm run lint, npm run format-check and npm run build pass in both client and server

If something is missing, we may ask you to update the pull request before we merge it.

Branching model

  • Code contributions go to the develop branch.
  • master holds stable releases.
  • Use descriptive branch names, such as fix/login-error or feat/add-alerts.
  • Start from the latest develop.

Thank you

Whether it's your first pull request or your 50th, thanks for helping make Checkmate better. Feel free to introduce yourself on Discord.

On this page

Was this page helpful?