Shadow CLJS User’s Guide

You can either compile a development build once or run a watch process which will monitor your source files and re-compile them automatically (and live-reload the code if desired).

All development builds are optimized for the developer experience with fast feedback cycles and other features like a REPL to directly interact with your running code.

A development build should never be shipped publicly since they can become quite large and may only work on the machine they were compiled on depending on the :target.

Creating a release build will strip out all the development related code and finally run the code through the Closure Compiler. This is an optimizing Compiler for JavaScript which will significantly reduce the overall size of the code.

shadow-cljs uses the Java Virtual Machine (JVM) and its "classpath" when working with files. This is a virtual filesystem composed of many classpath entries. Each entry is either

In the Clojure(Script) everything is namespaced and each name is expected to resolve to a file. If you have a (ns demo.app) namespace the compiler expects to find a demo/app.cljs (or .cljc) on the classpath. The classpath will be searched in order until it is found. Suppose you configured the :source-paths ["src/main" "src/test"] the compiler will first look for a src/main/demo/app.cljs and then src/test/demo/app.cljs. When the file is not found on any source path the JVM will begin looking into the .jar files on the classpath. When it finds a demo/app.cljs at the root of any of the libraries that file it will be used.

It is therefore recommended to be very disciplined about the names you choose and about properly namespacing everything. It may seem repetitive to always use (ns your-company.components.foo) over (ns components.foo) but it will save you from lot of headaches later on.

This is unlike npm where the package name itself is never used inside the package itself and only relative paths are used.

shadow-cljs can be started in "server" mode which is required for long-running tasks such as watch. A watch will implicitly start the server instance if it is not already running. The server will provide the Websocket endpoint that builds will connect to as well as all the other endpoints for nREPL, Socket REPL and the development HTTP servers.

When using the shadow-cljs CLI all commands will re-use a running server instance JVM instead of starting a new JVM. This is substantially faster since start-up time can be quite slow.

Once the server is running however you only have to restart it whenever your :dependencies change and everything else can be done via the REPL.

The REPL is at the heart of all Clojure(Script) development and every CLI command can also be used directly from the REPL as well. It is absolutely worth getting comfortable with the REPL even if the command line may seem more familiar.

This is a work in progress. If you find an error, please submit a PR to fix it, or an issue with details of the problem.

This source for this book is hosted on Github.

There are many examples in this book. Most things used in these should be obvious from their context, but to prevent misunderstanding it is important to know the author’s intentions.

