Elm mini SPA (step 0)

What?

This is the first step on creating a simple Elm web application using the Single-page Application architecture.

At this step we are only creating a basic Elm document with a local counter.

The full steps are:

Step0: Create a simple page applications (code)
Step1: Upgrade to a full navigation application (code)
Step2: Add an extra page (code)
Step3: Support for global shared data (code)
Step4: Make the illusion real (code)
Step5: Making the web server happy (code)
Step6: Adding a magical router (code)

IMPORTANT: This is only one way to provide SPA support for Elm, you do not need to implement new projects following exactly this code, please use it only as a reference and at the step level you may require.

How?

We will cover a sample step by step starting with a simple page with a counter until we have a multiple page Elm web application with multiple local and global counters.

For running this step code just execute the command:

cd elm-mini-spa-step0
elm-live -- src/Main.elm

And open your favorite browser pointing to http://localhost:8080

Where?

The source code is at https://github.com/csaltos/elm-mini-spa and the full tutorial at https://www.udemy.com/course/elm-the-complete-guide/.

Who?

This sample code is created with love by Carlos Saltos, please considere to buy me a coffee.

Elm mini SPA (step 1)

What?

This is the second step on creating a simple Elm web application using the Single-page Application architecture.

At this step we are upgrading the code to a full navigation application using two modules.

For implementing the change, just extract all the code to a new file called Page1.elm and map all the calls from Main.elm to the new Page1 module.

The idea is to upgrade the previous main function to a Browser.application call with full navigation mapping the original view function to the new pages viewBody function depending on which page to display in the next step.

The refactoring is not that complicated but requires a trick to cover different types using Html.map, Cmd.map, Sub.map for aligning message, commands and subscriptions types.

When this step is complete, the web app will look the same but now with two modules ready to jump to multiple pages on the next step.

NOTE: Obviously if you will have only one page, there is no need to create an extra module, this is just the preparation for applications when multiple pages are required.

The full steps are:

Step0: Create a simple page applications (code)
Step1: Upgrade to a full navigation application (code)
Step2: Add an extra page (code)
Step3: Support for global shared data (code)
Step4: Make the illusion real (code)
Step5: Making the web server happy (code)
Step6: Adding a magical router (code)

IMPORTANT: This is only one way to provide SPA support for Elm, you do not need to implement new projects following exactly this code, please use it only as a reference and at the step level you may require.

How?

We will cover a sample step by step starting with a simple page with a counter until we have a multiple page Elm web application with multiple local and global counters.

For running this step code just execute the command:

cd elm-mini-spa-step1
elm-live -- src/Main.elm

And open your favorite browser pointing to http://localhost:8080

Where?

The source code is at https://github.com/csaltos/elm-mini-spa and the full tutorial at https://www.udemy.com/course/elm-the-complete-guide/.

Who?

This sample code is created with love by Carlos Saltos, please considere to buy me a coffee.

Elm mini SPA (step 2)

What?

This is the third step on creating a simple Elm web application using the Single-page Application architecture.

At this step we are adding a second page, just copy the Page1.elm file to a new Page2.elm file refactoring the new module names.

After that, import the new module Page2 and the Main.elm and add the new page calls.

At some points you will requrire to add Cmd.batch and Sub.batch for including multiple commands and subscriptions for the multiple pages.

For making the multiple page navigation work we add a piece called a router and also a top bar visual navigation at the Main.elm file.

When this step is complete you will be able to change from one page to the other with local independent counters where we add some visual changes like different backgrounds and labels for the two pages.

Play around the now two local counters and check they work independanly.

But what if I want to make a global counter or any other kind of global shared piece of data? ... discover how in the next step.

NOTE: For this sample we are using similar pages but obviously you can have different interfaces, behaviours and contents for multiple different pages.

The full steps are:

Step0: Create a simple page applications (code)
Step1: Upgrade to a full navigation application (code)
Step2: Add an extra page (code)
Step3: Support for global shared data (code)
Step4: Make the illusion real (code)
Step5: Making the web server happy (code)
Step6: Adding a magical router (code)

