NOTE: work in progress

ClojureScript starter tool

A tool to answer the following questions:

• What would a great first run of ClojureScript look like?
• How do we create that in the clearest and cheapest way possible?
• Should it do everything?

Install

This installs the cljs command:

$ npm install -g cljs

* cljs is the abbreviation for ClojureScript

Basics

Using Lumo, fast experimenting is the default experience. Try the most basic things as fast as possible.

• REPL

  $ cljs
  
  cljs.user=> (+ 1 2 3)
  6

• Run script

  ;; my_file.cljs
  (println (+ 1 2 3))

  $ cljs my_file.cljs
  6

Use dependencies

You can pull in external libraries by specifying them in a plain config file, cljs.edn. Dependencies are automatically downloaded when running any cljs command or explicitly with cljs install.

• Dependencies

  ;; cljs.edn
  {:dependencies
   [[markdown-clj "0.9.94"]]}

  $ cljs
  
  cljs.user=> (require '[markdown.core :refer [md->html]])
  cljs.user=> (md->html "## Hello World")
  "<h2>Hello World</h2>"

• In Script

  ;; my_file.cljs
  (require '[markdown.core :refer [md->html]])
  
  (println (md->html "## Hello World"))

  $ cljs my_file.cljs
  <h2>Hello World</h2>

Use Namespaces

If you create a build name that points to a source directory, you can start organizing files into canonical namespaces.

• Specify src directory

  ;; cljs.edn
  {:dependencies [...]
   :builds {:main {:src "src"}}} ;; <-- Source at "src" directory,
                                 ;;     or use ["src" ...] for multiple.
                                 ;;     (:main can be any name for the build)

• Use namespaces

  ;; src/example/core.cljs
  (ns example.core)
  
  (defn hello []
    (println "Hello World"))

  $ cljs
  
  cljs.user=> (require 'example.core)
  cljs.user=> (in-ns 'example.core)
  example.core=> (hello)
  Hello World

Compile to JavaScript

To run your ClojureScript code without the cljs command, you can compile it to a JavaScript output file for use in a browser or elsewhere. Specify extra config for compiler:

• Compiler config

  ;; cljs.edn
  {:cljs-version "1.9.456"  ;; <-- compiler version
   :dependencies [...]
   :builds {:main {:src "src"
                   :compiler {:output-to "main.js"}}}} ;; <-- compiler options

• Build or watch (using the production JVM compiler)

• Pretty errors (borrowed from Figwheel)

  ;; modify src/example/core.cljs
  (ns example.core)
  
  (defn hello)  ;; <-- make an incomplete function

  Compiling src/foo/core.cljs
  ----  Could not Analyze  src/foo/core.cljs   line:3  column:1  ----
  
    Parameter declaration missing
  
    1  (ns example.core)
    2
    3  (defn hello)
       ^--- Parameter declaration missing
  
  ----  Analysis Error : Please see src/foo/core.cljs  ----

Develop for the web

Using Figwheel, you can compile your project with a much more fluid and interactive developer experience. You get a browser-connected REPL, hot-loading of files as they change, and an in-page status display.

• Figwheel config

  ;; cljs.edn
  {:cljs-version "1.9.456"
   :dependencies [...]
   :figwheel {...} ;; <-- optional server-level config
   :builds {:main {:src "src"
                   :figwheel ... ;; <-- optional build-level config
                   :compiler {...}}}}

• Run Figwheel

  $ cljs figwheel main

Try the example provided in this repo:

$ cljs figwheel example

cljs.user=>

Open public/index.html, then modify src-example/example/core.cljs to see status messages on your page:

Customize build scripts

For direct access to the ClojureScript compiler API, run with a Clojure file (.clj not .cljs).
Your Clojure program will be given access to the compiler API and your config in a *cljs-config* var.

• Custom Build

  ;; build.clj
  (require '[cljs.build.api :as b]) ;; <-- official cljs compiler api
  
  (let [{:keys [src compiler]} (-> *cljs-config* :builds :main)]
    (b/build src compiler))

• Run

  $ cljs build.clj