elm-live

Install the latest version of elm-live using one of the commands below.

# Using NPMnpm install elm-live # Using Yarnyarn add elm-live

If you need elm-live for Elm 0.18 you can install it using the following command:

# Using NPMnpm install elm-live@prev --save-dev # Using Yarnyarn add elm-live@prev --dev

elm-live <elm-file> [other-elm-files...] [flags] [--] [elm make flags]

Although all the flags are explained in the documentation below I want to cover the different parts of the command you see above so that there is nothing left you need to assume or guess at:

This is the name of the binary that is installed either to your local or global path.

This represents the one required argument and is the path to the Elm file you want to compile. This file path gets passed directly to elm make.

This represents the potentially infinite, but completely optional other Elm files you want to compile, E.g. elm-live src/Main.elm src/Widget.elm src/Tool.elm.

This represents the optional elm-live specific flags that help manage how the server is setup. See below for docs on how these are used.

elm-live src/Main.elm --path-to-elm=./node_modules/.bin/elm

Default: elm

Set the path to the Elm binary that elm-live should use when compiling your project. If you have the elm binary globally installed on your machine this is not needed. However, if you are using elm locally in your project using NPM or just have it located somewhere else on your machine this flag lets you tell elm-live where to look for the binary.

elm-live src/Main.elm --port=1234

Default: 4000

Set the port that the elm-live server is listening for requests at. If the default port used by elm-live is already in use this flag gives you a backdoor to pass in a port that is not in use. In the example above the url that your elm project would be available at would be http://localhost::1234.

elm-live src/Main.elm --host=my-site.com

Default: localhost

Set the host (the domain part of the url) that elm-live serves the files on.

elm-live src/Main.elm --ssl

Default: false

Boolean flag that generates a self signed ssl cert and makes your project available at an https:// url. Not needed if you are using --ssl-key and --ssl-cert to use local ssl credentials.

NOTE: This is a self-signed cert so you will most likely see a warning in the browser when you first open your project.

elm-live src/Main.elm --ssl-cert=./mycert.pem --ssl-key=./mykey.pem

Default: false

Relative path to your self generated certificate. If you are using this flag you must also use --ssl-key otherwise it will not work.

elm-live src/Main.elm --ssl-cert=./mycert.pem --ssl-key=./mykey.pem

Default: false

Relative path to your self generated key. If you are using this flag you must also use --ssl-cert otherwise it will not work.

elm-live src/Main.elm --dir=./dist

Default: ./

Set the root directory for the server. Everyone has the freedom to structure their projects however they see fit. So, this flag let's you tell the server where your asset files should be served from.

NOTE: If you are setting the --dir flag then make sure you are taking into account how that will interop with the --output flag you pass to elm make. If your output from the compiler is not inside of the directory you are passing to the dir flag you are going to run into bugs.

elm-live src/Main.elm --start-page=custom.html

Default: index.html

Set a custom html file for the server to look for when serving up your project. Did we mention that developers have the freedom to do whatever they want?

NOTE: Just like --dir keep in mind how this interacts with the --output flag from elm make. Since you are setting the name as something different than index you will always need to include the --output flag and either set it as the same value you passed to --start-page or as a JS file.

elm-live src/Main.elm --pushstate

Default: false

Tell the server to let the client handle routing and always serve the --start-page. One of the best features in Elm is the ability to control routing on the client. However, the server needs to know that you are expecting the client to handle routing too. That is what --pushstate is for.

elm-live src/Main.elm --hot

Default: false

Turn hot reloading on. Hot reloading is the ability to update the Javascript currently running without reloading. This means that the state of your Elm app is maintained across compiles.

NOTE: This only works if you are outputting your compiled Elm into a js file using the --output flag for elm make.

elm-live src/Main.elm --open

Default: false

Open the project in the browser once the server is started.

elm-live src/Main.elm --verbose

Default: false

Log more stuff.

elm-live src/Main.elm --no-reload

Default: true

Turn off all live reloading. This means you have to refresh the browser yourself.

elm-live src/Main.elm --no-server

Default: true

Turn off the server. This means elm-live only watches for changes to Elm files and compiles that code. Useful when you are using Elm in another ecosystem like Elixir, Wordpress, etc.

Sometimes, in production your frontend may be served by some static file mechanism in your backend system, but while developing that might not be the way you have it setup. So you may have your backend running on say localhost:5000 , but your frontend server (aka elm-live) runs separately on localhost:6000. In production all requests sent to /api know to make that request to the backend api, but on your local environment /api on the frontend sends that request to localhost:6000/api when it needs to be sent to localhost:5000. That is where proxies come in.

elm-live src/Main.elm --proxy-prefix=/api --proxy-host=http://localhost:5000

Default: false

The --proxy-prefix flag tells the server what path to capture and point to the server located at --proxy-host. It requires the --proxy-host flag and should be a string like /api.

NOTE: The string passed to --proxy-prefix will be removed from the --proxy-host url. If you would like the url to include the prefix just add it there as well like: http://localhost:5000/api.

elm-live src/Main.elm --proxy-prefix=/api --proxy-host=http://localhost:5000

Default: false

The --proxy-host flag tells the server what host to redirect requests to. It requires the --proxy-prefix flag and should be a full URL like http://localhost:5000.

These flags are passed through directly to elm make and are added to the elm-live command a little differently than the flags covered above. The elm make flags must be added after the separator -- in the command. The -- allows us to capture all flags after it into a single bucket so we can pass them right into elm make.

NOTE: If you are familiar with all of the elm make flags you will notice that there a some missing below, e.g. --optimize. I only cover --debug and --output because these are the only ones that apply to compiling for development. You can also pass the missing flags if you are really feeling it, but it is just not a regular or recommended practice during development.

elm-live src/Main.elm -- --debug

Default: false

Passing this flag adds the elm time-traveling debugger we all know and love.

elm-live src/Main.elm -- --output=elm.js

Default: index.html

This is a very important flag. This flag allows you to change both the name and the file type of your compiled Elm code. You can name your output anything you want, but the file type must be either html or js. You can also check out this section of the Elm guide for an overview of why you might want to do this: https://guide.elm-lang.org/interop/

NOTE: This flag can affect other elm-live flags you may be using. Since the --dir flag sets the root folder for the server you will need to make sure that the --output is inside that directory. The --start-page flag allows you to give a custom html file name for the server to use. So, if you are outputting html from the compiler the --output filename will need to match the --start-page.

I would love to hear from you. I want to make sure that elm-live is the most helpful tool it can be for the Elm community. You can reach out to me on Twitter at @wking__ or add an issue on the Github repo.

Also, if you haven't had a chance to take the survey yet that would be a huge help to making elm-live better: Take the quick survey