Contributing to Razzle
Hi there! Thanks for your interest in Razzle. This guide will help you get started contributing.
- Contributing to Razzle
- optionally install add-dependencies
- git checkout -b my-feature-branch master
- git checkout -b my-feature-branch three
- to make sure tests pass
- to add a new example
- to work on a example
- if it is a example with webpack5 you need to do
- switch back to webpack4 later to work with webpack4
- if you want to add dependencies to the example
- if you make changes to startserver plugin
- to run example tests with unreleased razzle packages with specific webpack and specific tests
- Commands being run during testing puts output and puppeteer screenshots in test-artifacts/
- Trouble with puppeteer?
- [Updating your fork](#updating-your-fork)
Razzle is monorepo made up of a several npm packages powered by Lerna.
examples: All examples go in here.
packages: This is where the magic happens
babel-preset-razzle: Razzle's default Babel preset.
create-razzle-app: Razzle's CLI tool responsible for initialization of new projects
razzle: The core library
razzle-dev-utils: Utilities and helpers
scripts: Utility scripts related to cleaning and bootstrapping the repo
test: End-to-end tests
First, fork the repo to your GitHub account. Then clone your fork to your local machine and make a new branch for your feature/bug/patch etc. It's a good idea to not develop directly on master so you can get updates.
git clone https://github.com/<YOUR_GITHUB_USERNAME>/razzle.git cd razzle git checkout -B <my-branch> NODE_ENV=development yarn install ---ignore-engines # optionally install add-dependencies sudo npm install add-dependencies -g
This will install all
node_modules in all the packages and symlink
inter-dependencies. Thus when you make local changes in any of the packages you can try them
immediately in all the examples.
add-dependencies can be used to just add packages to
yarn clean: Clean up all
node_modulesand remove all symlinks from packages and examples.
yarn test --runInBand: Runs all tests
yarn test:packages: Runs tests for packages
yarn test:e2e: Runs end-to-end tests
yarn build-docs: Builds docs/ updates doc TOC
yarn publish-all-canary: Does a
yarn publish-all-stable: Does a a stable release(uses the npm version released of the packages)
yarn new-example: Creates a new example from another example.
yarn new-example basic new-example.
yarn bootstrap-examples: Run
yarnwith specific examples as workspaces. Automatically symlinks inter-dependent modules. Run
yarn restrapin the example to reinstall.
yarn test:examples:simple: Runs tests for all simple examples (uses the npm version released of the packages)
yarn test:examples:complex: Runs tests for all complex examples (uses the npm version released of the packages)
yarn test:examples: Runs tests for all examples (uses the npm version released of the packages)
git clone https://github.com/<YOUR_GITHUB_USERNAME>/razzle.gitcd razzlegit checkout -b my-feature-branch canary# or# git checkout -b my-feature-branch master# git checkout -b my-feature-branch threesudo npm install add-dependencies yalc -gpwd# /home/oyvind/Documents/GitHub/razzle/NODE_ENV=development yarn install ---ignore-engines# to make sure tests passyarn test --runInBand# to add a new exampleyarn new-example existingexample with-somefeature# to work on a examplecd examples/basicexample="$(basename $PWD)"pushd ../..# if it is a example with webpack5 you need to doyarn add -W firstname.lastname@example.org email@example.com# switch back to webpack4 later to work with webpack4yarn add -W firstname.lastname@example.org email@example.com# thenyarn bootstrap-examples $examplepopdyarn build# if you want to add dependencies to the exampleadd-dependencies somedependencyyarn restrap# if you make changes to startserver pluginpushd ../..cd packages/razzle-start-server-webpack-pluginyarn buildpopd# to run example tests with unreleased razzle packages with specific webpack and specific testsWEBPACK_DEPS="firstname.lastname@example.org email@example.com" PACKAGE_MANAGER="yalc" NPM_TAG="development" yarn test:examples --runInBand -t with-tailwindcssWEBPACK_DEPS="firstname.lastname@example.org email@example.com" PACKAGE_MANAGER="yalc" NPM_TAG="development" yarn test:examples --runInBand -t with-tailwindcss# Commands being run during testing puts output and puppeteer screenshots in test-artifacts/# Trouble with puppeteer?sudo sysctl -w kernel.unprivileged_userns_clone=1
When you want to pull down changes to your fork enter the following into your terminal:
git checkout mastergit pull origin master
If you'd like to add an example, I suggest you duplicate the
yarn new-example basic your-exampleand use that as kind of base template. Before you start adding stuff, go ahead and change the name of the package in the your new example's
package.json. Then go back to the project root and run
yarn bootstrap-examples your-example. This will make sure that your new example is using your local version of all the
All example folders should be named
with-<thing-you-are-demonstrating>. Each example's npm package name (found in it's
package.json) should look like
- Make sure to comment the important parts of your code and include a well-written "Idea behind the example" section. This is more important to me than your actual code.
- Keep your example limited to one idea / library / feature (e.g. don't submit
with-styled-components-and-material-ui). That being said, there are times when this rule will be relaxed such as if you are showing how to use Apollo and Redux or \<Flux Library> + React Router.
- Your example MUST implement Hot Module Replacement. If it does not update when you make edits, you have broken something.
- Your example should be minimalistic and concise, or a direct copy of another prominent example from the original library (like copying an example directly from react-redux).
I will do my best to write out my reasoning before closing a PR, but 80% of the time it falls under one of these...
- You did not read this document
- Your code breaks an internal application (I will be transparent about this)
- Your code conflicts with some future plans (I will be transparent about this too)
- You've said something inappropriate or have broken the Code of Conduct
We use the project README to recognize the contributions of members of the project community.
To add a contributor:
all-contributors add github_username doc,code