👋 We're so excited you're interested in helping with Blitz! We happy to help you get started, even if you don't have any previous open-source experience :)
NOTE: This video is currently outdated as our codebase is going through some significant refactorings. We'll record a new one soon. But it's probably still somewhat helpful. Watch this video for a walkthrough of the entire Blitz codebase. This is a great way to get an overview of the various parts and how they fit together!
Issues with the label
are the best place to start.
We also label issues as
good first issue and
good second issue when
If you find one that looks interesting and no one else is already working on it, comment in the issue that you are going to work on it. But only claim an issue if you can start work on it within a couple days.
Please ask as many questions as you need, either directly in the issue or in Discord. We're happy to help!
The Blitzjs.com website and documentation repo also has issues with
ready to work on | help wanted.
If there's some other way you'd like to contribute, ask us about it in Discord!
After you contribute in any way, please add yourself as a contributor via the @all-contributors bot!
The Blitz codebase is like a community garden. There's a lot of beautiful plants and vegetables, but it won't take long until you find some weeds! When you find weeds, please remove them :) Minor refactoring is always encouraged. If you'd like to do some major refactoring, it's best to first either open an issue or check with us in Discord. Most likely we'll agree with you.
A Blitz maintainer will review your PR, usually within a couple days.
If your PR changes user facing code, make sure you also made a PR to the docs repo, otherwise this will block your PR from being merged.
You also need to add tests to cover the changes you made.
Once all the requirements are met and the maintainer is happy with your code, they will merge it to the canary branch. It will then be included in the next Blitz release.
Lastly, you will be added the all-contributors list as an official Blitz contributor. Congratulations!!
We use a GitHub Project Board to track all issues and PRs.
We give liberal commit access to the Blitz repo to anyone who is a half-way regular contributor. This allows you to push branches directly to the Blitz repo without using a fork.
We'll often give someone access if we notice they are regularly contributing. But you're also welcome to ask for access if you are regularly helping but haven't been given access yet.
In the main Blitz repo, code reviews by code owners are required to merge PRs.
But in the docs repo, anyone can merge PRs once someone else has approved the PR.
1. Fork the blitz repo
2. Clone your forked repo
# replace USERNAME below with your GitHub username git clone email@example.com:USERNAME/blitz.git cd blitz
3. Install dependencies
4. Start the package server. This must be running for any package development or example development
Most Blitz packages in
packages/ have jest unit tests.
yarn testinside that package folder (like
yarn testonly:packages. (Make sure you have ran
yarn devprior to running this)
Blitz integration tests are inside the root
Make sure you have
chromedriver installed for your Chrome version. You
can install it with
brew install --cask chromedriveron Mac OS X
chocolatey install chromedriveron Windows
You can run all integration tests by running
yarn test:integration from
the repo root. Or you can run
yarn testheadles to run them in headless
mode (so it doesn't open a web browser window).
To run a specific integration test, you can run this:
yarn testheadless --testPathPattern "integration/queries"
integration/queries is the path inside
You can manually run the integration app by running
blitz dev inside the
integration test folder, like
The example apps have been functioning as our integration tests, but we'll be moving those tests into the above integation test setup.
To run an example app, first run
yarn build or
yarn dev from the repo
root. Then in another window, change to the example app folder like
examples/auth/ and run
To run the example app tests, run
yarn test from the example app folder.
All Next.js tests are inside
nextjs/test/. There are a lot of tests,
so probably you will want to run only one at a time.
To run these tests, run the following inside the
yarn testonly --testPathPattern "integration/basic"
yarn testheadless --testPathPattern "integration/basic"
The typical workflow will be only run next.js integation tests related to your change. Then push to CI and see if any other intergration tests fail. If they do, then locally run the one that fails and fix the issue.
Currently, to test the local dev version of Blitz, you can only test
an app inside the
blitz/examples/ folder. In there, the blitz dependency
will automatically use the local dev version. We mainly use the
store example apps. We use them for development testing and for blitz
integration tests. You must also make sure you are running
yarn dev in
blitz folder at the same time.
For using in apps outside the repo, yalc should work, but hasn't been tested yet. If you figure out how to use yalc, please make a PR to this page explaining how to set it up!
git remote add upstream firstname.lastname@example.org:blitz-js/blitz.git ./scripts/fetchRemote.sh git merge upstream/canary
The following will link the development CLI as a local binary so you can use it anywhere for testing.
yarn link-cli yarn link blitz // `yarn unlink blitz` // `yarn unlink-cli` will unlink
If you run into issues that should be documented here, please submit a PR! ❤️
node-pty error when running
yarn. Fix by installing
sudo apt install -y make python build-essential
This issue is related with yarn > 1.19.1, if you get an error like this in your console:
An unexpected error occurred: "expected workspace package to exist for \"@wessberg/rollup-plugin-ts\"
Fix it with this command:
yarn policies set-version 1.19.1
Are you unable to commit? Do you get errors like
yarn: command not found
stdin is not a tty? That's probably a Husky error! Try checking their
If you run into symlink and EPERM errors when trying to run Preconstruct on Windows, you may need to enable Windows Developer Mode so that Preconstruct can create symlinks.
If you have errors about missing files even after you run
try cloning again your repository with the configuration
true like this:
git clone -c core.symlinks=true <URL>.