Skip to content

Instantly share code, notes, and snippets.

@mikeball

mikeball/cljs-installation.md

Last active June 28, 2017 20:39
Show Gist options
  • Save mikeball/0b816d345e6cd966a10891c727eba695 to your computer and use it in GitHub Desktop.
Save mikeball/0b816d345e6cd966a10891c727eba695 to your computer and use it in GitHub Desktop.
Download ZIP
CLJS Installation
Raw
cljs-installation.md

CLJS Setup

This guide is intended to help you get started with CLJS.

An important note: CLJS is best experienced when developing and testing interactively against a live running instance of your application. In this way it's different than most other languages which use an edit/compile/restart method of working. While it is technically possible to use an edit/compile/restart workflow, if you use it with CLJS, you're gonna have a bad time.

Tools Installation

{Embedded Video of Tools Installation}

JVM is Required

Yes, our project is trying to remove and minimize use of the JVM in CLJS project, but for the time being it's what the majority of the toolset requires. Sorry about that, and really it's not that bad. Trust us it's worth it.

Please enter the following into your terminal to verify that you have java installed

java --version
=> ...

If you see a message saying something different, please use the instructions here to install before proceeding.

windows jvm install link macos jvm install link linux jvm install link

Install Leinigen

Leiningen helps with many tasks in CLJS such as creating new projects from templates, downloading dependancies and starting dev environments. It's quite similar to NPM/Yarn. (* We recommend you install directly rather than homebrew or packagemanager because they often don't have the most recent version available)

windows install instructions macos/linux install instuctions

After successful installation you should see something like this on the console

lein version
=> ...

A Quick Hello World

{Embedded Video of this Step}

lein new figwheel hello-cljs
cd hello-cljs
lein figwheel

This will download a bunch of a bunch of dependancies(only the first time), start a server and launch your browser.

Now Let's add a couple numbers

=> (+ 1 2)
3

Now let's log a message to the browser console. First open you're browsers dev tools console. Then in the console REPL, run the following code.

=> (js/log "hello cljs!")

And you should see the message show up in the browser console.

Now open the file hello-cljs/src/core.clj in your favorite editor.

And change xxx within th efile then save. You should see your changes immediately in the browser.

Now let's deliberately cause an error to see what an error message looks like. Edit the file and add an X before ??.

So this is what we mean by Interactive development. You make a change and it's immediately reflected in the application.

Next, let's package this hello world into a deployable html page and .js file. After this, please don't leave, and continue down this path a bit further and get an editor connected repl running in the following section.

Then in your console

# exit from the repl, if you haven't already
=> :cljs/exit

# build the deployable html and js files
lein release

you should then see to files in public/??

So, what is in that js file? It's your application, but it's also got a full set of immutable data structures and a huge number of library functions for you to use. The google closure compiler has removed any unused parts for you as well to keep the size as small as possible for fast page loads too.

We hope you're feeling great at this point. If not tell us why, we really do care about the new user experience. Heck if you feel like it, tell us what we've done good too please.

Now let's move on to Editor Intgration, which will make your daily work with CLJS even more of a breeze.

Editor Setup & Integration

Because CLJS is interactively developed, integration with your editor is REALLY important for a smooth everyday experience. Yes you can type and work with items on the console, but it's a simply magical experience to be able to execute code from your editor and see the result immediately.

At the moment, Atom is the most approachable editor that has solid support for this mode of working, and so this is our current suggested editor. Eventually we want to support VSCode too. (* If you're already comfortable with Intellij, you might look at Cursive, and if you're an emacs person you might look into cider)

Install Atom Editor

windows macos linux

Install Plugins that Allow CLJS Editor Integration

Open your Atom settings, then the install on left hand bar. Search for and install the following packages.

parinfer atom-ink protorepl

ParInfer helps keep code formatted. It's invaluable in keeping all brackets and parenthesis in the correct place, and it does it by using indent to infer what should be where. It gives us a very similar experience to python, with the benifit of showing the actual structure of the code.

AtomInk gives us a way to draw REPL results right beside your code.

ProtoREPL is what helps Atom talk to your application.

(* if you'd like to make atom even better, please see the additional instructions to do things like make parenthesis light grey, etc.. https://gist.github.com/jasongilman/d1f70507bed021b48625 )

Let's Connect Atom to our hello-cljs application

{Embedded Video of this Step} Similar: https://www.youtube.com/watch?v=0WMga5E7Vsk

Open the folder of the hello-cljs in Atom

Start your development server REPL.

; from within the hello-cljs application folder
lein figwheel

Let's now connect to the REPL

By default figwheel uses port 7002 to listen for REPL connections. You can see where this is set by looking in the project.clj file in the

Now use the Atom Command pallet(ctrl+shift+p) and search for "nrepl". You should see a result "Proto Repl: Remote Nrepl Connection", select it.

It will then prompt you for a port. Enter 7002.

ProtoREPL should then make the connection and open a connection in a new Atom tab, with some messages and place to type commands.

We still MUST enter a couple of additional magic commands that allow us to use CLJS in the repl. Please enter both of the commands below.

(use 'figwheel-sidecar.repl-api)

(cljs-repl)

Use the REPL in the Atom REPL Tab

(+ 1 2)
=> 3

And now to the browser console

=> (js/log "hello from atom tab!")

Use the REPL from directly within Atom

Please open file src/core.cljs and enter the following in the file.

(+ 1 2)

Place your cursor at the end of the line, and press <keys??> to send the code block to the REPL. You should see the result "3" at the end of your line in your editor.

Let's log to the browser console again as well, you should see a nil at the end of your line of source code file.

=> (js/log "hello from source file!")

You should see the message logged to the browser console.

If you'd like to improve your Atom experience even more to make parenthesis less prominent, setup your own keybindings to execute code, and other helpful items, please see out atom-setup.md for more details.

Success!

You're now officially part of CLJS!

Next Steps:

  • Join the community and ask questions in our forum or chat
  • walkthrough build of a console line application that runs on nodejs
  • walkthrough a reagent app to build a more full featured browser app
  • walkthrough build of a REST API
  • connect to a postgres database with a console app
  • etc...
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment