CONTRIBUTING.md

Contributing

Love Redwood and want to get involved? You’re in the right place!

Before interacting with the Redwood community, please read and understand our Code of Conduct.

Table of Contents

• Contributing
  • Local Development
    • Copy and Watch
      • Specifying a RW_PATH
    • Local Package Registry Emulation
      • Setting Up and Running a Local NPM Registry
      • Publishing a Package
      • Installing Published Packages in Your Redwood App
  • Running Your Redwood App's Local Server(s)
  • Releases

Local Development

As a Redwood user, you're already familiar with the codebase yarn create redwood-app creates. Here we'll call this codebase a "Redwood App"--it’s the fullstack-to-Jamstack solution you already know and love.

As a contributor, you'll have to gain familiarity with one more codebase: the Redwood Framework. The Redwood Framework lives in the monorepo redwoodjs/redwood; it contains all the packages that make Redwood Apps work the way they do.

While you'll be making most of your changes in the Redwood Framework, you'll probably want to see your changes “running live" in one of your own Redwood Apps or in one of our example apps. We offer two workflows for making this possible: "copy and watch", which has some restrictions, and "local package registry emulation", which doesn't.

How to choose which one to use? If you've installed or upgraded a dependency, use the "local package registry emulation" workflow; otherwise, use "copy and watch".

Both workflows use redwood-tools (alias rwt), Redwood's companion CLI development tool.

Copy and Watch

First, build-and-watch files in the Redwood Framework for changes:

cd redwood
yarn build:watch

@redwoodjs/api: $ nodemon --watch src -e ts,js --ignore dist --exec 'yarn build'
@redwoodjs/core: $ nodemon --ignore dist --exec 'yarn build'
create-redwood-app: $ nodemon --ignore dist --exec 'yarn build'
@redwoodjs/eslint-plugin-redwood: $ nodemon --ignore dist --exec 'yarn build'

Then, watch-and-copy those changes into your Redwood App or example app (here, example-invoice):

cd example-invoice
yarn rwt copy:watch ../path/to/redwood

Redwood Framework Path:  /Users/peterp/Personal/redwoodjs/redwood
Trigger event:  add
building file list ... done

Now any changes made in the framework will be copied into your app!

Specifying a RW_PATH

You can create a RW_PATH environment variable so you don't have to specify the path in the copy:watch command.

On Linux

Add the following line to your ~/.bashrc:

export RW_PATH=”$HOME/path/to/redwood/framework”

Where /path/to/redwood/framework is replaced by the path to your local copy of the Redwood Framework.

Then, in your Redwood App or example app, you can just run:

yarn rwt copy:watch

And see your changes copied!

On Mac

Add the following line to your ~/.bash_profile:

export RW_PATH=”$HOME/path/to/redwood/framework”

Where /path/to/redwood/framework is replaced by the path to your local copy of the Redwood Framework.

Then, in your Redwood App or example app, you can just run:

yarn rwt copy:watch

And see your changes copied!

On Windows [Todo: please contribute a PR if you can help add instructions here.]

Local Package Registry Emulation

Sometimes you'll want to test the full package-development workflow: building, publishing, and installing in your Redwood App. We facilitate this using a local NPM registry called Verdaccio.

Setting Up and Running a Local NPM Registry

First, install Verdaccio:

yarn global add verdaccio

Then, in your local copy of the Redwood Framework, run:

./tasks/run-local-npm

This starts Verdaccio (http://localhost:4873) with our configuration file.

Publishing a Package

To build, unpublish, and publish all the Redwood packages to your local NPM registry with a "dev" tag, run:

./tasks/publish-local

Note: this script is equivalent to running:

npm unpublish --tag dev --registry http://localhost:4873/ --force
npm publish --tag dev --registry http://localhost:4873/ --force

You can build a particular package by specifying the path to the package: ./tasks/publish-local ./packages/api.

For example, if you've made changes to the @redwoodjs/dev-server package, you would run:

./tasks/publish-local ./packages/dev-server

Installing Published Packages in Your Redwood App

The last step is to install the package into your Redwood App. The CLI command redwood-tools (alias rwt) makes installing local NPM packages easy:

yarn rwt install @redwoodjs/dev-server

Note: this is equivalent to running:

rm -rf <APP_PATH>/node_modules/@redwoodjs/dev-server
yarn upgrade @redwoodjs/dev-server@dev --no-lockfile --registry http://localhost:4873/

Running Your Redwood App's Local Server(s)

When developing Redwood Apps, you’re probably used to running both the API and Web servers with yarn rw dev and seeing your changes included immediately. But for local package development, your changes won’t be included automatically--you'll need to manually stop/start the respective server to include them.

In this case you might find it more convenient to run the servers for each of the yarn workspaces independently:

yarn rw dev api
yarn rw dev web

Releases

To publish a new version of Redwood to NPM run the following commands:

yarn lerna version --force-publish
yarn lerna publish from-package

The changes the version of all the packages (even those that haven't changed) and publishes it to NPM.

Troubleshooting

If something went wrong you can use yarn lerna publish from-package to publish the packages that aren't already in the registry.