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.
We work closely with contributors on Discord. You'll find maintainers, community members and first-time contributors helping each other there.
New to contributing?
- Pick a
good first issue. - Comment on it to say you'd like to work on it.
- Follow the local setup below.
- 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
- Search the existing issues.
- If it isn't listed, open a new issue.
- Describe what happened, what you expected and the steps to reproduce it. Logs and screenshots help.
Suggest a feature
- Open a new issue with the feature request template.
- Explain your use case and why it would help.
- 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 --version1. Clone the repository
git clone https://github.com/bluewave-labs/Checkmate.git
cd Checkmate2. Start MongoDB
docker run -d -p 27017:27017 -v uptime_mongo_data:/data/db --name uptime_database_mongo mongo:8.03. Set up the server
cd server
npm installCreate 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 URLJWT_SECRET: the secret used to sign login tokens. Change it to something randomDB_CONNECTION_STRING: the MongoDB connection URLTOKEN_TTL: how long a login token lasts, in vercel/ms formatORIGIN: the origin used for CORSLOG_LEVEL:debug,info,warnorerror
The full list of server variables is in the installation guide.
Start the server with hot reload:
npm run devThe server runs at http://localhost:52345.
4. Set up the client
In a new terminal, from the repository root:
cd client
npm installCreate 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 URLVITE_APP_LOG_LEVEL:debug,info,warnorerror
Start the client:
npm run dev5. Open the app
- Frontend: http://localhost:5173
- Server API: http://localhost:52345
- API documentation: http://localhost:52345/api-docs
Manage the MongoDB container
docker stop uptime_database_mongo
docker start uptime_database_mongo
docker rm uptime_database_mongoTroubleshooting
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
- Pick or open an issue. Look at
good first issuefirst. - For a deeper look at the architecture, read the Checkmate overview on DeepWiki (optional).
- 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.
- Create a branch from
develop. - Write your code, then run and test it locally.
- Open a pull request against
develop.
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 rootREADME.mdand 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:
- Edit
client/src/locales/<code>.json. - Keep the key structure identical to
en.jsonand translate only the values. - Open a pull request against
develop. No language selector changes are needed.
To add a new language:
- Add
client/src/locales/<code>.jsonwith the same key structure asen.json. If you can't translate every key, leave those strings in English instead of removing the keys. - Add the language's display name to
languageNamesinclient/src/Components/inputs/LanguageSelector.tsx, for exampleit: "Italiano". The selector picks up the new file automatically. - 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.
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
developbranch
Smaller pull requests get faster and better reviews. The maintainers explain why in the importance of small pull requests.
Code guidelines
- Run
npm run lintandnpm run format-checkin bothclientandserver. Ifformat-checkreports problems, fix them withnpm run formatbefore you commit. - Use
camelCasefor variables,PascalCasefor components andUPPER_CASEfor 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-checkandnpm run buildpass in bothclientandserver
If something is missing, we may ask you to update the pull request before we merge it.
Branching model
- Code contributions go to the
developbranch. masterholds stable releases.- Use descriptive branch names, such as
fix/login-errororfeat/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.