Add workflows for local development

[peterp]

Local development

When contributing to Redwood you'll often want to add, fix, or change something in the Redwood Framework's monorepo, and see the implementation "running "live" in your own side project or one of our example apps.

We offer two workflows for making that possible: "watch and copy" with some restrictions, and "emulate npm" without restrictions. The consideration for using the "emulate npm" workflow is if you've installed or upgraded a dependency, otherwise the "watch and copy" workflow should be fine.

Watch and copy

The first step is to watch files for changes and build those changes in the Redwood framework:

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'

The second step is to watch and copy those changes into your Redwood project:

cd example-invoice
yarn rwdev watch ../path/to/redwood

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

You can also create a RW_PATH env var and then you don't have to specify the path in the watch command.

Now any changes that are made in the framework are copied into your project.

Emulating package publishing

Sometimes you'll want to test the full development flow from building and publishing our packages, to installing them in your project. We facilitate this using a local NPM registry called Verdaccio.

Setting up and running a local NPM registry

yarn add global verdaccio
./tasks/run-local-npm

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

Publishing a package

./tasks/publish-local will build, unpublish, and publish all the Redwood packages to your local NPM registry with a "dev" tag, for the curious it is the equivalent of 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.

Installing published packages

Redwood installs rwdev a companion CLI development tool that makes installing local npm packages easy: yarn rwdev install @redwoodjs/dev-server.

This is equivilant to running:

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

[jtoar]

@peterp Thanks for this! I tried it out on my PR (#423) and everything Just-Works.

The one hitch I ran into was that there wasn't a rwdev symlink in my local development app's node_modules/.bin. This'll be fixed in the next release right? (Edit: just saw you added this PR to the v0.6.0 milestone.) In the mean time, I made it work by linking it to rwdev.js in my clone of the redwood repo.

Here's some of my thoughts so far:

• Is it confusing to call the it rwdev when there's already rw dev? I didn't get confused, but I don't know if I'm a fair judge b/c I'm trying to pay careful attention to everything. The name rwdev's nice and straightforward--that's what we're doing when we're using it, developing redwood. But was wondering if you considered any other names / think its different enough to avoid confusion in general?

• What was the motivation for making a separate binary as opposed to more arguments to redwood / rw?

Sometimes you'll want to test the full development flow from building and publishing our packages, to installing them in your project.

• Would the use case for this workflow be If I'm building a plugin, like for auth for example? Or should this always be done? I.e. is rwdev watch the first step, where you can iterate quickly and see changes, and then, when you're focused on testing, you "switch" to emulate package publishing?

[thedavidprice]

@peterp I’m coordinating with Dominic on some other Documentation efforts, so chiming in here. But of course please correct/add as needed.

@jtoar

The one hitch I ran into…

^^ Correct, this will show up in the next release. You did the correct process for testing/using now.

Is it confusing to call the it rwdev when there's already rw dev?

^^ I think this is fine for now. But 100% agree it’s probably not perfect. For development-specific tooling, though, we have a lot more margin for making adjustments and breaking changes as we go right now. I’d say ship as is.

separate binary

^^ One important aspect is to not include it in the list when you type “yarn rw —help”, which would be confusing to people developing (and not contributing). (note for @peterp I believe there is a Yargs method of hiding a command, but then we have other problems… so I like overall the direction to make tooling commands their own set.)

Sometimes you'll want to test the full development flow from building and publishing our packages, to installing them in your project.

• Would the use case for this workflow be If I'm building a plugin, like for auth for example? Or should this always be done? I.e. is rwdev watch the first step, where you can iterate quickly and see changes, and then, when you're focused on testing, you "switch" to emulate package publishing?

^^ Ah, I see your confusion here. First off, there are two different ways Peter is stating that you can set up local development 1) Watch and copy and 2) Emulating package publishing. Number 1 is a bit “easier” and/or “lightweight”, but it does not work in all cases. Number 2 is more of a “heavy lift” but will always work (it’s just not always needed).

If your focus is code changes or additions (including files), then Number 1 will work.

If you are making any changes or running tests that include Package-level concerns -- e.g. new version, add package, remove package, etc. — you have to use workflow Number 2.

[peterp]

@jtoar

Is it confusing to call the it rwdev when there's already rw dev?

I initially called it rwd, but I'm open to ideas: rw-fw-tools/ rw-framework-tools

[thedavidprice]

For me, "dev" is confusing between contributing vs. application development. So "tools" is more intuitive on my end.

Maybe "redwood-tools" with the alias "rwt"?

[peterp]

Totes, @thedavidprice, could you handle the rename and alias?

[jtoar]

@peterp Some more thoughts as I'm using it more:

What do you think of this structure: rwdev copy and rwdev copy:watch, analogous to yarn build and yarn build:watch?

---

When a path isn't supplied to rwdev, the error message says:

~/projects/redwood/redwood-test$ yarn rwdev watch 
yarn run v1.22.4
$ /home/dominic/projects/redwood/redwood-test/node_modules/.bin/rwdev watch
Error: 'undefined' does not exist
error Command failed with exit code 1.
info Visit https://yarnpkg.com/en/docs/cli/run for documentation about this command.

Maybe it should say something like

Error: RW_PATH is undefined. Did you supply a path to your local copy of the Redwood Framework?

---

When I supply a false RW_PATH (here, ../../not-redwood--an empty dir), the command just sits there like this:

~/projects/redwood/redwood-test$ yarn rwdev watch ../../definitely-not-redwood/
yarn run v1.22.4
$ /home/dominic/projects/redwood/redwood-test/node_modules/.bin/rwdev watch ../../definitely-not-redwood/
Redwood Framework Path:  /home/dominic/projects/definitely-not-redwood

Ideally it should fail right?

---

I can try to tackle any of these changes--lemme know what you think.

[peterp]

What do you think of this structure: rwdev copy and rwdev copy:watch, analogous to yarn build and yarn build:watch?

Totally, that makes 100% more sense. Could you add an alias cp for copy and wcp for watch:copy

The path errors would be great too! with the wrong path it is kinda difficult to determine when it is a redwood project, but maybe you could import package.json and look at the name?

[jtoar]

@peterp Absolutely! I'm making the first set of changes at #445. Did you mean copy:watch (aliased cpw) when you said watch:copy (aliased wcp)? Or should I do it that latter way?