When command-line examples are given we may include BASH comments (starting with #), and will usually include the standard user UNIX prompt of $ to indicate separation of the command from its output.

Many of the examples are of the configuration file for the compiler. This file contains an EDN map. Where we have already discussed required options we will often elide them for clarity. In this case we’ll usually include an ellipsis to indicate "content that is required but isn’t in our current focus":

This allows us to concisely include enough context to understand the nesting of the configuration of interest:

Code examples may be similarly shortened.

A shadow-cljs command can be fairly slow to start. To improve this shadow-cljs can run in "server mode" which means that a dedicated process is started which all other commands can use to execute a lot faster since they won’t have to start a new JVM/Clojure instance.

Commands that do long-running things implicitly start a server instance (eg. watch) but it is often advisable to have a dedicated server process running.

You can run the process in the foreground in a dedicated terminal. Use CTRL+C to terminate the server.

You can also run the server in the background controlled via the common start|stop|restart functions.

Once any server is running every other command will use that and run much faster.

If you’d like to use Leiningen to manage your dependencies, you can do so by adding a :lein entry to your shadow-cljs.edn config. With this setting, the shadow-cljs command will use lein to launch the JVM, ignoring any :source-paths and :dependencies in shadow-cljs.edn; relying instead on lein to set them from project.clj.

When using project.clj to manage your :dependencies you must manually include the thheller/shadow-cljs artifact in your :dependencies (directly or in a profile).

The new deps.edn can also be used to manage your :dependencies and :source-paths instead of using the built-in methods or lein. All shadow-cljs commands will then be launched via the new clojure utility instead.

To use this set the :deps true property in your config. It is also possible to configure which deps.edn aliases should be used.

You must add the thheller/shadow-cljs artifact to your deps.edn manually.

With this you are all set, and can run shadow-cljs as normal.

The authors have little Boot experience, so this chapter is in need of contributions. We understand that Boot allows you to build your tool chain out of functions. Since shadow-cljs is a normal JVM library, you can call functions within it to invoke tasks.

Some boot tasks are available here: https://github.com/jgdavey/boot-shadow-cljs

By default the functions called by clj-run only have access to a minimal shadow-cljs runtime which is enough to run compile, release and any other Clojure functionality. The JVM will terminate when your function completes.

If you want to start a watch for a given build you need to declare that the function you are calling requires a full server. This will cause the process to stay alive until you explicitly call (shadow.cljs.devtools.server/stop!) or CTRL+C the process.

This starts a blank CLJS REPL with an already connected node process.

node-repl lets you get started without any additional configuration. It has access to all your code via the usual means, ie. (require '[your.core :as x]). Since it is not connected to any build it does not do any automatic rebuilding of code when your files change and does not provide hot-reload.

This starts a blank CLJS REPL and will open an associated Browser window where the code will execute. Besides running in the Browser this has all the same functionality as the above node-repl.

node-repl and browser-repl work without any specific build configuration. That means they’ll only do whatever you tell them to do but nothing on their own.

If you want to build a specific thing you should configure a build using one of the provided build-targets. Most of them automatically inject the necessary code for a ClojureScript REPL. It should not require any additional configuration. For the build CLJS REPL to work you need 2 things

Once you have both you can connect to the CLJS REPL via the command line or from the Clojure REPL.

If you see this you need to open your App in the Browser or start the node process.

It is also possible to use shadow-cljs entirely from within any other CLJ process. As long as the thheller/shadow-cljs artifact was loaded on the classpath you are good to go.

You can stop the embedded server by running (shadow.cljs.devtools.server/stop!). This will also stop all running build processes.

Your dependencies are managed via the :dependencies key at the root of the shadow-cljs.edn config file. They are declared in the same notation that other Clojure tools like lein or boot use.

Each dependency is written as a vector using [library-name "version-string"] nested in one outer vector.

Notice that the source path is only specified once in the entire configuration. The system will use namespace dependency graphs to determine what code is needed in the final output of any given build.

shadow-cljs integrates fully with the npm ecosystem to manage JavaScript dependencies.

You can use npm or yarn to manage your dependencies, please refer to their respective documentation.

Both manage your dependencies via a package.json file in your project directory. Almost every package available via npm will explain how to install it. Those instructions now apply to shadow-cljs as well.

Nothing more is required. Dependencies will be added to the package.json file and this will be used to manage them.

The shadow-cljs server provides a nREPL server via TCP. If you look at the startup message you’ll see the port of nREPL, and the port will also be stored in target/shadow-cljs/nrepl.port:

You can configure the port and additional middleware with shadow-cljs.edn:

The default global config file in ~/.nrepl/nrepl.edn or the local .nrepl.edn will also be loaded on startup and can be used to configure :middleware.

If the popular middleware cider-nrepl is found on the classpath (e.g. it’s included in :dependencies), it will be used automatically. No additional configuration required. This can be disabled by setting :nrepl {:cider false}.

You may configure the namespace you start in when connecting by setting :init-ns in the :nrepl options. It defaults to shadow.user.

The nREPL server can be disabled by setting :nrepl false.

A Clojure Socket REPL is started automatically in server-mode and uses a random port by default. Tools can find the port it was started under by checking .shadow-cljs/socket-repl.port which will contain the port number.

You can also set a fixed port by via shadow-cljs.edn.

The Socket REPL can be disabled by setting :socket-repl false.

The shadow-cljs HTTP servers support SSL. It requires a Java Keystore that provides a matching private key and certificate.

The above are the defaults so if you want to use those it is fine to just set :ssl {}.

You can create a Keystore using the java keytool command. Creating a trusted self-signed certificate is also possible but somewhat complicated.

The created Certificates.p12 (macOS) or localhost.pfx (Linux, Windows) file can be turned into the required keystore.jks via the keytool utility.

The shadow-cljs server starts one primary HTTP server. It is used to serve the UI and websockets used for Hot Reload and REPL clients. By default it listens on Port 9630. If that Port is in use it will increment by one and attempt again until an open Port is found.

When :ssl is configured the server will be available via https:// instead.

If you prefer to set your own port instead you can do this via the :http config.

:ssl switches the server to server https:// only. If you want to keep the http:// version you can configure a separate :ssl-port as well.

shadow-cljs can provide additional basic HTTP servers via the :dev-http config entry. By default these will serve all static files from the configured paths, and fall back to index.html when a resource is not found (this is what you typically want when developing an application which uses browser push state).

These servers are started automatically when shadow-cljs is running in server mode. They are not specific to any build and can be used to serve files for multiple builds as long as a unique :output-dir is used for each.

:dev-http expects a map of port-number to config. The config supports several shortcuts for the most common scenarios.

This would attempt to find a request to /index.html via public/index.html on the classpath. Which may include files in .jar files.

This would first attempt to find <project-root>/a/index.html then <project-root>/b/index.html then c/index.html on the classpath. If nothing is found the default handler will be called.

The longer config version expects a map and the supported options are:

The following two options only apply when using the default, built-in handler and typically do not need to be changed:

When running watch code for the REPL is injected automatically and usually does not require additional configuration. Additional options are available to control REPL behavior:

As a developer most of your time is spent in development mode. You’re probably familiar with tools like figwheel, boot-reload, and devtools. It’s almost certain that you want one or more of these in your builds.

Preloads are used to force certain namespaces into the front of your generated Javascript. This is generally used to inject tools and instrumentation before the application actually loads and runs. The preloads option is simply a list of namespaces either in the :devtools/:preloads section of shadow-cljs.edn or within the :preloads key of a specific module:

For example to only include the preloads within a main module during development, and not in a web worker:

:preloads are only applied to development builds and will not be applied to release builds.

The React and ClojureScript ecosystems combine to make this kind of thing super useful. The shadow-cljs system includes everything you need to do your hot code reload, without needing to resort to external tools.

In order to use it you simply run:

You can configure the compiler to run functions just before hot code reload brings in updated code, and just after. These are useful for stopping/starting things that would otherwise close over old code.

These can be configured via the :devtools section in your build config or directly in your code via metadata tags.

The possible stages the :build-hooks can use are:

With a running watch the :configure is only called once. Any of the others may be called again (in order) for each re-compile. The build-state will be re-used until the build config changes at which point it will be thrown away and a fresh one will be created.

It is sometimes desireable to fail a build with warnings rather than continuing with the build (eg. in CI envs). You can use the :warnings-as-errors compiler options to customize how that is handled.

A set of possible warning-type keywords can be found here.

:ignore takes a set of symbols refering to namespaces. Either direct matches or .* wildcards are allowed. :warning-types has the same functionality as above, not specifying it means all warnings will throw except the ignored namespaces.

The more dynamic your website gets, the more dynamic your requirements may get. The server may not always know what the client may end up needing. Therefore, it is possible to have the client load code dynamically when needed.

There are a couple ways of loading code dynamically. shadow.lazy is the most convenient and easiest.

Creating unique filenames for each release can be done via the :release-version config setting. Generally you’ll pass this in from the command line via --config-merge.

This would create the main.v1.js and extra.v1.js files in public/js instead of the usual main.js and extra.js.

You can use manual versions or something automated like the git sha at the time of the build. Just make sure that you bump whatever it is once you shipped something out to the user since with caching they won’t be requesting newer versions of old files.

You can add :module-hash-names true to your build config to automatically create a MD5 signature for each generated output module file. That means that a :main module will generate a main.<md5hash>.js instead of just the default main.js.

:module-hash-names true will include the full 32-length md5 hash, if you prefer a shorter version you can specify a number between 1-32 instead (eg. :module-hash-names 8). Be aware that shortening the hash may increase the chances of generating conflicts. I recommend using the full hash.

Instead of generating main.js it will now generate main.<hash>.js in the :output-dir.

Since the filename can change with every release it gets a little bit more complicated to include them in your HTML. If you want to accomplish this with a program external to shadow-cljs, you can find programmatic information about filenames in the Output Manifest. If you want to accomplish this as part of the build, have a look at Build Hooks, and at this hook specifically for inspiration.

The :browser target now uses a HUD to display a loading indicator when a build is started. It will also display warnings and errors if there are any.

You can disable it completely by setting :hud false in the :devtools section.

You may also toggle certain features by specifying which features you care about via setting :hud #{:errors :warnings}. This will show errors/warnings but no progress indicator. Available options are :errors, :warnings, :progress. Only options included will be enabled, all other will be disabled.

The Browser devtools can also reload CSS for you. This is enabled by default and in most cases requires no additional configuration when you are using the built-in development HTTP servers.

Any stylesheet included in a page will be reloaded if modified on the filesystem. Prefer using absolute paths but relative paths should work as well.

This will cause the browser to reload /css/main.css when public/css/main.css is changed.

shadow-cljs currently provides no support for directly compiling CSS but the usual tools will work and should be run separately. Just make sure the output is generated into the correct places.

When you are not using the built-in HTTP Server you can specify :watch-dir instead which should be a path to the document root used to serve your content.

When your HTTP Server is serving the files from a virtual directory and the filesystem paths don’t exactly match the path used in the HTML you may adjust the path by setting :watch-path which will be used as a prefix.

By default the devtools client will attempt to connect to the shadow-cljs process via the configured HTTP server (usually localhost). If you are using a reverse proxy to serve your HTML that might not be possible. You can set :devtools-url to configure which URL to use.

shadow-cljs will then use the :devtools-url as the base when making requests. It is not the final URL so you must ensure that all requests starting with the path you configured (eg. /shadow-cljs/*) are forwarded to the host shadow-cljs is running on.

The client will make WebSocket request as well as normal XHR requests to load files. Ensure that your proxy properly upgrades WebSockets.

Tools like webpack can potentially tree-shake npm dependencies to make their build output smaller. For this the :external-index file needs to generate ESM code, instead of the current default CommonJS, i.e. require().

This will only use import in the :external-index file. For release builds this file will list all the referenced imports, for watch/compile it’ll still reference everything.

Controlling what code is actually exported is done via :exports.

This will generate the public/js/demo.js file. The name is decided by taking the :output-dir and combining it with the key :demo in the :modules map.

It will be loadable directly in any ESM environment. For example the Browser. Putting this into a public/index.html and loading it via http://localhost:8000.

With npx shadow-cljs watch app you should see the hello world logged to the browser console when loading the page.

Note that only hello is accessible here since it was declared in the :exports. The (defn not-exported [] …​) will not be accessible and will most likely be removed entirely in :advanced release builds.

You will need the same basic main configuration as in other targets (like :source-paths), but you’ll need some node-specific build target options:

When compiled this results in a standalone out/demo-script/script.js file intended to be called via node script.js <command line args>. When run it will call (demo.script/main <command line args>) function on startup. This only ever produces the file specified in :output-to. Any other support files (e.g. for development mode) are written to a temporary support directory.

You will often write scripts that run as servers or some other long-running process. Hot code reload can be quite useful when working with these, and it is simple to set up:

Here is an example http server in node:

The associated configuration is (shadow-cljs.edn):

:exports-var will just return whatever is declared under that var. It can point to a defn or normal def.

It is effectively generating module.exports = demo.ns.f;

The keyword is used as the name of the entry in the exported object. No munging is done to this keyword name (but namespaces are dropped). So, the above example maps cljs f to g, etc.:

You can achieve the exact same thing by using :exports-var pointing to a def

In addition you may specify :exports-fn as a fully qualified symbol. This should point to a function with no arguments which should return a JS object (or function). This function will only ever be called ONCE as node caches the return value.

The example below creates a lib.js file intended to be consumed via the normal Node require mechanism.

The build configuration would be:

and the runtime use is as you would expect:

As :node-script this will only create the file specified in :output-to. The :exports map maps CLJS vars to the name they should be exported to.

The output includes two primary artifacts in your test-dir folder:

Any webserver is fine, :dev-http is just a convenient option.

See their website for full instructions. You’ll typically need something like this in your package.json:

So, you need Karma, a browser launcher, and the cljs-test integration.

The build options are:

So you might have something like this:

You also need a karma.conf.js:

then you can run the tests as follows (assuming you’ve installed global executables of the tools):

Most npm packages will also include some instructions on how to use the actual code. The “old” CommonJS style just has require calls which translate directly:

Whatever "string" parameter is used when calling require we transfer to the :require as-is. The :as alias is up to you. Once we have that we can use the code like any other CLJS namespace!

In shadow-cljs: always use the ns form and whatever :as alias you provided. You may also use :refer and :rename. This is different than what :foreign-libs/CLJSJS does where you include the thing in the namespace but then used a global js/Thing in your code.

Some packages just export a single function which you can call directly by using (:require ["thing" :as thing]) and then (thing).

More recently some packages started using ES6 import statements in their examples. Those also translate pretty much 1:1 with one slight difference related to default exports.

The following examples can be used for translation:

Notice that previously we were stuck using bundled code which included a lot of code we didn’t actually need. Now we’re in a better situation: Some libraries are also packaged in ways that allow you to include only the parts you need, leading to much less code in your final build.

react-virtualized is a great example:

With our improved support we we can easily translate this to:

If a :require does not seem to work properly it is recommended to try looking at it in the REPL.

Since printing arbitrary JS objects is not always useful (as seen above) you can use (js/console.dir x) instead to get a more useful representation in the browser console. goog/typeOf may also be useful at times.

shadow-cljs supports several different ways to include npm packages into your build. They are configurable via the :js-options :js-provider setting. Each :target usually sets the one appropriate for your build most often you won’t need to touch this setting.

Currently there are 3 supported JS Providers:

Nowadays many npm packages ship multiple build variants. shadow-cljs will by default pick the variant linked under the main or browser key in package.json. This most commonly refers to CommonJS code. Some modern packages also provide a module entry which usually refers to ECMAScript code (meaning "modern" JS). Interop between CommonJS and ESM can be tricky so shadow-cljs defaults to using CommonJS but it can be beneficial to use ESM.

It is largely dependent on the packages you use whether this will work or not. You can configure shadow-cljs to prefer the module entry via the :entry-keys JS option. It takes a vector of string keys found in package.json which will be tried in order. The default is "["browser" "main" "module"].

Make sure to test thoroughly and compare the build report output to check size differences when switching this. Results may vary greatly in positive or negative ways.

By default shadow-cljs will resolve all (:require ["thing" :as x]) requires following the npm convention. This means it will look at <project>/node_modules/thing/package.json and follow the code from there. To customize how this works shadow-cljs exposes a :resolve config option that lets you override how things are resolved.

By default shadow-cljs will only look at the <project-dir>/node_modules directory when resolving JS packages. This can be configured via the :js-package-dirs option in :js-options. This can be applied globally or per build.

Relative paths will be resolved relative to the project root directory. Paths will be tried from left to right and the first matching package will be used.

We already covered how npm packages are accessed by their name but on the classpath we access .js files by either a full path or relative to the current namespace.

Absolute requires like /some-library/components/foo mean that the compiler will look for a some-library/components/foo.js on the classpath; unlike node which would attempt to load the file from the local filesystem. The same classpath rules apply so the file may either be in your :source-paths or in some third-party .jar library you are using.

Relative requires are resolved by first looking at the current namespace and then resolving a relative path from that name. In the above example we are in demo/app.cljs to the ./bar require resolves to demo/bar.js, so it is identical to (:require ["/demo/bar"]).

The Closure Compiler is used for processing all JavaScript found on the classpath using its ECMASCRIPT_NEXT language setting. What exactly this setting means is not well documented but it mostly represents the next generation JavaScript code which might not even be supported by most browsers yet. ES6 is very well supported as well as most ES8 features. Similarly to standard CLJS this will be compiled down to ES5 with polyfills when required.

Since the Closure Compiler is getting constant updates newer features will be available over time. Just don’t expect to use the latest cutting edge preview features to be available immediately. Somewhat recent additions like async/await already work quite well.

The JS should be written using ES Module Syntax using import and export. JS files can include other JS files and reference CLJS code directly. They may also access npm packages directly with one caveat.

Since there are many popular JavaScript dialects (JSX, CoffeeScript, etc) that are not directly parsable by the Closure Compiler we need to pre-process them before putting them onto the classpath. babel is commonly used in the JavaScript world so we are going to use babel to process .jsx files as an example here.

We run babel to convert the files and write them to the configured src/gen directory. Which directory you use is up to you. I prefer src/gen for generated files.

babel itself is configured via the src/js/.babelrc. See the official example for JSX and more about configuration files.

Once babel writes the src/gen/demo/bar.js it will be available to use via ClojureScript and will even be hot loaded just like your ClojureScript sources.

The JS sources can access all your ClojureScript (and the Closure Library) directly by importing their namespaces with a goog: prefix which the Compiler will rewrite to expose the namespace as the default ES6 export.

CLJSJS packages basically just take the package from npm and put them into a .jar and re-publish them via clojars. As a bonus they often bundle Externs. The compiler otherwise does nothing with these files and only prepends them to the generated output.

This was very useful when we had no access to npm directly but has certain issues since not all packages are easily combined with others. A package might rely on react but instead of expressing this via npm they bundle their own react. If you are not careful you could end up including 2 different react versions in your build which may lead to very confusing errors or at the very least increase the build size substantially.

Apart from that not every npm package is available via CLJSJS and keeping the package versions in sync requires manual work, which means packages are often out of date.

shadow-cljs does not support CLJSJS at all to avoid conflicts in your code. One library might attempt to use the "old" cljsjs.react while another uses the newer (:require ["react"]) directly. This would again lead to 2 versions of react on your page again.

So the only thing we are missing are the bundled Externs. In many instances these are not required due to improved externs inference. Often those Externs are generated using third-party tools which means they are not totally accurate anyways.

Conclusion: Use npm directly. Use :infer-externs auto.

You can choose the optimization level using the :compiler-options section of the configuration:

See the the Closure compiler’s documentation for more information on available optimization levels.

If you wish to have separate configuration values in a build when running a release build then you can override settings by including a :dev and/or :release section in the build section:

To help deal with Externs the shadow-cljs compiler provides enhanced externs inference, which is enabled by default. The compiler will perform additional checks at compile time for your files only. It won’t warn you about possible externs issues in library code.

You’ll get warnings whenever the Compiler cannot figure out whether you are working with JS or CLJS code. If you don’t get any warnings you should be OK.

In :advanced the compiler might be renaming .baz to something "shorter" and Externs inform the Compiler that this is an external property that should not be renamed.

The warning tells you that the compiler did not recognize the property baz in the x binding. shadow-cljs can generate the appropriate externs if you add a typehint to the object you are performing native interop on.

The ^js typehint will cause the compiler to generate proper externs and the warning will go away. The property is now safe from renaming. You may either directly tag the interop form, or you may tag the variable name where it is first bound.

It can get tedious to annotate every single interop call, so you can annotate the variable binding itself. It will be used in the entire scope for this variable. Externs for both calls will still be generated. So, instead you do:

Calling a global using js/ does not require a typehint.

Calls on :require bindings are also inferred automatically.

Some libraries provide Externs as separate .js files. You can include them into your build via the :externs compiler options.

Writing Externs by hand can be challenging and shadow-cljs provides a way to write a more convenient way to write them. Start by creating a externs/<your-build>.txt, so build :app would be externs/app.txt. In that file each line should be one word specifying a JS property that should not be renamed. Global variables should be prefixed by global:

In this example the compiler will stop renaming something.foo(), something.bar().