Skip to content

Contributing to Ballerine

Thank you for investing your time in contributing to our project!

Before moving forward please read our code of conduct, and our style guide.

What to contribute

We accept contributions in different sizes and varied difficulty, from documentation and typos, to features and bug fixes. To see what you could help with, report an issue, or suggest a feature see issues and discussions.

Need help?


node: ">=16.15.1"
pnpm: ">=7.11.0"


  1. Clone Ballerine’s repository
git clone
  1. Navigate to the directory and install dependencies
cd ballerine && pnpm install
  1. Start the dev server
pnpm run dev
  1. Open the page in your browser

Project structure

├── apps # end user facing, interacts with packages and services
├── community # ui packs, ui components, and vendor integrations made by the community
├── packages # shared logic between apps, community, sdks, and services
├── sdks # dev kits for developers to create experiences and applications, interacts with apps
 (can load an app into a certain platform such as web or native)
└── services # backend microservices, services communicate through a communication layer
(i.e REST/HTTP requests), and may communicate with a database

First commit

Branch name

This project makes use of branchlint to ensure that all branch names follow a consistent format with a CLI to help with the process of creating a new branch, setting upstream, and checking out to the new branch.

Commit message

This project makes use of tools like commitizen and commitlint to ensure that all commits follow a consistent commit message format with a CLI to help with the process of pushing a commit.

  1. Create a new branch, set upstream, and checkout to the new branch

Make sure to run this NPM script in the root of the monorepo and follow the CLI prompts.

pnpm run branchlint
  1. Make your changes

  2. Push a formatted commit

Make sure to run this NPM script in the root of the monorepo and follow the CLI prompts.

pnpm run commit
  1. Push the commit
git push
  1. GitHub Actions

Now that the changes are pushed to the remote branch, GitHub Actions will run workflows for building, testing, linting, and formatting. Before creating a pull request, make sure that all workflows have passed.

  1. Create a pull request

When creating a pull request, make sure to follow the pull request template.

Contributing using a fork

  1. Head to the repository.
  2. Click on the “Fork” button on the top right corner of the GitHub page.
  3. Create the fork.
  4. Follow the instructions from prerequisites up to creating a pull request.
  5. On the compare page, click compare across forks.
  6. In the “base branch” drop-down menu, select the branch of the upstream repository you’d like to merge changes into.
  7. In the “head fork” drop-down menu, select your fork, then in the “compare branch” drop-down menu to select the branch you made your changes in.
  8. Create the pull request.