{"id":14004,"library":"shadow-cljs","title":"shadow-cljs","description":"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.","status":"active","version":"3.4.4","language":"javascript","source_language":"en","source_url":"https://github.com/thheller/shadow-cljs","tags":["javascript","clojurescript","cljs"],"install":[{"cmd":"npm install shadow-cljs","lang":"bash","label":"npm"},{"cmd":"yarn add shadow-cljs","lang":"bash","label":"yarn"},{"cmd":"pnpm add shadow-cljs","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Runtime 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.","package":"node","optional":false},{"reason":"The 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.","package":"java-sdk","optional":false},{"reason":"A JavaScript package manager is required to install and run the shadow-cljs npm package and manage JavaScript dependencies in your project.","package":"npm|bun|pnpm|yarn","optional":false}],"imports":[{"note":"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.","wrong":"import shadowCljs from 'shadow-cljs'","symbol":"shadow-cljs (CLI)","correct":"npx shadow-cljs <command>"},{"note":"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.","symbol":"Programmatic API (Clojure)","correct":"(shadow.cljs.devtools.api/compile :app)"}],"quickstart":{"code":"npx create-cljs-project my-app\ncd my-app\n\n# --- shadow-cljs.edn content (create this file) ---\n# {:source-paths [\"src/main\"]\n#  :dependencies []\n#  :builds {:app {:target :browser\n#                 :output-dir \"resources/public/js\"\n#                 :asset-path \"/js\"\n#                 :modules {:app {:init-fn my-app.core/init!}}\n#                 :compiler-options {:optimizations :simple}}}}\n# -----------------------------------------------------\n\n# --- src/main/my_app/core.cljs content (create this file) ---\n# (ns my-app.core\n#   (:require [reagent.core :as r]))\n#\n# (defn hello-world []\n#   [:div \"Hello from ClojureScript!\"])\n#\n# (defn init! []\n#   (r/render [hello-world] (js/document.getElementById \"app\")))\n# -----------------------------------------------------------------\n\n# Add 'dev' and 'release' scripts to your package.json:\n# \"scripts\": {\n#   \"dev\": \"shadow-cljs watch app\",\n#   \"release\": \"shadow-cljs release app\"\n# }\n\n# Install React and ReactDOM as npm dependencies (common for Reagent projects)\nnpm install react react-dom\n\n# Start the development watcher and built-in HTTP server\nnpm run dev\n\n# Once compiled, access your app at http://localhost:8020/ (default shadow-cljs dev server port).\n# Remember to create a public/index.html file to load your compiled JavaScript.","lang":"typescript","description":"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."},"warnings":[{"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.","message":"Version 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.","severity":"breaking","affected_versions":">=3.0.0"},{"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.","message":"Dependency 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.","severity":"gotcha","affected_versions":">=2.x"},{"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.","message":"As 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.","severity":"breaking","affected_versions":">=3.4.1"},{"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.","message":"When 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.","severity":"gotcha","affected_versions":">=2.x"},{"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.","message":"Google 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.","severity":"gotcha","affected_versions":">=2.x"}],"env_vars":null,"search_vec":"'3.4.4':64 'abstract':95 'activ':79 'address':71 'away':96 'broader':42 'browser':53 'bug':72 'build':50,110 'bundler':14 'chrome':57 'cljs':3,6,135 'clojurescript':10,21,34,131,134 'compil':11,27 'complex':97 'comprehens':9 'configur':98 'contrast':118 'css':36 'current':60 'cycl':83 'default':93 'depend':117 'develop':18,82,103,107 'differenti':86 'e.g':52 'ecosystem':44 'ensur':77 'experi':104 'extens':58 'fast':25 'featur':76 'figwheel':123 'figwheel-main':122 'focus':89 'frequent':69 'heavili':114 'high':101 'hot':30 'hot-reload':29 'includ':45 'increment':26 'integr':39 'introduc':74 'javascript':13,43,133 'key':85 'like':121 'main':124 'minor':75 'nativ':56 'node.js':54 'npm':46,116 'occur':68 'offer':24,99 'often':127 'optim':102 'packag':47 'particular':111 'point':66 'prefer':128 'project':22,113,132 'provid':91 'pure':130 'react':55 'releas':67,109 'reload':31 'respons':81 'robust':28 'seamless':38 'sensibl':92 'shadow':2,5 'shadow-clj':1,4 'simplifi':16 'stabl':61 'target':51 'tool':120 'util':115 'various':49 'version':62 'workflow':19","created_at":"2026-04-20T01:57:26.275131+00:00","updated_at":"2026-04-20T01:57:26.275131+00:00","problems":[{"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.","cause":"Google Closure Compiler (used by shadow-cljs) does not yet support a specific modern JavaScript syntax feature present in an npm dependency.","error":"Errors encountered while trying to parse file ... {'}' expected}"},{"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.","cause":"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.","error":"shadow-cljs - Stale Output! Your loaded JS was not produced by the running shadow-cljs instance. Is the watch for this build running?"},{"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>`.","cause":"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).","error":"No application has connected to the REPL server. Make sure your JS environment has loaded your compiled ClojureScript code."},{"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.","cause":"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.","error":"Failed to load Clojure or ClojureScript artifacts, potentially due to dependency conflicts or an incorrect classpath."}],"ecosystem":"npm","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":"shadow-cljs","cli_version":null,"type":"library","homepage":"https://shadow-cljs.org","github":"https://github.com/thheller/shadow-cljs","docs":null,"changelog":null,"pypi":null,"npm":"https://www.npmjs.com/package/shadow-cljs","openapi_spec":null,"status_page":null,"smithery":null,"categories":["web-framework","devops"],"base_url":null,"auth_type":null,"provenance":{"verified_status":null,"verified_at":null,"last_verified":"2026-06-17","next_check":"2026-07-18","install_tag":null}}