Enables ReactNative projects written in ClojureScript to use Figwheel Main's live reloading and REPL.
npm install react-native-figwheel-bridgeEnables React Native projects written in ClojureScript to use
Figwheel's live reloading and REPL.
The things discovered here will inform changes to Figwheel-main and
perhaps the ClojureScript compiler.
The ultimate goal is to eliminate the need for this library in the
first place and be able to support React Native directly from
figwheel-main or even the ClojureScript compiler.
Because of this, this library is going to primarily be compatible withfigwheel-main for now as I'm not going to be make incremental
improvements to both figwheel-main and lein figwheel during this
period of discovery.
I do advise that you use this library as it represents a very
straightforward way to use React Native along with Figwheel.
When you run npx react-native run-ios it launches the metro bundler
which basically runs a babel based watcher/compiler process with
some specific React Native presets. This compiles the index.js file
to a bundle that is loaded by React Native framework code that is
written in Objective-C.
You can see the Native code that loads the bundle inios/MyAwesomeProject/AppDelegate.m.
> The important thing to note about this, is that in terms of relating
> to ClojureScript and its tools, a React Native project is simply
> JavaScript that gets loaded into a React Native host environment.
Our goal is to get our compiled ClojureScript into the RN host
environment and establish a REPL connection so that we can get
reloading, editor integration, etc.
So this is not the hardest problem but there are a few tricky parts
and that's where this library comes in.
One of the tricky parts is the use of require. require is not just
used to include JavaScript libraries in React Native projects it's
also used to pull in assets like images, data etc. However unlike
node-js require doesn't actually exist in the JavaScript Core
runtime environment. The React Native metro bundler process resolves
and handles all requires in JavaScript code at compile time.
However, this doesn't work for hot-reloaded compiled ClojureScript
code which doesn't get processed by the Metro bundler. So (js/require won't work in hot-reloaded code without
"images/splash-logo.png")
some sort of intervention.
The other tricky part for ClojureScript code is to support the
requiring of of npm modules like react and react-native in
ClojureScript ns forms like this:
``clojure`
(ns example.main
(:require
[react :as react]
[react-native :as rn]))
;; now rn/Text is available here
So there will need to be an intervention for this as well.
We need to make requires available in a global object in theindex.js so that they are available to ClojureScript at:bundle
runtime. ClojureScript helps us here with it's new :bundle
target. When using the target the CLJS compiler collects allnpm_deps.js
these npm dependency requires and generates an file which
can be processed by the metro bundler.
The content of the npm_deps.js file typically looks like this:
``
module.exports = {
npmDeps: {
"react-native": require('react-native'),
"react": require('react') }
};
Finally, there is one more sticking point when integrating an
optimizations :none ClojureScript build into a React Native tooling
environment.
When React Native loads the Metro Compiled bundle it expects the root
of the React Native component to be registered synchronously when the
bundle initially loads. Unfortunately right now it is faster and simpler to
bootstrap and load the ClojureScript application code
asynchronously. So we have to register a proxy component before the
application code loads. This proxy in turn renders your actual
application when the application code actually loads.
This react-native-figwheel-bridge library addresses these problems
and I encourage you to read it and understand it. Reading the code
should eliminate much of the mystery and empower you to make your own
decisions about how you want to load and run your ClojureScript
application.
First you will need to make sure you have React Native and its
dependencies installed.
On the https://reactnative.dev/docs/environment-setup page you will
want to choose either the React Native CLI or the Expo CLI. I
prefer to start with the React Native CLI as there is less tooling to
deal with so its easier to figure out what is going on when you use
it.
Install your CLI of choice according to the instructions on that page.
Once things are installed you can then follow the instructions below
to get an ClojureScript project setup for Figwheel development.
Initialize a project:
For React Native CLI do:
`shell`
$ npx react-native init MyAwesomeProject
For Expo CLI do:
`shell`
$ npx expo init MyAwesomeProject
This will create an initial React Native project. Before you go any
further you will want to ensure that everything is setup so that you can
launch and run your application in a simulator.
Change in into the MyAwesomeProject directory and launch a simulator like so:
`shell`
$ npx react-native run-ios # or run-android
If everything is set up correctly this should launch a phone simulator
with the RN application defined in App.js.
If you have any problems with setting up an application please consult
the React Native documentation. I really recommend reading all of the
React Native Documentation as it is well written and will more than
likely save you lots of headaches.
If everything is up and running go ahead an close everything so that
we can setup a ClojureScript application that uses figwheel-main to
support hot reloading and a REPL.
First we need to add the react-native-figwheel-bridge to our npm
dependencies:
`shell`
$ yarn add react-native-figwheel-bridge
Now we'll start setting up a basic
figwheel.main project.
Create a deps.edn file in the MyAwesomeProject directory:
`clojure`
{:deps {org.clojure/clojurescript {:mvn/version "1.10.764"}
com.bhauman/figwheel-main {:mvn/version "0.2.5"}}}
Create a ios.cljs.edn file in the MyAwesomeProject directory:
`clojure`
^{:open-url false
:cljs-devtools false}
{:main awesome.main
:target :bundle}
Create a src/awesome/main.cljs file in the MyAwesomeProject directory:
`clojure
(ns awesome.main
(:require [react]
[react-native :as rn]))
(def <> react/createElement)
(defn renderfn [props]
(<> rn/View
#js {:style #js {:backgroundColor "#FFFFFF"
:flex 1
:justifyContent "center"}}
(<> rn/Text
#js {:style #js {:color "black"
:textAlign "center"}}
(str "HELLO"))))
;; the function figwheel-rn-root must be provided. It will be called by
;; react-native-figwheel-bridge to render your application.
;; You can configure the name of this function with config.renderFn
(defn figwheel-rn-root []
(renderfn {}))
`
Next we need to create the index file to start our Clojurescript
application this file will be different depending on which CLI tool we
are using.
The index file is the file that will be bundled by React Native
tooling.
Edit the index.js file in the MyAwesomeProject directory:
`javascript
import {AppRegistry} from 'react-native';
import {name as appName} from './app.json';
import {npmDeps} from "./target/public/cljs-out/ios/npm_deps.js";
// you can add other items to npmDeps here
// npmDeps["./assets/logo.png"]= require("./assets/logo.png");
// this url points to a file generated by the cljs compiler in the output-dir of your app
var options = {optionsUrl: "http://localhost:19001/target/public/cljs-out/ios/cljsc_opts.json"};
var figBridge = require("react-native-figwheel-bridge");
figBridge.shimRequire(npmDeps);
AppRegistry.registerComponent(appName,
() => figBridge.createBridgeComponent(options));
`
Now we are ready to launch our ClojureScript application:
First we will start the figwheel-main process to watch and compile
and create a Websocket for REPL communication.
`shell`
$ clj -m figwheel.main -b ios -r
The in another terminal window change into the MyAwesomeProjectreact-native
directory and start
`shell`
$ npx react-native run-ios
When using figwheel-main figwheel bridge will take care of auto
refreshing the application for you when figwheel reloads code.
You can see this behavior by editing the src/awesome/main.cljs"HELLO"
file. Try changing the to "HELLO THERE". You should seesrc/awesome/main.cljs
the application change when you save .
Create an index.js file in the MyAwesomeProject directory:
`javascript
import { registerRootComponent } from 'expo';
import {npmDeps} from "./target/public/cljs-out/ios/npm_deps.js";
var options = {optionsUrl: "http://localhost:19001/target/public/cljs-out/ios/cljsc_opts.json"};
var figBridge = require("react-native-figwheel-bridge");
figBridge.shimRequire(npmDeps);
registerRootComponent(figBridge.createBridgeComponent(options));
`
Now we have to expo that we want to use this index.js as the
entry point to our application.
Edit package.json and change "main": "node_modules/expo/AppEntry.js" to"main": "index.js".
Now we are ready to launch our ClojureScript application:
First we will start the figwheel-main process to watch and compile
and create a Websocket for REPL communication.
`shell`
$ clj -m figwheel.main -b ios -r
The in another terminal window change into the MyAwesomeProjectexpo
directory and start
`shell`
$ yarn ios
When using figwheel-main figwheel bridge will take care of auto
refreshing the application for you when figwheel reloads code.
You can see this behavior by editing the src/awesome/main.cljs"HELLO"
file. Try changing the to "HELLO THERE". You should seesrc/awesome/main.cljs
the application change when you save .
These are the options that you can pass in the configuration Object to
start.
appName: (required for react-native) the name that you created your React Native
project with.
optionsUrl: (optional) a url that will resolve to acljsc_opts.json file. I modified figwheel-main to output this file ascljsc_opts.edn
a JSON version of the file that the ClojureScriptoptionsUrl
compiler outputs. This contains all the information needed to
effectively boostrap and load a ClojureScript application. If a is not supplied you will need to supply the asset-path,main, preloads, and closure-defines options directly.
renderFn: (optional) the JS munged name of the function that returnsfigwheel_rn_root
the React elements for your application - defaults to
asset-path: (optional) this a url that resolves to the base of the:output-dir in most cases this is"http://localhost:8081/target/public/cljs-out/[[build-name]]" and in"http://localhost:8081/target/public/cljs-out/ios"
the current example this would be
main: (optional) the JS munged namespaces string of your root application"my_example.core"
namespace ie.
preloads: (optional) an array of JS munged namespace strings to loadmain
before the ns is loaded.
closure-defines: (optional) a JavaScript Object literal thatgoog-defines
provides custom values for your . Most importantly thisfigwheel.repl.connect_url
should contain a so that figwheel-main
knows where to connect.
After everything is loaded a figwheelBridgeRefresh function is registered on goog.
You can call this function to force the root element to reload.
So for the above example you could set the autoRefresh option to false.
In index.js this looks like:
`javascript`
figBridge.start({appName: "MyAwesomeProject",
optionsUrl: "http://localhost:8081/target/public/cljs-out/ios/cljsc_opts.json",
autoRefresh: false // <-- setting auto refresh to false
});
and control reloading via figwheel.main's reload hooks
in src/awesome/main.cljs this looks like:
`clojure
(ns ^:figwheel-hooks awesome.main
(:require [react]
[react-native :as rn]))
(def <> react/createElement)
(defn renderfn [props]
(<> rn/View
#js {:style #js {:backgroundColor "#FFFFFF"
:flex 1
:justifyContent "center"}}
(<> rn/Text
#js {:style #js {:color "black"
:textAlign "center"}}
(str "HELLO"))))
(defn figwheel-rn-root []
(renderfn {}))
;; adding the reload hook here
(defn ^:after-load on-reload [] (goog/figwheelBridgeRefresh))
`
This code heavily modified from the figwheel-bridge.js file inhttps://github.com/drapanjanas/re-natal which in turn was taken fromhttps://github.com/decker405/figwheel-react-native`.
the now non-existent