Compiler Options


Entries

:main - option

Specifies an entry point namespace. Behavior depends on :optimizations:

  • :simple,:advanced - only namespaces reachable from main are built
  • :none - all namespaces are built, but the :output-to file will be generated such that main is executed for the appropriate :target (browser or Node).
:main "foo.bar"

:modules - option

Employ code-splitting to replace the usual :output-to file with separate logical modules. Every namespace is assigned to exactly one logical module. Code-motion will enable code to be pulled across module boundaries when possible, but this is avoided if the compiler knows it will already be included on the page:

  • :output-to - output file of a module
  • :entries - namespaces to include (modules must have no entries in common)
  • :depends-on - modules expected to be included on the page beforehand
:modules
{:foo {:output-to "js/foo.js" :entries #{"my.foo"}}
 :bar {:output-to "js/bar.js" :entries #{"my.bar"} :depends-on #{:foo}}
 :baz {:output-to "js/baz.js" :entries #{"my.baz"} :depends-on #{:bar}}

 :cljs-base ;; <-- leftover namespaces are placed here for you
 {:output-to "js/cljs_base.js"}} ;; <-- specify to change base output

Preloads

:preloads - option

A list of namespaces to load before :main, allowing you to preload extra code for specific builds. For example, a development build can use it to setup logging or connecting REPLs. Only applies when :optimizations is :none.

:preloads '[foo.dev]

:browser-repl - option

Preload code necessary for connecting to the natively supported browser REPL. Defaults to false.

:browser-repl true

Output

:output-to - option

The path to the JavaScript file that will be output.

:output-to "resources/public/js/main.js"

:output-dir - option

Sets the output directory for temporary files used during compilation. Defaults to "out".

:output-dir "resources/public/js/out"

:asset-path - option

A path to :output-dir relative to your web server's root, if not already specified as such. Only required when :optimizations is :none and :main is set, because the generated :output-to file will then need to load other parts of the build at runtime.

:output-to "resources/public/main.js"
:output-dir "resources/public/js/compiled/out"
:asset-path "js/compiled/out" ;; <--- relative URL of output-dir

:fingerprint - option

Append content SHA to output file names. A manifest.edn file is emitted to :output-dir for mapping to fingerprinted filenames. Defaults to false.

:fingerprint true

Output formatting

:output-wrapper - option

Wrap the JavaScript output in an IIFE (function(){…​};)() to avoid clobbering globals. Defaults to false.

:output-wrapper true

:preamble - option

Prepends the contents of the given files to each output file. Only valid with :optimizations other than :none. Defaults to empty.

:preamble ["license.js"]

:pretty-print - option

Determines if the JavaScript output will be formatted to be human-readable. Only applies if :optimizations are enabled. Defaults to false.

:pretty-print true

Delimit sections of the compiled JavaScript file with // Input %d comment lines to help denote which code belongs to which input file. Defaults to false.

:print-input-delimiter true

Optimization

:optimizations - option

The compiler will produce JS based on the optimization level:

  • :none - multiple unminified files (fastest for development).
  • :whitespace - single file w/ comments and whitespace removed
  • :simple - single file w/ whitespace optimizations + minified local var names
  • :advanced - single file w/ aggressive renaming, dead code removal, and inlining
:optimizations :none     ;; <-- recommended for development
:optimizations :advanced ;; <-- recommended for production
:optimizations :simple   ;; <-- recommended for Node

:optimize-constants - option

Build a constant table to prevent duplicate allocation of keywords and symbols. Defaults to true for advanced :optimizations, otherwise false.

:optimize-constants true

:static-fns - option

Controls how multi-arity function calls are generated. A "static" call means the dispatch to the appropriate arity is handled at compile time (better performance), whereas a "dynamic" call means the dispatch is handled at run time (allows safer redefinition in REPL). Static is enabled by default in advanced :optimizations.

:static-fns true

:fn-invoke-direct - option

Requires :static-fns true. This option emits slightly different code that can speed up your code around 10-30%. Higher order function that don’t implement the IFn protocol are normally called with f.call(null, arg0, arg1 ...). With this option enabled the compiler calls them with a faster f(arg0, arg1 ...) instead.

:fn-invoke-direct true

Source map

:source-map - option

To help debugging at runtime, creates a standard source map JSON file used by Node and browsers to map compiled JS lines to their original CLJS files. Use a string path if there is a single output file expected, otherwise use true to auto-assign source map filenames.

:source-map "out/main.js.map"
:source-map true ;; <-- use if `:optimizations :none`, or any `:modules`

:source-map-asset-path - option

A compiled JS file can contain a sourceMappingURL comment, which cljs uses to locate the :source-map JSON file. You can prepend this location with a custom path if required by your web server configuration.

:source-map-asset-path "..."  ;; <-- custom server path of source map metadata

:source-map-path - option

Source maps associate compiled JS lines to their original CLJS files. Use this option if you configured your web server to host these original CLJS files at a custom path. If present, it is prepended to all sources inside the :source-map file.

:source-map-path "..."  ;; <-- custom server path of original CLJS files

:source-map-timestamp - option

Add cache busting timestamps to source map urls. This is helpful for keeping source maps up to date when live reloading code.

:source-map-timestamp true

Translation

:language-in - option

Set the input language for Google Closure Compiler.

:language-in :ecmascript6 ;; default

:language-out - option

Set the output language for Google Closure Compiler.

:language-out :no-transpile ;; default

:rewrite-polyfills - option

Rewrite any ES6+ feature usage with Closure Library's polyfills. :language-in must be at least :es6. Defaults to false.

:rewrite-polyfills true

Libs

:libs - option

Paths to JavaScript libraries that you wish to include in the build. Libs must be proper Google Closure namespaces, else use :foreign-libs or :npm-deps.

:libs ["src/js"                      ;; <-- all files in directory
       "src/org/example/example.js"] ;; <-- single file

:foreign-libs - option

Allows you to include and convert JavaScript libraries that are not proper Google Closure namespaces—if they are, use :libs instead. For an easier way to include libraries from npm use :npm-deps.

:foreign-libs
[{:file "local/file.js"         ;; file path or URL
  :provides ["my.example"]      ;; assign a fake namespace

  ;; optional keys
  :file-min "local/file.min.js" ;; used for :advanced optimizations
  :module-type ...              ;; :commonjs, :amd, or :es6
  :requires ["foo.bar"]         ;; inferred if :module-type supplied
  :preprocess ...}]             ;; custom preprocessor (e.g. JSX)

:npm-deps - option

Include libraries from npm. This experimental feature downloads the dependencies from npm and generates a :foreign-libs entry for each.

:npm-deps {:react "15.4.2"
           :lodash "4.17.4"}

:install-deps - option

:package-json-resolution - option

:deps-cmd - option

Node.js

:target - option

Determines the target environment the compiled code is expected to run on. Use :nodejs for Node.js. If no target is specified, the browser environment is assumed.

:target :nodejs  ;; <-- use when targeting Node.js

:hashbang - option

When using :target :nodejs the compiler will emit a shebang as the first line of the compiled source, making it executable. When your intention is to build a node.js module, instead of executable, use this option to remove the shebang.

:hashbang "/usr/bin/env node" ;; <-- default
:hashbang false               ;; <-- disable

:nodejs-rt - option

Externs

:externs - option

Files declaring JavaScript symbols that should not be munged under advanced :optimizations.

:externs ["react-externs.js"
          "jquery-externs.js"]

:infer-externs - option

A helpful facility for generating :externs whenever a . form is used on a type-hinted symbol ^js/Foo.Bar x. Enable *warn-on-infer* to be warned of failed inferences. Successful inferences are written to inferred_externs.js in :output-dir.

:infer-externs true

:use-only-custom-externs - option

Use only the custom externs specified in :externs, without including the default externs for the browser environment. Defaults to false.

:use-only-custom-externs true

Names

:rename-prefix - option

:rename-prefix-namespace - option

:pseudo-names - option

Allows you to retain var names similar to their original when compiling advanced :optimizations. Enable this along with :pretty-print if you wish to read the advanced output for debugging purposes.

:pseudo-names true

:stable-names - option

:anon-fn-naming-policy - option

Determines how Closure Compiler assigns names to anonymous functions in assignments and declarations. Defaults to :off.

  • :off - unnamed
  • :unmapped - named based on left-hand of assignment (after possible renaming)
  • :mapped - short unique name generated and mapped to left-hand of assignment
:anon-fn-naming-policy :unmapped ;; <-- assign names to anon functions

Cache analysis

:cache-analysis - option

Cache compiler analysis to disk to enable faster cold build and REPL startup times. Defaults to true in REPL and when :optimizations is disabled. Each CLJS file is cached to :output-dir with analysis formatted by :cache-analysis-format.

  • foo.cljs - copied source
  • foo.cljs.cache.json - analysis in transit format, or
  • foo.cljs.cache.edn - analysis in edn format
:cache-analysis true

:cache-analysis-format - option

Set the output format of the analysis cache if :cache-analysis is enabled. Defaults to transit json.

                                 ;; for foo.cljs
:cache-analysis-format :transit  ;; <-- foo.cljs.cache.json (default)
:cache-analysis-format :edn      ;; <-- foo.cljs.cache.edn

Warnings

:warnings - option

Enable all or specific compiler warnings. See full details for all warning options. Defaults to true.

:warnings true                  ;; enable all (default)
:warnings {:fn-deprecated true} ;; enable specific warnings

:warning-handlers - option

A list of functions that are called when a compiler warning occurs. Defaults to a single function which prints to stderr.

:warning-handlers [...]

:closure-warnings - option

Control specific warnings generated by the Closure compiler. Each warning must map to either :error, :warning, or :off.

:closure-warnings {:externs-validation :off}

:checked-arrays - option

Elide

:elide-asserts - option

Remove all assert calls during compilation, including :pre and :post condition checks for functions. Useful for production. Defaults to false, even in advanced mode.

:elide-asserts true

:elide-strict - option

Closure

:closure-defines - option

Assign goog-define vars with compile-time constants. Vars must be specified as a namespace-qualified symbol, and their values must be a string, number, or a boolean.

:closure-defines {my.core/foo "new-value"}

This will result in the following var being replaced:

(ns my.core)

(goog-define foo "default-value") ;; <-- replaced with "new-value"
(println foo) ;; <-- prints "new-value"

:closure-extra-annotations - option

Suppress warnings about JSDoc Tags unrecognized by Closure (like @api) that your project or other dependent libraries may be using.

:closure-extra-annotations #{"api" ...}

:closure-generate-exports - option

If you are using a Closure-compatible JS library that uses @export JSDoc tags, you will need to enable this option so the appropriate goog.export() calls are generated to allow their usage.

:closure-generate-exports true

:closure-module-roots - option

Set the root locations to search for CommonJS modules. Used by the Closure Compiler to find and process modules imported via require(). Defaults to [].

:closure-module-roots [...]

:closure-output-charset - option

:closure-property-map-in - option

:closure-property-map-out - option

:closure-variable-map-in - option

:closure-variable-map-out - option

Spec

:spec-skip-macros - option

Skip spec checks against macro forms. Defaults to false.

:spec-skip-macros true

Report

:verbose - option

Show the steps the compiler is taking to create the build.

:verbose true

:compiler-stats - option

Report basic timing measurements on compiler activity. Defaults to false.

:compiler-stats true

Watch

:watch-fn - option

Function called after a successful build (from cljs.build.api/watch).

:watch-fn (fn [] (println "Build succeeded."))

:watch-error-fn - option

Function called after a failed build (from cljs.build.api/watch). Receives the exception object as its first arg.

:watch-error-fn (fn [e] (print-my-error e))

Bootstrap

:dump-core - option

Dump the analysis cache of cljs.core into the output file, allowing you to evaluate basic ClojureScript code at runtime using cljs.js/eval-str without extra setup. Defaults to false.

:dump-core true

Uncategorized

:aot-cache - option

:bundle-cmd - option

:ignore-js-module-exts - option

:opts-cache - option

:parallel-build - option

Compile sources in parallel, utilizing multiple cores. Defaults to false.

:parallel-build true

:process-shim - option

:recompile-dependents - option

For correctness, this defaults to true in order to recompile dependent namespaces when a parent namespace changes. This prevents corrupted builds and swallowed warnings. However, this can impact compile times depending on the structure of the application.

:recompile-dependents false

:target-fn - option