IMPORTANT: This is only one way to provide SPA support for Elm, you do not need to implement new projects following exactly this code, please use it only as a reference and at the step level you may require.

How?

We will cover a sample step by step starting with a simple page with a counter until we have a multiple page Elm web application with multiple local and global counters.

For running this step code just execute the command:

cd elm-mini-spa-step2
elm-live -- src/Main.elm

And open your favorite browser pointing to http://localhost:8080

Where?

The source code is at https://github.com/csaltos/elm-mini-spa and the full tutorial at https://www.udemy.com/course/elm-the-complete-guide/.

Who?

This sample code is created with love by Carlos Saltos, please considere to buy me a coffee.

Elm mini SPA (step 3)

What?

This is the fourth step on creating a simple Elm web application using the Single-page Application architecture.

At this step we are adding a global counter as a sample on how to have shared data between pages and the Main module.

First add an integer called globalCounter at the Main module and show it at the top navigation bar.

The new global counter should show at the top of the page ... but ... how to share it between the pages? ... how to make the increment and decrement buttons of the pages to change the global counter at the Main module? ... for that we have added the notion of an action that are very similar to the original Elm messages but for passing signals from the pages to the Main module, for passing messages back from the pages.

Play with the local counters at each page and check how the global top navigation bar counter is in-sync.

When you click on the different pages links you will notice the browser URL does not change, this is because on an Elm application project all the navigation is intercepted so we can create the illusion of new pages but for making that illusion real we need to add a couple of things on the step 4.

NOTE: What we call globalCounter at this sample code can also be named as SharedModel and have a richer record type alias rather than just an integer and also you can propagate this new shared piece of data to the pages modules.

The full steps are:

Step0: Create a simple page applications (code)
Step1: Upgrade to a full navigation application (code)
Step2: Add an extra page (code)
Step3: Support for global shared data (code)
Step4: Make the illusion real (code)
Step5: Making the web server happy (code)
Step6: Adding a magical router (code)

IMPORTANT: This is only one way to provide SPA support for Elm, you do not need to implement new projects following exactly this code, please use it only as a reference and at the step level you may require.

How?

We will cover a sample step by step starting with a simple page with a counter until we have a multiple page Elm web application with multiple local and global counters.

For running this step code just execute the command:

cd elm-mini-spa-step3
elm-live -- src/Main.elm

And open your favorite browser pointing to http://localhost:8080

Where?

The source code is at https://github.com/csaltos/elm-mini-spa and the full tutorial at https://www.udemy.com/course/elm-the-complete-guide/.

Who?

This sample code is created with love by Carlos Saltos, please considere to buy me a coffee.

Elm mini SPA (step 4)

What?

This is the fifth step on creating a simple Elm web application using the Single-page Application architecture.

At this step we are upgrading all the internal illusion of navigation to a real navigation and for that we are adding calls to Browser.Navigation.pushUrl and Browser.Navigation.load, with that in place check that now the browser URL changes along the navigation and even external links like the one added to the top bar is also working.

Additionally we need what is called a "navigation key" and this is beause Elm application projects are intercepting all the URL request for us to create our own internal pages navigation but for synching this internal navigation with the browser we now need to do it explicitly using this "navitaion key" now stored in the model.

One piece is still missing, try to go to /page1.html and hit the browser reload button, you will got a 404 not found page, this is beacuse the request will be received by the web server and not our Elm internal navigation. We will see how to fix it at the next step.

The full steps are:

Step0: Create a simple page applications (code)
Step1: Upgrade to a full navigation application (code)
Step2: Add an extra page (code)
Step3: Support for global shared data (code)
Step4: Make the illusion real (code)
Step5: Making the web server happy (code)
Step6: Adding a magical router (code)

IMPORTANT: This is only one way to provide SPA support for Elm, you do not need to implement new projects following exactly this code, please use it only as a reference and at the step level you may require.

How?

We will cover a sample step by step starting with a simple page with a counter until we have a multiple page Elm web application with multiple local and global counters.

For running this step code just execute the command:

cd elm-mini-spa-step4
elm-live -- src/Main.elm

