A suggested module development workflow

module-development-workflow.md

Module Development Workflow

Overview

This is a suggested workflow for building npm modules locally. The particular context will be focused on building a React component lib, but the workflow can be applied for any npm module.

Linking

yarn link is a really great tool for local development. It builds a global npm module that is symlinked to your local repo. So when you make a change to the repo, the global module is automatically updated.

NOTE

yarn link and npm link do the same thing, but store the global module in a different location. This will be important when you want to unlink later.

To use link, hop into the root your module's repo and run yarn link or npm link.

$ cd projects/example-component-library
$ yarn link

You should see yarn build your package:

yarn link v1.2.0
success Registered "example-component-library".
info You can now run `yarn link "example-component-library"` in the projects where you want to use this module and it will be used instead.
✨  Done in 0.09s.

Great! Now we can pull this module into our app! We can add our symlinked module with yarn link example-component-library.

$ cd projects/my-react-app/
$ yarn link example-component-library
yarn link v1.2.0
success Using linked module for "example-component-library".
✨  Done in 0.12s.

NOTE

If you already have example-component-library in my-react-app this local module will replace the one your preexisting copy. You'll need to run yarn to reinstall the original external module when you're done.

Unlinking

To unlink this module we'll need to run yarn unlink example-component-library from my-react-app.

$ yarn unlink example-component-library
yarn unlink v1.2.0
success Removed linked module "example-component-library".
info You will need to run `yarn` to re-install the package that was linked.
✨  Done in 0.08s.

Rebuilding with Babel

So, remember when I said that our module will be automatically updated as we made changes with yarn link? Well, that was mostly true. The symlinked module is automatically updated, but our library is exporting the /build directory, which is compiled by Babel and does not auto-update. So now every time we need to see a change in our symlinked module, we need to run yarn build first.

Well, that's really annoying. So, we can add a watch script to example-component-library, yarn build:watch. Babel will watch for changes in /lib, auto-update the /build directory, and our symlinked module will be updated as well.

Awesome! Now we're ready to start using our local library.

Importing from the Local Module

Importing is super simple. npm treats our local module just like any other external module.

...
import { SomeComponent } from 'example-component-library';
...
  render() {
    return (
      <SomeComponent />
    );
  }
...

Now because we have our symlinked module running locally and our build:watch script running, we can make live updates and see the effects in my-react-app! That's pretty great!

Wrapping Up

Remember when you're done to yarn unlink example-component-library from my-react-app. You should probably also hop back to example-component-library and unlink the local module there too.

$ cd projects/example-component-library
$ yarn unlink
success Unregistered "example-component-library".
info You can now run `yarn unlink "example-component-library"` in the projects where you no longer want to use this module.
✨  Done in 0.12s.

Also remember to reinstall the external example-component-library module in my-react-app with yarn.