Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/cedricss/elm-batteries
Learn how Elm, Parcel, Cypress and Netlify work together. Get started with Elm navigation, routes, remote data and decoder.
https://github.com/cedricss/elm-batteries
cypress elm elm-test netlify parcel postcss purgecss tailwind-css
Last synced: 2 months ago
JSON representation
Learn how Elm, Parcel, Cypress and Netlify work together. Get started with Elm navigation, routes, remote data and decoder.
- Host: GitHub
- URL: https://github.com/cedricss/elm-batteries
- Owner: cedricss
- License: mit
- Created: 2019-03-25T09:34:07.000Z (over 5 years ago)
- Default Branch: master
- Last Pushed: 2021-10-21T19:44:16.000Z (about 3 years ago)
- Last Synced: 2024-10-09T19:05:36.484Z (2 months ago)
- Topics: cypress, elm, elm-test, netlify, parcel, postcss, purgecss, tailwind-css
- Language: Elm
- Homepage: https://elm-batteries.netlify.com/demo
- Size: 686 KB
- Stars: 116
- Watchers: 6
- Forks: 4
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
[](http://opensource.org/licenses/MIT)
[](https://elm-batteries.netlify.com)
# Elm Batteries Included
A project template and a generator to:
- Learn how [Elm](https://elm-lang.org/), [Parcel](https://parceljs.org), [Cypress](https://www.cypress.io) and [Netlify](https://www.netlify.com) 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 ›**](#table-of-contents)
## Quick Start
- `npm init elm-batteries ./my-elm-app`
- or `yarn create elm-batteries ./my-elm-app`
- or [generate from Github](https://github.com/cedricss/elm-batteries/generate)
[**Learn more ›**](#setup)
The generated Elm app. Started with Parcel
behind Netlify Dev and tested with Cypress:
Test file source:
demo.spec.js
## Links
- Demo: [elm-batteries.netlify.com/demo](https://elm-batteries.netlify.com/demo)
- Twitter: [@CedricSoulas](https://twitter.com/CedricSoulas)
- Newsletter: [concat.dev/elm](https://concat.dev/elm#subscribe)
- Chat: [Slack](https://elmlang.herokuapp.com/) (ping @CedricSoulas)
- Forum: [Discourse thread](https://discourse.elm-lang.org/t/elm-batteries-elm-parcel-cypress-netlify-project-template/4077)
## Overview
Usage with npm or yarn
## Table of contents
- Setup
- [From the CLI](#from-the-CLI)
- [From the repository template](#from-the-repository-template)
- Local development
- [Develop](#develop)
- [Run a live session](#run-a-live-session)
- Testing
- [Run Cypress](#run-cypress)
- [Run unit and fuzz tests](#run-unit-and-fuzz-tests)
- Production build and deployment
- [Build for production and deploy a preview](#build-for-production-and-deploy-a-preview)
- [Deploy to production](#deploy-to-production)
- [Going further](#going-further)
- Designing
- [Tailwind](#designing)
- [CSS build tools](#designing)
- See also
- [Html meta tags](#meta-tags)
- [Elm Navigation](#navigation)
## Setup
### From the CLI
The CLI lets you pick the batteries to include in your app:
#### `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
Click [Use this template](https://github.com/cedricss/elm-batteries/generate) to generate a new public or private project from [elm-batteries](https://github.com/cedricss/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](https://yarnpkg.com), run `yarn ` (instead of `npm run `). 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
```bash
npm run dev
```
or
```bash
yarn dev
```
Then open [localhost:8888](http://localhost:8888)
> ✓ development build with [Parcel](https://parceljs.org/)
> ✓ web server with Parcel behind [Netlify Dev](https://www.netlify.com/docs/cli/#netlify-dev-beta)
> ✓ serverless functions on your local machine
> ✓ hot code swapping with [elm-hot](https://github.com/klazuka/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](https://github.com/cedricss/elm-batteries/blob/master/PARCEL.md) to use this project template without Netlify Dev and serverless functions.
### Run a live session
To share your development session with a coworker, run:
```bash
npm run dev:live
```
> ✓ development build with [Parcel](https://parceljs.org/)
> ✓ live sharing with [Netlify Dev](https://www.netlify.com/docs/welcome/)
## Testing
### Run Cypress
These tests are in `cypress/integration/*`. [Start your Elm app](#1-develop-with-serverless-functions) then launch the Cypress runner app:
```bash
npm run cypress:open
```
If you open one test from the list of spec files (for example [demo.spec.js](https://github.com/cedricss/elm-batteries/blob/master/cypress/integration/demo.spec.js)) then you should see your application loaded:
Alternatively, to run Cypress tests from the CLI without the GUI:
```bash
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 ›](https://docs.cypress.io/guides/references/best-practices.html#Selecting-Elements)
To learn more about Cypress and play with it, [install and start it](https://docs.cypress.io/guides/getting-started/installing-cypress.html#Installing) in a fresh new project folder: it will initialize a `cypress` folder with several examples.
### Run unit and fuzz tests
Install [elm-test](https://github.com/rtfeldman/node-test-runner).
These tests are in `tests/*`. To start the runner in [watch mode](https://github.com/rtfeldman/node-test-runner#--watch):
```bash
npm run test:watch
```
Alternatively, run it just once:
```bash
npm run test
```
## Production build and deployment
### Build for production and deploy a preview
```bash
npm run deploy
```
or
```bash
yarn deploy
```
> ✓ production build with [Parcel](https://parceljs.org/)
> ✓ compilation with the Elm `optimize` flag
> ✓ minification with [`terser`](https://github.com/terser-js/terser)
> ✓ deployment to a [Netlify](https://www.netlify.com/docs/welcome/) _Live Draft URL_
💡 If you are using Netlify for the first time, run `netlify login` to authenticate (learn more about [Netlify CLI](https://www.netlify.com/docs/cli/)).
💡 The JS code from Elm is minified with [special flags](https://elm-lang.org/0.19.0/optimize) 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
```bash
npm run deploy:prod
```
> ✓ deployment to production with [Netlify](https://www.netlify.com/docs/welcome/)
### Going further
`deploy` commands are great when rapidly iterating. Consider also setting up [continuous deployment with Netlify »](https://www.netlify.com/docs/continuous-deployment/).
## Designing
[Tailwind CSS](https://tailwindcss.com/), an utility-first CSS framework, is included along with:
- [`postcss`](https://postcss.org/) (read [`postcss.config.js`](postcss.config.js)),
- [`autoprefixer`](https://github.com/postcss/autoprefixer) to add vendor prefixes,
- [`purgecss`](https://github.com/FullHuman/purgecss) to remove unused selectors,
- and [`cssnano`](https://cssnano.co/) 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`](index.html) has meta tags included, like [Twitter Card](https://developer.twitter.com/en/docs/tweets/optimize-with-cards/guides/getting-started.html) 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`](https://package.elm-lang.org/packages/elm/browser/latest/Browser#UrlRequest) (read [Browser.application](https://package.elm-lang.org/packages/elm/browser/latest/Browser#application)).
- A [navigation `Key`](https://package.elm-lang.org/packages/elm/browser/latest/Browser-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
- Demo: [elm-batteries.netlify.com/demo](https://elm-batteries.netlify.com/demo)
- Documentation: [Table of contents](https://github.com/cedricss/elm-batteries#table-of-contents)
- Twitter: [@CedricSoulas](https://twitter.com/CedricSoulas)
- Newsletter: [concat.dev/elm](https://concat.dev/elm#subscribe)
- Chat: [Slack](https://elmlang.herokuapp.com/) (ping @CedricSoulas)
- Forum: [Discourse thread](https://discourse.elm-lang.org/t/elm-batteries-elm-parcel-cypress-netlify-project-template/4077)
- Project template: [github.com/cedricss/elm-batteries](https://github.com/cedricss/elm-batteries)
- Built with elm-batteries:
- [reactive.how/rxjs](https://reactive.how/rxjs)
- [concat.dev](https://concat.dev)
## License
Authored by [Cédric Soulas](https://twitter.com/CedricSoulas), released under the [MIT](LICENSE) License. Read [LICENSE](LICENSE).