Routing

One of the best features in elm-spa is the automatic routing system! Inspired by popular JS frameworks, the names of your files determine the routes in your application.

Every elm-spa project will have a src/Pages folder containing all the pages in your app:

In this section, we'll cover the different kinds of routes you'll find in every elm-spa application.

The homepage

Home_.elm is a reserved filename that handles requests to your homepage. The easiest way to add a new homepage is with the elm-spa add covered in the CLI docs:

elm-spa add /

Home.elm (without the underscore) is seen as a route to /home! To handle requests to the homepage, make sure to include the trailing underscore.

Static routes

Most pages will be static routes, meaning the filepath will translate to a single URL.

elm-spa add /people

This command creates a file called People.elm that will be shown when the user visits /people in your application.

These are a few more examples of static routes:

Capitalization matters

Notice how the filename AboutUs.elm was created from the route /about-us?

If we named the path /aboutus (without the dash between words) then we'd have a file Aboutus.elm (with a lowercase "u").

In elm-spa, we use "kebab-case" rather than "snake_case" as the convention for separating words.

Nested static routes

You can even have nested static routes within folders:

elm-spa add /settings/users

This example creates a file at Settings/Users.elm, which will handle all requests to /settings/user. This pattern continues, supporting nesting things multiple levels deep:

elm-spa add /settings/user/contact

Dynamic routes

Sometimes a 1:1 mapping is what you need, but other times, its useful to have a single page that will handles requests to similar URL structures.

A common example is providing a different ID for a blog post, user, or another item in a collection.

elm-spa add /people/:name

This creates a file at People/Name_.elm. In elm-spa, we call this a dynamic route. It handles requests to any URLs that match /people/____ and provides the dynamic bit in the req.params value passed into your page!

The underscore at the end of the filename (Name_.elm) indicates that this route is dynamic. Without the underscore, it would only handle requests to a single URL: /people/name

The name of the req.params variable (name in this example) is determined by the name of the file! If we named the file Id_.elm instead, the dynamic value would be at req.params.id.

Nested dynamic routes

Just like we saw earlier with nested static routes, you can use nested folders to create nested dynamic routes!

elm-spa add /users/:name/posts/:id

This creates a file at src/Users/Name_/Posts/Id_.elm, which handles any request that matches /users/___/posts/___:

Not found page

If a user visits a URL that doesn't have a corresponding page, it will redirect to the NotFound.elm page.

By default, the not found page is generated for you in the .elm-spa/defaults/Pages folder. When you are ready to customize your 404 page, move it from the defaults folder into src/Pages:

.elm-spa/
 |- defaults/
     |- Pages/
         |- NotFound.elm

-- move into

src/
 |- Pages/
     |- NotFound.elm

Once you have a NotFound.elm within your src/Pages folder, elm-spa will stop generating the other one, and use your custom 404 file instead.

The technique of moving a file from the .elm-spa/defaults folder is known as "ejecting a default file". Throughout the guide, we'll find more examples of files that we might want to move into our src folder.

Next up: Pages