Re-Natal

Bootstrap ClojureScript-based React Native apps with Reagent and re-frame

Artur Girenko, MIT License @drapanjanas

---

This project is a fork of dmotz/natal by Dan Motzenbecker with the goal of generating skeleton of native app for iOS and Android based on Reagent and re-frame.

The support of Figwheel is based on brilliant solution developed by Will Decker decker405/figwheel-react-native which works in both platforms.

Re-Natal is a simple command-line utility that automates most of the process of setting up a React Native app running on ClojureScript with Reagent an re-frame.

Generated project works in iOS and Android devices.

For more ClojureScript React Native resources visit cljsrn.org.

Contributions are welcome.

State

• Uses React Native v0.18.0
• Same codebase for iOS and Android
• Figwheel used for REPL and live coding.
  • Works in iOS (real device and simulator).
  • Works in real Android device
  • Works in Android simulator Genymotion (with re-natal use-figwheel -H 10.0.3.2)
  • Works in stock Android emulator (with re-natal use-figwheel -H 10.0.2.2)
  • Figwheel REPL can be started within nREPL
  • Simultaneous development of iOS and Android apps is supported
  • You can reload app any time, no problem.
  • Custom react-native components are supported (with re-natal use-component )
  • Source maps are available when you "Debug in Chrome"
• Optimizations :simple is used to compile "production" index.ios.js and index.android.js
• Unified way of using static images of rn 0.14+ works
• Works on Linux (Android only)

Usage

Before getting started, make sure you have the required dependencies installed.

Then, install the CLI using npm:

$ npm install -g re-natal

To bootstrap a new app, run re-natal init with your app's name as an argument:

$ re-natal init FutureApp

If your app's name is more than a single word, be sure to type it in CamelCase. A corresponding hyphenated Clojure namespace will be created.

Re-Natal will create a simple skeleton based on the current version of Reagent and Day8/re-frame. If all goes well you should see printed out basic instructions how to run in iOS simulator.

$ cd future-app

To run in iOS:

$ re-natal xcode

and then run your app from Xcode normally.

To run in Android, connect your device and:

$ adb reverse tcp:8081 tcp:8081
$ react-native run-android

Initially the ClojureScript is compiled in "prod" profile, meaning index.*.js files are compiled with optimizations :simple. Development in such mode is not fun because of slow compilation and long reload time.

Luckily, this can be improved by compiling with optimizations :none and using Figwheel.

Using Figwheel in iOS simulator

Start your app from Xcode as described above.

Then, to start development mode execute commands:

$ re-natal use-figwheel
$ lein figwheel ios

This will generate index.ios.js and index.android.js which works with compiler modeoptimizations :none.

Using Figwheel in real Android device

To run figwheel with real Android device please read Running on Device. To make it work on USB connected device I had also to do the following:

$ adb reverse tcp:8081 tcp:8081
$ adb reverse tcp:3449 tcp:3449

Then:

$ re-natal use-figwheel
$ lein figwheel android

And deploy your app:

$ react-native run-android

Using Figwheel in Genymotion simulator

With genymotion Android simulator you have to use IP "10.0.3.2" in urls to refer to your local machine. To specify this use:

$ re-natal use-android-device genymotion
$ re-natal use-figwheel
$ lein figwheel android

Start your simulator and deploy your app:

$ react-native run-android

Using Figwheel in stock Android emulator (AVD)

With stock Android emulator you have to use IP "10.0.2.2" in urls to refer to your local machine. To specify this use:

$ re-natal use-android-device avd
$ re-natal use-figwheel
$ lein figwheel android

Start your simulator and deploy your app:

$ react-native run-android

Swiching between Android devices

Run use-android-device to configure device type you want to use in development:

$ re-natal use-android-device <real|genymotion|avd>
$ re-natal use-figwheel
$ lein figwheel android

Developing iOS and Android apps simultaneously

$ re-natal use-figwheel
$ lein figwheel ios android

Then start iOS app from xcode, and Android by executing react-native run-android

Starting Figwheel REPL from nREPL

To start Figwheel within nREPL session:

$ lein repl

Then in the nREPL prompt type:

user=> (start-figwheel "ios")

Or, for Android build type:

user=> (start-figwheel "android")

Or, for both type:

