Creating Externs

Why do we need externs?

When a ClojureScript project uses external JS libraries, the external references to those libraries will be munged when compiling in Advanced Optimizations mode. This is the result of the Google Closure compiler aggressively renaming all unexported symbols. details here

(CLJS code) -----------> (Closure-safe JS Code) ------------> (Optimized JS)
                 |                ^                   |
                CLJS              |         Google Closure Compiler
              Compiler            |            (Advanced Mode)
                                  | 
                                  |
                 Any external library symbols used here
                will be munged in the optimized JS unless
                  they are defined in an externs file.

Since the majority of Javascript libraries do not follow Google Closure's coding standards for advanced optimization, they cannot simply be fed into the Google Closure compiler. Thus, the compiler allows for an externs file describing which external symbols are not to be touched during optimization.

What are externs exactly?

An externs file is a normal Javascript file that only contains functions and variable declarations. Declared functions have empty bodies. Declared variables can be var statements without assignment, or a can be an object containing other variables and functions.

function hello() {}
var world;
var nested = {
   foo: {},
   bar: function() {}
};

The function and variable declarations can contain optional annotations in the form of JSDoc comment tags. This is mainly useful for us to tell Google Closure which functions are constructors for defining types, and if a variable is of a specific type.

/** @interface */
function Foo() {}
Foo.prototype.bar = function() {};

/** @type {!Foo} */
var foo;

Examples

• chance externs
• csv externs
• d3 externs
• firebase externs
• hammer externs
• jquery externs
• moment externs
• openlayers externs
• pikaday externs
• react externs

Extra Resources

• [Using Javascript libraries in ClojureScript](A thorough guide to ClojureScript compilation, include externs )
• Advanced Compilation and Externs
• Annotating Javascript for the Closure Compiler
• Externs for Common Libraries

Extern Generators

• Generator written in ClojureScript (recommended)
• Generate externs automatically

Open Questions

• How are some of the cljsjs package externs generated with so many annotations?
• Is there a way we can automate the testing externs to some extent?