Writing a React Native Tutorial in an Age of Flux

Writing a tutorial on building mobile apps with React Native hasn’t been easy. When Nick and I started this project 10 months ago, it was a pretty untested technology. There were doubts, some which remain unresolved— “Just how cross-platform is it?”, “How native is it, really?”, and “What’s up with navigation?” But I for one am glad we invested our time in building a resource for learners to get started building awesome mobile apps.

In this post I’d like to share frustrations we’ve faced in creating the tutorial, as well as the approaches that may have helped make it successful.

React Native API Changes

First on the list of frustrations is navigation. Seriously, could it be any more confusing for someone starting with React Native? For those new to the issue, let me provide the backstory:

When React Native launched in 2015, it had two options for navigation:NavigationIOS and Navigator. The former was easy to use, but Facebook dropped support and announced that Navigator would be the chosen router. Then things changed again. Facebook announced that they were using something called NavigationExperimental internally. We all thought that this would be crowned ruler of the routers. And then, another option appeared?—?react-native-router-flux.

As a newcomer to React Native, how do you choose? At this point it seems arbitrary. Keep in mind that all of these changes were happening while we were trying to write our tutorial, which depends on navigation (:palm-to-face).

For our tutorial, we decided to focus on Navigator until a winner is announced. While I like the last two options, I think that the nameNavigationExperimental sends a “buyer beware” message to users. The name react-native-router-flux is just as bad?—?it makes me think of a mutant creature composed of all the confusing things in React-land, when in reality it’s pretty easy to use.

Fixture-first, Redux-last Development

When we started building out Assemblies (a Meetup clone) for our tutorial, we struggled with this decision?—?“Should we build the API first and then code the app, or vice versa?” Nick advocated working on the API first and addressing problems such as —“How will we host the API?”, “What foreign key associations do we need?”, etc. I calmly talked him off of that cliff, and we developed the app with fake data.

The thing with API-driven-development is that many times, you don’t know what data you’ll need until you see your app in action. You might decide that a feature you thought was important is useless in real life. So I made a seed file to create fake users, groups, and messages to build out our app’s UI. While most people would use something like casual or faker, I put the exact data that I wanted to see, messages and all, along with some funny messages from HipsterIpsum. This takes a little more time, but gives a feel for how the app should behave and can be fun.

At this point it was standard to learn Redux with React. Anyone who was using React or React Native without Redux was not cool (or so it seemed). We thought about developing the entire app using Redux, but reconsidered. Learning React Native alone can be overwhelming?—?a new set of UI elements, new APIs, and in the case of React newbies, new core concepts. We felt that adding Redux into that complexity would drive people away from React Native.

As for after learning React Native, I think it’s a great idea to use Redux in React Native apps. And that’s exactly what we did in the tutorial, adding a chapter at the end that shows how to convert state into a Redux store.

Deployd (DPD) as an API Framework

Nick and I looked at several options for building the API for the mobile app.Meteor was an option, but we felt that it was more than what users needed. We considered using Express with MongoDB, but then that would take time for users to learn as well. Finally, Nick suggested Deployd, a framework for building APIs built on Node and MongoDB.

Deployd was a great fit for the tutorial, because it required almost no configuration. You simply install the command line tool (npm install -g deployd) and create an API (dpd create api). Adding collections to MongoDB along with the appropriate API routes was as simple as a drag-and-drop. This allowed us to focus more on React Native than on API development in the tutorial, although we did devote an entire chapter on deploying Deployd?—?even if it sounds redundant.

eBook Tools?—?Meteor and Gitbook

Although we didn’t use Meteor as our API for the tutorial, we did use it to host our tutorial content at www.buildreactnative.com. This was an easy process. We keep a single chapterData.js file that contains info on all chapters, and then feed that data into our routes component. Each object links to a markdown file, hosted in a separate folder on the server.

For example, here’s what the chapterData for chapter 2 might look like:

{
  fileName: '/users/tom/build-react-native/chapter_2.md,
  paidChapter: false,
  component: Chapter2
}

With this data, we could access the relevant markdown, using the fspackage.

let markdown = fs.readFileSync(chapterData.fileName, 'utf-8');

After the server sends the text to the client, we parse it with the react-highlight library.

Gitbook was a joy to work with. In Gitbook we write chapters in Github-flavored markdown, with a live preview of the content. Each edit adds to the commit history of a Git repo, which we clone on our website server. This way, a change in the markdown content doesn’t require a redeployment of the website. This made editing mistakes and updating content a breeze.

Conclusion

Making this tutorial was a labor of love. Through it, I feel that I’ve improved my understanding of React Native and mobile development. Taking complex concepts, breaking them down and explaining them to learners is quite honestly the best way of learning.

So far, it seems that this approach is working. We have 100’s of users and have gotten great feedback as we continue to add more content to the tutorial.

If you enjoyed this article, please click “like.” You can also follow me on Twitter as @tomgoldenberg.

If you’re interested in React Native, please check out the tutorial Build React Native. Several of the chapters are available for free. Check it out!