And open your favorite browser pointing to http://localhost:8080

Where?

The source code is at https://github.com/csaltos/elm-mini-spa and the full tutorial at https://www.udemy.com/course/elm-the-complete-guide/.

Who?

This sample code is created with love by Carlos Saltos, please considere to buy me a coffee.

Elm mini SPA (step 5)

What?

This is the sixth step on creating a simple Elm web application using the Single-page Application architecture.

At this step we are trying to fix the 404 not found pages when the user hits the reload button and for that we need to tell the web server where to find this pages.

There are several ways to patch this web server requests, the idea is to create an alias from the original Elm web application to every new page we add.

One way to do it is with simple file aliases using soft links but you can also use rewrite rules with an nginx or HA-Proxy server or even templates with the support of a Laravel or Ruby on rails server.

For our sample code we just added aliases using soft link, this aliases files page1.html and page2.html are already created and pointing to index.html but you can also create them your self with these commands:

ln -s index.html page1.html
ln -s index.html page2.html

These will only on Linux, Mac and any other real Unix operating system, for Windows you can create copies of the index.html file into page1.html and page2.html or also try to use WSL.

Now play a little bit with the code and navigation, try to remove the alias files, use the browser reload button, add the aliases again and even try to add new pages like a page for /about.html.

The full steps are:

Step0: Create a simple page applications (code)
Step1: Upgrade to a full navigation application (code)
Step2: Add an extra page (code)
Step3: Support for global shared data (code)
Step4: Make the illusion real (code)
Step5: Making the web server happy (code)
Step6: Adding a magical router (code)

IMPORTANT: This is only one way to provide SPA support for Elm, you do not need to implement new projects following exactly this code, please use it only as a reference and at the step level you may require.

How?

We will cover a sample step by step starting with a simple page with a counter until we have a multiple page Elm web application with multiple local and global counters.

For running this step code just execute the command:

cd elm-mini-spa-step5
elm-live -- src/Main.elm

And open your favorite browser pointing to http://localhost:8080

Where?

The source code is at https://github.com/csaltos/elm-mini-spa and the full tutorial at https://www.udemy.com/course/elm-the-complete-guide/.

Who?

This sample code is created with love by Carlos Saltos, please considere to buy me a coffee.

Elm mini SPA (step 6)

What?

This is the seventh step on creating a simple Elm web application using the Single-page Application architecture.

At this step we will add a module called Route.elm for better using multiple pages path routes.

You can use several different kind of routes and even create your own manually but we are here presenting a magical router developed by Simon Lydell at elm-app-url

For using elm-app-url you may install it with the command:

elm install lydell/elm-app-url

Then move all the routes created at Main.elm to a new module called Route.elm and add helper functions to locate the routes and use them from the Main.elm module.

That's it, now you have a solid router to handle your Elm web application, of course with just two pages there is no need for an explicit router but for real massive multipages applications a router is a life saver.

More info about elm-app-url may be found at Elm Radio Episode 077: elm-app-url with Simon Lydell.

Congratulations !! ... You have created an Elm SPA application, rather simple but it can work as a fundation real Elm web multipages applications like the ones we use at Talenteca using Elm and elm-ui, just please remember to used only as a reference and adapt it to your own projects requirements.

The full steps are:

Step0: Create a simple page applications (code)
Step1: Upgrade to a full navigation application (code)
Step2: Add an extra page (code)
Step3: Support for global shared data (code)
Step4: Make the illusion real (code)
Step5: Making the web server happy (code)
Step6: Adding a magical router (code)

IMPORTANT: This is only one way to provide SPA support for Elm, you do not need to implement new projects following exactly this code, please use it only as a reference and at the step level you may require.

How?

We will cover a sample step by step starting with a simple page with a counter until we have a multiple page Elm web application with multiple local and global counters.

For running this step code just execute the command:

cd elm-mini-spa-step6
elm-live -- src/Main.elm

And open your favorite browser pointing to http://localhost:8080

Where?

The source code is at https://github.com/csaltos/elm-mini-spa and the full tutorial at https://www.udemy.com/course/elm-the-complete-guide/.

