The CLI

To install the elm-spa CLI via npm run this command:

npm install -g elm-spa@latest

This CLI gives us these six commands:

1. elm-spa new - creates a new project
2. elm-spa server - runs a dev server as you code
3. elm-spa add - adds a page to an existing project
4. elm-spa build - one-time production build
5. elm-spa gen - generates files, without elm make
6. elm-spa watch - generates files as you code

What do these do? Let's dive into each in detail!

elm-spa new

When you want to create a new project, use the elm-spa new command. This creates a new project in the current folder:

elm-spa new

New project created in:
/Users/ryan/code/my-new-app

The new command creates three files:

elm-spa server

The first thing you'll want to do after creating a new project is see it in the browser! The elm-spa server command is all you need to see the app in action:

elm-spa server

This command starts a development server for your project at http://localhost:1234.

When you edit your code, elm-spa server automatically compiles your application.

elm-spa add

You can add new pages to your app with the elm-spa add command:

elm-spa add /contact

This creates a new file at src/Pages/Contact.elm. If you visit http://localhost:1234/contact in the browser, you'll see a new page with the text "Contact" displayed.

adding other pages

Here are a few examples of other routes you can create with the add command

elm-spa add /              # src/Pages/Home_.elm
elm-spa add /settings      # src/Pages/Settings.elm
elm-spa add /people/:id    # src/Pages/People/Id_.elm

We'll cover this in more detail in the routing section

using page templates

The elm-spa add command also accepts an optional template argument too for common pages you might create.

elm-spa add /example static
elm-spa add /example sandbox
elm-spa add /example element

We'll explore those page types in the pages section

elm-spa build

The elm-spa server command is great for development, but for production, you'll want the elm-spa build command.

elm-spa build

This compiles your app into an optimized and minified JS file. This makes it great for serving your application in the real world!

A note on hosting

By default, the public folder can be statically served. Hosting platforms like Netlify make this free and easy.

Because this is a single page application, be sure to setup redirects to public/index.html. Here's an example of how to do this with Netlify.

elm-spa gen

If you are working with another dev server, you won't need the .js file generated by the build command. To only generate elm-spa files, use the elm-spa gen command:

elm-spa gen

This will generate code in the .elm-spa folder, but allow your custom workflow to define it's own way of compiling Elm. This is a great command to combine elm-spa with another tool like Vite or Parcel.

elm-spa watch

If you want the automatic code generation on change, but don't need elm make or an HTTP server, you can use the elm-spa watch command:

elm-spa watch

This will automatically generate code and compile your Elm files on save, but without the server.

Next up: Routing