ClojureScript - Compiler Options (original) (raw)

:anon-fn-naming-policy

Strategies for how the Google Closure compiler does naming of anonymous functions that occur as r-values in assignments and variable declarations. Defaults to :off.

:anon-fn-naming-policy :unmapped

The following values are supported:

:aot-cache

Defaults to true if ClojureScript is being used via cljs.main, and falseotherwise or if ClojureScript is being used as agit dep. Controls whether the shared AOT cache is used for compiler artifacts produced from JARs.

:browser-repl

Automatically inject components required by the standard browser REPL. When launching the browser REPL this default to true.

:cache-analysis

Experimental. Cache compiler analysis to disk. This enables faster cold build and REPL start up times.

For REPLs, defaults to true. Otherwise, defaults to true if and only if :optimizations is :none.

:closure-defines

Set the values of Closure libraries' variables annotated with@defineor with the cljs.core/goog-define helper macro. A common usage is setting goog.DEBUG to false:

:closure-defines {"goog.DEBUG" false}

You can also use symbols:

:closure-defines {my.cool-ns/some-def true}

Note when using Lein the quote is unnecessary due to implicit quoting.

| | For :optimizations :none, a :main option must be specified for defines to work, and only goog-define defines are affected.:closure-defines currently does not have any effect with:optimizations :whitespace. | | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

You can use the variables set in :closure-defines to eliminate parts of your code at compile time (DCE). However, to do so you must use ifor cond in combination with an identical? comparison. Any other forms (such as case or condp) will work correctly at runtime, but the javascript output will contain the dead code branches.

For example, if you want to make a localized build of your application which only contains the translation messages relevant for the locale:

(def messages
  (cond
    (identical? js/goog.LOCALE "nl") i18n.nl/messages
    (identical? js/goog.LOCALE "fr") i18n.fr/messages
    :else i18n.en/messages))

Define extra JSDoc annotations that a closure library might use so that they don’t trigger compiler warnings.

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

:closure-output-charset

Configure the output character set. May be:

Defaults to utf-8

:closure-output-charset "iso-8859-1"

:closure-warnings

Configure warnings generated by the Closure compiler. A map from Closure warning to configuration value, only :error, :warning and :off are supported.

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

The following Closure warning options are exposed to ClojureScript:

:access-controls
:analyzer-checks
:check-regexp
:check-types
:check-useless-code
:check-variables
:closure-dep-method-usage-checks
:conformance-violations
:const
:constant-property
:debugger-statement-present
:deprecated
:deprecated-annotations
:duplicate-message
:duplicate-vars
:es5-strict
:externs-validation
:extra-require
:function-params
:global-this
:invalid-casts
:j2cl-checks
:jsdoc-missing-type
:late-provide
:lint-checks
:message-descriptions
:misplaced-msg-annotation
:misplaced-type-annotation
:missing-getcssname
:missing-override
:missing-polyfill
:missing-properties
:missing-provide
:missing-require
:missing-return
:missing-sources-warnings
:module-load
:msg-conventions
:non-standard-jsdoc
:report-unknown-types
:strict-missing-properties
:strict-missing-require
:strict-module-dep-check
:strict-requires
:suspicious-code
:too-many-type-params
:tweaks
:type-invalidation
:undefined-variables
:underscore
:unknown-defines
:unnecessary-escape
:unused-local-variable
:unused-private-property
:use-of-goog-base
:violated-module-dep
:visiblity

:compiler-stats

Report basic timing measurements on compiler activity.

Defaults to false.

:deps-cmd

Set the command to install node_modules. Only "npm" and "yarn" supported.

:elide-asserts

This flag will cause all (assert x ) calls to be removed during compilation, including implicit asserts associated with :pre and:post conditions. Useful for production. Default is always false even in advanced compilation. Does NOT specify goog.asserts.ENABLE_ASSERTS, which is different and used by the Closure library.

| | Note that, with JVM ClojureScript, it is not possible to dynamically set*assert* to false at runtime; this compiler flag must explicitly be used to effect the elision. With self-hosted ClojureScript, on the other hand, setting *assert* will cause asserts to be elided as in Clojure. | | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

:elide-strict

Whether to elide use strict statements in JavaScript output. Defaults to true.

:fingerprint

Defaults to false. Whether to enable fingerprinting, which will append a content SHA to output file names. An manifest.edn is generated to:output-dir for mapping fingerprinted file names. This is especially useful when using :modules and :source-map options, as the fingerprinted file names will be appropriately referenced.

:fn-invoke-direct

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.

| | The :fn-invoke-direct feature is in alpha status. For some libraries such as Reagent, :fn-invoke-direct is known to generate incorrect code. | | ----------------------------------------------------------------------------------------------------------------------------------------------- |

:hashbang

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.

:infer-externs

Enables automatically generating externs for interop calls to JavaScript. Defaults to false. For more info seeExterns (Alpha)

:language-in and :language-out

Configure the input and output languages for the closure library. May be:

:language-in defaults to :ecmascript5 :language-out defaults to :no-transpile

:language-in  :ecmascript5
:language-out :no-transpile

:libs

Adds dependencies on external js libraries, i.e. Google Closure-compatible javascript files with correct goog.provides() andgoog.requires() calls. Note that files in these directories will be watched and a rebuild will occur if they are modified.

