Scripting API
This API is only available for
figwheel.main 0.1.6
and higher.
Starting Figwheel from the REPL (or Script)
The scripting API isn’t quite as general as the command line API. It focuses on creating and managing running build processes.
To use the API you will need to ensure that you have
the dependencies and the classpaths
sorted out to use figwheel.main
. Then you will need to require the
figwheel.main.api
namespace and call the figwheel.main.api/start
function.
Let’s assume we have a dev.cljs.edn
build file and we want to start
Figwheel from the Clojure REPL. You can start the dev
build with a
REPL as follows:
$ clj
Clojure 1.9.0
user=> (require 'figwheel.main.api)
nil
user=> (figwheel.main.api/start "dev")
;; ... Figwheel startup output ommitted ...
ClojureScript 1.10.238
cljs.user=>
As you can see this starts a Figwheel build process along with a ClojureScript REPL.
If you want to start a Figwheel build without a REPL you will need to
ensure that the :mode
option is :serve
. You can do this in
the metadata in the build file or you can supply a replacement for the
figwheel-main.edn
config options like so:
$ clj
user=> (figwheel.main.api/start {:mode :serve} "dev")
[Figwheel] Compiling build dev to "target/public/cljs-out/dev-main.js"
[Figwheel] Successfully compiled build dev to "target/public/cljs-out/dev-main.js" in 0.782 seconds.
[Figwheel] Watching and compiling paths: ("src" "devel") for build - dev
[Figwheel] Starting Server at http://localhost:9500
2018-08-06 17:53:26.155:INFO::main: Logging initialized @15707ms
Opening URL http://localhost:9500
nil
user=>
As you can see this starts the Figwheel build process, launches a server and does not launch a ClojureScript REPL, instead it returns you to the Clojure REPL so you can continue interacting with your Clojure process.
Now that you have the dev
Figwheel build running in the background,
you can now use the rest of the Scripting API. For example, you can
launch a ClojureScript REPL attached to the running dev
build
process like so:
;; in the Clojure REPL after you have started the "dev" build
user=> (figwheel.main.api/cljs-repl "dev")
This will start a REPL into the running dev
build. You can quit the
REPL via :cljs/quit
and then restart it by calling
figwheel.main.api/cljs-repl
again.
REPL switching example
For this example to work, one will need to set up the normal Figwheel
dependencies along with com.bhauman/rebel-readline-cljs
.
We’ll start off by starting a Rebel Readline Clojure REPL.
$ clojure -m rebel-readline.main
user=>
Assuming that we already have a build set up in dev.cljs.edn
and a
background build defined in admin.cljs.edn
.
We can start both of these builds running with:
user=> (require '[figwheel.main.api :as fig])
nil
user=> (fig/start {:mode :serve} "dev" "admin")
Now we’ll start a REPL for the dev
build:
user=> (fig/cljs-repl "dev")
;; .. figwheel REPL startup output omitted ...
cljs.user=> (js/console.log "hey")
nil
There are a couple of things to notice at this point. If you check
the console of the browser window that the dev
application is
running in you will notice that the word "hey"
is printed out. You
should also notice that your ClojureScript REPL is utilizing Rebel
Readline.
You can now quit the dev
REPL and launch a REPL into admin
.
cljs.user=> :cljs/quit
nil
;; returns us to the Clojure REPL prompt
user=> (fig/cljs-repl "admin")
;; .. figwheel REPL startup output omitted ...
cljs.user=>
We’ve successfully switched between ClojureScript REPLs for our builds all the while staying in a Rebel Readline environment.
API Docs
figwheel.main.api/start
Args: ([build] [figwheel-options-or-build build & background-builds])
Starts a Figwheel build process.
Has two arities:
(start build) (start figwheel-config-or-build build & backgound-builds)
You can call start
with any number of build
arguments. The first
one will be the foreground build and any builds that follow will be
background builds. When you provide more than one argument to start
the first argument can optionally be a map of Figwheel Main options.
A build
arg can be either:
- the name of a build like “dev” (described in a .cljs.edn file)
- a map describing a build with the following form
{
:id "dev" ; a required string build id
:options {:main 'hello-world.core} ; a required map of cljs compile options
:config {:watch-dirs ["src"]} ; an options map of figwheel.main config options
}
If the :options
map has Figwheel options metadata, it will be used
unless there is a non-nil :config
option. The presence of a non-nil
:config
option map will cause any metadata on the :options
map
to be ignored.
The figwheel-config-or-build
arg can be a build or a map of
Figwheel options that will be used in place of the options found in
a figwheel-main.edn
file if present.
The background-builds
is a collection of build
args that will be
run in the background.
Examples:
; The simplest and most common case. This will start figwheel just like
; `clojure -m figwheel.main -b dev -r`
(start "dev")
; With inline build config
(start {:id "dev"
:options {:main 'example.core}
:config {:watch-dirs ["src"]}})
; With inline figwheel config
(start {:css-dirs ["resources/public/css"]} "dev")
; With inline figwheel and build config:
(start {:css-dirs ["resources/public/css"]}
{:id "dev" :options {:main 'example.core}})
REPL API Usage
Starting a Figwheel build stores important build-info in a build registry. This build data will be used by the other REPL API functions:
figwheel.main.api/cljs-repl
figwheel.main.api/repl-env
figwheel.main.api/stop
If you are in a REPL session the only way you can use the above
functions is if you start Figwheel in a non-blocking manner. You can
make start
not launch a REPL by providing a :mode :serve
entry in
the Figwheel options.
For example neither of the following will start a REPL:
(start {:mode :serve} "dev")
(start {:id "dev"
:options {:main 'example.core}
:config {:watch-dirs ["src"]
:mode :serve}})
The above commands will leave you free to call the cljs-repl
,
repl-env
and stop
functions without interrupting the server and
build process.
However once you call start
you cannot call it again until you
have stopped all of the running builds.
figwheel.main.api/cljs-repl
Args: ([build-id])
Once you have already started Figwheel in the background with a
call to figwheel.main.api/start
, you can supply a build name of a
running build to this function to start a ClojureScript REPL for the
running build.
Example:
(figwheel.main.api/cljs-repl "dev")
figwheel.main.api/repl-env
Args: ([build-id])
Once you have already started a build in the background with a call
to start
, you can supply the build-id
of the running build to
this function to fetch the repl-env for the running build. This is
helpful in environments like vim-fireplace that need the repl-env.
Example:
(figwheel.main.api/repl-env "dev")
The repl-env returned by this function will not open urls when you start a ClojureScript REPL with it. If you want to change that behavior:
(dissoc (figwheel.main.api/repl-env "dev") :open-url-fn)
The REPL started with the above repl-env will be inferior to the
REPL that is started by either figwheel.main.api/start
and
figwheel.main.api/cljs-repl
as these will listen for and print out
well formatted compiler warnings.
figwheel.main.api/stop
Args: ([build-id])
Takes a build-id
and stops the given build from running. This
will not work if you have not started the build with start
.
figwheel.main.api/stop-all
Args: ([])
Stops all of the running builds.
figwheel.main.api/start-join
Args: ([& args])
Takes the same arguments as start
.
Starts figwheel and blocks. Useful when you want Figwheel to block
on the server it starts when using :mode :serve
. You would
normally use this in a script that would otherwise exit
prematurely.