Interested in making GrowthBook better? So are we! This guide should help get you setup with a local development environment so you can make changes, create PRs, and get your code merged.
If you just want to contribute a client library in a new language and not make changes to the app itself, you can skip the instructions here and view https://docs.growthbook.io/lib/build-your-own instead.
- MacOS or Linux (Windows may work too, but we haven't tested it)
- NodeJS 18.x or above
- Check version by running
node -v
on terminal
- Check version by running
- Yarn
- Python 3.8+ (for the stats engine)
- Docker (for running MongoDB locally)
One sure shot way to run GrowthBook on Windows is through installing Windows Subsystem for Linux (WSL). These are some of the steps to follow, also outlined in the link above:
- Search for your terminal app in the windows search bar
- Select the option to "Run as administrator"
- Now, on the terminal, run
wsl --install
- After the installation is complete, restart your computer
- Set up your Linux username and password
- Run
sudo apt update && sudo apt upgrade
(for Ubuntu or Desbian) to update and upgrade packages
Now you have the basic Linux system set up, and can follow along with all the other steps.
It's strongly recommended that if you are using WSL on Windows that you run the project from your /home/:user
directory rather than a /mnt/
directory: the /mnt
directory has poor performance, and the file watcher for nodemon will not work, requiring you to manually stop and re-run the yarn dev
command.
- Fork the project
- Clone your forked project by running
git clone git@github.com:{ YOUR_USERNAME }/growthbook.git
- Can also use
git clone
and list the HTTPS URL of the repo afterwards
- Can also use
- Run
cd growthbook
- Run
yarn
to install dependencies - Install poetry
- Run
curl -sSL https://install.python-poetry.org | python3 -
- Close and reopen your terminal
- Run
poetry --version
to confirm a successful install - If unsuccessful add the Poetry path (ex.
$HOME/.poetry/bin
) to your global path (ex./etc/profile
,/etc/environment
,~/.bashrc
,~/.zshrc
)
- Run
- Run
yarn setup
to do the initial build - If you have Docker installed, start MongoDB in Docker:
docker run -d -p 27017:27017 --name mongo \
-e MONGO_INITDB_ROOT_USERNAME=root \
-e MONGO_INITDB_ROOT_PASSWORD=password \
-v ~/gb_mongo_data/:/data/db \
mongo
The -v is optional and will store the data in your ~/gb_mongo_data directory on your computer. This will allow you to start a new docker container with the same command in case the old one dies preserving your data. Setup can also be shared between devs by replacing the contents of that directory with theirs.
If docker isn't running, view this. Look at this for other docker issues with Linux
Otherwise, install Mongo directly (no Docker)
- Run
yarn dev
to start the app in dev mode - Visit http://localhost:3000 in your browser and verify the app is working correctly
If you need to change any of the default configuration settings, you can use environment variables:
- Back-end:
cp packages/back-end/.env.example packages/back-end/.env.local
- Front-end:
cp packages/front-end/.env.example packages/front-end/.env.local
Then, edit the .env.local
files as needed.
This repository is a monorepo with the following packages:
- packages/front-end is a Next.js app and contains the full UI of the GrowthBook app.
- packages/back-end is an Express app and serves as the REST api for the front-end.
- package/shared is a collection of Typescript functions and constants shared between the front-end and back-end.
- package/enterprise contains proprietary code governed under the GrowthBook Enterprise license. We typically do not accept outside contributions for this package.
- packages/sdk-js is our javascript SDK (
@growthbook/growthbook
on npm) - packages/sdk-react is our React SDK (
@growthbook/growthbook-react
on npm) - packages/stats is our Python stats engine (
gbstats
on PyPi) - docs is a Docusaurus instance for our documentation site (https://docs.growthbook.io).
Depending on what you're changing, you may need to edit one or more of these packages.
The yarn dev
command starts both the front-end and back-end in parallel.
The packages are available at the following urls with hot-reloading:
- Front-end: http://localhost:3000
- Back-end: http://localhost:3100
GrowthBook uses MongoDB as a primary data store, and while working on the code it may be necessary to access the database directly. MongoDB Compass is the easiest way, but you can also use the mongosh shell.
To access MongoDB with the MongoDB Compass GUI, you can do the following after opening MongoDB Compass:
- In the menu bar, click Connect and choose New Connection
- Paste the connection string you configured in your
.env.local
here - Press Connect
At this point you should be connected to MongoDB and see your databases. Click into the desired database, e.g. growthbook
, to view your collections.
To access MongoDB with the mongosh
shell, run the following command:
docker exec -it mongo bash
Alternatively, if you are using Docker Desktop, you can click the CLI button to execute the shell for the Mongo container.
Then login as the user of the database. If your user is root
:
mongosh -u root
show dbs
should show you the databases in Mongouse <databasename>
will allow you to change to the right database. By default, you may be in another database and may need to calluse growthbook
show collections
should show you the collections for the database you are using. This will throw an error if you are not logged in as the correct user.db
is available and you should be able to run queries against it, e.g.db.users.find()
To start the docs site, first cd docs
and then run yarn
to install and yarn dev
to run the docs server. You can view the site at http://localhost:3200
To work on the SDKs, cd
into the desired directory and the following commands are available:
yarn test
- Run Jestyarn build
- Run the rollup build processyarn size
- Get the gzip size of the bundle (must runyarn build
first)
Releasing SDK updates is a very manual process right now. It requires bumping versions in many different files, updating changelogs, and adding metadata to shared packages.
- Create a branch from the latest main
- Bump version of the Javascript SDK
- Bump version in
packages/sdk-js/package.json
- Bump dependency version in
packages/back-end/package.json
- Bump dependency version in
package/shared/package.json
- Bump dependency version in
packages/sdk-react/package.json
- Add new entry to
packages/sdk-js/CHANGELOG.md
- Add new entry to
packages/shared/src/sdk-versioning/sdk-versions/javascript.json
- Add new entry to
packages/shared/src/sdk-versioning/sdk-versions/nodejs.json
- If any new capabilities were introduced and they work by default, update
packages/shared/src/sdk-versioning/sdk-versions/nocode.json
. - Update resolutions in
package.json
- Bump version in
- Bump versions of the React SDK
- Bump version in
packages/sdk-react/package.json
- Bump dependency version in
package/front-end/package.json
- Add new entry to
packages/shared/src/sdk-versioning/sdk-versions/react.json
- Bump version in
- Do a global search for the old version strings for both Javascript and React to make sure nothing was missed. Update these instructions if needed.
- Run
yarn install
. There should be zero changes toyarn.lock
. If there are, you missed something above. - Create a PR and let CI complete successfully. Use the changelog entry as the PR description.
- Publish the Javascript SDK
yarn build
npm publish
- Publish the React SDK
yarn build
npm publish
- Merge the PR
Ensure you have run yarn setup
first to install the poetry virtual environment before working in the stats engine. Otherwise, pre-commit hooks and the following commands will error.
yarn workspace stats test
- Run pytestyarn workspace stats lint
- Run flake8, black, and pyrightyarn workspace stats build
- Run the build processyarn workspace stats notebook
- Spin up a Jupyter Notebook withgbstats
and other dependencies in the kernel
You can also just run yarn *
where * is test, lint, build if you cd
to the packages/stats
directory first.
There are a few repo-wide code quality tools:
yarn test
- Run the full test suite on all packagesyarn type-check
- Typescript type checkingyarn lint
- Typescript code lintingyarn workspace stats lint
- Python code linting (ensure you have runyarn setup
first to install the poetry virtual environment)
There is a pre-commit hook that runs yarn lint
automatically, so you shouldn't need to run that yourself.
-
Please Provide a thoughtful commit message and push your changes to your fork using
git push origin main
(assuming your forked project is usingorigin
for the remote name and you are on themain
branch). -
Open a Pull Request on GitHub with a description of your changes.
If you see this warning, it is likely because you ran yarn setup
from within a Python virtual environment, and Poetry currently does not create a custom environment for the stats library from within another virtual environment (see: python-poetry/poetry#4055).
To resolve this, ensure you are not using a Python virtual environment and re-run yarn setup
from the project root.
Join our Slack community if you need help getting set up or want to chat. We're also happy to hop on a call and do some pair programming.