Edit: this is old and probably no longer accurate!

** This post has been revamped and added to the Elm website, you can read it here. **

In this post I will try to guide you through some first steps of writing Elm.

First, we'll talk about the installation process and the tools that come with it, but since Elm has a pretty good Online Editor you can definitely skip it for now.

After that we'll talk about actually learning how to write Elm programs. The Elm website has a lot of information in it and it's not always clear where to start, so this guide will try to put these heap of information into order.

Installation

First, visit the Install page on the elm site, download an installer for your platform and install Elm-platform, which will install the following tools:

  • elm
  • elm-package
  • elm-make
  • elm-repl
  • elm-reactor

Let's go over them one by one:

elm

elm is actually a way to run all other tools. Try opening a terminal and run elm to see the help message.

elm-package

elm-package is a package managing tool for elm, making it easy to install and publish packages to and from package.elm-lang.org.

When starting a new elm project, run:

elm package install

This will install the elm-core package and will create an elm project file: elm-package.json.

In elm-package.json we state information on the project, such as: the project name, author, license, dependencies, etc.

Interesting commands:

  • install: install dependencies in elm-package.json
  • publish: publish your library to package.elm-lang.org
  • bump: bump version numbers based on API changes
  • diff: get the difference between two APIs

elm-make

elm-make is used to compile elm code (file or project) into HTML or JavaScript.

When compiling a file (for example: Main.elm) into an HTML file (for example: index.html), you probably want to write something like this:

elm make Main.elm --output=index.html

Interesting flags:

  • --warn: Prints warnings to improve code quality

elm-repl

elm-repl is a Read-Evaluate-Print Loop tool for Elm. In it you can write elm expressions and evaluate them using Node.js. You can also import code and libraries, but for obvious reasons browser related stuff will not work.

Important commands:

  • :help: will print a help message
  • :quit: quit the repl

elm-reactor

elm-reactor is an interactive development tool for elm. With elm-reactor you can run elm code without using elm-make to compile them first, hot swapping and time travel debugging.

Running elm reactor will open a web server on 0.0.0.0:8000 where you can go to from any browser and select the file you want to run. If you want to use elm reactor's abilities, press the wrench next to the name of the file on the left. It will open the file with a column on the right where you can use those capabilities.

Important flags:

  • -a=ADDRESS: Change the address in which elm reactor runs. Since the default address, 0.0.0.0 is not supported on browser such as chrome and is broadcasting to anyone, I recommend always using -a=localhost
  • -p=PORT: Change the port in which elm reactor runs.

So for example, if you want to run the elm reactor, write:

elm reactor -a=localhost

Learning Elm

In the documentation page on the website, you can find a bunch of resources on elm.

For beginners, I recommend first starting with the Elm Complete Guide (link to part 1) and play with what you learn on the elm-repl or Online Editor. Writing Elm is essential to understanding it, and Elm Provides you the tools to easily do so.

After the Elm Complete Guide, you might want to read about Elm's Syntax and Style Guide. (an important thing to note is that there are constructs in Elm that are indentation sensitive.)

Checkout the many examples in the Examples page.

Read the Elm Architecture Tutorial.

You can also go over the cs223 Functional Programming course by the University of Chicago which has many good tutorials on elm and purely functional data structures, but bear in mind that the course uses Elm 0.14.1, which might be a little different. No worries! That's why you read the complete guide and the syntax guide.

Read more tutorials like Elm for the Frontend, Right Now, Checkboard Grid Tutorial and Building HTML by Parsing Parameters and others you can find on /r/elm and the mailing list.

But most importantly, don't forget to write code! Here are a few ideas for simple projects for you to get started:

  1. An elm program that writes Right or Left in the middle of the screen depending on whether the mouse cursor is on the left half of the screen or right half of the screen
  2. An elm program that displays dots randomly on the screen, with reset and pause/play buttons
  3. An elm program that displays the list of repositories of a github user entered on a text field
  4. Snake clone (extra: add highscore)

And, if you ever get stuck, try posting on the mailing list or come to #elm IRC channel on irc.freenode.net