Dear friends,

Last November me (@Kureev) and Mike (@grabbou) started RNPM. We aimed to bring you a better developer experience and bridge the tooling gap we had back then. Now, as you may know, RNPM is merged into React Native core. It means that from now on you don't need to install a third-party software to use your favorite linking functionality (just use a react-native cli). We'd like to say a big "Thank you!" to everybody who supported us, filed new issues, composed PRs and helped us to review them.

Now, when RNPM is a part of React Native, we're going to seal this repository and keep working on React Native tooling inside the core. That said, I kindly ask you to file all new issues / prs in react-native repo and cc us. This repo (and other rnpm plugins) will be a available for a few more months in a read-only mode.

With love, Alexey Kureev and Michał Grabowski

rnpm logo

npm version dependencies

React Native Package Manager built to ease your daily React Native development. Inspired by CocoaPods, fastlane and react-native link it acts as your best friend and guides you through the native unknowns. It aims to work with almost all packages available with no extra configuration required.

RNPM should always be run in projects that use version control to ensure any changes made can be easily reverted

Requirements

node >= 4.1

Getting started

Installation

$ npm install rnpm -g

Running

Installing dependency:

If you want to install a dependency and link it in one run:

$ rnpm install <name>

Linking dependency:

If you already have some installed (but not linked) modules, run:

$ rnpm link

In the case you want to link only one dependency, you can specify its name as an argument:

$ rnpm link <name>

Rationale

Why? Tooling is important. We all know this. One of the biggest advantages of native iOS development is Xcode and its great tools. Unfortunately, the process of adding native dependencies to React Native projects is far from perfect and our aim is to make it fun again.

React Native Package Manager provides you with (soon) multiple actions to help you with daily development, including automatic app store releases, over-the-air integration with AppHub and react-native-playground shares.

But hey, we are tired of tools and 9000+ .rc files

So are we. That's why we have spent great amount of work on getting configuration done right. Our packager automatically scans your source directory and dependencies you are working with. This approach allows it to link all the things without supplying any extra configuration. It detects Android package names, import paths, gradle location - and for iOS - it works with any code structure you have ever came up with.

And don't worry - in case it fails, you can always add rnpm object to your package.json - our npm in a name is not a mistake! We embrace existing ecosystem and integrate with the present tooling for maximum developer experience.

Available commands

rnpm link [name]

Automatically updates your project by linking all dependencies for Android (if present) and for iOS (if present). It's a great fit to your postinstall hook to always make sure you are linked. You can supply optional [name] argument to link only one dependency, e.g.

$ npm install react-native-module --save
$ rnpm link react-native-module

Source: https://github.com/rnpm/rnpm-plugin-link

rnpm install [name]

Automatically installs the given package and links it to your project. It's equivalent to running the previous example. It's just instead of running two commands, you can now just:

$ rnpm install react-native-module

Source: https://github.com/rnpm/rnpm-plugin-install

Advanced usage

If you're authoring an awesome react-native library with custom assets, you probably need an additional step after linking - copying assets to the application folder. Well, that's not complicated: just add rnpm section in your package.json file:

...
"rnpm": {
  "assets": ["Fonts"]
},
...

We'll copy your assets carefully with love for Android :heart: For iOS, we will add files to Resources group and update Info.plist so fonts are available for you to use straight away!

Plugins

As of version 1.1.0, rnpm supports plugin system. It allows you to write your own / use third-party commands to make your rnpm sharpened for specific purposes.

Installing plugins

In order to install 3rd party plugin simply run below from your project directory:

$ npm install rnpm-plugin-<name> --save-dev
$ rnpm --help # you'll see installed plugin in the commands list

Command exported by installed plugin will be available straight away.

Mastering your first plugin

First of all, every plugin is just a function which accepts config and args parameters. Every plugin consists of public interface for CLI and implementation intself.

We use public interface to make your plugins auto-pluggable and easy to use for end-users. Every public interface consists of name, func & description fields:

name - Name of the plugin. After plugin installation it'll be used as a command name. For instance a plugin with the following interface:

module.exports = {
  func: require('./src/link'),
  description: 'This action updates your project and links all native dependencies',
  name: 'link [packageName]',
};

can be used like via rnpm like this:

$ rnpm link

func - Plugin itself. This function will be used when you run a command above
description - Command description. If user runs $ rnpm --help, this field will be displayed as a command description.
options - An array of flags user can specify for your plugin to run. When defined, your exported func will receive an object of options as a 3rd argument. For instance a plugin with the following:
```
options: [{
  flags: '-L, --list [path]',
  description: 'List flag',
  parse: (val) => val.split(',').map(Number),
  default: [1,2,3],
}],
```
will receive the following object:
```
{ list: [1,2,3] }
```
by default.

Note: parse and default are optional. You can check commander.js docs for more information on how to define flags value.

Also, in the case you want to expose multiple commands from the one plugin, you may use an array syntax:

module.exports = [{
  func: require('./src/link'),
  description: 'This action updates your project and links all native dependencies',
  name: 'link [packageName]',
}, {
  func: require('./src/unlink'),
  description: 'This action updates your project and unlink specific dependency',
  name: 'unlink <packageName>',
}]

Using third-party plugins

All existing plugins follows a naming convention: rnpm-plugin-<plugin name> (e.g. rnpm-plugin-link). To include plugin to your rnpm build, just install it as a npm package, it'll be included to your rnpm tool automatically (wow, magic!). Let's consider following example: we have a rnpm-plugin-something plugin which we doesn't provide you automatically with rnpm tool. To install it manually, you need to run npm install rnpm-plugin-something --save-dev inside your project folder. Then, you can run it by rnpm something or check if command has been successfully installed by running rnpm --help - you should see a new plugin in the list of commands.

For further reading you can check our example plugin

Commands

In the case you need an additional input from the user, you may make a command for this purpose. Commands works similar to the npm scripts.

Depdendency's package.json:

"rnpm": {
  "commands": {
    "prelink": "./bin/requestGAToken",
    "postlink": "./bin/linkingSucceeded"
  }
}

In this scenario we're using custom prelink and postlink hooks for rnpm-plugin-link to tell rnpm that we want to run prelink script before and postlink after the linking process.

Note: commands may be async and require some user input using third-party libraries (inquirer for instance). You don't need to worry about async queues, we do it for you under the rnpm hood.

While making your own plugins for rnpm you may use any names for the commands, but we strongly recommend you to use a convention we suggest to avoid collisions: when + plugin name: prelink = pre + link.

Params

On Android - you can specify a custom packageInstance to be used when linking your project. The reason for that is often that your package constructor simply requires extra user provided config (e.g. API token). rnpm allows you to define an array of additional arguments to get from user during linking process that you can then, reference in your packageInstance.

Simply include the following in your package.json:

"rnpm": {
  "params":

Rnpm

Install / Use

README