elm-starter

elm-starter is an experimental Elm-based Elm bootstrapper that can also be plugged into already existing Elm applications.

Post "elm-starter", a tool for the Modern Web.

Example of the installed version, with and without Javascript enabled:

Demos

These are three simple examples of websites built with elm-starter:

https://elm-starter.guupa.com/ (Code)
https://elm-todomvc.guupa.com/ (Code)
https://elm-spa-example.guupa.com/ (Code)
https://elm-physics-example.guupa.com/ (Code)

Characteristics

Generate a PWA (Progressive Web Application)
Mostly written in Elm
Pages are pre-rendered at build time
Works offline
Works without Javascript(*)
SEO
Preview cards (Facebook, Twitter, etc.) work as expected
Installable both on desktop and on mobile
High score with Lighthouse
Friendly notifications: "Loading...", "Must enable Javascript...", "Better enable Javascript..."
Potentially compatible with all Elm libraries (elm-ui, elm-spa, etc.)
Hopefully relatively simple to use and maintain
Non invasive (you can easily add/remove it)
Works with Netlify, Surge, etc.
Supports websites living in subfolder

Lighthouse report:

Slack's previews (note how different urls have different snapshot and meta-data):

How to bootstrap a new project

elm-starter is not published in npm yet and it doesn't have a specific command to bootstrap a project, so the way it works now is cloning this repo.

The fastest way is to click here. This will automatically clone the repo and publish in Netlify.

Otherwise the steps are:

git clone https://github.com/lucamug/elm-starter
mv elm-starter my-new-project
cd my-new-project
rm -rf .git
npm install

Done! elm-starter is installed.

To start using it you should create your own git repository, add files and make a commit (example: git init && git add . && git commit -m "initial commit").

These are the available commands:

`$ npm start`

Runs the app in the development mode. Open http://localhost:8000 to view it in the browser.

Edit src/Main.elm and save to reload the browser.

Also edit src/Index.elm and package.json for further customization.

`$ npm run build`

Builds the app for production to the elm-stuff/elm-starter-files/build folder.

`$ npm run serverBuild`

Launches a server in the build folder.

Open http://localhost:9000 to view it in the browser.

How to use `elm-starter` in existing Elm application

Let's suppose your existing project is in my-elm-app

