2.2

Installation

Before we get started, we need to install and configure a few tools essential for learning Elm.

Installing Node.js

Node.js is a JavaScript runtime environment for building mostly server-side applications.

Why Node.js?
This book is all about learning a language for building client-side applications. So why do we need to install Node.js? We need it for two reasons:
  • elm-repl - a tool we will be using later to experiment with Elm - works by compiling the Elm code to JavaScript. Node.js provides an environment for running that JavaScript code.
  • Node.js comes with a package manager called NPM (Node.js Package Manager). Most tools and libraries for building front-end applications are distributed as NPM packages. We won’t be making a heavy use of NPM in this book, but you need it in your arsenal to be a productive Elm programmer.

Follow the instructions listed on the official site to install Node.js on your computer. Node.js comes with NPM. So you don’t need to download them separately. Once installed, run the following command from the terminal to verify that you have Node.js 4.0 or higher installed. It doesn’t matter which directory you run this command from.

node --version

Installing Elm Platform

The Elm Platform bundles together all the tools we need to work with Elm. Follow the instructions listed on the official site to install the Elm Platform on your computer. Once the installation is complete, run the following command from the terminal to verify that Elm is installed properly. It also doesn’t matter which directory you run this command from.

elm --version

You should see the version number of the Elm Platform installed on your computer. We will be using the 0.18.0 version throughout the book unless mentioned otherwise.

Source Code Editor

This book will make you write a lot of code. Some of that code will be executed inside the terminal using elm-repl. Some will have to be saved in a file and compiled. Elm doesn’t come with a source code editor. So you are free to choose whatever you like. Out of the box, most editors don’t support features such as syntax highlighting and autocompletion that will significantly enhance the experience of writing Elm code. You will have to install a plugin for that. Select a plugin for your editor from the Configure Your Editor section in the official guide.

Because tab characters are syntax errors in Elm, don’t forget to configure your editor to insert spaces when the tab key is pressed.

Installing elm-format

The Elm compiler will accept any valid program, but the Elm community at large prefers those programs to be written in a certain style. In most other languages, we need to remember what that style is and follow them diligently. Not only does this take up extra space in our brain, but also distracts us when we are in the middle of solving a problem. elm-format tackles this issue by automatically formatting our code according to a set of rules standardized by the community. Although you don’t have to install elm-format to follow along, I highly recommend that you do.

elm-format Release Status
As of this writing, elm-format is still in alpha. Don’t be surprised if the current format of your program looks different from the one 1.0.0 version of elm-format produces in the future. Despite its alpha status, most community members are already using it. So you should be fine using it too. All code in the book that is meant to be saved in a file has been formatted using elm-format.

Unlike the Elm Platform, elm-format doesn’t come with an installer. The elm-format team has indicated that a simple installation option will be available when a stable release is out. Until then, we need to do a little bit of extra work to get it running.

Step 1: From the installation section, download the version appropriate for your operating system and unzip it. You need the one that’s compatible with Elm 0.18.

Step 2: In order to be able to run elm-format from anywhere in the terminal and not just the download directory, we need to add its location to PATH.

PATH
PATH is an environment variable that specifies a set of directories in which executable programs are located. Once a program is added to the PATH variable, we can run that program from the terminal without typing the whole path to the file.

The best way for us to add elm-format to PATH is to copy it to the directory that contains the elm program. The Elm Platform installer puts the elm program file in a directory that’s already included in PATH. So copying elm-format to the same directory enables us to run it from anywhere in the terminal. On Unix you can print the full path of the elm program by running the following command:

which elm
/usr/local/bin/elm

On Windows, you can do the same by running this command: where elm.

Step 3: Let’s see elm-format in action. Create a new directory called beginning-elm. It doesn’t matter where you create this directory. Also create a file called TestElmFormat.elm inside that directory and add the following code to it.

module Main exposing (..)

import Html exposing (beginnerProgram, div, button, text)
import Html.Events exposing (onClick)


main =
  beginnerProgram {
    model = 0, view = view, update = update
  }

view model =
  div []
    [ button [onClick Decrement] [text "-"]
    , div [] [text (toString model)]
    , button [onClick Increment] [text "+"]
    ]

type Msg = Increment | Decrement
update msg model =
  case msg of
    Increment -> model + 1
    Decrement -> model - 1

Don’t worry about understanding the code above for now. You’ll be able to fully understand code that’s even more complex than this by the end of this book.

Although the code above is valid in Elm, it doesn’t quite follow the Elm style guide. Let’s use elm-format to fix that. Go to the beginning-elm directory in the terminal and run this command:

elm-format TestElmFormat.elm

You will see the following warning.

This will overwrite the following files to use Elm's preferred style:

    TestElmFormat.elm

This cannot be undone! Make sure to back up these files before proceeding.

Are you sure you want to overwrite these files with formatted versions? (y/n)

Answer y. Now if you look inside the TestElmFormat.elm file, you will notice that elm-format has nicely formatted the code inside that file as shown below.

module Main exposing (..)

import Html exposing (beginnerProgram, div, button, text)
import Html.Events exposing (onClick)


main =
    beginnerProgram
        { model = 0
        , view = view
        , update = update
        }


view model =
    div []
        [ button [ onClick Decrement ] [ text "-" ]
        , div [] [ text (toString model) ]
        , button [ onClick Increment ] [ text "+" ]
        ]


type Msg
    = Increment
    | Decrement


update msg model =
    case msg of
        Increment ->
            model + 1

        Decrement ->
            model - 1

If you want to bypass the warning, run elm-format with --yes flag.

elm-format TestElmFormat.elm --yes

We won’t be needing the TestElmFormat.elm file anymore. Go ahead and delete it, but keep the beginning-elm directory.

Step 4: Running elm-format from the terminal whenever we change an Elm file can be tedious. Therefore, most source code editors offer a plugin for automatically running it every time we save an Elm file. Install a plugin for your editor from the official site. Some plugins require you to manually turn on the format on save option. Make sure to read the instructions (listed on the official site) on how to do that as well.

Back to top

New chapters are coming soon!

Sign up for the Elm Programming newsletter to get notified!

* indicates required
Close