Scripting API

You can readily start and stop a Figwheel build process from the REPL or a script.

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.

Build Inputs← Back Next →Main Script