/README.md

  1# cljs-devmode
  2
  3A development mode for ClojureScript. It allows you to develop Clojure
  4web applications in combination with ClojureScript seamlessly. You can
  5develop your normal Clojure web application (with Ring and Compojure
  6for example) and whenever you change a ClojureScript source file it is
  7automatically recompiled and you can test the changes in your web
  8browser.
  9
 10## Usage
 11
 12Follow the [Quick Start
 13Guide](https://github.com/clojure/clojurescript/wiki/Quick-Start) of
 14ClojureScript (the bootstrap step is required)
 15
 16After bootstrapping ClojureScript get cljs-devmode:
 17      
 18    git clone git@github.com:maxweber/cljs-devmode.git
 19
 20In the cljs-devmode folder invoke:
 21
 22    lein cljs-devmode-bootstrap
 23
 24If you haven't set the $CLOJURESCRIPT_HOME environment variable yet,
 25then pass the full path to your ClojureScript installation as the
 26first command line argument.
 27
 28The cljs-devmode-bootstrap leiningen plugin copies all necessary jar
 29files into the lib folder of $CLOJURESCRIPT_HOME to make this
 30development mode work.
 31
 32### Start the ClojureScript compiler and cljs-devmode from the REPL
 33
 34To run the hello sample of ClojureScript in development mode do the
 35following:
 36
 37* Start the ./script/repl in the $CLOJURESCRIPT_HOME folder. 
 38* Then invoke this lines on the REPL:
 39
 40<pre>
 41    (require '[cljs.closure :as cljsc]) 
 42    (defn compile-fn []
 43          (cljsc/build "samples/hello/src" 
 44                       {:output-dir "samples/hello/out"
 45                        :output-to "samples/hello/hello.js"})) 
 46    (use 'cljs-devmode.core)
 47    (start-devmode "samples/hello" compile-fn)
 48</pre>
 49
 50* This brings up a Jetty server on port 9090, so open
 51  http://localhost:9090/hello-dev.html to see the hello sample of
 52  ClojureScript. On every request cljs-devmode checks, if any .cljs
 53  file inside samples/hello has changed. In the case of a change the
 54  above defined compile-fn is invoked. 
 55* So change the greeting message inside
 56  samples/hello/src/hello/core.cljs.
 57* When you refresh the http://localhost:9090/hello-dev.html you will
 58  see the new greeting message.
 59
 60### cljs-devmode supports to automate the above steps
 61
 62Take a look at the
 63[cljs-devmode-example](https://github.com/maxweber/cljs-devmode-example). In
 64the project folder of cljs-devmode-example you can invoke:
 65
 66    lein cljs-devmode
 67
 68This generates a cljs-devmode.sh file in the project folder. The
 69generated shell script starts the Clojure REPL in the
 70$CLOJURESCRIPT_HOME folder. Furthermore 'lein cljs-devmode' has also
 71generated a Clojure script, which is a string inside the shell script
 72and is passed to the Clojure REPL process for evaluation. This Clojure
 73script does the same as the script in the previous section. But the
 74paths are adapted to the current project folder (here the
 75cljs-devmode-example project). So if you execute the cljs-devmode.sh
 76script:
 77
 78    chmod 755 cljs-devmode.sh 
 79    ./cljs-devmode.sh
 80
 81Then the ClojureScript compiler and the cljs-devmode are started
 82automatically.
 83
 84The cljs-devmode-example also demonstrates how to use the
 85wrap-cljs-forward Ring middleware. This middleware takes care that all
 86request to /cljs/* (for example) are forwarded to localhost:9090,
 87where the cljs-devmode is running. So now you can develop your normal
 88Clojure web application and let ClojureScript do the JavaScript
 89part. Whenever you modify a .cljs file the whole ClojureScript project
 90is automatically recompiled and you can test the changes immediately
 91in your web browser.
 92
 93'lein cljs-devmode' has some defaults / conventions for the folder
 94structure of the project. But all defaults can be changed through a
 95:cljs-devmode entry in the project.clj. These would be the default
 96settings:
 97
 98    (defproject cljs-devmode-example
 99        ...
100        :cljs-devmode {:dir "PROJECT_HOME/cljs"
101                       :src-dir "PROJECT_HOME/cljs/src"
102                       :output-dir "PROJECT_HOME/cljs/out")
103                       :output-to "PROJECT_HOME/cljs/cljs-devmode-example.js")}
104
105You do not have to specifiy the :cljs-devmode entry inside your
106project.clj as long as the folder structure of your project follows
107the conventions. Take a look at the folder structure of the
108cljs-devmode-example. The whole ClojureScript project is in the cljs/
109subfolder. The ClojureScript project itself adheres to the folder
110structure of the ClojureScript samples. The :cljs-devmode entry can
111also be leveraged to pass additional parameters to the ClojureScript
112compiler. As you can see in the above example the :output-dir and
113:output-to entries are settings for the ClojureScript compiler, every
114additional map entry will also be passed to the ClojureScript compiler.
115
116
117## TODOs
118
119This is a really primitive prototype for a ClojureScript development
120mode. I only wrote it to get started with ClojureScript in one of my
121Clojure web applications. 
122There are many things which can be improved. For example the
123generation of the .sh shell script is a little bit nasty ;-) You can
124also let the JVM process of leiningen start the ClojureScript
125compiler and the devmode via:
126
127    lein cljs-devmode start
128
129But then you will not see the output (stdout and stderr) of the
130ClojureScript compiler and therefore you cannot read the helpful error
131messages of the ClojureScript compiler.  Nevertheless there is no
132automated way to do a switch to "production mode" yet (e.g. invoke the
133Google Closure Compiler in advanced mode and move the resulting js
134file to the public/cljs folder).
135
136## License
137
138Copyright (C) 2011 Maximilian Weber
139
140Distributed under the Eclipse Public License, the same as Clojure.