2015-11-20 19:07:09 +00:00
# Re-Natal
2015-11-21 09:42:24 +00:00
### Bootstrap ClojureScript-based React Native apps with Reagent and re-frame
2015-11-21 11:30:33 +00:00
Artur Girenko, MIT License
[@drapanjanas ](https://twitter.com/drapanjanas )
2015-08-30 04:01:40 +00:00
---
2015-11-21 11:30:33 +00:00
This project is a fork of [dmotz/natal ](https://github.com/dmotz/natal ) by Dan Motzenbecker with
2015-11-20 19:07:09 +00:00
the goal of generating skeleton of native app for iOS and Android based on
2016-05-03 19:31:39 +00:00
[Reagent ](https://github.com/reagent-project/reagent ) + [re-frame ](https://github.com/Day8/re-frame ),
[Om.Next ](https://github.com/omcljs/om/wiki/Quick-Start-(om.next )) or
[Rum ](https://github.com/tonsky/rum ).
2015-11-20 19:07:09 +00:00
2015-12-24 20:16:16 +00:00
The support of Figwheel is based on brilliant solution developed by Will Decker [decker405/figwheel-react-native ](https://github.com/decker405/figwheel-react-native )
which works in both platforms.
2015-11-27 23:45:38 +00:00
2015-11-20 19:07:09 +00:00
Re-Natal is a simple command-line utility that automates most of the process of
2015-11-21 09:42:24 +00:00
setting up a React Native app running on ClojureScript with Reagent an re-frame.
2015-08-30 04:01:40 +00:00
2015-11-21 09:42:24 +00:00
Generated project works in iOS and Android devices.
2015-08-30 04:02:14 +00:00
2015-12-15 20:07:50 +00:00
For more ClojureScript React Native resources visit [cljsrn.org ](http://cljsrn.org ).
Contributions are welcome.
2015-11-27 23:45:38 +00:00
## State
2016-09-24 12:10:21 +00:00
- Uses React Native v0.34
2015-11-27 23:45:38 +00:00
- Same codebase for iOS and Android
2015-11-28 15:42:37 +00:00
- Figwheel used for REPL and live coding.
2016-01-21 19:41:28 +00:00
- Works in iOS (real device and simulator).
2015-12-06 20:19:26 +00:00
- Works in real Android device
2016-01-26 19:03:56 +00:00
- Works in Android simulator Genymotion (with re-natal use-android-device genymotion)
- Works in stock Android emulator (with re-natal use-android-device avd)
2015-12-15 18:25:50 +00:00
- Figwheel REPL can be started within nREPL
2016-01-24 12:46:34 +00:00
- Simultaneous development of iOS and Android apps is supported
2015-11-28 15:42:37 +00:00
- You can reload app any time, no problem.
2016-01-05 18:42:24 +00:00
- Custom react-native components are supported (with re-natal use-component < name > )
2016-02-06 15:00:09 +00:00
- Source maps are available when you "Debug in Chrome" (with re-natal enable-source-maps)
2016-05-03 19:31:39 +00:00
- Supported React wrappers:
[Reagent ](https://github.com/reagent-project/reagent )
[Om.Next ](https://github.com/omcljs/om/wiki/Quick-Start-(om.next ))
[Rum ](https://github.com/tonsky/rum )
2015-11-28 10:13:53 +00:00
- Optimizations :simple is used to compile "production" index.ios.js and index.android.js
2015-12-07 20:52:06 +00:00
- [Unified way of using static images of rn 0.14+ ](https://facebook.github.io/react-native/docs/images.html ) works
2016-02-01 19:07:13 +00:00
- Works on Linux and Windows (Android only)
2015-11-27 23:45:38 +00:00
2016-04-08 19:48:11 +00:00
## Creating new project
2015-08-31 02:03:00 +00:00
2015-10-03 18:50:12 +00:00
Before getting started, make sure you have the
2016-01-08 20:10:11 +00:00
[required dependencies ](#dependencies ) installed.
2015-08-31 02:03:00 +00:00
Then, install the CLI using npm:
2015-08-30 04:02:14 +00:00
```
2015-11-20 19:07:09 +00:00
$ npm install -g re-natal
2015-08-30 04:02:14 +00:00
```
2015-11-20 19:07:09 +00:00
To bootstrap a new app, run `re-natal init` with your app's name as an argument:
2015-08-30 04:02:14 +00:00
```
2015-11-20 19:07:09 +00:00
$ re-natal init FutureApp
2015-08-30 04:02:14 +00:00
```
2016-05-03 19:31:39 +00:00
Or, specify -i option to generate Om.Next, Reagent v0.6 or Rum project:
2016-02-11 12:18:21 +00:00
```
2016-05-03 19:31:39 +00:00
$ re-natal init FutureApp -i [om-next | reagent6 | rum]
2016-02-11 12:18:21 +00:00
```
2015-08-30 04:02:14 +00:00
2015-10-17 17:17:29 +00:00
If your app's name is more than a single word, be sure to type it in CamelCase.
2015-08-30 04:02:14 +00:00
A corresponding hyphenated Clojure namespace will be created.
2016-09-04 01:43:25 +00:00
The init process will take a few minutes — coffee break! If all goes well you should see printed out basic instructions how to run in iOS simulator.
2015-08-30 04:16:58 +00:00
```
$ cd future-app
```
2015-11-27 23:45:38 +00:00
To run in iOS:
```
2016-01-31 12:34:40 +00:00
$ react-native run-ios
2015-11-27 23:45:38 +00:00
```
2015-12-06 11:55:52 +00:00
To run in Android, connect your device and:
2015-11-27 23:45:38 +00:00
```
2015-12-05 22:53:27 +00:00
$ adb reverse tcp:8081 tcp:8081
2015-11-27 23:45:38 +00:00
$ react-native run-android
```
2016-04-08 19:48:11 +00:00
## Development with Figwheel
2015-11-27 23:45:38 +00:00
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
2015-12-05 22:53:27 +00:00
Figwheel.
2015-11-27 23:45:38 +00:00
2016-03-03 22:33:45 +00:00
Start your app from Xcode and pick a simulator target, or just run `react-native run-ios`
2015-12-06 20:17:52 +00:00
Then, to start development mode execute commands:
2015-11-27 23:45:38 +00:00
```
$ re-natal use-figwheel
$ lein figwheel ios
2015-11-28 15:42:37 +00:00
```
This will generate index.ios.js and index.android.js which works with compiler mode`optimizations :none`.
2015-10-04 23:29:36 +00:00
2016-04-08 19:48:11 +00:00
NOTE: you might need to restart react native packager and reload your app in simulator.
If all went well you should see REPL prompt and changes in source files
should be hot-loaded by Figwheel.
2016-05-25 05:44:37 +00:00
To disable Figwheel run `lein prod-build`
2016-04-08 19:48:11 +00:00
#### 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':
```clojure
(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 reload 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)
#### Using real iOS device
2016-03-03 22:33:45 +00:00
Switch to using your iOS device: `re-natal use-ios-device real` .
If this doesn't correctly detect your computer's IP you can pass your IP address explicitly: `re-natal use-ios-device IP`
Then follow the remaining directions above for the iOS simulator except pick your connected device in Xcode
2016-04-08 19:48:11 +00:00
#### Using real Android device
2015-11-28 15:42:37 +00:00
To run figwheel with real Android device please read [Running on Device ](https://facebook.github.io/react-native/docs/running-on-device-android.html#content ).
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
```
2015-12-06 20:17:52 +00:00
Then:
```
$ re-natal use-figwheel
$ lein figwheel android
```
And deploy your app:
```
2015-12-06 20:23:14 +00:00
$ react-native run-android
2015-12-06 20:17:52 +00:00
```
2016-04-08 19:48:11 +00:00
#### Using Genymotion simulator
2015-12-06 20:17:52 +00:00
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:
```
2016-01-24 12:46:34 +00:00
$ re-natal use-android-device genymotion
$ re-natal use-figwheel
2015-12-06 20:17:52 +00:00
$ lein figwheel android
```
Start your simulator and deploy your app:
```
2015-12-06 20:23:14 +00:00
$ react-native run-android
2015-12-06 20:17:52 +00:00
```
2015-11-28 15:42:37 +00:00
2016-04-08 19:48:11 +00:00
#### Using stock Android emulator (AVD)
2015-12-06 20:17:52 +00:00
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:
```
2016-01-24 12:46:34 +00:00
$ re-natal use-android-device avd
$ re-natal use-figwheel
2015-12-06 20:17:52 +00:00
$ lein figwheel android
```
Start your simulator and deploy your app:
```
2015-12-06 20:23:14 +00:00
$ react-native run-android
2015-12-06 20:17:52 +00:00
```
2016-03-03 22:33:45 +00:00
#### Switching between Android devices
2016-01-24 17:07:46 +00:00
Run `use-android-device` to configure device type you want to use in development:
2016-01-24 12:46:34 +00:00
```
$ 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`
2015-11-28 15:42:37 +00:00
2016-03-21 21:50:54 +00:00
#### Faster Figwheel hot reloading
2016-03-23 15:31:24 +00:00
Since version 0.22 React Native supports Hot Module Reload. But at least for now, this feature is useless
2016-03-21 21:50:54 +00:00
as Figwheel is doing that as good.
It looks like Figwheel reloads are faster if Hot Moduler Reload is OFF.
Also, no need packager to watch for changed files - Figwheel does that.
Two things you can do:
2016-03-21 22:08:01 +00:00
2016-03-21 21:50:54 +00:00
1. Turn off HMR from the development menu.
2. Start packager with option `--nonPersistent` . You can use `npm start` for that.
2015-12-15 18:25:50 +00:00
#### Starting Figwheel REPL from nREPL
To start Figwheel within nREPL session:
```
$ lein repl
```
Then in the nREPL prompt type:
```
2016-01-24 12:46:34 +00:00
user=> (start-figwheel "ios")
2015-12-15 18:25:50 +00:00
```
Or, for Android build type:
```
2016-01-24 12:46:34 +00:00
user=> (start-figwheel "android")
```
Or, for both type:
```
user=> (start-figwheel "ios" "android")
2015-12-15 18:25:50 +00:00
```
2015-11-28 15:42:37 +00:00
## REPL
2015-12-06 20:17:52 +00:00
You have to reload your app, and should see the REPL coming up with the prompt.
2015-11-27 23:45:38 +00:00
At the REPL prompt, try loading your app's namespace:
2015-08-30 04:16:58 +00:00
```clojure
2015-11-21 11:01:44 +00:00
(in-ns 'future-app.ios.core)
2015-08-30 04:16:58 +00:00
```
2015-10-04 23:29:36 +00:00
Changes you make via the REPL or by changing your `.cljs` files should appear live
in the simulator.
2015-08-30 04:16:58 +00:00
Try this command as an example:
```clojure
2015-11-22 09:57:51 +00:00
(dispatch [:set-greeting "Hello Native World!"])
2015-08-30 04:16:58 +00:00
```
2015-12-16 06:51:55 +00:00
## 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` .
2015-12-16 11:30:01 +00:00
This was reported in [#3 ](https://github.com/drapanjanas/re-natal/issues/3 )
2015-12-16 06:51:55 +00:00
See also [Linux and Windows support ](https://facebook.github.io/react-native/docs/linux-windows-support.html )
in React Native docs.
2015-08-30 04:16:58 +00:00
2015-11-27 23:45:38 +00:00
## "Prod" build
Do this with command:
2015-11-21 09:42:24 +00:00
```
2015-11-27 23:45:38 +00:00
$ lein prod-build
2015-11-21 09:42:24 +00:00
```
2015-11-27 23:45:38 +00:00
It will clean and rebuild index.ios.js and index.android.js with `optimizations :simple`
2015-11-28 15:42:37 +00:00
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.
2015-11-21 11:01:44 +00:00
2016-01-17 17:51:29 +00:00
## Static Images
2016-01-17 18:12:37 +00:00
Since version 0.14 React Native supports a [unified way of referencing static images ](https://facebook.github.io/react-native/docs/images.html )
2016-01-17 17:51:29 +00:00
2016-01-17 18:12:37 +00:00
In Re-Natal skeleton images are stored in "images" directory. Place your images there and reference them from cljs code:
2016-01-17 17:51:29 +00:00
```clojure
(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.
2015-12-06 10:40:40 +00:00
## Upgrading existing Re-Natal project
2016-06-04 08:08:28 +00:00
#### Upgrading React Native version
To upgrade React Native to newer version please follow the official
[Upgrading ](https://facebook.github.io/react-native/docs/upgrading.html ) guide of React Native.
Re-Natal makes almost no changes to the files generated by react-native so the official guide should be valid.
#### Upgrading Re-Natal CLI version
2015-12-06 10:40:40 +00:00
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
2015-12-06 11:31:45 +00:00
Then to continue development using figwheel
```
$ re-natal use-figwheel
```
2016-02-06 15:00:09 +00:00
### Enabling source maps when debugging in chrome
To make source maps available in "Debug in Chrome" mode re-natal patches
2016-01-21 21:27:36 +00:00
the react native packager to serve \*.map files from file system and generate only index.\*.map file.
2016-02-06 15:00:09 +00:00
To achieve this [this line ](https://github.com/facebook/react-native/blob/master/packager/react-packager/src/Server/index.js#L413 )
2016-01-21 21:27:36 +00:00
of file "node_modules/react-native/packager/react-packager/src/Server/index.js" is modified to match only index.\*.map
2015-12-06 10:40:40 +00:00
2016-02-06 15:00:09 +00:00
To do this run: `re-natal enable-source-maps` and restart packager.
You can undo this any time by deleting `node_modules` and running `re-natal deps`
2016-01-26 19:03:56 +00:00
## Example Apps
* [Luno ](https://github.com/alwx/luno-react-native ) is a demo mobile application written in ClojureScript.
2016-05-13 22:18:11 +00:00
* [Re-Navigate ](https://github.com/vikeri/re-navigate ) example of using new Navigation component [NavigationExperimental ](https://github.com/ericvicenti/navigation-rfc )
2016-02-26 20:10:24 +00:00
* [Showcase of iOS navigation ](https://github.com/seantempesta/om-next-react-native-router-flux ) with react-native-router-flux and Om.Next
2016-05-24 19:22:53 +00:00
* [Catlantis ](https://github.com/madvas/catlantis ) is a funny demo application about cats
2016-01-26 19:03:56 +00:00
2015-08-30 04:02:33 +00:00
## Tips
2015-10-04 23:29:36 +00:00
- 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
2016-02-06 13:37:49 +00:00
`react-native run-ios` in your app's root directory (since RN 0.19.0).
2015-10-04 23:29:36 +00:00
2015-11-21 11:07:33 +00:00
- To change advanced settings run `re-natal xcode` to quickly open the Xcode project.
2015-08-30 04:02:33 +00:00
2016-02-06 17:03:04 +00:00
- If you have customized project layout and `re-natal upgrade` does not fit you well,
2016-02-06 13:37:49 +00:00
then these commands might be useful for you:
2016-02-06 17:03:04 +00:00
* `re-natal copy-figwheel-bridge` - just copies figwheel-bridge.js from current re-natal
2015-10-05 00:55:16 +00:00
2015-10-03 18:50:12 +00:00
## Dependencies
2015-11-27 23:45:38 +00:00
As Re-Natal is the orchestration of many individual tools, there are quite a few dependencies.
2015-10-03 18:50:12 +00:00
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 ](https://www.npmjs.com ) `>=1.4`
- [Node.js ](https://nodejs.org ) `>=4.0.0`
2016-01-08 20:10:11 +00:00
- [react-native-cli ](https://www.npmjs.com/package/react-native-cli ) `>=0.1.7` (install with `npm install -g react-native-cli` )
2015-10-03 18:50:12 +00:00
- [Leiningen ](http://leiningen.org ) `>=2.5.3`
- [Java 8 ](http://www.oracle.com/technetwork/java/javase/downloads/index.html )
2015-12-09 21:32:25 +00:00
- [Xcode ](https://developer.apple.com/xcode ) (+ Command Line Tools) `>=6.3` (optional for Android)
2015-10-03 18:50:12 +00:00
- [OS X ](http://www.apple.com/osx ) `>=10.10`
2016-05-11 19:07:31 +00:00
## Local Development
If you would like to run any of this on your local environment first clone the code to an appropriate place on your machine and install dependencies
```
$ git clone https://github.com/drapanjanas/re-natal.git
$ cd re-natal
$ npm install
```
To test any changes made to re-natal, cd to an already existing project or a brand new dummy project:
```
$ cd ../already-existing
```
and run the re-natal command line like so
```
2016-05-11 19:08:25 +00:00
$ node ../re-natal/index.js
2016-05-11 19:07:31 +00:00
Usage: re-natal [options] [command]
Commands:
init [options] < name > create a new ClojureScript React Native project
upgrade upgrades project files to current installed version of re-natal (the upgrade of re-natal itself is done via npm)
xcode open Xcode project
deps install all dependencies for the project
use-figwheel generate index.ios.js and index.android.js for development with figwheel
use-android-device < type > sets up the host for android device type: 'real' - localhost, 'avd' - 10.0.2.2, 'genymotion' - 10.0.3.2
use-ios-device < type > sets up the host for ios device type: 'simulator' - localhost, 'device' - auto detect IP on eth0, IP
use-component < name > configures a custom component to work with figwheel. name is the value you pass to (js/require) function.
enable-source-maps patches RN packager to server *.map files from filesystem, so that chrome can download them.
copy-figwheel-bridge copy figwheel-bridge.js into project
Options:
-h, --help output usage information
-V, --version output the version number
```
You can then run any of the commands manually.