shadow-cljs is composed of 2 parts:

• The shadow-cljs Clojure library which handles all the actual work.

• The shadow-cljs npm package which provides a convenient interface for running most of the build functionality directly from command line.

If desired you can easily integrate the shadow-cljs Clojure library into any other Clojure/JVM build tool (eg. leiningen or the Clojure CLI tools).

Use the npm package as the command-line launcher and deps.edn as the dependency manager. This combines the launcher’s server reuse with the Clojure CLI’s dependency and classpath management. Keep build configuration in shadow-cljs.edn; set :deps true there to enable the recommended integration.

When working with shadow-cljs you will be defining one or more builds in the shadow-cljs.edn configuration file. Each build will have a :target property which represents a configuration preset optimized for the target environment (eg. the Browser, a node.js application or a Chrome Extension).

Each build can either produce development or release output depending on the command used to trigger the compilation. The standard build commands are: compile, watch and release.

1.2.1. Development Mode

1.2.2. Release Mode

There are several important concepts that you should familiarize yourself with when using shadow-cljs. They are integral to understanding how everything fits together and how the tool works with your code.

1.3.1. The Classpath

1.3.2. Server Mode

1.3.3. REPL

1.4.1. Work in Progress

1.4.2. Contributing

1.4.3. Conventions Used

# A comment. This command lists files:
$ ls -l
deps.edn
shadow-cljs.edn
...

{:deps true}

{...
 :dev-http {8000 "public"}
 ...}

{...
 :builds {:build-id {...
                     :output-dir "resources/public/js"}}}

You will need:

• Node.js (a currently supported LTS release is recommended)

• npm (comes with node by default) or yarn

• A Java SDK (version 21 or higher, LTS release recommended)

• The Clojure CLI for the recommended deps.edn dependency management

Use deps.edn to manage Clojure(Script) dependencies and source paths, and shadow-cljs.edn to configure builds. The npm package supplies the command-line launcher and works with this setup. See Configuration for the two files to create.

In your project directory you will also need a package.json. If you do not have one yet, create it with npm init -y.

If you have a package.json already and just want to add shadow-cljs run

For convenience, you can run npm install -g shadow-cljs or yarn global add shadow-cljs. This will let you run the shadow-cljs command directly later. There should always be a shadow-cljs version installed in your project, the global install is optional.

The recommended setup combines the npm launcher with deps.edn. You can also embed the shadow-cljs library in another Clojure JVM process or use Leiningen for an existing project.

The artifact can be found at:

If installed globally, you can use the shadow-cljs command directly.

If you prefer to only use the local npm install you can invoke it via npx or yarn.

The guide will assume there is a global install to keep examples short but this is not required.

Sometimes you may run into some release issues due to :advanced compilation. These commands can help track down the causes.

3.1.1. Server Mode

$ shadow-cljs server

# or (if you'd like REPL to control the server process)
$ shadow-cljs clj-repl

$ shadow-cljs start
$ shadow-cljs stop
$ shadow-cljs restart

Use deps.edn to manage Clojure(Script) dependencies and source paths. Keep using the npm launcher for commands such as npx shadow-cljs watch app; it launches the JVM through the Clojure CLI and reuses a running shadow-cljs server.

shadow-cljs.edn remains the build configuration file in this setup. Its built-in dependency resolver is a fallback, not the recommended dependency manager. Existing Leiningen projects can also use the integration below.

3.2.1. tools.deps / deps.edn (Recommended)

{:deps true
 :builds {...}}

{:paths ["src"]
 :deps {thheller/shadow-cljs {:mvn/version "VERSION"}}}

{:deps {:aliases [:cljs]}
 :builds {...}}

{:paths ["src/main"]
 :aliases
 {:cljs
  {:extra-paths ["src/test"]
   :extra-deps {thheller/shadow-cljs {:mvn/version "VERSION"}}}}}

{:paths ["src"]
 :aliases
 {:shadow-cljs
  {:extra-deps {thheller/shadow-cljs {:mvn/version "VERSION"}}
   :main-opts ["-m" "shadow.cljs.devtools.cli"]}}}

$ clojure -M:shadow-cljs watch app

3.2.2. Leiningen

{:lein true
 ; :source-paths and :dependencies are now ignored in this file
 ; configure them via project.clj
 :builds {...}}

{:lein {:profile "+cljs"}
 :builds {...}}

(defproject my-awesome-project
  ...
  :profiles
  {:cljs
   {:source-paths ["src/cljs"]
    :dependencies [[thheller/shadow-cljs "..."]
                   [my/library "1.0.0"]]}})

$ lein run -m shadow.cljs.devtools.cli compile build-id

$ lein run -m shadow.cljs.devtools.cli release build-id

3.2.3. Boot (Legacy Integration)

You can use the shadow-cljs CLI to call specific Clojure functions from the command line. This is useful when you want to run some code before/after certain tasks. Suppose you wanted to rsync the output of your release build to a remote server.

You can pass arguments to the invoked functions via the command line.

You have access to the full power of Clojure here. You can build entire tools on top of this if you like. As a bonus everything you write this way is also directly available via the Clojure REPL.

3.3.1. Calling watch via clj-run

(ns demo.run
  (:require [shadow.cljs.devtools.api :as shadow]))

;; this fails because a full server instance is missing
(defn foo
  [& args]
  (shadow/watch :my-build))

;; this metadata will ensure that the server is started so watch works
(defn foo
  {:shadow/requires-server true}
  [& args]
  (shadow/watch :my-build))

By default you can choose between a node-repl and a browser-repl. They both work similarly and the differentiating factor is that one runs in a managed node.js process while the others opens a Browser Window that will be used to eval the actual code.

4.1.1. Node REPL

$ shadow-cljs node-repl

4.1.2. Browser REPL

$ shadow-cljs browser-repl

4.1.3. Build-specific REPL

$ shadow-cljs watch build-id
...

# different terminal
$ shadow-cljs cljs-repl build-id
shadow-cljs - connected to server
[3:1]~cljs.user=>

$ shadow-cljs clj-repl
...
[2:0]~shadow.user=> (shadow/watch :browser)
[:browser] Configuring build.
[:browser] Compiling ...
[:browser] Build completed. (341 files, 1 compiled, 0 warnings, 3,19s)
:watching
[2:0]~shadow.user=> (shadow/repl :browser)
[2:1]~cljs.user=>

[3:1]~cljs.user=> (js/alert "foo")
There is no connected JS runtime.

A Clojure REPL is also provided in addition to the provided ClojureScript REPLs. This can be used to control the shadow-cljs process and run all other build commands through it. You can start with a Clojure REPL and then upgrade it to a CLJS REPL at any point (and switch back).

The shadow.cljs.devtools.api namespace has functions that map more or less 1:1 to the CLI counterparts. It is aliased as shadow by default.

4.2.1. Embedded

$ lein repl
nREPL server started on port 57098 on host 127.0.0.1 - nrepl://127.0.0.1:57098
REPL-y 0.4.3, nREPL 0.6.0
Clojure 1.10.0
...

