developers

Creating Your First Elm App: From Authentication to Calling an API (Part 1)

Explore building an app in the functional front-end language Elm. Part 1 focuses on Elm history, architecture, syntax, and calling an API.

Kim Maida

Group Manager, Developer Content

Aug 4, 2016 • 21 min read

Update:

This article and its supporting GitHub repos have been updated to Elm v0.18!

TL;DR: We can write statically typed, functional SPAs on the front end with Elm. Elm's compiler prevents runtime errors and compiles to JavaScript, making it an excellent choice for clean, speedy development. In part one of this tutorial, learn how to write your first Elm app and request data from an API. In part two, we'll add authentication using JSON Web Tokens. The full code is available at this GitHub repository.

All JavaScript app developers are likely familiar with this scenario: we implement logic, deploy our code, and then in QA (or worse, production) we encounter a runtime error! Maybe it was something we forgot to write a test for, or it's an obscure edge case we didn't foresee. Either way, when it comes to business logic in production code, we often spend post-launch with the vague threat of errors hanging over our heads.

Enter Elm: a functional front-end programming language that compiles to JavaScript, making it great for web applications that run in the browser. Elm's compiler presents us with friendly error messages before runtime, thereby eliminating runtime errors.

Why Elm?

Elm's creator Evan Czaplicki positions Elm with several strong concepts, but we'll touch on two in particular: gradual learning and usage-driven design. Gradual learning is the idea that we can be productive with the language before diving deep. As we use Elm, we are able to gradually learn via development and build up our skillset, but we are not hampered in the beginner stage by a high barrier to entry. Usage-driven design emphasizes starting with the minimum viable solution and iteratively building on it, but Evan points out that it's best to keep it simple, and the minimum viable solution is often enough by itself.

If we head over to the Elm site, we're greeted with an attractive featureset highlighting "No runtime exceptions", "Blazing fast rendering", and "Smooth JavaScript interop". But what does this boil down to when writing real code? Let's take a look.

Building an Elm Web App

In the first half of this two-part tutorial, we're going to build a small Elm application that will call an API to retrieve random Chuck Norris quotes. In doing so, we'll learn Elm basics like how to compose an app with a view and a model, how to update application state, and how to implement common real-world requirements like HTTP. In part two of the tutorial, we'll add the ability to register, log in, and access protected quotes with JSON Web Tokens.

If you're familiar with JavaScript but new to Elm the language might look a little strange at first--but once we start building, we'll learn how the Elm Architecture, types, and clean syntax can really streamline development. This tutorial is structured to help JavaScript developers get started with Elm without assuming previous experience with other functional or strongly typed languages.

Setup and Installation

The full source code for our finished app can be cloned on GitHub here.

We're going to use Gulp to build and serve our application locally and NodeJS to serve our API and install dependencies through the Node Package Manager (npm). If you don't already have Node and Gulp installed, please visit their respective websites and follow instructions for download and installation.

Note: Webpack is an alternative to Gulp. If you're interested in trying a customizable webpack build in the future for larger Elm projects, check out elm-webpack-loader.

We also need the API. Clone the NodeJS JWT Authentication sample API repository and follow the README to get it running.

Installing and Configuring Elm App

To install Elm globally, run the following command:

npm install -g elm

Once Elm is successfully installed, we need to set up our project's configuration. This is done with an 

elm-package.json
file:

// elm-package.json

{
    "version": "1.0.0",
    "summary": "Build an App in Elm with JWT Authentication and an API",
    "repository": "https://github.com/auth0-blog/elm-with-jwt-api.git",
    "license": "MIT",
    "source-directories": [
        "src",
        "dist"
    ],
    "exposed-modules": [],
    "dependencies": {
        "elm-lang/core": "5.1.1 <= v < 6.0.0",
        "elm-lang/html": "2.0.0 <= v < 3.0.0",
        "elm-lang/http": "1.0.0 <= v < 2.0.0",
        "rgrempel/elm-http-decorators": "2.0.0 <= v < 3.0.0"
    },
    "elm-version": "0.18.0 <= v < 0.19.0"
}

We'll be using Elm v0.18 in this tutorial. The 

elm-version
here is restricted to minor point releases of 0.18.

Now that we've declared our Elm dependencies, we can install them:

elm package install

Once everything has installed, an 

/elm-stuff
folder will live at the root of your project. This folder contains all of the Elm dependencies we specified in our 
elm-package.json
file.

Build Tools

Now we have Node, Gulp, Elm, and the API installed. Let's set up our build configuration. Create and populate a 

package.json
file, which should live at our project's root:

// package.json

