The 1–2–3’s of React Native Templates

This past February, with the release of React Native 0.42.0Martin Konicek (@martinkonicek) gave us a gift. And as far as I can tell, that gift has pretty much been underappreciated and underhyped. Let’s change that!

You might be wondering…what is this gift he speaks of? Well, it’s the gift of project templates. And this specific commit gave them to us…

CLI: Add support for project templates (3a6dff4) — @mkonicek

What’s a Project Template?

Simply put, this allows you to create custom, reusable, sharable react native scaffolds.

Once created, this allows you to init new react native projects using your scaffold as the base template instead of the default “Welcome to React Native!” template we’ve all become so familiar with by now. That command looks something like this…

react-native init myapp --template myFancyTemplate

First, Let’s Say Thanks

Before I go on to show you how to create your own, let’s all take a moment to raise our glasses in a toast and say, “Thank you Martin!”

The 1–2–3’s of Creating Your Own Project Template

Here are the basic steps you’ll need to take to creating your own template

1. init & modify the basic template
2. templetize
3. use the template

Sounds simple enough, right? Shall we get started? Great! Let’s do…

Init & Modify the Basic Template

I’m going to assume you’ve gone through the Getting Started Guide so that you’re environment is setup for react native development. If not, go do that first. Then, run this command to initiate a new project. You can name your project anything you want. I’m going to call mine geirman (because while I may be unoriginal, but my last name is not)

react-native init geirman

Now tweak the template however you like, adding navigation, adding whichever state management libraries you want, getting your files and folders setup exactly as you like, etc. As I mentioned before, you can include any native dependencies you like as well. Go crazy and have fun, but not too crazy because remember, this is suppose to be the base project all your future projects will be derived from.

For my geirman template, I’m going to keep things simple and install just one dependency.

yarn add react-navigation

I’m also going to update the render method of App.js just to make it different enough to prove that it works. I’ll clean up the imports and styles too while I’m at it. You can view the final result at react-native-template-geirman/App.js

“HelloWorld” is a magic word, as this will be automagically replaced with the name of your app. This is why we need to make one more change to the template’s index.js to make sure it all works properly when we use this template.

In the rootindex.js make the following change…

AppRegistry.registerComponent('HelloWorld', () => App);

Templetize

Now we get to the fun part, templatizing what we’ve done. Let’s start by adding a new file called dependencies.json to our project root.

touch dependencies.json

in that file, you’ll create an object that defines any dependencies you installed from the npm registry. You can copy those from your package.json file, minus the standard react native dependencies. My dependencies.json ended up looking like this since I installed just the one dependency.

{    
    "react-navigation": "^1.0.0-beta.15"
}

Next we just need to clean up our package.json to remove everything except the name and version. Here’s what mine now looks like

{    
    "name": "react-native-template-geirman", 
    "version": "0.0.1"
}

And let’s delete the nativeios and android directories too.

rm -rf android
rm -rf ios

Use the Template

As I mentioned earlier, to use the template you’d simply pass the --template flag to the react-native init command along with the location of your template. Your template can be called from npm, file://, http://, https://, or git://.

npm — Your template must follow a prescribed naming convention when installed from npm, where all templates must begin with react-native-template followed by your template name, like so…

react-native-template-{template-name}

Installing from npm is probably the easiest way to go, and publishing to npm is SUPER easy. Once published to npm, you’d use your template like so…

react-native init test --template geirman

file:// — To use your new template to scaffold an app based on a locally saved template, we’ll need to pass it a fully qualified file://path like so...file://,

react-native init test --template file:///Users/ChrisGeirman/dev/mobile/playground/templates/react-native-template-geirman

http:// — And to use your template from http://, https://, or git:// you’d pass the url like so…

// also works with http://, git://, or any other URL supported by npm
react-native init test --template https://github.com/geirman/react-native-template-geirman

When installing by file://, http://, https://, or git:/ your template can be named whatever you like. It’s only when installed by npm that it matters.

All dependencies will be installed for you, including native dependencies which will also be automatically linked, so there’s no need to runreact-native link yourself afterwards.

If you’ve been following along and actually created a new project using one of the above methods, you should be able to cd test into your app directory and react-native run-ios or react-native run-android as you normally would and you should see something like this…

My entire template is published on my github, so you can review it in its entirety here…

geirman/react-native-template-geirman

Final Thoughts & Disclaimer

This feature only works with react-native init which requires people to have Xcode / Android Studio to run their apps. It sounds like a cool idea to eventually add this feature to create-react-native-app (CRNA) which is a much easier to use tool to get started with. But for now it’s a super useful as is and I’m glad it exists. As always, YMMV so use at your own risk :)

I haven’t written much, so if you enjoyed this article, give me a few claps, leave me an encouraging comment below, share it on twitter, etc. I’d appreciate the encouragement and would love to hear from you.