whackage

Multi-repo development tooling for React Native

What is this?

whackage provides a hot-reload-friendly workflow for working across multiple React Native packages

React Native packager, the development server that bundles your app's JavaScript sources, has a few rough edges when it comes to developing apps and libraries that span across multiple repositories. It doesn't handle symlinks reliably, and the Haste module system gets easily confused by @providesModule declarations in subdependencies.

whackage 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.

We wrote whackage to scratch our own itch when working on Victory Native. It's a blunt instrument, but it works well. Hope you find it useful!

How-to

Install

Install whackage globally (requires node >=6 and OSX/Linux, Windows currently not supported):

npm i -g whackage

You'll now have access to the whack command on your command line. To get started, generate an empty whackage.json in your project's root directory:

whack init

Link modules

You can then link local copies of React Native libraries to your project with whack link <path>, e.g.:

whack link ../victory-core-native
whack link ../victory-chart-native

whackage doesn't install and flatten transitive dependencies, so any linked libraries need to have been previously installed with npm install / yarn. Typically you would use whackage to make changes to libraries which are already defined in your package.json dependencies.

You'll now have a whackage.json file that looks as follows:

{
  "include": "/**/*.js",
  "exclude": "/node_modules/*",
  "dependencies": {
    "victory-chart-native": "../victory-chart-native",
    "victory-core-native": "../victory-core-native"
  }
}

The dependencies map specifies which modules to synchronize, and paths to directories where to look for the sources.

By default whackage watches changes to .js files, and ignores changes to the sources' node_modules. You can change the include and exclude glob patterns as needed.

Start packager

Start the packager server with whack run <command>, where command is the npm script you normally use to start your development server.

If you usually start the server with npm start, the corresponding whackage command is:

whack run start

When started, the whackage server will overwrite the specified dependencies in your node_modules with the sources you linked with whack link, and start a file watcher that synchronizes changes made in the source directories into your node_modules as they happen.

It will also specify a CLI config which adds the node_modules within linked source directories to the Haste blacklist to avoid @providesModules naming collisions.

Why the name?

It's wacky, it's hacky, and it rhymes with package. Also it whacks your node_modules irreplaceably.

Please note

This project is in a pre-release state. The API may be considered relatively stable, but changes may still occur.

MIT licensed