Introducing Whackage

A multi-repo developer tool for React Native app and library authors

We love React Native. Sometimes, though, it doesn’t feel like it reciprocates your love. One such time is when working with codebases that span across multiple repositories. When you want to make changes to a package your app depends on, achieving that snappy hot-reloading workflow you’ve grown accustomed to suddenly becomes a lot more difficult.

Packager woes

If you’ve developed libraries for React Native, you’ve probably noticed that “Packager”, the development server that bundles your app’s JavaScript sources, doesn’t play nicely with npm link. You might have experienced the dreaded Haste @providesModule name collision error, or had the packager crash with a mysteriously missing Babel preset.

The React Native core team is working on improving the Packager, and better multi-repo support is high on the wish list. In the meantime, while developing Victory Native, our charting library for React Native, we needed a solution that works today.

Enter whackage

Whackage is a hot-reloading-friendly npm link replacement that works with React Native. It synchronizes changes in your local workspace to your project’s node_modules without using symlinks, and automatically generates a packager blacklist for linked modules to avoid Haste naming collisions.

You can install Whackage with:

$ npm install -g whackage

You now have a command line tool called whack. To get started, initialize a new whackage.json in your project directory with whack init, and link a local copy of your package with whack link <path>:

$ whack init
$ whack link ../../victory-core-native

Your project now has a whackage.json file that looks something like this:

{
  "include": "/**/*.js",
  "exclude": ["/node_modules/*", ".babelrc", ".git"],
  "dependencies": {
    "victory-core-native": "../../victory-core-native"
  }
}

All that is left to do is to start the Whackage server with whack run <npm_task>. In a typical React Native project the npm task to start the Packager is start, in which case the corresponding whackage command is:

$ whack run start

And that’s it! You can now edit code in the linked package, and see the changes reflected in your app immediately, as they should be.

Give it a whack

Whackage is, suffice to say, a blunt instrument. As its name suggests, it’s a bit wacky and a bit hacky, but it gets the job done. We wrote it to scratch our own itch, and we hope it can be helpful to you, too.

The source code is available at https://github.com/FormidableLabs/whackage. For more information, read the docs, or turn to whack --help for assistance.