Paths or filenames can be given. Relative paths are relative to the current working directory (usually project root).

Defaults to the empty vector []

:libs ["closure/library/third_party/closure"
       "src/js"
       "src/org/example/example.js"]

:nodejs-rt

Flag to disable Node.js runtime support. Useful when not targeting Node.js but rather targeting JavaScript tools which understand Node.js style requireconventions

:optimize-constants

When set to true, constants, such as keywords and symbols, will only be created once and will be written to a separate file (cljs/core/constants.js). The compiler will emit a reference to the constant as defined in the constants table instead of creating a new object for it. This option is mainly intended to be used for a release build since it can increase performance due to decreased allocation. Defaults totrue under :advanced optimizations otherwise to false.

:output-wrapper

Wrap the Javascript output to avoid clobbering globals. There are four possible value types:

  1. Function - Takes one argument, the compiled javascript output. Should return some other valid javascript output. For the simplest case, just string concatenate the javascript output with something akin to #3 (the default wrapper)
  2. String - Some format interpolation compatible string. For example,"(function(){%s};)()". format receives the compiled javascript output as the second argument and nothing else.
  3. Truthy - Wrap with the default (function(){…​};)()
  4. Falsey - Don’t wrap. This is the default.
;; function
(fn [js-output]
  (str "(function(){" js-output "};).call(window);"))

;; string
"(function(){%s};).call(window);"

;; truthy
true

;; falsey
false

:package-json-resolution

Configures which package.json entries (e.g. "browser", "module" or "main") are used in which order when resolving dependencies on (and between) NPM packages.

Defaults to

Can also take a custom vector of entries such as ["browser", "main"].

:parallel-build

When set to true, compile source in parallel, utilizing multiple cores.

:preamble

Prepends the contents of the given files to each output file. Files should reside on the classpath. Only valid with optimizations other than :none.

Defaults to the empty vector []

Determines whether comments will be output in the JavaScript that can be used to determine the original source of the compiled code.

Defaults to false.

:print-input-delimiter false

:process-shim

Defaults to

Automatically provide a shim for Node.js process.envcontaining a single Google Closure define, NODE_ENV with "development"as the default value. In production NODE_ENV will be set to "production". If set to false all of the stated behavior is disabled.

:pseudo-names

With :advanced mode optimizations, determines whether readable names are emitted. This can be useful when debugging issues in the optimized JavaScript and can aid in finding missing externs. Defaults to false.

:recompile-dependents

For correctness the ClojureScript compiler now always recompiles 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. This option defaults to true.

:recompile-dependents false

:rename-prefix

Specifies a prefix that will be prepended to all variables. Can be used whenCode Splitting to prevent interference with other code in JavaScript’s global scope.

:rewrite-polyfills

If set to true, the google closure compiler will add polyfills (for example when you use native javascript Promise).This requires :language-in to be set to :es6 or higher or it will silently be ignored!

:language-in  :es6
:rewrite-polyfills true

:source-map-asset-path

Provides fine grained control over the sourceMappingURL comment that is appended to generated JavaScript files when source mapping is enabled.

:source-map-path

Set the path to source files references in source maps to avoid further web server configuration.

:source-map-path "public/js"

This option affects the sources entry of the emitted source map V3 JSON file.

:source-map-asset-path "http://foo.com/public/js/out"

:source-map-timestamp

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

:spec-skip-macros

Whether to disable spec macro checking. Defaults to false.

:static-fns

Employs static dispatch to specific function arities in emitted JavaScript, as opposed to making use of the call construct. Defaults to false except under advanced optimizations. Useful to have set to false at REPL development to facilitate function redefinition, and useful to set to true for release for performance.

This setting does not apply to the standard library, which is always compiled with :static-fns implicitly set to true.

| | To enable static dispatch for calls to declared functions, supply :arglistsmeta. For example, if (declare foo) preceeds (foo 1 2), dynamic dispatch will be employed. If instead (declare ^{:arglists '([x y])} foo) preceeds(foo 1 2), static dispatch will be employed if :static-fns is enabled. | | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

:target-fn

Set an arbitrary Clojure function to generate the development main entry point JavaScript file. Must be a symbol representing a Clojure function that exists in a namespace on the classpath. Only used under :optimization :none.

:target-fn 'some.custom.dev-bootstrap

:warnings

This flag will turn on/off compiler warnings for references to undeclared vars, wrong function call arities, etc. Can be a boolean for enabling/disabling common warnings, or a map of specific warning keys with associated booleans. Defaults to true.

:warnings true
;; OR
:warnings {:fn-deprecated false} ;; suppress this warning

The following warnings are supported:

:watch-fn

Is a function that will be called after a successful build.

Only available for cljs.build.api/watch

:watch-fn (fn [] (println "Updated build"))

:warning-handlers

Set a vector of handlers to customize handling of emitted warnings. A handler should be either a symbol (to be resolved as a function) or a function. The signature of each function is [warn-type env warn-info].warn-type is a keyword describing the warning,env is the analysis environment, and warn-info is a map of extra useful information for a particular warning type.

Defaults to:

:warning-handlers [cljs.analyzer/default-warning-handler]