Home

Welcome to the shadow-build wiki!

shadow-build uses the normal CLJS analyzer & compiler under the hood but has some significant differences in how it all comes together and interfaces with the Closure Compiler.

It is very opinionated on certain aspects of a "build" which I'll highlight first, since you won't have much fun with it if these don't work for you.

• Builds intended for the browser each need one directory. That directory should not contain any files not generated by shadow-build, neither should it contain sub-directories. You should be ready to rm -rf that-dir at any time, although you should not need to. The directory is required because most CLJS builds will typically emit more than one file (eg. source-maps, compiled files, source files). Specifying a path for each file is tedious and error-prone.

• Each "build" is composed of one or more modules. Each module is produces one javascript file. It is recommended to start with one module (ie. one .js file to include) and eventually split into multiple modules as your project grows.

• Each "module" has one or more "entry" namespaces. These namespaces either contain (defn ^:export a-fn [...] ...) functions or code that just executes when loading the file. You generally use these namespaces to interface with HTML. A module may depend on zero or more other modules. Each namespace can only be in ONE module, it will automatically be moved to the correct one in the dependency graph if multiple modules require it.

CLJS things that shadow-build does not support

Pretty much only because they are alpha and I have some doubts that they will reliably work on non-toy projects.

• :infer-externs
• cljs.closure/js-transforms + npm support

Differences to CLJS

• CLJS currently still allows to build without an "entry point" (ie. everything in one directory). That is not possible with shadow-build, you need at least one entry point so we can figure out which files to load.
• Closure Modules work in :none (and any other :optimizations).
• Full Closure JS support. Just put it side by side with your .cljs and it just works. No :libs required.
• shadow-build overall is much stricter than CLJS. Several things that are allowed/ignored in CLJS will cause warnings or errors. I consider these things bugs so I fixed them, some have pending CLJS JIRA issues. If you see warnings that you didn't see before that is why.