common cljs build format ideas

An_Explanation.md

A common build configuration format that all ClojureScript tools can consume

cljsbuilds1.edn

; A common shared Clojurescript build configuration file that can
; handle build tool specific concerns on a per build basis.

; in cljs-builds.edn
{ 
  ; id is a common concern among all tools
  :dev {
        ; source-paths is common concern among all tools
        :source-paths ["src" "dev"]
        
        ; build tool "build" specific concern
        :figwheel { :on-jsload 'example.core/reload }
        
        ; build tool "build" specific concern
        :cljbuild { :notify-command ["growl" "-f"] }
        
        :compiler { :output-to "example.js" 
                    :optimizations :none
                    ... }}}

; Question: should it be standard require eval on read?

; global build tool concerns (like server-port) can be implemented as a build tool desires...
; but it would be cool say if figwheel had a figwheel.edn and cljsbuild read a cljsbuild.edn 
; and doo had a doo.edn

; The figwheel.edn file could look as so

{:dev {:server-port 5000}
 :prod false}

; Edn files would allow folks to trivially read configuration in from scripts

cljsbuilds2.edn

; another approach would be to have a gereral build config that doesn't have any 
; build tool specific information in it
; I think I like this better

;cljs-builds.edn
; don't include any build tool specific information in this config
{:dev {:source-paths ["src" "dev"]
       :compiler { :output-to "example.js" 
                   :optimizations :none
                   ... }}}
                   
; in the project.clj the above could be entered like this
:cljs-builds { :dev {...}
               :prod {...}}

; The above has some real advantages.  We can write one library to read validate and thoroughly document this
; general configuration format. And then leave the tool specific validation to the individual tools.

; We then place "build" specific information in the build tool configuration wherever that may be

; figwheel.edn or in project.clj depending on mode of tool
{ :server-port 4555
  :builds {:dev {:on-jsload 'example.core/reload}} }

;this is cleaner but maybe less clear when someone is trying to understand the config

; in a project.clj the above could be entered under the :figwheel key like so
:figwheel { :server-port 4555 
            :builds {} }

Either of the above look fine to me. I like the separation—I think the initial implementation of CLJS-1492 was too aggressive and started triggering on build-tool specific config appearing in :compiler.

With respect to read eval and/or a validation lib—keep portability in mind (Planck could use such a lib if it is ClojureScript-compatible—it doesn't have Clojure available).

Even though Planck isn't a build tool, per se, some of the Planck knobs are build-related (source paths, whether to use :static-fns, :foreign-libs config), and some of the knobs are essentially imitations of standard REPL config items (:repl-verbose, etc.), and some of the other stuff is just Planck startup options (a lot of which actually mirror things that you can do with the Clojure REPL, including things like configuring Socket REPL). The long and short of this, in my opinion, is that Planck following whatever standard we come up with makes complete sense, even if Planck isn't truly 100% build tool. (In fact, Planck has bent over backwards to try to minimize differences from existing prior standards in our tooling community like implementing support for the JVM classpath, even though Planck has no JVM in sight—it just makes things easier for humans, and also enables things like

planck -c `lein classpath`

In other words, I think standardizing on common configuration where possible between all of these tools is pretty important, especially given how complex the ClojureScript tooling story currently is.

Obvious downside is that we are changing things up on folks, yet again. But if we could rally around one central build config in one place I think the change would be worth it especially if we can share read and validation.