Love Redwood and want to get involved? You’re in the right place!
⚡️ Quick Links
There are several contributing docs and references, each covering specific topics:
- 🧭 Overview and Orientation
- 📓 Reference: Contributing to the Framework Packages (👈 you are here)
- 🪜 Step-by-step Walkthrough (including Video Recording)
- 📈 Current Project Status: v1 Release Board
- 🤔 What should I work on?
Before interacting with the Redwood community, please read and understand our Code of Conduct.
As a Redwood developer, you're already familiar with the codebase created by yarn create redwood-app. In this document, we'll refer to that codebase as a Redwood Project.
As a contributor, you'll have to familiarize yourself with one more codebase: the Redwood Framework. The Redwood Framework lives in the monorepo redwoodjs/redwood (which is where you're probably reading this). It contains all the packages that make Redwood Projects work the way they do. In a Redwood Project, you can find the Redwood Framework in node_modules/@redwoodjs.
Here we'll assume your local copy of the Redwood Framework is in a directory called redwood and your Redwood Project is in a directory called redwood-project.
Chances are that you'll have more than a few VS Codes open when you're contributing—one with the Redwood Framework and one with a Redwood Project at least. An easy way to tell which-is-which is by looking for a red bar at the bottom. The one with a red bar is the Redwood Framework:
Use git clone to get a local copy of the Redwood Framework. If you've already got a local copy, make sure you've got the main branch's latest changes using git pull. Then run yarn install in the root directory to install the dependencies:
git clone https://github.com/redwoodjs/redwood.git
cd redwood
corepack enable
yarn install
You'll almost always want to test the functionality of your changes to the Redwood Framework in a Redwood Project. When it comes to getting a Redwood Project to test your changes out in, you have several options:
- run
yarn create redwood-app ./redwood-project git clonethe RedwoodJS Tutorial Blog- use a project you've already created
- create a functional test project: go to the location of your local copy of the Redwood Framework and use
yarn run build:test-project <project directory>👀
Using the functional test project might be the fastest and easiest way to test your changes.
You can create a Redwood Project that contains a lot of functionality in just a few minutes. For example, here's a brief overview of all the things yarn run build:test-project <project directory> does. It...
- installs using the
create-redwood-apptemplate in the current branch of your Redwood Framework - with the current
canaryversion of Redwood Packages (with the option to use thelateststable version) - with a TypeScript language target (with the option for JavaScript)
- then applies code mods from the Redwood tutorial to add functionality and styling
- and initializes a Prisma DB migration for SQLite
Run yarn run build:test-project <project path> from the root of your local copy of the Redwood Framework to create a functional test project.
Besides
<project directory>,build:test-projecttakes a few other options as well:
Arguments & Options Description <project directory>Directory to build test project [default: "./blog-test-project"] --javascriptGenerate a JavaScript project [default: false] --linkCopy Framework dependencies and packages into Test-project [default: false] --verboseVerbose output [default: false] --cleanDelete existing directory and recreate Test-project [default: false] --canaryUpgrade project to latest canary version; NOT compatible with --link [default: true] --helpShow help Example:
cd redwood/ yarn run build:test-project ~/my-repos/redwood-project --javascript --link
Unless you've already got a project with a lot of functionality, it'd take quite some effort to add all of this yourself. Moreover, testing your changes in a project that has a lot of functionality will increase your confidence in the changes you're making.
But how do you actually test your changes in the Redwood Framework in your Redwood Project? With another command, this time in the root of your Redwood Project: yarn rwfw.
As you make changes to the Redwood Framework, you'll want to see your changes reflected "live" in a Redwood Project. Since we're always looking for ways to make contributing to Redwood easier, there are a few workflows we've come up with. The one you'll want to use is yarn rwfw.
rwfwis short for Redwood Framework.
The command requires an env var RWFW_PATH. Unless you add the env var and value to your shell, the command structure will be RWFW_PATH=<framework directory> yarn rwfw [option].
Note: On Windows, use
yarn cross-env RWFW_PATH=<framework directory> rwfw [option]
Navigate to your Redwood Project and run the following, replacing ~/redwood to match your local path:
cd redwood-project
RWFW_PATH=~/redwood yarn rwfw project:sync
Where ~/redwood is the path to your local copy of the Redwood Framework. Once provided to rwfw, it'll remember it and you shouldn't have to provide it again unless you move it.
As project:sync starts up, it'll start logging to the console. In order, it:
- cleans and builds the framework
- copies the framework's dependencies to your project
- runs
yarn installin your project - copies over the framework's packages to your project
- waits for changes
Step two is the only explicit change you'll see to your project. You'll see that a ton of packages have been added to your project's root package.json:
This is all the packages in the Redwood Framework. It's a lot! But don't worry, this'll be cleaned up when you exit the yarn rwfw project:sync command.
Congratulations, you're all setup! Any changes you make in the Redwood Framework should be reflected in your Redwood Project.
While you can test the CLI using yarn rwfw, there's an easier way.
If you've made build or design time changes to RedwoodJS—that is, if you've modified one of the following packages:
- api-server
- cli
- core
- eslint-config
- internal
- prerender
- structure
- testing
You can run a development version of the CLI directly from your local copy of the Redwood Framework. You don't even have to sync any dependencies or files!
For all the packages above, the entry point is the CLI. They're what we consider "build time" and "design time" packages, rather than "run-time" packages (which are web, auth, api, and forms).
To do that, use the --cwd option to set the current working directory to your Redwood Project:
cd redwood
yarn build
cd packages/cli
yarn dev <cli command> --cwd <project directory>
yarn dev runs the CLI and --cwd makes the command run in your Redwood Project. If you make a change to the code, remember to rebuild the packages!
Tip: You can use
yarn build:watchto automatically build the framework whilst you're making changes.Tip 2: --cwd is optional, it will reference the
__fixtures__/example-todo-mainproject in the framework.
You can use the button below to start a developer environment in the cloud and access it through your browser or favourite IDE locally!
This generates a functional test project and links it with the Redwood Framework code in main, giving you an easy playground to try out your fixes and contributions.
Note: if you make changes to the framework, you will need to run
yarn rwfw project:syncin the terminal, so that your changes are watched and reflected in the test project
All of these checks are included in Redwood’s GitHub PR Continuous Integration (CI) automation. But it’s good practice to understand what they do by using them locally too. The E2E tests aren’t something we use every time anymore (because it takes a while), but you should learn how to use it because it comes in handy when your code is failing tests on GitHub and you need to diagnose.
Within your Framework directory, use the following tools and commands to test your code:
- Build the packages:
yarn build- to delete all previous build directories:
yarn build:clean
- to delete all previous build directories:
- Syntax and Formatting:
yarn lint- to fix errors or warnings:
yarn lint:fix
- to fix errors or warnings:
- Run unit tests for each package:
yarn test - Check Yarn resolutions and package.json format:
yarn check- includes yarn dedupe, constraints, and package.json formatter
We use Cypress to test the steps in the tutorial. You can run this end-to-end (e2e) test locally by running the following in your local copy of the Redwood Framework:
yarn e2e
This creates a new project using yarn create redwood-app in a temporary directory. Once created, it upgrades the project to the most-recent canary release, which means it'll use the code that's in the main branch. Once upgraded, it starts Cypress.
If you want to run any of the integration tests against an existing project instead of creating a new one, just provide the path to the project:
yarn e2e <project directory>
In this case, the command will not upgrade the project to the most-recent canary release.
Windows Not Supported: The command for this is written in bash and will not work on Windows.
Most of the time your contribution to Redwood won't involve adding any new dependencies. But of course it also sometimes will, and there's some gotchas in our CI checks that you should be aware of:
- we have a yarn constraint that fails if it sees a caret in a version (e.g. something like
^2.5.4isn't allowed)- the solution to this is simple: pin the version (e.g.
2.5.4, without the caret—yarn constraints --fixmay do this for you)
- the solution to this is simple: pin the version (e.g.
- we check for duplicate dependencies and fail if we find any
- the solution to this is also simple: run
yarn dedupe
- the solution to this is also simple: run
- we check that all of our
package.jsons are sorted- if you happen to accidentally "unsort" a package.json, fixing this should be easy: run
yarn dlx sort-package-jsonin the unsorted workspace
- if you happen to accidentally "unsort" a package.json, fixing this should be easy: run
As of v0.37, the Redwood Framework has moved from yarn v1 to yarn v3.
If you already have a local copy of the Redwood Framework, or if you're switching between branches that are using different versions, you'll have to run:
git clean -fxd -e .env
yarn install
...and then you'll be good to go.
Note: Yarn v3 is installed in the directory, while Yarn v1 is installed globally. This allows us to switch as needed per branch and/or project.
yarn add --interactive
Reuse the specified package from other workspaces in the project. Example:
yarn workspace create-redwood-app add -i rimraf
Note: Interactivity is enabled by default
For example, if we're using yarn add to add a dependency to a workspace (say packages/codemods), and we already have that dependency in another workspace (say packages/api-server), yarn will ask us if we want to use the same version:
redwood/packages/codemods$ yarn add yargs
? Which range do you want to use? …
❯ Reuse yargs@16.2.0 (originally used by @redwoodjs/api-server@0.37.2 and 2 others)
Use yargs@^17.2.1 (resolved from latest)
yarn workspaces foreach ...
This is a command from the workspaces plugin. Runs the command across all workspaces. Example:
yarn workspaces foreach -i -v some-package
-v: outputs the package name the command is currently running against
yarn dedupe --check
Duplicates are defined as descriptors with overlapping ranges being resolved and locked to different locators. They are a natural consequence of Yarn's deterministic installs, but they can sometimes pile up and unnecessarily increase the size of your project. This command dedupes dependencies in the current project using different strategies (only one is implemented at the moment):
yarn constraints
See new file constraints.pro for repo config
- https://yarnpkg.com/features/constraints
- Reference from Babel project: https://github.com/babel/babel/blob/main/constraints.pro
Aside from a few plugins, we aren't using most of it's advanced features (like PnP) yet.
So besides the output in your terminal looking different, not much else is.
We may explore things like PnP in the future. We just have to take things one step at a time since we're trying to release
v1.
Some of the benefit yarn v3 brings us as we prepare for v1 are:
- faster CI (up to 50% faster)
- most importantly, no more Windows timeouts!
- faster yarn installs
- better dependency guarantees
One of the most significant changes in yarn v3 is it's stance on hoisting.
Yarn v3 keeps more of itself in the repo than before.
For example, yarn v3 isn't installed globally, but on a per-project basis.
Here's a quick overview of some of the new yarn-related files in this repo:
| File | Description |
|---|---|
.yarnrc.yml |
Yarn's configuration file |
.yarn/plugins |
Where installed plugins live |
.yarn/releases |
The yarn v3 binaries themselves |
If needed, there's more information in this PR #3154 comment about special cases:
- "Binary hoisting" is no longer allowed
- Specifying Yarn v1 binary (when necessary)
yarn dlx- Set
YARN_IGNORE_PATH=1to ignore local yarn version settings. - how "postinstall" script works
Are you about to open an issue? Including a reproduction, either as a series of steps, as a public GitHub repo, or as a Gitpod snapshot, will definitely let us help you faster!
This is a great option when the issue you're reporting is cross-platform. I.e., it isn't a Windows-specific issue. Here's a video walkthrough on how to create a snapshot of the Redwood-Gitpod starter repo:
Reproductions.with.Gitpod.2.mp4
You can always fork the Redwood-Gitpod starter repo which is a brand new project with the latest stable version of Redwood. Once you make your changes in your fork, include the link to your repo in your issue. This'll make it much easier for us to understand what's going on.
Every time a commit is added to the main branch, a canary release is automatically published to npm. The most recent canary packages can be used in Redwood Project via the following command:
yarn rw upgrade --tag canary
For testing and QA purposes, Release Candidates (RCs) will be published prior to a GA release. The process is (will be) automated:
- a release branch is created from
main, e.g.release/minor/v1.2.0 - once published, any commits to the release branch will trigger automatic publishing of an RC, e.g.
v1.2.0-rc.1
The most recent RC packages can be used in Redwood Projects via the following command:
yarn rw upgrade --tag rc