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…
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
- init & modify the basic template
- 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.
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 root
index.js make the following change…
AppRegistry.registerComponent('HelloWorld', () => App);
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.
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.
Next we just need to clean up our
package.json to remove everything except the
version. Here’s what mine now looks like
And let’s delete the native
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 — 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…
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...
react-native init test --template file:///Users/ChrisGeirman/dev/mobile/playground/templates/react-native-template-geirman
// also works with http://, git://, or any other URL supported by npmreact-native init test --template https://github.com/geirman/react-native-template-geirman
All dependencies will be installed for you, including native dependencies which will also be automatically linked, so there’s no need to run
react-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…
react-native-template-geirman - this is a simple react native template (not useful), created purely for my own…
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.