Guide

Welcome to elm-spa, a framework for building web applications with Elm! If you are new to Elm, you should check out the official guide, which is a great introduction to the language.

The goal of this guide is to help you solve common problems you might run into with real world single-page web applications.

Features

Here are a few benefits to using elm-spa:

Automatic routing - routes for your web app are automatically generated based on file names. No need to maintain URL routing logic or wire pages together manually.
Simple shared state - comes with a straightforward way to share data within and between pages. You can also make pages as simple or complex as you need!
Zero configuration - Includes a hot-reloading dev server, build tool, and everything you need in one CLI tool! No need for webpack, uglify, or other NPM packages.

Quickstart

Creating your first project

You can create a new elm-spa project from scratch my creating a new folder:

mkdir my-new-project && cd my-new-project

And then running this command in your terminal:

npx elm-spa new

This will create a brand new project in the my-new-project folder! It should only contain these three files:

my-new-project/
 - .gitignore      # folders to ignore in git
 - elm.json        # project dependencies
 - src/
 - public/
    - index.html   # entrypoint to your application

Running the dev server

Running this command will start a development server at http://localhost:1234:

npx elm-spa server

Adding your first page

To add a homepage, run the elm-spa add command:

npx elm-spa add /

This will create a new page at ./src/Pages/Home_.elm. Try editing the text in that file's view function, it will automatically change in the browser!

Installation

So far, we've been using the npx command built into Node.js to run the elm-spa CLI. If we would rather use the CLI without this prefix, we can install elm-spa globally:

npm install -g elm-spa@latest

This will ensure we have the latest version of elm-spa available in our terminal. You can make sure it works by calling elm-spa directly:

elm-spa help

elm-spa – version 6.0.0

Commands:
elm-spa new . . . . . . . . .  create a new project
elm-spa add <url> . . . . . . . . create a new page
elm-spa build . . . . . . one-time production build
elm-spa watch . . . . . . .  runs build as you code
elm-spa server  . . . . . . start a live dev server

Visit https://next.elm-spa.dev for more!

If you see this message, you can run all the CLI commands without needing to prefix them with npx!

Next up: The CLI

2.8 KiB Raw Blame History Unescape Escape