user=> (start-figwheel "ios" "android")

REPL

You have to reload your app, and should see the REPL coming up with the prompt.

At the REPL prompt, try loading your app's namespace:

(in-ns 'future-app.ios.core)

Changes you make via the REPL or by changing your .cljs files should appear live in the simulator.

Try this command as an example:

(dispatch [:set-greeting "Hello Native World!"])

Running on Linux

In addition to the instructions above on Linux you might need to start React Native packager manually with command react-native start. This was reported in #3

See also Linux and Windows support in React Native docs.

"Prod" build

Do this with command:

$ lein prod-build

It will clean and rebuild index.ios.js and index.android.js with optimizations :simple

Having index.ios.js and index.android.js build this way, you should be able to follow the RN docs to proceed with the release.

Using external React Native Components

Lets say you have installed an external library from npm like this:

$ npm i some-library --save

And you want to use a component called 'some-library/Component':

(def Component (js/require "some-library/Component"))

This would work when you do lein prod-build and run your app, but will fail when you run with figwheel. React Native packager statically scans for all calls to require function and prepares the required code to be available at runtime. But, dynamically loaded (by figwheel) code bypass this scan and therefore require of custom component fails.

To overcome this execute command:

$ re-natal use-component some-library/Component

Then, regenerate index.*.js files:

$ re-natal use-figwheel

And last thing, probably, you will have to restart the packager and refresh your app.

NOTE: if you mistyped something, or no longer use the component and would like to remove it, please, manually open .re-natal file and fix it there (its just a list of names in json format, so should be straight forward)

Static Images

Since version 0.14 React Native supports a unified way of referencing static images

In Re-Natal skeleton images are stored in "images" directory. Place your images there and reference them from cljs code:

(def my-img (js/require "./images/my-img.png"))

Adding an image during development

When you have dropped a new image to "images" dir, you need to restart RN packager and re-run command:

$ re-natal use-figwheel

This is needed to regenerate index.*.js files which includes require calls to all local images. After this you can use a new image in your cljs code.

Upgrading existing Re-Natal project

Do this if you want to use newer version of re-natal.

Commit or backup your current project, so that you can restore it in case of any problem ;)

Upgrade re-natal npm package

$ npm upgrade -g re-natal

In root directory of your project run

$ re-natal upgrade

This will overwrite only some files which usually contain fixes in newer versions of re-natal, and are unlikely to be changed by the user. No checks are done, these files are just overwritten:

• files in /env directory
• figwheel-bridge.js

Then to continue development using figwheel

$ re-natal use-figwheel

To upgrade React Native to newer version please follow the official Upgrading guide of React Native. Re-Natal makes almost no changes to the files generated by react-native so the official guide should be valid.

Changes Re-Natal does to original RN application

It would be perfect not to do any changes there, but...

• To make source maps available in "Debug in Chrome" mode re-natal patches the react native packager to serve *.map files from file system and generate only index.*.map file. To achieve this this line of file "node_modules/react-native/packager/react-packager/src/Server/index.js" is modified to match only index.*.map

Tips

• Having rlwrap installed is optional but highly recommended since it makes the REPL a much nicer experience with arrow keys.

• Running multiple React Native apps at once can cause problems with the React Packager so try to avoid doing so.

• You can launch your app on the simulator without opening Xcode by running re-natal launch in your app's root directory.

• By default new Natal projects will launch on the iPhone 6 simulator. To change which device re-natal launch uses, you can run re-natal listdevices to see a list of available simulators, then select one by running re-natal setdevice with the index of the device on the list.

• To change advanced settings run re-natal xcode to quickly open the Xcode project.

• The Xcode-free workflow is for convenience. If you're encountering app crashes, you should open the Xcode project and run it from there to view errors.

Dependencies

As Re-Natal is the orchestration of many individual tools, there are quite a few dependencies. If you've previously done React Native or Clojure development, you should hopefully have most installed already. Platform dependencies are listed under their respective tools.

• npm >=1.4
  • Node.js >=4.0.0
• react-native-cli >=0.1.7 (install with npm install -g react-native-cli)
• Leiningen >=2.5.3
  • Java 8
• Xcode (+ Command Line Tools) >=6.3 (optional for Android)
  • OS X >=10.10