Who?

This sample code is created with love by Carlos Saltos, please considere to buy me a coffee.

How to publish an Elm package guide

Intro

This guide is focused on the mechanics on how to publish a new Elm package at https://package.elm-lang.org/, for more in-depth details please check the Real Life section.

Step 1 - Preparation

For publishing a new Elm package we need to ensure we have an elm.json file configuration similar to this:

{
    "type": "package",
    "name": "TheBestDeveloper/my-first-elm-package",
    "summary": "A sample Elm package reference",
    "license": "BSD-3-Clause",
    "version": "1.0.0",
    "exposed-modules": [
        "MyMath.FourierCalc",
        "MyMath.FrontierCalc"
    ],
    "elm-version": "0.19.0 <= v < 0.20.0",
    "dependencies": {
        "elm/core": "1.0.0 <= v < 2.0.0",
        "elm/html": "1.0.0 <= v < 2.0.0"
    },
    "test-dependencies": {}
}

The type of the project should be package since normal application projects are not allows as libraries at https://package.elm-lang.org/.

The field name contains the full Elm package name including the owner separated by an slash /, the owner should be a valid GitHub account you own.

Decide which license to use and add its code to the field license and its content to the file LICENSE including the fullname of the project owners.

The recommended license to use is BSD3, but of course you can use any license you want, a non-exhaustive list of possible licenses to use can be found at https://opensource.org/license.

For the initial version use 1.0.0 and the next versions will be calculated automatically by the system based and how deep are the evolution of the changes of your package along time.

Add a good summary using less than 80 characters.

Ensure the Elm version and dependencies version is under a valid range your packge library supports, here we are using Elm 0.19.x and elm/core and elm/html as a reference.

Then decide which modules you want to expose as part of the public API of your new package with entries at exposed-modules, you do not need to make all your modules public, try to expose as little as possible.

Include a README.md file at the root of your project with good documentation and useful examples.

Finally, you should document all of the publicly exposed modules and functions, here a guide about the documentation format to use -> http://package.elm-lang.org/help/documentation-format.

Step 2 - Clean, Compile and Test

With the new package configuration and README.md file in place then clean and compile your project from scratch ensuring the tests run successfully.

Step 3 - Publish the first version

Ensure all your code, documentation and configuration files are commited at GitHub and then tag it with the first version 1.0.0 using the commands:

git tag -a 1.0.0 -m "Initial release"
git push --tags

Now using this new tag, let's publish your new Elm package with the command:

elm publish

And that's it !! ... if you have all the requisites fullfiled, your new package will be published at https://package.elm-lang.org/.

If a requisite is not met of you found an error please double check the prepartion and compilation step and tune your package and try again.

Publish new versions

Once you have your first version published, a long the time you may require to add new features or fix possible bugs, for that just create new commits with the changes and then checking all the requisites as before, run the command:

elm bump

This will check your code and decide the new version following the rules of semantic versioning which normally creates a patch version on small changes and minor or even mayor version for more involved changes, but once again, all of this is calculated automatically and saved at your elm.json file.

If you want to inspect what are the changes and try to keep the versioning more fine grained run the command elm-package diff for getting more information about the new version automatic calculation process

With a new version calulated automatically, just clean, compile and test your project as before and then create a new tag at your repo using the new version with a command like:

git tag -a 1.0.1 -m "Adding a new feature"
git push --tags

Replace 1.0.1 with your previously automatic calculated version and give a more using tag comment

Then publish your new updated version with the command:

elm publish

Real life

Creating good packages requires more than just these mechanical steps, please visit Dillon Kearns in-depth publish tips at the Idiomatic Elm Package Guide

Some tips about new packages design can also be found at https://package.elm-lang.org/help/design-guidelines by Evan Czaplicki.

The original guide can be found at the history commits of the old elm-package repo found at https://github.com/elm-lang/elm-package created by Evan Czaplicki

Buy me a coffee

If you like this content and find it useful, please considere to buy me a coffee using:

Carlos Saltos Tech Blog