icmconsulting / lein-cljs-externs

Leiningen plugin to generate JS extern files (from metadata)

lein-cljs-externs

A Leiningen plugin for generating simple JS extern files from metadata within the source.

Objectives

So, you've decided that you want to compile your clojurescript using :advanced optimizations. Good for you! If you're using a third party JS library, you're going to want to include some externs in that compilation. You could try a few things:

1. Hope that there are premade ones, maybe you'll look in the Closure project: (https://github.com/google/closure-compiler/tree/master/contrib/externs)
2. You couldn't find a premade extern file for that library? Maybe you'll decide to try your luck with just including the JS file as the extern itself.
3. When that doesn't work, most of the time, you could try generating one: (http://www.dotnetwise.com/Code/Externs/)
4. Still not working? Why don't you try handcoding one?.....

And that's where the lein-cljs-externs plugin will help. Instead of handcoding an extern file, and only remembering to update it at the last minute, you can add metadata throughout your cljs source, and have the cljs-externs task build the externs file for you before running the cljsbuild task.

Usage

1. Put

into the :plugins vector of your project.clj.

2. Add the following to the cljsbuild build map in your project.clj

:cljsbuild {:builds
...
  [{:id "prod"
    :source-paths ["src/cljs"]

    :extern-gen {:output-to "resources/externs/three.generated.js"}

  :compiler {:output-dir "resources/public/js/cljs-out-prod"
  :output-to  "resources/public/js/compiled.prod.js"
  :optimizations :advanced
  :pretty-print false
  :externs ["react/externs/react.js"
            "resources/externs/jquery-1.9.js"
            "resources/externs/three.generated.js"]}}]

3. Before running the cljsbuild task, run $ lein cljs-externs [build-id] where [build-id] = the cljsbuild build id (prod in the above example)

Well, that did nothing - it just generated an empty file. The plugin isn't magic - you need to add some metadata to your cljs source to tell it what javascript references you need extern'ed.

4. Add a metadata map in the functions that use the third party JS libraries, with an :extern key. For example:

(defn plane-geometry
  "Create PlaneGeometry"
  ^{:externs [THREE.PlaneGeometry]} ;; Add just the 'type' THREE.PlaneGeometry
  [width height]
  (THREE.PlaneGeometry. width height))

(defn rotate-y
  "Rotate mesh on its Y axis in DEGREES"
  ^{:externs [[THREE.Mesh rotation] [THREE.Euler y x]]} ;; Add two types, THREE.Mesh (and its function 'rotation'),
  ;; and the THREE.Euler (and its property 'y')
  [mesh degrees]
  (set! (.. mesh -rotation -y)
        (util/to-radians degrees))
  (set! (.. mesh -rotation -x)
        (util/to-radians degrees)))

In reality, you can add the extern metadata to any form that can accept metadata (except ns, as the clojure reader still rips out metadata from this form) and the cljs-externs task will find it and add it to the generated file.

Generated file

At the moment, the cljs-externs task will generate a file in a format that looks not too dissimilar to the following:

/* Generated by cljs-externs leiningen plugin */

var THREE = {"ShaderMaterial":{},"PlaneGeometry":{},"Euler":{"z":{},"y":{},"set":{},"x":{}},  ...

This "JSONy" format will work with the advanced Closure optimisations most of the time. If you require type information, let me know and we can work something out.

License

Copyright © 2014 ICM Consulting Pty Ltd (http://www.icm-consulting.com.au)

Distributed under the Eclipse Public License either version 1.0 or (at your option) any later version.