elm-spa

single page apps made easy

When you create an app with the elm/browser package, you can build anything from a static Html msg page to a fully-fledged web Browser.application.

elm-spa uses that design at the page-level, so you can quickly add new pages to your Elm application!

✅ Automatically generate routes and pages

✅ Read and update global state across pages

static pages

-- can render a static page
page : Page Flags Model Msg
page =
    Page.static
        { view = view
        }

sandbox pages

-- can keep track of page state
page : Page Flags Model Msg
page =
    Page.sandbox
        { init = init
        , update = update
        , view = view
        }

element pages

-- can perform side effects
page : Page Flags Model Msg
page =
    Page.element
        { init = init
        , update = update
        , subscriptions = subscriptions
        , view = view
        }

component pages

-- can read and update global state
page : Page Flags Model Msg
page =
    Page.component
        { init = init
        , update = update
        , subscriptions = subscriptions
        , view = view
        }

easily put together pages!

The reason we return the same Page type is to make it super easy to write top-level init, update, view, and susbcriptions functions.

(And if you're using the official cli tool, this code will be automatically generated for you)

init

init : Route -> Global.Model -> ( Model, Cmd Msg, Cmd Global.Msg )
init route =
    case route of
        Route.Home -> pages.home.init ()
        Route.About -> pages.about.init ()
        Route.Posts slug -> pages.posts.init slug
        Route.SignIn -> pages.signIn.init ()

update

update : Msg -> Model -> Global.Model -> ( Model, Cmd Msg, Cmd Global.Msg )
update bigMsg bigModel =
    case ( bigMsg, bigModel ) of
        ( Home_Msg msg, Home_Model model ) ->
            pages.home.update msg model

        ( About_Msg msg, About_Model model ) ->
            pages.about.update msg model
      
        ( Posts_Msg msg, Posts_Model model ) ->
            pages.posts.update msg model
      
        ( SignIn_Msg msg, SignIn_Model model ) ->
            pages.signIn.update msg model

        _ ->
            always ( bigModel, Cmd.none, Cmd.none )

view + subscriptions

-- handle view and subscriptions in one case expression!
bundle : Model -> Global.Model -> { view : Document Msg, subscriptions : Sub Msg }
bundle bigModel =
    case route of
        Home_Model model -> pages.home.bundle model
        About_Model model -> pages.about.bundle model
        Posts_Model model -> pages.posts.bundle model
        SignIn_Model model -> pages.signIn.bundle model

install the npm package

The cli tool has commands like elm-spa init, elm-spa add, and elm-spa build for generating your routes and pages for you!

npm install -g elm-spa
elm-spa init new-project

install the elm package

If you'd rather define routes and pages by hand, you can add the elm package to your project:

elm install ryannhg/elm-spa

rather see an example?

This repo comes with an example project that you can play around with. Add in some pages and see how it works!

html example

git clone https://github.com/ryannhg/elm-spa
cd elm-spa/examples/html
npm start

elm-ui example

git clone https://github.com/ryannhg/elm-spa
cd elm-spa/examples/elm-ui
npm start

The elm-spa will be running at http://localhost:8000