shadow-cljs

library3.4.4jsnpmunverified

shadow-cljs is a comprehensive ClojureScript compiler and JavaScript bundler that simplifies the development workflow for ClojureScript projects. It offers fast incremental compilation, robust hot-reloading for both ClojureScript and CSS, and seamless integration with the broader JavaScript ecosystem, including npm packages and various build targets (e.g., browser, Node.js, React Native, Chrome extensions). The current stable version is 3.4.4, with point releases occurring frequently to address bugs and introduce minor features, ensuring an active and responsive development cycle. A key differentiator is its focus on providing sensible defaults and abstracting away complex configurations, offering a highly optimized developer experience for both development and release builds, particularly for projects heavily utilizing npm dependencies, contrasting with tools like Figwheel-main which are often preferred for purely ClojureScript projects.

web-framework devops

npm install shadow-cljs

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · SHADOW-CLJS

shadow-cljs

web-frameworkjavascriptv3.4.4

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

shadow-cljs (CLI)

✓ npx shadow-cljs <command>

✗ import shadowCljs from 'shadow-cljs'

shadow-cljs is primarily a command-line interface tool. While it is distributed via npm, its primary use is through the `shadow-cljs` executable or `npx`. There is no direct JavaScript/TypeScript import for the compiler itself for general usage, though internal programmatic Clojure APIs exist.

Programmatic API (Clojure)

✓ (shadow.cljs.devtools.api/compile :app)

For advanced use cases and integration with other Clojure/JVM build tools, shadow-cljs exposes a Clojure API (e.g., `shadow.cljs.devtools.api`) that can be used from Clojure code to programmatically control builds. This is not a direct JavaScript/TypeScript import and cannot be called directly from JavaScript.

Demonstrates how to scaffold a new shadow-cljs project, configure a basic browser build, create a sample ClojureScript application with Reagent, and run the development watcher.

npx create-cljs-project my-app cd my-app # --- shadow-cljs.edn content (create this file) --- # {:source-paths ["src/main"] # :dependencies [] # :builds {:app {:target :browser # :output-dir "resources/public/js" # :asset-path "/js" # :modules {:app {:init-fn my-app.core/init!}} # :compiler-options {:optimizations :simple}}}} # ----------------------------------------------------- # --- src/main/my_app/core.cljs content (create this file) --- # (ns my-app.core # (:require [reagent.core :as r])) # # (defn hello-world [] # [:div "Hello from ClojureScript!"]) # # (defn init! [] # (r/render [hello-world] (js/document.getElementById "app"))) # ----------------------------------------------------------------- # Add 'dev' and 'release' scripts to your package.json: # "scripts": { # "dev": "shadow-cljs watch app", # "release": "shadow-cljs release app" # } # Install React and ReactDOM as npm dependencies (common for Reagent projects) npm install react react-dom # Start the development watcher and built-in HTTP server npm run dev # Once compiled, access your app at http://localhost:8020/ (default shadow-cljs dev server port). # Remember to create a public/index.html file to load your compiled JavaScript.

shadow-cljs --version

Debug

Known issues

breakingVersion 3.0.0 introduced significant breaking changes, including an updated `closure-compiler` version, removal of `node-libs-browser` polyfills, and a hard requirement for Java 21+ (earlier versions required Java 8 or 11). Ensure your JVM environment is updated to avoid startup failures.

fix

Upgrade your Java Development Kit (JDK) to version 21 or later. Review your `shadow-cljs.edn` configuration for deprecated options and adjust polyfill strategies if `node-libs-browser` was explicitly relied upon.

affects: >=3.0.0

gotchaDependency conflicts are a common issue, especially when `shadow-cljs` is used alongside other Clojure/JVM build tools (e.g., Leiningen, deps.edn) that manage core Clojure/ClojureScript libraries or Google Closure Compiler dependencies. `shadow-cljs` bundles specific versions of these internal dependencies.

fix

It is strongly recommended to let `shadow-cljs` manage its internal dependencies. If conflicts arise, check the `shadow-cljs` changelog and `clojars` for the exact dependency versions it uses and align your project's `project.clj` or `deps.edn` to match, or use `shadow-cljs.edn` exclusively for dependency management where possible to leverage its internal checks.

affects: >=2.x

breakingAs of version 3.4.1, the automatic installation of `npm-deps` defined in ClojureScript libraries is now manual due to security concerns with running `npm install` automatically.