...
  "dependencies": {},
  "devDependencies": {
    "gulp": "^3.9.0",
    "gulp-connect": "^4.0.0",
    "gulp-elm": "^0.6.1",
    "gulp-plumber": "^1.1.0",
    "gulp-util": "^3.0.7"
  }
...

Once the 

package.json
file is in place, install the Node dependencies:

npm install

Next, create a 

gulpfile.js
file:

// gulpfile.js

var gulp = require('gulp');
var elm = require('gulp-elm');
var gutil = require('gulp-util');
var plumber = require('gulp-plumber');
var connect = require('gulp-connect');

// File paths
var paths = {
  dest: 'dist',
  elm: 'src/*.elm',
  static: 'src/*.{html,css}'
};

// Init Elm
gulp.task('elm-init', elm.init);

// Compile Elm to HTML
gulp.task('elm', ['elm-init'], function(){
    return gulp.src(paths.elm)
        .pipe(plumber())
        .pipe(elm())
        .pipe(gulp.dest(paths.dest));
});

// Move static assets to dist
gulp.task('static', function() {
    return gulp.src(paths.static)
        .pipe(plumber())
        .pipe(gulp.dest(paths.dest));
});

// Watch for changes and compile
gulp.task('watch', function() {
    gulp.watch(paths.elm, ['elm']);
    gulp.watch(paths.static, ['static']);
});

// Local server
gulp.task('connect', function() {
    connect.server({
        root: 'dist',
        port: 3000
    });
});

// Main gulp tasks
gulp.task('build', ['elm', 'static']);
gulp.task('default', ['connect', 'build', 'watch']);

The default 

gulp
task will compile Elm, watch and copy files to a 
/dist
folder, and run a local server where we can view our application at http://localhost:3000.

Our development files should be located in a 

/src
folder. Please create the 
/dist
and 
/src
folders at the root of the project. Our file structure now looks like this:

Elm Application Structure

Syntax Highlighting

There's one more thing we should do before we start writing Elm, and that is to grab a plugin for our code editor to provide syntax highlighting and inline compile error messaging. There are plugins available for many popular editors. I like to use VS Code with vscode-elm, but you can download a plugin for your editor of choice here. With syntax highlighting installed, we're ready to begin coding our Elm app.

Chuck Norris Quoter App

We're going to build an app that does more than echo "Hello world". We're going to connect to an API to request and display data and in part two, we'll add registration, login, and make authenticated requests--but we'll start simple. First we'll display a button that appends a string to our model each time it's clicked.

Once we've got things running, our app should look like this:

elm quote

Let's fire up our Gulp task. This will start a local server and begin watching for file changes:

gulp

Note: Since Gulp is compiling Elm for us, if we have compile errors they will show up in the command prompt / terminal window. If you have one of the Elm plugins installed in your editor, they should also show up inline in your code.

HTML

We'll start by creating a basic 

index.html
file:

<!-- src/index.html -->
<!DOCTYPE html>
<html>
    <head>
        <meta charset="utf-8">
        <title>Chuck Norris Quoter</title>
        <script src="Main.js"></script>
        <link rel="stylesheet" href="https://maxcdn.bootstrapcdn.com/bootstrap/3.3.7/css/bootstrap.min.css">
        <link rel="stylesheet" href="styles.css">
    </head>
    <body>
    </body>
    <script>
        var app = Elm.Main.fullscreen();
    </script>
</html>

We're loading a JavaScript file called 

Main.js
. Elm compiles to JavaScript and this is the file that will be built from our compiled Elm code.

We'll also load the Bootstrap CSS and a local 

styles.css
file for a few helper overrides.

Finally we'll use JS to tell Elm to load our application. The Elm module we're going to export is called 

Main
(from 
Main.js
).

CSS

Next, let's create the 

styles.css
file:

/* src/styles.css */

.container {
    margin: 1em auto;
    max-width: 600px;
}
blockquote {
    margin: 1em 0;
}
.jumbotron {
    margin: 2em auto;
    max-width: 400px;
}
.jumbotron h2 {
    margin-top: 0;
}
.jumbotron .help-block {
    font-size: 14px;
}

Introduction to Elm

We're ready to start writing Elm. Create a file in the 

/src
folder called 
Main.elm
. The full code for this step is available in the source repository on GitHub:

src/Main.elm - Step 1: Introduction to Elm

Our file structure should now look like this:

file structure 2

If you're already familiar with Elm you can skip ahead. If Elm is brand new to you, keep reading: we'll introduce The Elm Architecture and Elm's language syntax by thoroughly breaking down this code. Make sure you have a good grasp of this section before moving on; the next sections will assume an understanding of the syntax and concepts.

