ClojureScript: Quick Start

Build a simple ClojureScript project.

Source

• GitHub

Dependencies

Required

• Clojure

1. Create project structure

1.1. The project structure

NOTE

• quick-start/ is the project directory
  • not used used in any parts of the project
  • only used to contain project directories and files
• deps.edn is the configuration file
  • used to configure project dependencies
  • think of it as package.json but using Clojure instead of JSON
• src/ is the default root classpath to interop with Java
• quick_start/ is a namespace
  • namespace file names must be separated with an underscore
  • namespace directories are converted to packages in Java
• core is a Clojure convention to represent the main file
  • think of it as index.js used as project entry point
  • it is discouraged to use single segment namespaces

1.2. Create project directories and files

2. Install ClojureScript compiler

2.1. Edit deps.edn

NOTE

• ClojureScript compiler is a Clojure library
• Being a Clojure library, it also means that it is a JAR file
• Library version must be set explicitly
• Keys and versions can be determined at either GitHub or Maven repos
• An example of a valid library key is org.clojure/clojurescript (Maven)
• Clojure-specific JARs can also be found at Clojars

2.2. Install dependencies

IMPORTANT

It is possible to use JavaScript libraries directly within in ClojureScript with CLJSJS but that is not the recommended approach these days since versions tend to get out of date fast and can end up using similar packages with different versions that will lead to a much bigger build size. To solve these problems, use a build tool like shadow-cljs.

NOTE

• clj is a shorthand for clojure
  • it is a runner to open the Clojure compiler
  • it installs dependencies (if there are any)
  • press ctrl+c, ctrl+d or ctrl+z to exit
  • or enter (System/exit 0) or (. System exit 0) to exit
• To remove all JARs, delete then re-create ~/.m2 directory
• To re-install dependencies, delete the .cpcache directory then re-run clj

3. Write, compile and run

3.1. Edit core.cljs

NOTE

• A namespace on top of file is required to locate the namespace
• A namespace should match the exact namespace directory structure
• Use dashes to separate namespace names in ClojureScript code
• Use underscores to separate namespace directory and file segment names
• js/ is a special namespace that directly passes the variable after it

3.2. Compile and run

NOTE

• -m (or --main) calls the specified namespace (a function)
• cljs.main enable launching ClojureScript programs with java command
• -c (or --compile) compiles the specified ClojureScript namespace
  • it is one of cljs.main options
  • its compiled files are written to out/ directory
• -r (or --repl) opens the REPL after compilation
  • it is also one of cljs.main options
  • it opens the built-in browser-connected REPL
  • it also automatically opens the default web browser
• -c and -r options must be included last as options
• By default, compiled files are written to out/ directory
• By default, the bundled JavaScript code is written to out/main.js
• Press ctrl+shift+i to open web browser's inspector to view Console tab
• You should see hello, world in the web browser's Console tab

4. The REPL

4.1. Develop with REPL

NOTE

You should see hi in the web browser's Console tab.

4.2. Update the REPL

NOTE

You should see 3 in the web browser's Console tab.

5. Compile and build

NOTE

• -O is a shorthand for --optimizations
  • It sets the optimization level that Google Closure will use
  • It only works with with -c option
  • It should be included before -c option
  • Valid values are none, whitespace, simple and advanced
    • whitespace only removes whitespaces (no variable shortening)
    • simple removes whitespaces and also shortens variable names
    • Use none during development
    • Use advanced for production build
• The build file (a.k.a. bundle) is generated as out/main.js

6. Built-in web server

NOTE

• -s is a shorthand for --serve
  • It runs a web server on current directory
  • It uses its own index.html if no index.html exists
  • It does not automatically open a web browser
  • Visit served resource at localhost:9000

7. Run on Node.js

IMPORTANT

This requires npm.

7.1. Compile

NOTE

• -t is a shorthand for --target
  • It is used to target a JavaScript environment
• -o is a shorthand for --output-to
  • It is to specify the compiled file destination
• There is no reason to use Google Closure when targeting Node.js

7.2. Run

NOTE

You should see hello, world in the terminal.

7.3. REPL

NOTE

• re is a shorthand for --repl-env
  • It is used to target the REPL environment

References

• Quick Start