Skip to content
/ elm-batteries Public template

Learn how Elm, Parcel, Cypress and Netlify work together. Get started with Elm navigation, routes, remote data and decoder.

License

Notifications You must be signed in to change notification settings

cedricss/elm-batteries

Folders and files

NameName
Last commit message
Last commit date

Latest commit

Β 

History

62 Commits
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 

Repository files navigation

MIT license Netlify Status

Elm Batteries Included

A project template and a generator to:

  • Learn how Elm, Parcel, Cypress and Netlify work together πŸ˜‹
  • Get started with Elm css, navigation, routes, remote data and JSON decoder

Features

  • Local web server and optional serverless functions
  • Hot code and style reloading, keeping app state
  • CSS transformations with postcss (autoprefixer, purgecss...)
  • Front-end testing
  • Optimized and minified production build
  • Preview and production deployments

Table of contents β€Ί

Quick Start

  • npm init elm-batteries ./my-elm-app
  • or yarn create elm-batteries ./my-elm-app
  • or generate from Github

Learn more β€Ί

The generated Elm app. Started with Parcel
behind Netlify Dev and tested with Cypress:

elm-batteries template demo

Test file source: demo.spec.js

Links

Overview

Usage with npm or yarn

Website documentation (sneak peek)

Table of contents

Setup

From the CLI

The CLI lets you pick the batteries to include in your app:

create-elm-batteries cli generator

npm

npm init elm-batteries ./my-elm-app
cd my-elm-app && npm run dev

or yarn

yarn create elm-batteries ./my-elm-app
cd my-elm-app && yarn dev

From the repository template

Use this Github Template

Click Use this template to generate a new public or private project from elm-batteries.

Install the dependencies with npm install or yarn install and run npm run dev or yarn dev.


πŸ’‘ In the following documentation, if you use yarn, run yarn <command-name> (instead of npm run <command-name>). Alternatively, you can define short aliases in your terminal to run these commands.

Local development

Develop

To run serverless functions along your Elm app, run

npm run dev

or

yarn dev

Then open localhost:8888

Netlify Dev on top of Parcel and serverless functions

βœ“ development build with Parcel
βœ“ web server with Parcel behind Netlify Dev
βœ“ serverless functions on your local machine
βœ“ hot code swapping with elm-hot

⚠️ Netlify Dev connects to the 1234 default Parcel port. Make sure this port isn't used by another application.

Develop without Netlify Dev

Read Elm + Parcel to use this project template without Netlify Dev and serverless functions.

Run a live session

To share your development session with a coworker, run:

npm run dev:live

βœ“ development build with Parcel
βœ“ live sharing with Netlify Dev

Testing

Run Cypress

These tests are in cypress/integration/*. Start your Elm app then launch the Cypress runner app:

npm run cypress:open

If you open one test from the list of spec files (for example demo.spec.js) then you should see your application loaded:

Cypress runner app

Alternatively, to run Cypress tests from the CLI without the GUI:

npm run cypress

The Elm app uses data-* attributes to provide context to the selectors and insulate them from CSS or JS changes. Learn more β€Ί

To learn more about Cypress and play with it, install and start it in a fresh new project folder: it will initialize a cypress folder with several examples.

Run unit and fuzz tests

Install elm-test.

These tests are in tests/*. To start the runner in watch mode:

npm run test:watch

Alternatively, run it just once:

npm run test

Production build and deployment

Build for production and deploy a preview

npm run deploy

or

yarn deploy

βœ“ production build with Parcel
βœ“ compilation with the Elm optimize flag
βœ“ minification with terser
βœ“ deployment to a Netlify Live Draft URL

πŸ’‘ If you are using Netlify for the first time, run netlify login to authenticate (learn more about Netlify CLI).

πŸ’‘ The JS code from Elm is minified with special flags that work for Elm apps because they have no side-effects (otherwise it would be unreliable to use such flags).

If this preview looks good, deploy to production.

Deploy to production

npm run deploy:prod

βœ“ deployment to production with Netlify

Going further

deploy commands are great when rapidly iterating. Consider also setting up continuous deployment with Netlify Β».

Designing

Tailwind CSS, an utility-first CSS framework, is included along with:

purgecss and cssnano are used on production mode to minify the css. They are ignored on development mode.

See also

Meta tags

index.html has meta tags included, like Twitter Card tags and Open Graph tags. Make sure to update their values and the content preview image (img/content_preview.jpg).

Elm

Navigation

  • All links in an application create a UrlRequest (read Browser.application).
  • A navigation Key is needed to create navigation commands that change the URL: it is stored in the Model.
  • Nav.pushUrl changes the address bar without starting a page load.

Links and sources

License

Authored by CΓ©dric Soulas, released under the MIT License. Read LICENSE.