import Html exposing (..)
import Html.Events exposing (..)
import Html.Attributes exposing (..)

At the top of our app file, we need to import dependencies. We expose the 

Html
package to the application for use. Because we'll be writing a view function, we will expose 
Html.Events
and 
Html.Attributes
to use click and input events, IDs, classes, and other element attributes.

Everything we're going to write is part of The Elm Architecture. In brief, this refers to the basic pattern of Elm application logic. It consists of 

Model
(application state), 
Update
(way to update the application state), and 
View
(render the application state as HTML). You can read more about The Elm Architecture in Elm's guide.

main : Program Never Model Msg
main =
    Html.program
        { init = init
        , update = update
        , subscriptions = \_ -> Sub.none
        , view = view
        }

main : Program Never Model Msg
is a type annotation. This annotation says "
main
has type 
Program
and should 
Never
expect a flags argument". If this doesn't make a ton of sense yet, hang tight—we'll be covering more type annotations throughout our app.

Every Elm project defines 

main
as a program. There are a few program candidates, including 
beginnerProgram
, 
program
, and 
programWithFlags
. Initially, we'll use 
main = Html.program
.

Next we'll start our app with a record that references an 

init
function, an 
update
function, and a 
view
function. We'll create these functions shortly.

subscriptions
may look strange at first. Subscriptions listen for external input and we won't be using any in the Chuck Norris Quoter so we don't need a named function here. Elm does not have a concept of 
null
or 
undefined
and it's expecting functions as values in this record. This is an anonymous function that declares there are no subscriptions.

Here's a breakdown of the syntax. 

\
begins an anonymous function. A backslash is used because it resembles a lambda (λ). 
_
represents an argument that is discarded. 
->
signifies the body of the function. 
subscriptions = \_ -> ...
in JS might look like either of these:

// JS
subscriptions = function() { ... }

subscriptions = function(anyArg) {
    // do nothing with anyArg
}

(What would an anonymous function requiring an argument look like? Answer: 

\x -> ...
)

Next up are the model type alias and the 

init
function:

{-
    MODEL
    * Model type
    * Initialize model with empty values
-}

type alias Model =
    { quote : String
    }

init : (Model, Cmd Msg)
init =
    ( Model "", Cmd.none )

The first block is a multi-line comment. A single-line comment is represented like this:

-- Single-line comment

A type alias is a definition for use in type annotations. In future type annotations, we can now say 

Something : Model
and 
Model
would be replaced by the contents of the type alias.

We expect a record with a property of 

quote
that has a string value. We've mentioned records a few times, so we'll expand on them briefly: records look similar to objects in JavaScript. However, records in Elm are immutable: they hold labeled data but do not have inheritance or methods. Elm's functional paradigm uses persistent data structures so "updating the model" returns a new model with only the changed data copied.

Now we've come to the 

init
function that we referenced in our 
main
program. The type annotation for 
init
means "
init
returns a tuple containing record defined in Model type alias and a command for an effect with an update message". That's a mouthful--and we'll be encountering additional type annotations that look similar but have more context, so they'll be easier to understand. What we should take away from this type annotation is that we're returning a tuple (an ordered list of values of potentially varying types). So for now, let's concentrate on the 
init
function.

Functions in Elm are defined with a name followed by a space and any arguments (separated by spaces), an 

=
, and the body of the function indented on a newline. There are no parentheses, braces, 
function
or 
return
keywords. This might feel sparse at first but hopefully you'll find the clean syntax speeds development.

Returning a tuple is the easiest way to get multiple results from a function. The first element in the tuple declares the initial values of the Model record. Strings are denoted with double quotes, so we're defining 

{ quote = "" }
on initialization. The second element is 
Cmd.none
because we're not sending a command (yet!).

{-
    UPDATE
    * Messages
    * Update case
-}


type Msg = GetQuote

update : Msg -> Model -> (Model, Cmd Msg)

update msg model =
    case msg of
        GetQuote ->
            ( { model | quote = model.quote ++ "A quote! " }, Cmd.none )

The next vital piece of the Elm Architecture is update. There are a few new things here.

First we have 

type Msg = GetQuote
: this is a union type. Union types provide a way to represent types that have unusual structures (they aren't 
String
, 
Bool
, 
Int
, etc). This says 
type Msg
could be any of the following values. Right now we only have 
GetQuote
but we'll add more later.

Now that we have a union type definition, we need a function that will handle this using a 

case
expression. We're calling this function 
update
because its purpose is to update the application state via the model.

