👋 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 :)
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.
Make sure you're using Node 14 — Next uses
node-sass which does not work
with newer Node versions.
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. (Optional, macOS only) Install required packages for
If you spot any issues related to
sodium-native, run the following
command to fix it:
brew install autoconf automake
4. Install dependencies
5. Start the package server. This must be running for any package development or example development
Most Blitz packages in
packages/ have vitest unit tests.
pnpm testinside that package folder (like
pnpm test. (Make sure you have ran
pnpm devprior to running this). Note: this will run all tests, including integration tests.
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 tests (both unit tests and integration tests) by running
pnpm test from the repo root.
You can manually run the integration app by running
blitz dev inside the
integration test folder, like
Currently, to test the local dev version of Blitz, you can test an app
blitz/apps/ folder. In there, the blitz dependency will
automatically use the local dev version. We use it for development
testing. You must also make sure you are running
pnpm dev in the
folder at the same time.
The following will link the development CLI as a local binary so you can use it anywhere for testing.
pnpm link ./packages/blitz
We use the changesets package
& a forked version of their GitHub action which can be found here:
GitHub - blitz-js/changesets-action.
Every user facing PR should have a changeset. When that PR gets approved
and merged to the
main branch the "release" PR with the name
Version packages (beta) is automatically created or updated. This PR
updates each internal package's changelog & each blitz package's version
by incrementing it in the
Once the auto generated PR accumulates enough changesets, It's time to do
a release by merging this PR into the
main branch. To trigger the
release action, you must squash and merge the PR without waiting for the
requirements to be met, bypassing the branch protections rule. This is
because the CI doesn't run on PR's generated by a github action. Once you
merge this PR, it will generate the release action and publish on npm &
create a release on GitHub.
The auto generated release on GitHub, still requires some manual cleaning. It's recommended to remove some "fluff" like:
Updated dependencies [3b213a3] @firstname.lastname@example.org
It's also important to note, that since we haven't done a stable release
yet that we're in a pre-release mode set with the
changesets package. So
with that being said, you will need to uncheck the
Set as a pre-release
checkbox while editing the release on Github, and selecting
Set as the latest release checkbox.
While on the category of being in prerelease mode with the
package, when published to npm we also want to ensure that each package
gets tagged with
latest. This requires manual work and the correct npm
permissions. This is mostly for our internal team. For each package run:
npm dist-tag add email@example.com latest npm dist-tag add @firstname.lastname@example.org latest npm dist-tag add @email@example.com latest npm dist-tag add @firstname.lastname@example.org latest
For more information about
changesets pre-release mode, you can read
their documentation here:
changesets/prereleases.md at main · changesets/changesets · GitHub
If you run into issues that should be documented here, please submit a PR! ❤️
Are you unable to commit? Do you get errors like
command not found or
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>.