Clone elm-starter with
$ git clone https://github.com/lucamug/elm-starter.git
Copy the folder elm-starter/src-elm-starter/ to my-elm-app/src-elm-starter/
Copy the file elm-starter/src/Index.elm to my-elm-app/src/Index.elm
Copy the function conf from elm-starter/src/Main.elm to my-elm-app/src/Main.elm (remember also to expose it)
If you don't have package.json in your project, add one with $ npm init
Be sure that you have these values in package.json as they will be used all over the places:
- "name" - An npm-compatible name (cannot contain spaces)
- "nameLong" - The regular name used all over the places, like in the <title> of the page, for example
- "description"
- "author"
- "twitterSite" - A reference to a Twitter handle (Just the id without "@")
- "twitterCreator" - Another Twitter handle, refer to [Twitter cards markups](https://developer.twitter.com/en/docs/ tweets/optimize-with-cards/overview/markup)
- "version"
- "homepage"
- "license"
- "snapshotWidth" - default: 700 px
- "snapshotHeight" - default: 350 px
- "themeColor" - default: { "red": 15, "green": 85, "blue": 123 }

Add node dependencies with these commands

npm install --save-dev chokidar-cli
npm install --save-dev concurrently
npm install --save-dev elm
npm install --save-dev elm-go
npm install --save-dev html-minifier
npm install --save-dev puppeteer
npm install --save-dev terser

Add src-elm-starter as an extra source-directory in elm.json, the same as in elm-starter/elm.json

Add these commands to package.json (or run them directly)

  "scripts": {
    "start":       "node ./src-elm-starter/starter.js start",
    "build":       "node ./src-elm-starter/starter.js build",
    "serverBuild": "node ./src-elm-starter/starter.js serverBuild"
  },

Done!

`sandbox` vs. `element` vs. `document` vs. `application`

In Elm there are several ways to start an application:

Browser.sandbox
Browser.element
Browser.document
Browser.application

Among these, the first two take over only one specific node of the DOM, the other two instead take over the entire body of the page. So we need to follow two different strategies.

Case for `sandbox` & `element`

In the Index.elm you need to create a <div> that will be used to attach the Elm application.

In the elm-starter example we use a <div> with id elm. In Index.elm, see the line:

    ++ [ div [ id "elm" ] [] ]

Then we use this node to initialize Elm:

var node = document.getElementById('elm');
window.ElmApp = Elm.Main.init(
    { node: node
    , flags: ...you flags here...
    }

Then, to be sure that the node created by the static page generator is replaced later on, we need to add such <div> in the view of Main.elm like this:

view : Model -> Html.Html Msg
view model =
    Html.div
        [ Html.Attributes.id "elm" ]
        [ ...you content here... ]

Note: You can change the id from elm to anything you like.

Case for `document` & `application`

This case require a different approach. You can see an example in the elm-spa-example.

The main differences compared to the above approach are:

You don't need to create a specific <div> with id elm.
You need to move all Javascript section of the page into the htmlToReinjectInBody section (see Index.elm as example).

htmlToReinjectInBody will be injected after the page is generated during the build process assuring that the system will work also in this case.

Netlify

When setting up the app with Netlify, input these in the deploy configuration:

Build command: npm run build (or node ./src-elm-starter/starter.js start)
Publish directory: elm-stuff/elm-starter-files/build

Other CI/CD platforms

There are cases where some CI process is not able to install and use Puppeteer properly.

One of these cases was solved installing chromium manually running

RUN apk update && apk add --no-cache bash chromium

Then setting up some environment variables:

ENV PUPPETEER_SKIP_CHROMIUM_DOWNLOAD=true
ENV PUPPETEER_EXECUTABLE_PATH=/usr/bin/chromium-browser

Then extra paramater were added to elm-starter

--no-sandbox
--disable-setuid-sandbox
--disable-dev-shm-usage

More info at https://github.com/puppeteer/puppeteer/blob/main/docs/troubleshooting.md#running-on-alpine

(*) Applications working without Javascript

Working without Javascript depends on the application. The elm-starter example works completely fine also without Javascript, the only missing thing is the smooth transition between pages.

The elm-todomvc example requires Javascript. Note that in this example, compared to Evan's original TodoMVC, I slightly changed the CSS to improve the a11y (mainly lack of contrast and fonts too small).

The elm-spa-example partially works without Javascript. You can browse across pages but the counters are not working.

elm-starter and elm-todomvc use Browser.element, while elm-spa-example use Browser.application.

The setup for these two cases is a bit different. Browser.application requires to use htmlToReinjectInBody (see Index.elm) because Elm is wiping out all the content in the body. Also the node where Elm attach itself needs to be removed (see node.remove() ).

The working folder of elm-starter is elm-stuff/elm-starter-files. These files are automatically generated and should not be edited directly, unless during some debugging process.

Advanced stuff

`htmlToReinjectInHead` and `htmlToReinjectInBody`

These two functions are used to re-inject some HTML after Puppeteer generated the page. This can be useful in several cases:

Using Browser.document or Browser.application (see above).
Using Google Tags, Google Analytics or other advanced JavaScript dependencies that should run only once. In these cases better not to add these JavaScript snipped during the development, but inject them using htmlToReinjectInHead only after the generation of HTML is done.

File generation

Most of the logic is written in Elm, including the code to generate all necessary files:
- index.html (generated from Index.elm using zwilias/elm-html-string)
- sitemap.txt
- manifest.json
- service-worker.js
- robots.txt

Disabling pre-rendering

Is possible to disable pre-rendering just passing an empty list to Main.conf.urls. In this case the app will work as "Full CSR" (Full Client-side Rendering)

This is an example of application with pre-rendering disabled. In this case also the WebGL animation caused some time out issue with puppeteer and it would not be necessary anyway to have this application render without Javascript as it based entirely on Javascript.

Not the message when Javascript is disabled:

How to customize your project

The main two places where you can change stuff are:

src/Index.elm
src/Main.elm (conf function)

elm-starter is opinionated about many things. If you want more freedom, you can change stuff in

src-elm-starter/**/*.elm

The reason Main.conf is inside Main.elm is so that it can exchange data. For example:

title: Main.conf -> Main
urls: Main.conf <- Main

Moreover Main.conf is used by src-elm-starter to generate all the static files.

elm-console-debug.js for nice console output

Support https://github.com/kraklin/elm-debug-transformer out of the box for nice Debug.log messages in the console.

Changing meta-tags

For better SEO, you should update meta-tags using the predefined port changeMeta that you can use this way:

Cmd.batch
    [ changeMeta { querySelector = "title", fieldName = "innerHTML", content = title }
    , changeMeta { querySelector = "meta[property='og:title']", fieldName = "content", content = title }
    , changeMeta { querySelector = "meta[name='twitter:title']", fieldName = "value", content = title }
    , changeMeta { querySelector = "meta[property='og:image']", fieldName = "content", content = image }
    , changeMeta { querySelector = "meta[name='twitter:image']", fieldName = "content", content = image }
    , changeMeta { querySelector = "meta[property='og:url']", fieldName = "content", content = url }
    , changeMeta { querySelector = "meta[name='twitter:url']", fieldName = "value", content = url }
    ]

You can validate Twitter preview cards at https://cards-dev.twitter.com/validator

Configuration

You can verify the configuration in real-time using elm reactor:

node_modules/.bin/elm reactor

and check the page

http://localhost:8000/src-elm-starter/Application.elm

Globally available objects

There are three global objects available

`ElmStarter`

ElmStarter contain metadata about the app:

{ commit: "abf04f3"   // coming from git
, branch: "master"    // coming from git
, env: "dev"          // can be "dev" or "prod"
, version: "0.0.5"    // coming from package.json
}

This data is also available in Elm through Flags.

`ElmApp`

ElmApp is another global object that contains the handle of the Elm app.

`Elm`

This is the object exposed by the compiler used to initialize the application.

Website living in subfolder

If your website need to live in a subfolder, including all the assets, simply specify the subfolder in homepage of package.json.

    "homepage": "https://example.com/your/sub/folders",

This will adjust all the links for you automatically. So for example, elm.js instead being loaded as

<script src="/elm.js"></script>

It will be loaded as

<script src="/your/sub/folders/elm.js"></script>

Remember to account for these extra folders in your Elm route parser.

Extra commands

To avoid possible conflicts with other commands in package.json, al commands are also available with a prefix:

$ npm run elm-starter:boot
$ npm run elm-starter:start
$ npm run elm-starter:generateDevFiles
$ npm run elm-starter:build
$ npm run elm-starter:buildExpectingTheServerRunning
$ npm run elm-starter:serverBuild
$ npm run elm-starter:serverDev
$ npm run elm-starter:serverStatic
$ npm run elm-starter:watchStartElm

This list also include extra commands that can be useful for debugging

Limitations

Javascript and CSS to generate the initial index.html are actually strings :-(
src-elm-starter/starter.js, the core of elm-starter, is ~330 lines of Javascript. I wish it could be smaller
If your Elm code relies on data only available at runtime, such as window size or dark mode, prerendering is probably not the right approach. In this case you may consider disabling pre-rendering and use other alternatives, such as Netlify prerendering

Note

The smooth rotational transition in the demo only works in Chrome. I realized it too late, but you get the picture

How does it work internally

Command `start`

* [function bootstrap]
    * Set initial values for some folder and file names
    * Compile `Worker.elm`
    * Execute `Worker.elm` using data set initially and other data coming from `package.json` and command line options
    * `Worker.elm` generates a configuration file that will be used for the next tasks. A copy of it is accessible at http://localhost:8000/conf.json
* [function command_start]
    * [function command_generateDevFiles]
        * Clean the `developmennt` working folder
        * Generate files as per `conf.json` and also copy over assets
        * Touch `src/Main.elm` so that `elm-go` recompile and the browser refresh
    * Starts two commands: `serverDev` and `watchStartElm` (see below)

Command `serverDev`

* [function bootstrap] (see above)
* [function command_serverDev]
    * start `elm-go` at http://localhost:8000

Command `watchStartElm`

* [function bootstrap] (see above)
* Watch all Elm files in `elm-starter` folder and `src/Index.elm` for modifications
* If there is a change, it run the command `generateDevFiles` (see below)

Command `generateDevFiles`

* [function bootstrap] (see above)
* [function command_generateDevFiles] (see above)

..TO BE CONTINUED

Non-goals

Things that elm-starter is not expected to do

Doesn't generate Elm code automatically, like Route-parser, for example
Doesn't touch/wrap the code of your Elm Application
Doesn't do live SSR (Server Side Render) but just pre-render during the build
Doesn't change the Javascript coming out from the Elm compiler
Doesn't create a web site based on static files containing Markdown
There is no "hydration", unless Elm does some magic that I am not aware of.

You can find several of these characteristics in some of the similar projects.

Using as reference the table at the bottom of the article Rendering on the Web, elm-starter can support you in these rendering approach

Static SSR
CSR with Prerendering
Full CSR

It cannot help you with

Server Rendering
SSR with (re)hydration

Similar projects

These are other projects that can be used to bootstrap an Elm application or to generate a static site:

elm-pages
elmstatic
elm-spa
create-elm-app
spades
gulp-elm-starter-project

Here are similar projects for other Languages/Frameworks:

staticgen.com

Files

README.md

Latest commit

History