The 

update
function has a type annotation that says "
update
takes a message as an argument and a model argument and returns a tuple containing a model and a command for an effect with an update message".

This is the first time we've seen 

->
in a type annotation. A series of items separated by 
->
represent argument types until the last one, which is the return type. The reason we don't use a different notation to indicate the return has to do with currying. In a nutshell, currying means if you don't pass all the arguments to a function, another function will be returned that accepts whatever arguments are still needed. You can learn more about currying elsewhere.

The 

update
function accepts two arguments: a message and a model. If the 
msg
is 
GetQuote
, we'll return a tuple that updates the 
quote
to append 
"A quote! "
to the existing value. The second element in the tuple is currently 
Cmd.none
. Later, we'll change this to execute the command to get a random quote from the API. The case expression models possible user interactions.

The syntax for updating properties of a record is:

{ recordName | property = updatedValue, property2 = updatedValue2 }

Elm uses 

=
to set values. Colons 
:
are reserved for type definitions. A 
:
means "has type" so if we were to use them here, we would get a compiler error.

We now have the logic in place for our application. How will we display the UI? We need to render a view:

{-
    VIEW
-}


view : Model -> Html Msg
view model =
    div [ class "container" ] [
        h2 [ class "text-center" ] [ text "Chuck Norris Quotes" ]
        , p [ class "text-center" ] [
            button [ class "btn btn-success", onClick GetQuote ] [ text "Grab a quote!" ]
        ]
        -- Blockquote with quote
        , blockquote [] [
            p [] [text model.quote]
        ]
    ]

The type annotation for the 

view
function reads, "
view
takes model as an argument and returns HTML with a message". We've seen 
Msg
a few places and now we've defined its union type. A command 
Cmd
is a request for an effect to take place outside of Elm. A message 
Msg
is a function that notifies the 
update
method that a command was completed. The view needs to return HTML with the message outcome to display the updated UI.

The 

view
function describes the rendered view based on the model. The code for 
view
resembles HTML but is actually composed of functions that correspond to virtual DOM nodes and pass lists as arguments. When the model is updated, the view function executes again. The previous virtual DOM is diffed against the next and the minimal set of updates necessary are run.

The structure of the functions somewhat resembles HTML, so it's pretty intuitive to write. The first list argument passed to each node function contains attribute functions with arguments. The second list contains the contents of the element. For example:

button [ class "btn btn-success", onClick GetQuote ] [ text "Grab a quote!" ]

This 

button
's first argument is the attribute list. The first item in that list is the 
class
function accepting the string of classes. The second item is an 
onClick
function with 
GetQuote
. The next list argument is the contents of the button. We'll give the 
text
function an argument of "Grab a quote!".

Last, we want to display the quote text. We'll do this with a 

blockquote
and 
p
, passing 
model.quote
to the paragraph's 
text
function.

We now have all the pieces in place for the first phase of our app! We can view it at http://localhost:3000. Try clicking the "Grab a quote!" button a few times.

Note: If the app didn't compile, Elm provides compiler errors for humans in the console and in your editor if you're using an Elm plugin. Elm will not compile if there are errors! This is to avoid runtime exceptions.

That was a lot of detail, but now we're set on basic syntax and structure. We'll move on to build the features of our Chuck Norris Quoter app.

Calling the API

Now we're ready to fill in some of the blanks we left earlier. In several places we claimed in our type annotations that a command 

Cmd
should be returned, but we returned 
Cmd.none
instead. Now we'll replace those with the missing command.

When this step is done, our application should look like this:

elm quote

Clicking the button will call the API to get and display random Chuck Norris quotes. Make sure you have the API running at http://localhost:3001 so it's accessible to our app.

Once we're successfully getting quotes, our source code will look like this:

src/Main.elm - Step 2: Calling an API

The first thing we need to do is import the dependency necessary for making HTTP requests:

import Http

We'll need Http to make requests and handle responses.

Next we'll update our 

init
function:

init : (Model, Cmd Msg)
init =
    ( Model "", fetchRandomQuoteCmd )

Now instead of 

Cmd.none
we have a command called 
fetchRandomQuoteCmd
. A command is a way to tell Elm to do some effect (like HTTP). We're commanding the application to fetch a random quote from the API on initialization. We'll define the 
fetchRandomQuoteCmd
function shortly.

{-
   UPDATE
   * API routes
   * GET
   * Messages
   * Update case
-}
-- API request URLs


api : String
api =
    "http://localhost:3001/"


randomQuoteUrl : String
randomQuoteUrl =
    api ++ "api/random-quote"



-- GET a random quote (unauthenticated)


