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// 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-versionNow that we've declared our Elm dependencies, we can install them:
elm package install
Once everything has installed, an
/elm-stuffelm-package.jsonBuild Tools
Now we have Node, Gulp, Elm, and the API installed. Let's set up our build configuration. Create and populate a
package.json// 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.jsonnpm install
Next, create a
gulpfile.js// 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/distOur development files should be located in a
/src/dist/src
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:
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<!-- 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.jsWe'll also load the Bootstrap CSS and a local
styles.cssFinally we'll use JS to tell Elm to load our application. The Elm module we're going to export is called
MainMain.jsCSS
Next, let's create the
styles.css/* 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
/srcMain.elmsrc/Main.elm - Step 1: Introduction to Elm
Our file structure should now look like this:
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
HtmlHtml.EventsHtml.AttributesEverything 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
ModelUpdateViewmain : Program Never Model Msg main = Html.program { init = init , update = update , subscriptions = \_ -> Sub.none , view = view }
main : Program Never Model MsgmainProgramNeverEvery Elm project defines
mainbeginnerProgramprogramprogramWithFlagsmain = Html.programNext we'll start our app with a record that references an
initupdateviewsubscriptionsnullundefinedHere's a breakdown of the syntax.
\_->subscriptions = \_ -> ...// 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{- 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 : ModelModelWe expect a record with a property of
quoteNow we've come to the
initmaininitinitinitFunctions in Elm are defined with a name followed by a space and any arguments (separated by spaces), an
=functionreturnReturning 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 = "" }Cmd.none{- 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 = GetQuoteStringBoolInttype MsgGetQuoteNow that we have a union type definition, we need a function that will handle this using a
caseupdateThe
updateupdateThis is the first time we've seen
->->The
updatemsgGetQuotequote"A quote! "Cmd.noneThe syntax for updating properties of a record is:
{ recordName | property = updatedValue, property2 = updatedValue2 }
Elm uses
=::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
viewviewMsgCmdMsgupdateThe
viewviewThe 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
buttonclassonClickGetQuotetextLast, we want to display the quote text. We'll do this with a
blockquotepmodel.quotetextWe 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
CmdCmd.noneWhen this step is done, our application should look like this:
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
initinit : (Model, Cmd Msg) init = ( Model "", fetchRandomQuoteCmd )
Now instead of
Cmd.nonefetchRandomQuoteCmdfetchRandomQuoteCmd{- 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
fetchRandomQuoteHttp.getStringHTTP 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
fetchRandomQuoteCmdHttp.sendWe then need to respond to the completed request with a message that handles successes and errors:
FetchRandomQuoteCompletedOkquoteErr_Let's add
FetchRandomQuoteCompleted-- 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
MsgFetchRandomQuoteCompletedHttp.ErrorNext we add this case to the
update(Model, Cmd Msg)GetQuoteGetQuotefetchRandomQuoteCmdFetchRandomQuoteCompletedOkIt's important to remember that the
updateMsg -> Model -> (Model, Cmd Msg)caseNothing changes in the
viewGetQuoteAside: 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[1, 2, 3]List number[]List aElm 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.
About the author
Kim Maida
Group Manager, Developer Content