How to Contribute

👋 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 :)

First Things First

1. New to open source? take a look at How to Contribute to an Open Source Project on GitHub
2. Familiarize yourself with the Blitz Code of Conduct
3. Learn how the community operates

What to Work On?

Issues with the label status/ready-to-work-on are the best place to start.

We also label issues as good first issue and good second issue when appropriate.

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.

Things that are ALWAYS welcome

• Adding tests
• Improved documentation
• Improved error messages
• Improved logging (i.e. more clear, more beautiful)
• Performance or security improvements
• Educational content like blogs, videos, courses

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!

Our Codebase is a Garden

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.

What to Expect After Submitting a PR

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!!

Project Management

We use a GitHub Project Board to track all issues and PRs.

Commit Access

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.

Development Setup

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 git@github.com:USERNAME/blitz.git
cd blitz

3. (Optional, macOS only) Install required packages for sodium-native

If you spot any issues related to sodium-native, run the following command to fix it:

brew install autoconf automake

4. Install dependencies

pnpm i

5. Start the package server. This must be running for any package development or example development

pnpm dev

Running Tests

Blitz.js Tests

Unit Tests

Most Blitz packages in packages/ have vitest unit tests.

• Run tests in a single package by running pnpm test inside that package folder (like packages/blitz-next)
• Run all unit tests from the repo root by running pnpm test. (Make sure you have ran pnpm build or pnpm dev prior to running this). Note: this will run all tests, including integration tests.

Integration Tests

Blitz integration tests are inside the root integration-tests/ folder.

Make sure you have chromedriver installed for your Chrome version. You can install it with

• brew install --cask chromedriver on Mac OS X
• chocolatey install chromedriver on Windows
• Or manually download the version that matches your installed chrome version (if there's no match, download a version under it, but not above) from the chromedriver repo and add the binary to <blitz-repo>/node_modules/.bin

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 integration-tests/auth/.

Testing Development Version of Blitz Inside an App

Link the Blitz CLI (Optional)

The following will link the development CLI as a local binary so you can use it anywhere for testing.

pnpm link ./packages/blitz

Doing A Release

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 package.json files.

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]
	@blitzjs/rpc@2.0.0-beta.18

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 changesets 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 blitz@2.0.0-beta.18 latest
npm dist-tag add @blitzs/auth@2.0.0-beta.18 latest
npm dist-tag add @blitzs/rpc@2.0.0-beta.18 latest
npm dist-tag add @blitzs/next@2.0.0-beta.18 latest

For more information about changesets pre-release mode, you can read their documentation here: changesets/prereleases.md at main · changesets/changesets · GitHub

Troubleshooting

If you run into issues that should be documented here, please submit a PR! ❤️

Git errors

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 troubleshoot guide.

Preconstruct errors

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.

Missing files in Windows

If you have errors about missing files even after you run pnpm build, try cloning again your repository with the configuration core.symlinks set to true like this: git clone -c core.symlinks=true <URL>.