Undefined Rants

Code, Ramen and Avocado

Let's Elm - Setting Up Everything

In this post, I will walk you through the step from 0 to display “Hello, Elm” in your browser. We will also discover some tools in Elm ecosystem which make our development with Elm becomes easy and fun.

Note: The easiest way to try out elm is through the online repl – http://elm-lang.org/try. This is a good place to paste examples from official documentation and play with it.

Setting up Elm

First of all you can download an installer based on your OS from the official installation guide. Or easier, we can install by using npm.

1
npm -g install elm

After finished installing, you should be able to type the elm command.

1
2
3
4
5
6
7
8
9
❯ elm                                                     
Elm Platform 0.16.0 - a way to run all Elm tools
Available commands include:

make      Compile an Elm file or project into JS or HTML
package   Manage packages from <http://package.elm-lang.org>
reactor   Develop with compile-on-refresh and time-travel debugging
repl      A REPL for running individual expressions
// skip for brevity

Congrats, now Elm is successfully installed. We will go through each command carefully.

Let’s kickstart of an Elm project. Our first project will be getting some HTML display on browser.

Install dependencies

1
2
3
4
5
6
❯ mkdir learn-elm && cd learn-elm
❯ elm package install
...
Do you approve of this plan? (y/n) y
Downloading elm-lang/core
Packages configured successfully!

Let’s see what it gives us:

1
2
❯ ls                                                      
elm-package.json elm-stuff

So the important thing here is the elm-package.json. Here is where we declare all our dependencies. We can ignore elm-stuff right now.

To display something on browser using Elm we will need to add elm-html package.

1
❯ elm package install evancz/elm-html

Elm will ask you politely whether to add dependency to elm-package.json and upgrade plan. We just need to answer yes by typing y.

1
2
3
4
5
6
7
8
To install evancz/elm-html I would like to add the following dependency to elm-package.json:

"evancz/elm-html": "4.0.2 <= v < 5.0.0"

May I add that to elm-package.json for you? (y/n) y
...
Do you approve of this plan? (y/n) y
...

So if you open elm-package.json you will notice our new package is added to the dependencies field.

Create your Main.elm

Let’s create a new Main.elm file in our project directory.

1
2
3
4
5
6
module Main where

import Html

main =
    Html.text "Hello, Elm"

Let’s go through line by line. Firstly, we define our module name – Main and the keyword where is to tell Elm that this is a module.

In the next line, we import the module from elm-html dependency which we just installed.

To be more explicit what we want to expose from a specific module, we can use the keyword exposing. The following code produce the same result.

1
2
3
4
5
...
import Html exposing (text)

main =
    text "Hello, Elm"

Finally we have our main function. This is the place where elm program starts from. Currently we just tell it to print out “Hello, Elm”. Let’s try to display this on browser.

Compile into JavaScript

Because we want to display it on the browser and browser can’t talk to Elm directly so we need to compile Elm into the language which browser can understand. Here is where the command elm make comes into play. Let’s compile our module into a file name index.html.

1
2
3
4
 elm make Main.elm --output index.html
Success! Compiled 37 modules.
Successfully generated index.html
 open index.html

If you are using window open might not work for you. In this case just drag the index.html into browser to see the result.

Congrats, now you’re an Elm programmer.

Embedding into HTML

We can generate a new html page by using elm make Main.elm --output index.html but in real life, we probably want to include a lot of thing in our index.html. For eg: bootstrap(duh) and google analytics script. So it’s a good idea to generate a js file and embed it into HTML.

1
2
3
elm  elm make Main.elm --output main.js
Success! Compiled 1 modules.
Successfully generated main.js

Here we compile our elm module to a javascript file named main.js. We need a html !!! Let’s create a new html file name main.html. We will also include the generate main.js file using the script tag.

1
2
3
4
5
6
7
8
9
10
<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
</head>
<body>
  <div id="app"><!-- we will embed our Elm app here --></div>
  <script src="main.js"></script>
</body>
</html>

However if you open this in browser you will see nothing. This is because we haven’t tell Elm where to render our module. To do that let’s add another script under the main.js:

1
2
3
4
<script>
    var node = document.getElementById('app');
    var app = Elm.embed(Elm.Main, node);
</script>

Because we named our module as Main so when we render our view using “Elm.Main”. Our final html looks like this.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
<html lang="en">
<head>
  <meta charset="UTF-8">
  <title></title>
</head>
<body>
  <div id="app"></div>
  <script src="main.js"></script>
  <script>
    var node = document.getElementById('app');
    var app = Elm.embed(Elm.Main, node);
  </script>
</body>
</html>

We now know how to embed Elm application into html template but it’s quite troublesome to type the command elm make everytime we make a change during development.

Elm reactor

As you realize, the compilation time was quite long. In development we need faster cycle. Let’s meet the Elm reactor.

1
2
3
❯ elm-reactor
elm reactor 0.16.0
Listening on http://0.0.0.0:8000/

Point your browser to localhost:8000 and you will see a list contains all our files.

Click Main.elm under Elm Files directory, and you will see our app. Now all the changes we made will be recompiled automatically. Make a change, refresh the browser and mind blown.

To stop the elm-reactor, press ctrl + c.

By default elm-reactor run on localhost:8000. We can also specify address and port by running:

1
elm-reactor -a=localhost -p=4040

REPL (Read-Eval-Print-Loop)

Finally we can play with repl by typing elm-repl. This is particurly useful when you want to try out some core function or in offline mode. Let’s try out a few function:

1
2
3
4
5
❯ elm-repl
 > max 1 100
 > 100 : number
 > > sqrt 100
 > 10 : Float

Type :exit to stop the repl.

Conclusion

Let’s see what we had learned * install Elm in our own machine, install packages using elm-package install command * by utilizing elm-make, we can also generate a single JavaScript module to embed it into any part of html by using Elm.embed * elm-reactor let you see changes quickly. It is very handy in development * to test our elm quickly, we just need to elm-repl

Comments