fetchRandomQuote : Http.Request String
fetchRandomQuote =
    Http.getString randomQuoteUrl


fetchRandomQuoteCmd : Cmd Msg
fetchRandomQuoteCmd =
    Http.send FetchRandomQuoteCompleted fetchRandomQuote


fetchRandomQuoteCompleted : Model -> Result Http.Error String -> ( Model, Cmd Msg )
fetchRandomQuoteCompleted model result =
    case result of
        Ok newQuote ->
            ( { model | quote = newQuote }, Cmd.none )

        Err _ ->
            ( model, Cmd.none )

We've added some code to our update section. First we'll store the API routes.

The Chuck Norris API returns unauthenticated random quotes as strings, not JSON. Let's create a function called 

fetchRandomQuote
. We can use the 
Http.getString
 method to make the HTTP request with the API route as an argument.

HTTP is something that happens outside of Elm. A command is needed to request the effect and a message is needed to notify the update that the effect was completed and to deliver its results.

We'll do this in 

fetchRandomQuoteCmd
. This function's type annotation declares that it returns a command with a message. 
Http.send
 is a command that sends a request.

We then need to respond to the completed request with a message that handles successes and errors: 

FetchRandomQuoteCompleted
. If the request returns 
Ok
, we'll set the 
quote
in the model with the string that is returned. In the case of an error (
Err
), we aren't going to do anything special. For the sake of brevity, we'll handle API errors when we get to authentication but not for getting unauthenticated quotes. Since we're discarding this argument, we can pass a discarded argument 
_
. This will return a tuple that sends the model in its current state and no command. You may want to handle errors here on your own after completing the provided code.

Let's add 

FetchRandomQuoteCompleted
to our messages and update:

-- Messages


type Msg
    = GetQuote
    | FetchRandomQuoteCompleted (Result Http.Error String)  



-- Update

update : Msg -> Model -> ( Model, Cmd Msg )
update msg model =
    case msg of
        GetQuote ->
            ( model, fetchRandomQuoteCmd )

        FetchRandomQuoteCompleted result ->
            fetchRandomQuoteCompleted model result

We add these two new messages to the 

Msg
union type and annotate the types of their arguments. 
FetchRandomQuoteCompleted
accepts a result with an 
Http.Error
 or the new Chuck Norris quote string from the API. These are the possible fail / success results of the HTTP request.

Next we add this case to the 

update
function and declare what we want returned in the 
(Model, Cmd Msg)
tuple. We also need to update the 
GetQuote
tuple to fetch a quote from the API. We'll change 
GetQuote
to return the current model and issue the command to fetch a random quote, 
fetchRandomQuoteCmd
.

FetchRandomQuoteCompleted
's argument is the response result. We use this to update the model in our 
Ok
case.

It's important to remember that the 

update
function's type is 
Msg -> Model -> (Model, Cmd Msg)
. This means that all branches of the 
case
statement must return the same type. If any branch does not return a tuple with a model and a command, a compiler error will occur.

Nothing changes in the 

view
. We altered the 
GetQuote
onClick function logic, but everything that we've written in the HTML works fine with our updated code. This concludes our basic API integration for the first half of this tutorial. Try it out! In part two, we'll tackle adding users and authentication.

Aside: Reading Compiler Type Errors

If you've been following along and writing your own code, you may have encountered Elm's compiler errors. Though they are very readable, type mismatch messages can sometimes seem ambiguous.

Here's a small breakdown of some things you may see:

String -> a

A lowercase variable 

a
means "anything could go here". The above means "takes a string as an argument and returns anything".

[1, 2, 3]
has a type of 
List number
: a list that only contains numbers. 
[]
is type 
List a
: Elm infers that this is a list that could contain anything.

Elm always infers types. If we've declared type definitions, Elm checks its inferences against our definitions. We'll define types upfront in most places in our app. It's best practice to define the types at the top-level at a minimum. If Elm finds a type mismatch, it will tell us what type it has inferred. Resolving type mismatches can be one of the larger challenges to developers coming from a loosely typed language like JS (without Typescript), so it's worth spending time getting comfortable with this.

Recap and Next Steps

We've covered installing and using the Elm language and learned how to create our first app. We've also integrated with an external API through HTTP. You should now be familiar with Elm's basic syntax, type annotation, and compiler errors. If you'd like, take a little more time to familiarize with Elm's documentation. The Elm FAQ is another great resource from the Elm developer community. In the second half of this tutorial: Creating your First Elm App - Part 2, we'll take a deeper dive into authenticating our Chuck Norris Quoter app using an access token.