user=> (require '[shadow.cljs.devtools.server :as server])
nil
user=> (server/start!)
...
:shadow.cljs.devtools.server/started
user=> (require '[shadow.cljs.devtools.api :as shadow])
nil
user=> (shadow/compile :foo)
...

{:paths ["src"]
 :deps {thheller/shadow-cljs {:mvn/version "VERSION"}}}

{:deps true
 :dev-http {8000 "public"}
 :builds
 {:app {:target :esm
        :output-dir "public/js"
        :modules {:main {:init-fn my.app/init}}}}}

(ns my.app)

(defn init []
  (js/console.log "Hello from ClojureScript"))

<!doctype html>
<html>
  <head><meta charset="utf-8"><title>My app</title></head>
  <body><script type="module" src="/js/main.js"></script></body>
</html>

.
├── deps.edn
├── package.json
├── shadow-cljs.edn
├── public
│   └── index.html
└── src
    └── my
        └── app.cljs

With the recommended setup, :paths in deps.edn configures the project’s source directories on the JVM classpath. The compiler uses that classpath to find Clojure(Script) source files (e.g. .cljs and .cljc) and other resources.

It is fine to put everything in src. You can also group application, development and test sources into separate directories. Aliases let you add paths only when needed.

Declare source paths once for the project, rather than separately for each build. Namespace dependency graphs determine which files are included in each build. Restart the shadow-cljs server after changing the classpath or active aliases.

It is not necessary to separate source files by extension (e.g. src/clj, src/cljs, src/cljc). Grouping them by purpose often makes shared .cljc code easier to work with.

5.2.1. Clojure(Script)

{:paths ["src"]
 :deps {thheller/shadow-cljs {:mvn/version "VERSION"}
        my/library {:mvn/version "1.0.0"}}}

{:source-paths ["src"]
 :dependencies [[my/library "1.0.0"]]
 :builds {...}}

5.2.2. JavaScript

# npm
$ npm install the-thing

# yarn
$ yarn add the-thing

The required JS dependency "react" is not available, it was required by ...

Keep project dependencies and source paths in deps.edn, and build configuration in shadow-cljs.edn. Some settings may be user-specific, such as editor middleware or the command used to open source files.

User configuration is read from the first existing file in this order: $XDG_CONFIG_HOME/shadow-cljs/config.edn, $LOCALAPPDATA/shadow-cljs/config.edn, then ~/.shadow-cljs/config.edn. It applies to all projects on that machine. The examples below use the home-directory fallback.

Adding dependencies is allowed via the usual :dependencies key. Note that dependencies added here will apply to ALL projects. Keep them to a minimum and only put tool related dependencies here. Everything required to build a project belongs in its deps.edn so it is available to other users. These dependencies will automatically be added when using deps.edn or lein as well.

When using deps.edn to resolve dependencies you may sometimes want to activate additional aliases. This can be done via :deps-aliases.

This will make the shadow-cljs command use the [:cljs :cider] aliases in projects using deps.edn. This might be useful if you have an additional :cider alias in your ~/.clojure/deps.edn.

By default the shadow-cljs server-mode will launch an embedded nREPL server which you might not need. You can disable this by setting :nrepl false in user config.

Other useful user settings include :open-file-command and :local-ip for runtime connections. User configuration is merged with project configuration, so avoid putting project-specific build or server settings here.

This section is for other options that configure the shadow-cljs server instance. They are optional.

5.4.1. nREPL

$ shadow-cljs watch app
shadow-cljs - HTTP server available at http://localhost:8600
shadow-cljs - server version: <version> running at http://localhost:9630
shadow-cljs - nREPL server started on port 64967
shadow-cljs - watching build :app
[:app] Configuring build.
[:app] Compiling ...

{...
 :nrepl {:port 9000
         :middleware []} ; optional list of namespace-qualified symbols
 ...}

{...
 :nrepl {:init-ns my.repl}
 ...}

(shadow/watch :the-build)
(shadow/repl :the-build)

(defproject my-amazing-project "1.0.0"
  ...
  :repl-options
  {:init-ns shadow.user ;; or any of your choosing
   :nrepl-middleware
   [shadow.cljs.devtools.server.nrepl/middleware]}
  ...)

5.4.2. Socket REPL

{...
 :socket-repl
 {:port 9000}
 ...}

5.4.3. SSL

{...
 :ssl {:keystore "ssl/keystore.jks"
       :password "shadow-cljs"}
 ...}

$ keytool -importkeystore -destkeystore keystore.jks -srcstoretype PKCS12 -srckeystore localhost.pfx

5.4.4. Primary HTTP(S)

shadow-cljs - server running at http://0.0.0.0:9630

{...
 :http {:port 12345
        :host "my.machine.local"}
 ...}

{...
 :http {:port 12345
        :ssl-port 23456
        :host "localhost"}
 ...}

5.4.5. Development HTTP(S)

{...
 :dev-http {8000 "public"}
 :builds {...}}

:dev-http {8000 "public"}

:dev-http {8000 "classpath:public"}

:dev-http {8000 ["a" "b" "classpath:c"]}

{...
 :dev-http
 {8080 {:root "public"
        :handler my.app/handler}}}

{...
 :dev-http
 {8000
  {:root "public"
   :proxy-url "https://some.host"}}}

With deps.edn, put JVM options in an alias and enable it in shadow-cljs.edn.

The npm launcher also forwards top-level :jvm-opts from shadow-cljs.edn when launching through the Clojure CLI, but keeping them in deps.edn lets other Clojure CLI invocations use the same options. When using Leiningen, configure JVM options in project.clj.

For the built-in resolver fallback, configure :jvm-opts ["-Xmx1G"] at the root of shadow-cljs.edn.

Restart a running server after changing JVM options. Available arguments depend on the Java version; the defaults are usually sufficient.

{:deps true
 :builds
 {:app   {:target     :esm
          ... esm-specific options ...}
  :tests {:target :browser-test
          :test-dir "out/test"}}}

Each build in shadow-cljs must define a :target which defines where you intend your code to be executed. There are default built-ins for the browser and node.js. They all share the basic concept of having :dev and :release modes. :dev mode provides all the usual development goodies like fast compilation, live code reloading and a REPL. :release mode will produce optimized output intended for production.

Targets are covered in separate chapters.

Here are some of them:

:esm

Output ES modules for browsers, Node.js or other JavaScript tools. The recommended target for code running in a web browser.

:browser

Output classic scripts for running in a web browser. Still supported, but prefer :esm for new projects.

:browser-test

Scan for tests to determine required files, and output tests suitable for running in the browser.

:karma

Scan for tests to determine required files, and output karma-runner compatible tests. See the Karma compatibility section.

:node-library

Output code suitable for use as a node library.

:node-script

Output code suitable for use as a node script.

:npm-module

Output code suitable for use as an NPM module.

The targets listed above are covered in more detail in their own chapters since the remaining build options vary on the target you select.

Each build :target typically provides some development support. They are grouped under the :devtools key for each :build.

6.2.1. REPL

{...
 :builds
 {:app {...
        :devtools {:repl-init-ns my.app
                   :repl-pprint true
                   ...}}}}

6.2.2. Preloads

{...
 :builds
 {:app {...
        :devtools {:preloads [fulcro.inspect.preload]
                   ...}}}}

{...
 :builds
 {:app {...
        :modules {:main {...
                         :preloads
                         [com.fulcrologic.fulcro.inspect.preload
                          com.fulcrologic.fulcro.inspect.dom-picker-preload]
                         :depends-on #{:shared}}
                  :shared {:entries []}
                  :worker {...
                           :depends-on #{:shared}}}}}}

6.2.3. Hot Code Reload

shadow-cljs watch build-id

{...
 :builds
 {:app
  {:target :react-native
   :init-fn some.app/init
   :output-dir "app"
   ...
   :devtools
   {:reload-strategy :full}}}}

6.2.4. Lifecycle Hooks

(ns my.app)

(defn ^:dev/before-load stop []
  (js/console.log "stop"))

(defn ^:dev/after-load start []
  (js/console.log "start"))

(ns my.app)

(defn ^:dev/before-load-async stop [done]
  (js/console.log "stop")
  (js/setTimeout
    (fn []
      (js/console.log "stop complete")
      (done))))

(defn ^:dev/after-load-async start [done]
  (js/console.log "start")
  (js/setTimeout
    (fn []
      (js/console.log "start complete")
      (done))))

(ns ^:dev/once my.thing)

(js/console.warn "will only execute once")

(ns ^:dev/always my.thing)

(js/console.warn "will execute on every code change")

{...
 :builds
 {:app {...
        :devtools {:before-load  my.app/stop
                   :after-load   my.app/start
                   ...}}}}

It is sometimes desirable to execute some custom code at a specific stage in the compilation pipeline. :build-hooks let you declare which functions should be called and they have full access to the build state at that time. This is quite powerful and opens up many possible tool options.

They are configured per build under the :build-hooks key

This example would call (my.util/hook build-state 1 2 3) after the build completed the :flush stage (ie. written to disk). The example would print [:hello-world (1 2 3)] but please do something more useful in actual hooks.

The hook is a just a normal Clojure function with some additional metadata. The {:shadow.build/stage :flush} metadata informs the compiler to call this hook for :flush only. You may instead configure {:shadow.build/stages #{:configure :flush}} if the hook should be called after multiple stages. At least one configured stage is required since the hook otherwise would never do anything.

All build hooks will be called after the :target work is done. They will receive the build-state (a clojure map with all the current build data) as their first argument and must return this build-state modified or unmodified. When using multiple stages you can add additional data to the build-state that later stages can see. It is strongly advised to use namespaced keys only to ensure not accidentally breaking the entire build.

The build-state has some important entries which might be useful for your hooks:

• :shadow.build/build-id - the id of the current build (eg. :app)

• :shadow.build/mode - :dev or :release

• :shadow.build/stage - the current stage

• :shadow.build/config - the build config. You can either store config data for the hook in the build config directly or pass it as arguments in the hook itself

6.3.1. Compilation Stages

shadow-cljs will cache all compilation results by default. The cache is invalidated whenever anything relevant to the individual source files changes (eg. changed compiler setting, changed dependencies, etc.). This greatly improves the developer experience since incremental compilation will be much faster than starting from scratch.

Invalidating the cache however can not always be done reliably if you are using a lot of macros with side-effects (reading files, storing things outside the compiler state, etc.). In those cases you might need to disable caching entirely.

Namespaces that are known to include side-effecting macros can be blocked from caching. They won’t be cached themselves and namespaces requiring them will not be cached as well. The clara-rules library has side-effecting macros and is blocked by default. You can specify which namespaces to block globally via the :cache-blockers configuration. It expects a set of namespace symbols.

In addition you can control how much caching is done more broadly via the :build-options :cache-level entry. The supported options are:

The cache files are stored in a dedicated directory for each build so the cache is never shared between builds. A build with the id :app will have the :dev cache in the directory:

The :cache-root setting defaults to .shadow-cljs and controls where ALL cache files will be written. It can only be configured globally, not per build.

The :cache-root is always resolved relative to the project directory. You can also specify absolute paths (eg. /tmp/shadow-cljs).

The Closure Library & Compiler allow you to define variables that are essentially compile time constants. You can use these to configure certain features of your build. Since the Closure compiler treats these as constants when running :advanced optimizations they are fully supported in the Dead-Code-Elimination passes and can be used to remove certain parts of the code that should not be included in release builds.

You can define them in your code

This defines the your.app/VERBOSE variable as false by default. This will cause the println to be removed in :advanced compilation. You can toggle this to true via the :closure-defines options which will enable the println. This can either be done for development only or always.

Closure Defines from the Closure Library

• goog.DEBUG: The Closure Library uses this for many development features. shadow-cljs automatically sets this to false for release builds.

• goog.LOCALE can be used to configure certain localization features like goog.i18n.DateTimeFormat. It accepts a standard locale string and defaults to en. Pretty much all locales are supported, see here and here.

The CLJS compiler supports several options to influence how some code is generated. For the most part shadow-cljs will pick some good defaults for each :target but you might occasionally want to change some of them.

These are all grouped under the :compiler-options key in your build config.

Most of the standard ClojureScript Compiler Options are either enabled by default or do not apply. So very few of them actually have an effect. A lot of them are also specific to certain :target types and do not apply universally (e.g. :compiler-options {:output-wrapper true} is only relevant for :target :browser).

Currently supported options include

• :optimizations supports :advanced, :simple or :whitespace, defaults to :advanced. :none is the default for development and cannot be set manually. release with :none won’t work.

• :infer-externs :all, :auto, true or false, defaults to :auto

• :static-fns (Boolean) defaults to true

• :fn-invoke-direct (Boolean) defaults to false

• :elide-asserts (Boolean) default to false in development and true in release builds

• :pretty-print and :pseudo-names default to false. You can use shadow-cljs release app --debug to enable both temporarily without touching your config. This is very useful when running into problem with release builds

• :source-map (Boolean) defaults to true during development, false for release.

• :source-map-include-sources-content (Boolean) defaults to true and decides whether source maps should contains their sources in the .map files directly.

• :source-map-detail-level :all or :symbols (:symbols reduces overall size a bit but also a bit less accurate)

• :externs vector of paths, defaults to []

• :checked-arrays (Boolean), defaults to false

• :anon-fn-naming-policy

• :rename-prefix and :rename-prefix-namespace

• :warnings as a map of {warning-type true|false}, eg. :warnings {:undeclared-var false} to turn off specific warnings.

Unsupported or non-applicable Options

Options that don’t have any effect at all include

• :verbose is controlled by running shadow-cljs compile app --verbose not in the build config.

• :foreign-libs and :libs

• :stable-names always enabled, cannot be disabled

• :install-deps

• :source-map-path, :source-asset-path and :source-map-timestamp

• :cache-analysis always enabled, cannot be disabled.

• :recompile-dependents

• :preamble

• :hashbang (the :node-script target supports this, others don’t)

• :compiler-stats use --verbose to get detailed information instead

• :optimize-constants always done for release builds, cannot be disabled

• :parallel-build always enabled

• :aot-cache

• :package-json-resolution see :js-options :resolve instead

• :watch-fn

• :process-shim

6.6.1. Warnings as Errors

{...
 :builds
 {:app
  {...
   :compiler-options {:warnings-as-errors true}}}}

{...
 :builds
 {:app
  {...
   :compiler-options {:warnings-as-errors #{:undeclared-var}}}}}

{...
 :builds
 {:app
  {...
   :compiler-options {:warnings-as-errors {:ignore #{some.ns some.library.*}
                                           :warning-types #{:undeclared-var}}}}}}

The default compiler setting is :output-feature-set :es-unsupported, which preserves JavaScript features supported by the bundled Closure Compiler rather than targeting a fixed older ECMAScript version. Targets may override this: for example, :react-native defaults to :es5 for development and :es2020 for release.

Choose an explicit feature set when your deployment environment requires older syntax. This affects processing of imported JavaScript as well as compiler-generated output. It does not guarantee that all browser or Node.js APIs used by your dependencies are available; test in the environments you support.

You can configure this via the :output-feature-set in :compiler-options. The older :language-out option should not be used as :output-feature-set replaced it.

Supported options are:

• :bare-minimum

• :es3

• :es5

• :es6 - class, const, let, …​

• :es7 - exponent ** operator

• :es8 or :es2017 - includes async/await

• :es9 or :es2018 - async iteration, Promise.finally, several RegExp features, spread syntax in object literals

• :es2019

• :es2020 - features such as BigInt and the ?? operator

• :es2021

• :es-next - the features in Closure Compiler’s ES_NEXT feature set

• :es-next-in or :es-unstable - Closure Compiler’s unstable feature set

• :es-unsupported - Closure Compiler’s broadest feature set (the default)

• :browser-2020 - :es2019 minus several RegExp features

• :browser-2021 - :es2020 minus RegExp Unicode properties

• :browser-2022, :browser-2023, :browser-2024, :browser-2025 - additional browser-oriented feature sets

Documentation on these options is a bit sparse and is mostly documented in the code here.

shadow-cljs lets you configure additional reader features in .cljc files. By default you can only use reader conditionals to generate separate code for :clj, :cljs or :cljr. In many CLJS builds however it is also desirable to select which code is generated based on your :target.

Example: Some npm packages only work when targeting the browser, but you may have a ns that you also want to use in a :node-script build. This might happen frequently when trying to use Server-Side Rendering (SSR) with your React App. codemirror is one such package.

This namespace will compile fine for both builds (:node-script and :esm) but when trying to run the :node-script it will fail since the codemirror package tries to access the DOM. Since react-dom/server does not use refs the init-cm function will never be called anyways.

While you can use :closure-defines to conditionally compile away the init-cm fn you can not use it to get rid of the extra :require. Reader conditionals let you do this easily.

The :server build will then no longer have the codemirror require and the init-cm function is removed. Becoming only

It is sometimes desirable to make small adjustments to the build configuration from the command line with values that can’t be added statically to the shadow-cljs.edn config or may change depending on the environment you are in.

You can pass additional config data via the --config-merge {:some "data"} command line option which will be merged into the build config. Data added from the CLI will override data from the shadow-cljs.edn file.

--config-merge expects one EDN map and can be used multiple times, they will be merged left to right. The data added is also visible to build-hooks. It will also accept a file path like --config-merge a/path.edn or --config-merge classpath:a/resource.edn.

It is possible to use environment variables to set configuration values in shadow-cljs.edn but you should consider using --config-merge instead. If you really must use an environment variable you can do so via the #shadow/env "FOO" reader tag. You can also use the shorter #env.

The are also a few more supported forms that you can use #shadow/env with.

Supported :as coercions are :int, :bool, :keyword, :symbol. Supplied :default values will not be converted and are expected to be in the correct type already.

It is possible to use set defaults that will be used for all builds, or for all targets of a certain type.

Configuration merge order is as follows :build-defaults → :target-defaults → actual build config → extra config overrides.

In this example the :app target will inherit both :build-defaults and the :target-defaults for :esm.

{:deps true
 :dev-http {8000 "public"}
 :builds
 {:app
  {:target :esm
   :output-dir "public/js"
   :modules {:main {:init-fn my.app/init}}}}}

(ns my.app)

(defn init []
  (js/console.log "Hello from ClojureScript"))

<!doctype html>
<html>
  <head><meta charset="utf-8"><title>My app</title></head>
  <body><script type="module" src="/js/main.js"></script></body>
</html>

All files are written to the configured :output-dir. Each module ends up as a <module-id>.js file in that directory. Unlike :target :browser no :asset-path is needed, since generated files reference each other using relative import paths. You only need to serve the :output-dir with some kind of web server and load the module via <script type="module"> or import.

Each module has its own set of options that control how the module is constructed. Specifying multiple modules will mean that the code is split between them.

shadow-cljs follows the dependency graph from the namespaces referenced by :init-fn, :entries and :exports to find everything needed in the output. Namespaces that are not required will not be included.

7.2.1. Module Exports

{:deps true
 :dev-http {8000 "public"}
 :builds
 {:app
  {:target :esm
   :output-dir "public/js"
   :modules {:demo {:exports {hello demo.lib/hello}}}}}}

(ns demo.lib)

(defn hello []
  (js/console.log "hello world"))

(defn not-exported []
  (js/console.log "foo"))

<script type="module">
  import { hello } from "/js/demo.js";
  hello();
</script>

{:deps true
 :dev-http {8000 "public"}
 :builds
 {:app
  {:target :esm
   :output-dir "public/js"
   :modules {:demo {:exports {default demo.lib/hello}}}}}}

<script type="module">
  import hello from "/js/demo.js";
  hello();
</script>

{:deps true
 :dev-http {8000 "public"}
 :builds
 {:app
  {:target :esm
   :output-dir "public/js"
   :modules {:demo {:init-fn demo.lib/hello}}}}}

<script type="module" src="/js/demo.js"></script>

{:deps true
 :dev-http {8000 "public"}
 :builds
 {:app
  {:target :esm
   :output-dir "public/js"
   :modules
   {:demo
    {:init-fn demo.lib/hello
     :exports {hello demo.lib/hello}}}}}}

<script type="module">
  import { hello } from "/js/demo.js";
  hello();
</script>

Declaring more than one module splits the code between them, so that each page or feature only loads what it actually needs.

And adding

Here we declare 3 modules with one :base module and two other modules which both depend on the :base module. The :base module declared an empty :entries [] vector which is a convenience to say that it should extract all the namespaces that both of the other modules share (eg. cljs.core in this case).

You may now load each :module independently in the HTML.

The browser will automatically load the /js/base.js as well, but not the /js/other.js as the code above doesn’t need it. Unlike with :target :browser you do not need to include the <script> tags for dependencies yourself or worry about their order, since each module imports the modules it depends on.

You can use :modules to split code for separate sections of your website. Say you have a traditional website with actual different pages.

• www.acme.com - serving the homepage

• www.acme.com/login - serving the login form

• www.acme.com/protected - protected section that is only available once the user is logged in

One possible configuration for this would be to have one common module that is shared between all the pages. Then one for each page.

Modules can also be loaded dynamically at runtime via the provided shadow.esm/dynamic-import helper.

This loads an ESM module at runtime without a static import. The URL must be loadable by the runtime. It can refer to an external module or one of your generated :modules.

Using dynamic-import directly requires knowing which module a given piece of code ended up in. Instead you can tag a var with ^:lazy-loadable and load it by name, letting the compiler figure out which module needs to be loaded.

Let’s assume that the on-event function above is called when something in your app happens, for example when the user clicked a button. esm/load-by-name will import() the module the var was compiled into (thing.js here) and returns a promise. Note that demo.app does not :require demo.thing, otherwise it would end up in the :main module and there would be nothing to load lazily.

The promise resolves to a zero-arity function returning the current value of the var, not the value itself. This is so that hot-reload keeps working and you never hold on to an outdated reference. Call it whenever you need the value instead of storing the result.

esm/get-loaded returns that same function if the var has already been loaded, or nil otherwise. This is useful when you want to use something synchronously if available, and only go async when it is not.

If you prefer not to use the fully qualified name you can supply a custom name instead, e.g. (defn ^{:lazy-loadable "thing"} x [e] …​) and (esm/load-by-name "thing").

Browsers support loading ES modules natively in Web Workers via {type: "module"}, so no extra configuration is required. A worker is just another module, usually with its own :init-fn and a dedicated CLJS namespace.

The empty :entries [] in the :shared module will make it collect all the code shared between the :main and :worker modules. The code in the my.app.worker namespace will only ever be loaded by the worker.

The worker imports shared.js itself, the same way the page loading main.js does.

In a web setting it is desirable to cache .js files for a very long time to avoid extra requests. For this the URL needs to change for every released version, so users never end up with outdated files.

The recommended way to do this is a dedicated output directory per version. Leave the regular :output-dir in your build config for development and override it for release builds via --config-merge.

This writes all modules to public/js/v2, which you then reference in your HTML.

Since the generated modules import each other using relative paths everything in the directory stays consistent, and the files of a release never change once written. Previous versions can be kept around, so users still running an older version of your page can continue to load its files. The version can be anything, for example a manually maintained number or the git commit at the time of the build. Just make sure to bump it for every release you ship.

How the version gets into the HTML depends on how you generate it. A server-side template, a script in your deployment process or a build hook are all fine options.

The :devtools section of a build configures the HUD, CSS reloading and runtime connections. With the default :runtime :browser the :esm target uses the same browser development client as :target :browser, so everything in this section applies to both. Configure optional development HTTP servers separately with the top-level :dev-http setting.

7.8.1. Heads-Up Display (HUD)

{:open-file-command
 ["idea" :pwd "--line" :line :file]}

$ idea /path/to/project-root --line 3 /path/to/project-root/src/main/demo/foo.cljs

{:open-file-command
 ["emacsclient" "-n" ["+%s:%s" :line :column] :file]}

$ emacsclient -n +3:1 /path/to/project-root/src/main/demo/foo.cljs

7.8.2. CSS Reloading

<link rel="stylesheet" href="/css/main.css"/>

[:link {:rel "stylesheet" :href "/css/main.css"}]

:dev-http {8000 "public"}

{...
 :builds
 {:app {...
        :devtools {:watch-dir "public"}}}}

{...
 :builds
 {:app
  {...
   :devtools {:watch-dir "public"
              :watch-path "/foo"}}}}

7.8.3. Proxy Support

{...
 :builds
 {:app {...
        :devtools {:before-load  my.app/stop
                   :after-load   my.app/start
                   :devtools-url "https://some.host/shadow-cljs"
                   ...}}}}

wss://some.host/shadow-cljs/api/remote-relay?server-token=...

ws://localhost:9630/api/remote-relay?server-token=...

With the default :js-provider :shadow, JavaScript dependencies are bundled and provided by shadow-cljs. This is done so the output is directly loadable in the Browser. When importing the :target :esm output into another build tool environment (eg. webpack) that may lead to duplicated dependencies.

Instead, you can configure shadow-cljs to not bundle any JS dependencies and instead leave that to the other tool.

Set :js-provider :import under :js-options in your build config.

With :js-provider :import, npm dependencies remain as ES imports in the generated output. Another bundler, a browser import map, or an ESM runtime must resolve those imports. For example, a browser cannot resolve the bare "react" specifier without an import map or a bundler. :runtime selects development support; it does not itself choose how dependencies are bundled.

{:deps true

 :builds
 {:app {:target :browser
        :output-dir "public/assets/app/js"
        :asset-path "/assets/app/js"
        :modules {:main {:entries [my.app]}}}}}

The browser target outputs a lot of files, and a directory is needed for them all. You’ll need to serve these assets with some kind of server, and the Javascript loading code needs to know the server-centric path to these assets. The options you need to specify are:

:output-dir

The directory to use for all compiler output.

:asset-path

The relative path from web server’s root to the resources in :output-dir.

Your entry point javascript file and all related JS files will appear in :output-dir.

The :asset-path is a prefix that gets added to the paths of module loading code inside of the generated javascript. It allows you to output your javascript module to a particular subdirectory of your web server’s root. The dynamic loading during development (hot code reload) and production (code splitting) need this to correctly locate files.

Locating your generated files in a directory and asset path like this make it so that other assets (images, css, etc.) can easily co-exist on the same server without accidental collisions.

For example: if your web server will serve the folder public/x when asked for the URI /x, and your output-dir for a module is public/assets/app/js then your asset-path should be /assets/app/js. You are not required to use an absolute asset path, but it is highly recommended.

Modules configure how the compiled sources are bundled together and how the final .js are generated. Each Module declares a list of Entry Namespace and from that dependency graph is built. When using multiple Modules the code is split so that the maximum amount of code is moved to the outer edges of the graph. The goal is to minimize the amount of code the browser has to load initially and loading the rest on-demand.

The :modules section of the config is always a map keyed by module ID. The module ID is also used to generate the Javascript filename. Module :main will generate main.js in :output-dir.

The available options in a module are:

The following example shows a minimum module configuration:

shadow-cljs will follow the dependency graph from the root set of code entry points in the :entries to find everything needed to actually compile and include in the output. Namespaces that are not required will not be included.

The above config will create a public/js/main.js file. During development there will be an additional public/js/cljs-runtime directory with lots of files. This directory is not required for release builds.

Declaring more than one Module requires a tiny bit of additional static configuration so the Compiler can figure out how the Modules are related to each other and how you will be loading them later.

In addition to :entries you’ll need to declare which module depends on which (via :depends-on). How you structure this is entirely up to your needs and there is no one-size-fits-all solution unfortunately.

Say you have a traditional website with actual different pages.

• www.acme.com - serving the homepage

• www.acme.com/login - serving the login form

• www.acme.com/protected - protected section that is only available once the user is logged in

One possible configuration for this would be to have one common module that is shared between all the pages. Then one for each page.

In your HTML for the Homepage you’d then always include the shared.js on each page and the others conditionally depending on which page the user is on.

8.3.1. Loading code dynamically

(ns demo.app
  (:require
    [shadow.lazy :as lazy]
    [shadow.cljs.modern :refer (js-await)]))

(def x-lazy (lazy/loadable demo.thing/x))

(defn on-event [e]
  (js-await [x (lazy/load x-lazy)]
    (x e)))

(ns demo.thing)
(defn x [e]
  "hello world")

(def xy (lazy/loadable [demo.thing/x demo.other/y]))

(def xym (lazy/loadable {:x demo.thing/x
                         :y demo.other/y}))

{...
 :builds
   {:app
     {:target :browser
      ...
      :module-loader true
      :modules {:main  {:entries [my.app]}
                :extra {:entries [my.app.extra]
                        :depends-on #{:main}}}}}}

(ns my.app
  (:require [shadow.loader :as loader]))

(defn fn-to-call-on-load []
  (js/console.log "extra loaded"))

(defn fn-to-call-on-error []
  (js/console.log "extra load failed"))

;; load returns a goog.async.Deferred, and can be used like a promise
(-> (loader/load "extra")
    (.then fn-to-call-on-load fn-to-call-on-error))

;; must be a JS array, also returns goog.async.Deferred
(loader/load-many #js ["foo" "bar"])

(loader/with-module "extra" fn-to-call-on-load)

Release builds only: The code generated by the Closure Compiler :advanced compilation will create a lot of global variables which has the potential to create conflicts with other JS running in your page. To isolate the created variables the code can be wrapped in an anonymous function to the variables only apply in that scope.

release builds for :browser with only one :modules are wrapped in (function(){<the-code>}).call(this); by default. So no global variables are created.

When using multiple :modules (a.k.a code splitting) this is not enabled by default since each module must be able to access the variables created by the modules it depends on. The Closure Compiler supports an additional option to enable the use of an output wrapper in combination with multiple :modules named :rename-prefix-namespace. This will cause the Compiler to scope all "global" variables used by the build into one actual global variable. By default this is set to :rename-prefix-namespace "$APP" when :output-wrapper is set to true.

This will only create the MY_APP global variable. Since every "global" variable will now be prefixed by MY_APP. (e.g. MY_APP.a instead of just a) the code size can go up substantially. It is important to keep this short. Browser compression (e.g. gzip) helps reduce the overhead of the extra code but depending on the amount of global variables in your build this can still produce a noticeable increase.

The :modules configuration may also be used to generate files intended to be used as a Web Workers. You may declare any module as a Web Worker by setting :web-worker true. The generated file will contain some additional bootstrap code which will load its dependencies automatically. The way :modules work also ensures that code used only by the worker will also only be in the final file for the worker. Each worker should have a dedicated CLJS namespace.

The above configuration will generate worker.js which you can use to start the Web Worker. It will have all code from the :shared module available (but not :main). The code in the my.app.worker namespace will only ever execute in the worker. Worker generation happens in both development and release modes.

Note that the empty :entries [] in the :shared module will make it collect all the code shared between the :main and :worker modules.

In a web setting it is desirable to cache .js files for a very long time to avoid extra request. It is common practice the generate a unique name for the .js file for every released version. This changes the URL used to access it and thereby is safe to cache forever.

8.6.1. Release Versions

shadow-cljs release app --config-merge '{:release-version "v1"}'

{...
 :builds
   {:app
     {:target :browser
      ...
      :output-dir "public/js"
      :asset-path "/js"
      :modules {:main  {:entries [my.app]}
                :extra {:entries [my.app.extra]
                        :depends-on #{:main}}}}}}

8.6.2. Filenames with Fingerprint-Hash

{...
 :builds
   {:app
     {:target :browser
      ...
      :output-dir "public/js"
      :asset-path "/js"
      :module-hash-names true
      :modules {:main  {:entries [my.app]}
                :extra {:entries [my.app.extra]
                        :depends-on #{:main}}}}}}

shadow-cljs generates a manifest.edn file in the configured :output-dir. This file contains a description of the module config together with an extra :output-name property which maps the original module name to actual filename (important when using the :module-hash-names feature).

The manifest contains all :modules sorted in dependency order. You can use it to map the :module-id back to the actual generated filename.

Development builds also produce this file and you may check if for modifications to know when a new build completed. :module-hash-names does not apply during development so you’ll get the usual filenames.

You can configure the name of the generated manifest file via the :build-options :manifest-name entry. It defaults to manifest.edn. If you configure a filename with .json ending the output will be JSON instead of EDN. The file will be relative to the configured :output-dir.

The :browser target uses the same development client as :target :esm. The HUD, CSS reloading and :devtools-url proxy support are all configured the same way, see Development Support in the :esm chapter.

Sometimes npm packages you may wish to use may use features that shadow-cljs itself does not support. Some packages are even written with the explicit expectation to be processed by webpack. In these cases it might be simpler to just use webpack (or similar), instead of letting shadow-cljs try to bundle those packages and working arround the issues that may occur.

shadow-cljs supports an option to let it focus on compiling CLJS code, but let something else process the npm/JS requires. You can do so via :js-provider :external. I wrote more on this subject in this blogpost.

In your build config you add:

shadow-cljs will then just output all required npm package requires in a format that regular JS tools can understand. You’ll then need to run webpack (or similar) manually, and include the output of that build separately from the shadow-cljs output.

So, instead of just including one script tag in your HTML, you include two.

With libs.js here presuming to be the output of webpack.

8.9.1. JS Tree Shaking

{:builds
 {:app
  {:target :browser
   :output-dir "..."
   :modules {:main {...}}
   :js-options
   {:js-provider :external
    :external-index "target/index.js"
    :external-index-format :esm}}}}

{:deps true
 ...
 :builds
 {:app
  {:target :react-native
   :init-fn demo.app/init
   :output-dir "app"}}}

A plain React Native project loads the generated app/index.js from its JavaScript entry file. The CLJS init function must register the root component using React Native’s AppRegistry. The following repository illustrates the integration, but its dependency versions and tooling setup may be historical:

• https://github.com/thheller/reagent-react-native

Expo can load the generated output as a custom entry point. For a project without Expo Router, set main in package.json to the output file:

The CLJS init function must register the root component. See Expo’s registerRootComponent documentation. Expo Router projects have their own entry-point conventions; the setup above assumes the CLJS init function owns application startup.

These older repositories illustrate shadow-cljs integration, but their expo init commands and app.json entryPoint configuration should not be copied into a current project:

• https://github.com/thheller/fulcro-expo

• https://github.com/thheller/reagent-expo

shadow.expo/render-root registers a React component and accepts a React element to render. This helper requires the expo and create-react-class npm packages in addition to the React Native project’s dependencies.

init is called once on startup. Since the example doesn’t need to do any special setup it just calls start directly. start will be called repeatedly when watch is running each time after the code changes were reloaded. The reagent.core/as-element function can be used to generate the required React Element from the reagent hiccup markup.

React native requires to reload not only compiled files and files explicitly requiring those, but also their transitive dependents, for changes to take effect. To accomplish this, use :reload-strategy option as in Hot Reload of Transitive Dependents.

The :target :node-script produces single-file stand-alone output that can be run using node.js. The code is just ClojureScript, and an entry point is easy to define:

10.1.1. Build Options

{:deps true
 ...
 :builds
 {:script
  {:target :node-script
   :main demo.script/main
   :output-to "out/demo-script/script.js"}}}

10.1.2. Hot Code Reload

(ns demo.script
  (:require ["http" :as http]))

(defn request-handler [req res]
  (.end res "foo"))

; a place to hang onto the server so we can stop/start it
(defonce server-ref
  (volatile! nil))

(defn main [& args]
  (js/console.log "starting server")
  (let [server (http/createServer #(request-handler %1 %2))]

    (.listen server 3000
      (fn [err]
        (if err
          (js/console.error "server start failed")
          (js/console.info "http server running"))
        ))

    (vreset! server-ref server)))

(defn start
  "Hook to start. Also used as a hook for hot code reload."
  []
  (js/console.warn "start called")
  (main))

(defn stop
  "Hot code reload hook to shut down resources so hot code reload can work"
  [done]
  (js/console.warn "stop called")
  (if-some [srv @server-ref]
    (.close srv
      (fn [err]
        (vreset! server-ref nil)
        (js/console.log "stop completed" err)
        (done)))
    (done)))

(js/console.log "__filename" js/__filename)

{...
 :builds
   { :script {... as before

              ; add in reload hooks
              :devtools {:before-load-async demo.script/stop
                         :after-load demo.script/start}}}}

The :target :node-library emits code that can be used (via require) as a standard node library, and is useful for publishing your code for re-use as a compiled Javascript artifact.

As with other modes the main configuration options apply and must be set. The target-specific options are:

The output uses CommonJS. In a package with "type": "module", choose a .cjs output filename. Use the :esm target for ES module output.

The hot code reload story is similar to the script target, but may not work as well since it cannot as easily control all of the code that is loaded.

Controlling what code is actually exported is done via one of the following options:

• :exports - a map of keyword to fully qualified symbols

• :exports-var - a fully qualified symbol

• :exports-fn - a fully qualified symbol

10.2.1. Single static "default" export

{...
 :builds {:lib {:output-to "lib.js"
                :exports-var demo.ns/f
                ...}}}

(ns demo.ns)

(defn f [...] ...)
;; OR
(def f #js {:foo ...})

$ node
> var f = require('./lib.js');
f(); // the actual demo.ns/f function

10.2.2. Multiple static named exports

{...
 :builds {:lib {:exports {:g       demo.ns/f
                          :h       other.ns/thing
                          :ok?     another.ns/ok?}
                ...}}}

$ node
> var lib = require('./lib.js');
lib.g(); // call demo-ns/f
lib.ok_QMARK_(); // call another.ns/ok?

(def exports #js {:g f
                  ...})

10.2.3. "Dynamic" exports

(ns demo.ns
  (:require [demo.other :as other]))

(defn hello []
  "hello")

(defn generate-exports []
  #js {:hello hello
       :foo other/foo})

{...
 :builds {:lib {:exports-fn demo.ns/generate-exports
                ...}}}

10.2.4. Full Example

(ns demo.lib)

(defn hello []
  (prn "hello")
  "hello")

{...
 :builds {:library {:target    :node-library
                    :output-to "out/demo-library/lib.js"
                    :exports   {:hello demo.lib/hello}}}}

$ cd out/demo-library
$ node
> var x = require('./lib');
undefined
> x.hello()
hello
'hello'

Use :node-library for CommonJS exports or :esm for ES module exports. Build with release and include the generated output in the package. JavaScript dependencies left as require() or import calls must also be declared in the package’s package.json.

The package entry points must match the generated files and their module format. See the npm publishing guide for package metadata, inspecting package contents and publishing.

{...
 :builds
 {:code
  {:target :npm-module
   :output-dir "out"
   :entries [demo.foo]}}}

Unlike the :node-library target, the module target does not know what you want to call the symbols you’re exporting, so it just exports them as-is. If you use advanced compilation, then everything will get a minified munged name!

This is easy to remedy, simply add :export metadata on any symbols that you want to preserve:

This is a standard annotation that is understood by ClojureScript and prevents Google Closure from renaming an artifact. JS code will still be able to access them after optimizations. Without the ^:export hint the closure-compiler will likely have removed or renamed them.

(ns demo.app-test
  (:require [cljs.test :refer (deftest is)]))

(deftest a-failing-test
  (is (= 1 2)))

This target will create a test runner including all test namespaces matching the given regular expression.

The relevant configuration options are:

The :node-test target only generates the test file. You can run it via node.

The default runner also supports listing tests and selecting namespaces or individual test vars. These options are passed to the generated Node.js script:

Selections are exact names, not regular expressions. They only select tests already included by the build’s :ns-regexp and active classpath.

The node process exit code will be set to 0 when successful and 1 on any failures. (The node process exit code will not be returned when using :autorun.)

This target is meant for gathering up namespaces that contain tests (based on a filename pattern match), and running them in the browser. It contains a built-in runner that will automatically scan for cljs.test tests, run them and display the results.

The relevant configuration options are:

The normal :devtools options are supported, so you will usually create an http server to serve the files. In general you will need a config that looks like this:

Run shadow-cljs watch test and open http://localhost:8021. All tests run when the page loads.

12.2.1. The Test Runner

{:target :browser-test
 :test-dir "out/test"
 :closure-defines {shadow.test.runner/ASYNC-TIMEOUT 60000}}

12.2.2. Headless and Automated Use

{"status": "failed",
 "summary": {"tests": 26, "passed": 5, "failed": 14, "errors": 7,
             "notRun": 0, "outdated": 0, "assertions": 66},
 "run": {"id": 1, "status": "done", "reason": "load", "completed": 26, "durationMs": 4460,
         "testIds": ["demo.foo-test/foo", "demo.foo-test/map-diff", ...]},
 "namespaceErrors": [],
 "tests": [
   {"id": "demo.foo-test/map-diff", "ns": "demo.foo-test", "name": "map-diff",
    "file": "demo/foo_test.cljs", "line": 41,
    "status": "fail", "durationMs": 1,
    "assertions": {"pass": 0, "fail": 1, "error": 0},
    "out": null,
    "failures": [
      {"type": "fail",
       "message": null,
       "testing": [],
       "expected": "(= {:id 1, :name \"foo\"} {:id 1, :name \"bar\"})",
       "actual": "{:id 1, :name (mismatch (expected \"foo\") (actual \"bar\"))}",
       "text": "FAIL in demo.foo-test/map-diff (demo/foo_test.cljs:42)\n..."}]},
   ...]}

npm install --save-dev playwright
npx playwright install chromium

npx shadow-cljs compile test   # or: npx shadow-cljs release test
node run-browser-tests.mjs out/test
node run-browser-tests.mjs out/test --test=my.app.core-test
node run-browser-tests.mjs http://localhost:8021 --json

#!/usr/bin/env node
// Runs the tests of a shadow-cljs :browser-test build in a headless browser.
// Prints the results and exits with 0 if all tests passed, 1 if any failed, 2 if the tests could not run.
//
// Requires playwright: npm install --save-dev playwright && npx playwright install chromium
//
// Usage:
//   node run-browser-tests.mjs <test-dir-or-url> [options]
//
//   <test-dir-or-url>  the :test-dir of a compiled or released build, served by this script,
//                      or the URL of an already served test page, eg. http://localhost:8021
//
// Options:
//   --test=a.ns,a.ns/some-test  only run these namespaces and tests
//   --filter=text               only run tests whose ns/name contains text, comma separated alternatives
//   --json                      print the JSON report instead of the text report
//   --console                   also print the console output of the page
//   --browser=chromium          chromium, firefox or webkit
//   --timeout=120000            give up after this many ms

import http from "node:http";
import fs from "node:fs";
import path from "node:path";

const USAGE = "Usage: node run-browser-tests.mjs <test-dir-or-url> [--test=...] [--filter=...] [--json] [--console] [--browser=chromium] [--timeout=ms]";

function parseArgs(argv) {
  const opts = { target: null, test: null, filter: null, json: false, console: false, browser: "chromium", timeout: 120000 };
  for (const arg of argv) {
    if (arg === "--json") opts.json = true;
    else if (arg === "--console") opts.console = true;
    else if (arg.startsWith("--test=")) opts.test = arg.slice(7);
    else if (arg.startsWith("--filter=")) opts.filter = arg.slice(9);
    else if (arg.startsWith("--browser=")) opts.browser = arg.slice(10);
    else if (arg.startsWith("--timeout=")) opts.timeout = parseInt(arg.slice(10), 10);
    else if (arg.startsWith("--")) fail(`Unknown option: ${arg}\n${USAGE}`);
    else opts.target = arg;
  }
  if (!opts.target) fail(USAGE);
  return opts;
}

// problems running the tests, as opposed to failing tests
class RunnerError extends Error {}

function fail(msg) {
  throw new RunnerError(msg);
}

async function loadPlaywright() {
  for (const name of ["playwright", "playwright-core"]) {
    try {
      return await import(name);
    } catch (e) {
      // try the next one
    }
  }
  fail("playwright not found. Install it via: npm install --save-dev playwright && npx playwright install chromium");
}

const MIME_TYPES = {
  ".html": "text/html; charset=utf-8",
  ".js": "text/javascript; charset=utf-8",
  ".mjs": "text/javascript; charset=utf-8",
  ".css": "text/css; charset=utf-8",
  ".json": "application/json",
  ".map": "application/json",
  ".svg": "image/svg+xml",
  ".png": "image/png",
  ".wasm": "application/wasm",
};

// minimal static file server for the generated index.html and its JS modules
function serveDir(dir) {
  const root = path.resolve(dir);
  if (!fs.existsSync(path.join(root, "index.html"))) {
    fail(`${root}/index.html not found. Compile the :browser-test build first, eg. npx shadow-cljs compile test`);
  }

  const server = http.createServer((req, res) => {
    const urlPath = decodeURIComponent(new URL(req.url, "http://localhost").pathname);
    const file = path.join(root, urlPath.endsWith("/") ? urlPath + "index.html" : urlPath);
    if (!file.startsWith(root + path.sep)) {
      res.writeHead(403).end();
      return;
    }
    fs.readFile(file, (err, data) => {
      if (err) {
        res.writeHead(404).end();
      } else {
        res.writeHead(200, { "content-type": MIME_TYPES[path.extname(file)] || "application/octet-stream" });
        res.end(data);
      }
    });
  });

  return new Promise((resolve) => {
    server.listen(0, "127.0.0.1", () => {
      resolve({ server, url: `http://127.0.0.1:${server.address().port}/` });
    });
  });
}

async function main() {
  const opts = parseArgs(process.argv.slice(2));
  const pw = await loadPlaywright();
  const browserType = pw[opts.browser];
  if (!browserType) fail(`Unknown browser: ${opts.browser}`);

  let server = null;
  let url = opts.target;
  if (!/^https?:\/\//.test(url)) {
    ({ server, url } = await serveDir(url));
  }

  const pageUrl = new URL(url);
  if (opts.test) pageUrl.searchParams.set("test", opts.test);
  if (opts.filter) pageUrl.searchParams.set("filter", opts.filter);

  const browser = await browserType.launch();
  const pageErrors = [];
  let exitCode = 2;

  try {
    const page = await browser.newPage();
    page.on("pageerror", (err) => {
      pageErrors.push(err);
      if (opts.console) console.error(`[pageerror] ${err.stack || err.message}`);
    });
    if (opts.console) {
      page.on("console", (msg) => console.error(`[console.${msg.type()}] ${msg.text()}`));
    }

    const deadline = Date.now() + opts.timeout;
    const remaining = () => Math.max(1, deadline - Date.now());

    await page.goto(pageUrl.toString(), { timeout: remaining() });

    try {
      await page.waitForFunction(() => window.shadowTest, null, { timeout: Math.min(remaining(), 30000) });
    } catch (e) {
      const errors = pageErrors.map((err) => `  ${err.message}`).join("\n");
      fail(`The page at ${pageUrl} did not load the shadow-cljs test runner (window.shadowTest).` +
           (errors ? `\nPage errors:\n${errors}` : ""));
    }

    const done = page.evaluate(() => shadowTest.done());
    // rejects when the browser is closed after a timeout, nothing left to do then
    done.catch(() => {});

    const report = await Promise.race([
      done,
      new Promise((resolve) => setTimeout(() => resolve(null), remaining())),
    ]);

    if (!report) {
      fail(`Tests did not complete within ${opts.timeout}ms.`);
    }

    if (opts.json) {
      console.log(JSON.stringify(report, null, 2));
    } else {
      console.log(await page.evaluate(() => shadowTest.text()));
    }

    if (report.status === "passed") {
      exitCode = 0;
    } else if (report.status === "failed") {
      exitCode = 1;
    } else {
      // "idle", nothing ran. eg. --test or --filter didn't match anything
      if (!opts.json) console.error("No tests ran.");
      exitCode = 2;
    }
  } finally {
    await browser.close();
    if (server) server.close();
  }

  process.exit(exitCode);
}

main().catch((e) => {
  console.error(e instanceof RunnerError ? e.message : (e.stack || String(e)));
  process.exit(2);
});

(js/shadowTest.status)                       ;; "passed", "failed", "running" or "idle"
(shadow.test.runner/text-report)             ;; same text as the console output
(shadow.test.runner/run-tests! '[my.app.core-test/some-test my.app.other-test/foo])

12.2.3. Custom Runner

(ns tests.client-test-main
  {:dev/always true}
  (:require [shadow.test :as st]
            [shadow.test.env :as env]))

(defn start []
  (-> (env/get-test-data)
      (env/reset-test-data!))

  ;; prints the results to the browser console using the default cljs.test reporter
  (st/run-all-tests))

(defn stop [done]
  ; tests can be async. You must call done so that the runner knows you actually finished
  (done))

(defn init []
  (start))