fix

Instead of relying on automatic installation, you must manually trigger the `npm-deps` installer using `npx shadow-cljs run shadow.cljs.npm-deps` (or the `clj -X` or `lein run` equivalents) when your dependencies change.

affects: >=3.4.1

gotchaWhen running `shadow-cljs` inside Docker containers or similar virtualized environments, the default file watching mechanism may not function correctly, leading to a lack of hot-reloading.

fix

Configure `shadow-cljs` to use a polling-based file watcher by setting `:fs-watch {:impl :polling}` in your `shadow-cljs.edn` configuration or via the `SHADOW_CLJS` environment variable. This is more resource-intensive but ensures changes are detected in containerized setups.

affects: >=2.x

gotchaGoogle Closure Compiler, used by `shadow-cljs`, can sometimes lag in supporting the latest ECMAScript features (e.g., static class fields), leading to parsing errors when consuming modern JavaScript libraries from npm.

fix

If encountering parsing errors with modern JS libraries, consider using an external JavaScript bundler like ESBuild (via a `shadow-cljs` hook or manual step) to pre-process problematic JavaScript dependencies before `shadow-cljs` compiles your ClojureScript.

affects: >=2.x

Errors

Common errors & fixes

Errors encountered while trying to parse file ... {'}' expected}

Google Closure Compiler (used by shadow-cljs) does not yet support a specific modern JavaScript syntax feature present in an npm dependency.

fix

Pre-process the problematic JavaScript library using another bundler (e.g., ESBuild, Babel) before `shadow-cljs` compilation, or configure `shadow-cljs` to exclude the parsing of that specific file if it's not directly needed for ClojureScript compilation.

shadow-cljs - Stale Output! Your loaded JS was not produced by the running shadow-cljs instance. Is the watch for this build running?

The browser or Node.js environment is loading an old build artifact, or the `shadow-cljs` watcher for the specific build target is not actively running or has not finished its initial compilation.

fix

Ensure the `shadow-cljs watch <build-id>` command is running in your terminal and has successfully completed its initial compilation before refreshing the browser or running the Node.js application. Avoid opening the build target URL before compilation is complete.

No application has connected to the REPL server. Make sure your JS environment has loaded your compiled ClojureScript code.

The ClojureScript code compiled by `shadow-cljs` (which establishes the REPL connection) has not yet been loaded and executed in the target JavaScript environment (browser or Node.js).

fix

For browser builds, ensure your HTML page loads the compiled JavaScript file (e.g., `public/js/main.js`). For Node.js builds, ensure your Node.js process requires the compiled output (e.g., `node -e 'require("./dist/index.js")'`) after starting `shadow-cljs node-repl <build-id>`.

Failed to load Clojure or ClojureScript artifacts, potentially due to dependency conflicts or an incorrect classpath.

The underlying JVM process failed to start or resolve critical Clojure/ClojureScript dependencies, often due to mismatched versions with `shadow-cljs`'s internal requirements or an improperly configured classpath.

fix

Check your `project.clj` or `deps.edn` for `org.clojure/clojure`, `org.clojure/clojurescript`, and `com.google.javascript/closure-compiler-unshaded` versions. Ensure they match what `shadow-cljs` expects (consult its `clojars` dependencies for the exact versions for your `shadow-cljs` version). Consider using `shadow-cljs.edn` for all dependency management to simplify this.

Upgrade

Version history

3.4.4latest on npm

Audit

Dependencies

noderequiredRuntime environment for the npm package wrapper. Node.js >=6.0.0 is technically required by the npm package, but recent shadow-cljs versions often imply or explicitly require later Node.js for smooth operation alongside specific JVM versions.

java-sdkrequiredThe core shadow-cljs compiler runs on the Java Virtual Machine. Java SDK 21+ (latest LTS recommended) is required for recent versions of shadow-cljs. This is a critical runtime dependency for the underlying Clojure tooling.

npm|bun|pnpm|yarnrequiredA JavaScript package manager is required to install and run the shadow-cljs npm package and manage JavaScript dependencies in your project.

Agent activity

4 hits · last 30 days

node

Resources

githubhttps://github.com/thheller/shadow-cljs ↗

packagehttps://www.npmjs.com/package/shadow-cljs ↗

homepagehttps://shadow-cljs.org ↗