Adding an Example App to Your React Native Library

Challenges with adding example apps

You made a shiny new library for React Native and now it’s time to show it to the world. But you need to add an example app, so people can try it out before installing. Having an example also makes it easy to test changes as you develop. This seems like such a simple thing, doesn’t it?

Unfortunately it’s not that simple and can be quite challenging. I’ll describe the process I use and maybe it’ll help you out a bit. Note that I’ll cover JS only libraries. If your library has native code, then this article will still be useful, but you’ll need a separate step for hooking up the native code to the app.

So let’s get started.

Why is it hard?

Before exploring solutions, let’s discuss why it’s hard. React Native uses a custom packager called Metro Bundler for bundling your JavaScript code and a module resolution mechanism called haste.

Metro is quite fast and great for large codebases. But right now it has few limitations, which makes it a little hard to use for an example:

• We can’t use symlinks, since watchman, the file watcher used by Metro Bundler, doesn’t support it.
• We cannot import modules outside of the current directory.
• It produces warnings (previously errors) when it encounters two modules with the same name, which is easy to run into in our case since we’ll have same modules installed for development and for the example.

But you know what? It’s actually possible to configure the packager so that we can work around the limitations for our example app. However the configuration options are not documented yet, so it can be hard to configure unless you are familiar with it.

If you have ideas on how to solve these problems, please open an issue for discussion or open a PR in the Metro Bundler repository :)

How do we do it?

Here, I’ll assume that you are using Expo for your example. Why Expo? Because it’s super easy for you to develop and it’s unbelievably easy for people to check the example out. But I’ll also include notes for people who don’t want to/can’t use Expo (in case your library requires native code).

Before starting, here’s the directory structure I use. You can use a different one, but you’ll need to tweak the guide for your needs which can be challenging. So I recommend to stick to the following directory structure.

Our library exists under the src/ folder, whereas the example app (which is a full Expo or React Native app) exists under the example/ folder.

Let’s go ahead and initialize a new example app with exp init example, if you want to use Expo or react-native init example, if you want to go with vanilla React Native.

Configuring Babel

We’d need to add our library as a dependency to the example app. My naive approach was to add the library as a file: dependency, which more or less works. But when you change things, you always have to remember to reinstall, which results in a poor DX. Furthermore, npm@5 installs file: dependencies as symlinks, which breaks with React Native Packager.

What if we could alias the library instead, like we do with Webpack? That’s what babel-plugin-module-resolver does!

First, install the plugin.

Now, let’s create a .babelrc file (or edit it if it already exists), and make sure it looks like this:

Note: If your example is a React Native project and not an Expo project, make sure it’s react-native instead of expo in the presets field.

Remember to replace name-of-my-library with the name of your library which you’ll use to import the library throughout the example. This is optional and you can always import it like ../../, but it’s inconvenient, and makes it impossible to directly copy-paste code-snippets from the example into a project.

If you are planning to use react-native-vector-icons in your library and using Expo for the example app, your .babelrc should look like this, since you’ll need to duplicate expo’s config.

Now we are done with configuring babel, but we still need to configure Metro Bundler.

Configuring Metro Bundler

Packager uses special configuration file which is usually named metro.config.js (rn-cli.config.js in older versions). Let’s create that file in our example folder and paste the following:

This tells the packager to set the project root to current directory (which is the example folder) and watch the parent directory. This allows us to import files from the parent directory.

Unfortunately, the imports for node modules will fail for the files in the parent directory, i.e. the directory where the source code for our library exists. So we need to duplicate the dependencies in the example folder.

Say we have lodash and prop-types modules as dependencies of the library, we now need to install them in the example folder.

Now, we’ll need to configure metro’s resolver so it can find these dependencies. To do that, let’s add a new resolver key in the config. Under the resolver key, we need to add providesModuleNodeModulesproperty which lists all of the imported modules in the library (both direct dependencies and peer dependencies). It’ll look something like this:

We’ll also need to blacklist the parent node_modules directory, otherwise packager is going to complain about duplicate modules. Let’s install escape-string-regexp package and then update the config.

Now, let’s update our config to add a blacklistRE property under resolver, which should look like this:

If you’re using an older version of Metro (for example React Native ≤ 0.55), it’ll look like this instead:

Note that, if you have other node_modules folders somewhere in the parent directory (say a docs folder with it own node_modules), you might have to add it to the blacklist too.

Now we are done with the config for packager. We just need to make React Native use it. If you are using expo, add the following keys under packagerOpts key in exp.json.

Note: We need to specify projectRoots as an empty string to override the default value set by Expo.

If you are not using Expo, you can pass the config with the--configparameter in the React Native CLI.

Wrapping up

Now you should be able to run exp start or yarn start (for non-expo projects) inside the example folder and everything should work as expected. You should be able to change files under src/ and reload the example app to see changes instantly.

You can checkout the react-native-tab-view project for an example of the example!

Was the article useful? If you find it confusing, want more explanation, or just want to give some general feedback or suggestions, contact us.