Elm Batteries Included

A project template and a generator to:

• Develop Elm apps with Parcel, Netlify, Tailwind CSS and Cypress
• Learn how these delightful web technologies work together 😋
• Get started with Elm css, navigation, routes, remote data and JSON decoder

---

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

Links

• Demo: elm-batteries.netlify.com/demo
• Documentation: concat.dev/elm
• News and support:
  • Twitter
  • Mailing list
  • Slack (ping @CedricSoulas)

Features

• Elm app with css, navigation, routes, remote data and JSON decoder
• Local web server and serverless functions
• Hot code and style reloading, keeping app state
• Front-end testing
• Optimized and minified production build
• Live, preview and production deployments

Table of contents

• Setup
  • Generate a new project from this template
• Local development
  • Develop (Elm + Parcel)
  • Develop with serverless functions (Elm + Parcel + Netlify Dev)
  • Run a live session
• Testing
  • Run Cypress
  • Run unit and fuzz tests
• Production build and deployment
  • Build for production and deploy a preview
  • Deploy to production
  • Going further
• Designing
  • Tailwind
  • CSS build tools
• See also
  • Html meta tags
  • Elm Navigation

Documentation

Setup

Generate a new project

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

Install the dependencies:

npm install

💡 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 (Elm + Parcel)

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

Develop with serverless functions (Elm + Parcel + Netlify Dev)

To run serverless functions along your Elm app, run:

npm run dev

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

• Web page: http://localhost:8888
• Serverless function example:
  • http://localhost:8888/.netlify/functions/version
  • source: functions/version/version.js

Run a live session

To share your development session with a coworker, run:

npm run dev:live

✓ development build with Parcel
✓ live session 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 then you should see your application loaded:

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

✓ 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:

• postcss (read postcss.config.js),
• autoprefixer to add vendor prefixes,
• purgecss to remove unused selectors,
• and cssnano to compress the css (by default with Parcel).

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.

Site and sources

• Documentation: concat.dev/elm/batteries
• Project template: github.com/cedricss/elm-batteries
• News and support:
  • Twitter
  • Mailing list
  • Slack (ping @CedricSoulas)
• Built with elm-batteries:
  • reactive.how/rxjs
  • concat.dev

License

Authored by Cédric Soulas, released under the MIT License.