Elm App Boilerplate
Provides an efficient development workflow and a starting point for building Elm applications.
- automated build of all application resources using webpack
- Hot Module Replacement for the Elm code using elm-hot-loader
- styling using elm-css
- continuous integration and deployment based on Shippable
- dependency checking using npm-check-updates
- consistent code formatting using elm-format
Fork and clone this repo.
npm install npm start
http://localhost:8080/ in a browser.
For an alternative host or port run:
npm start -- --host=0.0.0.0 --port=8081
Run tests once off:
Restart the tests on code change:
The deployment is automated using Shippable and is triggered as follows:
npm version [major|minor|patch]on the
- Add release notes in GitHub.
On success, the demo app is deployed to elm-app-boilerplate GitHub Pages.
Build Configuration Using Environment Variables
The default environment variables used by the build scripts are defined in the
.env file. The defaults are always overridden by the variables defined in the environment. They are useful for abstracting away the differences between the development and production environments. For example, the following command builds the application with a custom
BASE_PATH suitable for deployment to GitHub Project Pages.
BASE_PATH=/elm-app-boilerplate npm run build
The environment variables are first available to the
Currently the following variables are supported:
BASE_PATH- defines the location of the generated JS and CSS files, and is prepended to all pathnames handled by the Elm application.
This project customizes the standard
npm version script to also:
- ensure that the dependencies are up to date
- execute all tests
- update the version in
- push the branch on which the version change was made
- push the created tag
Dependency check and update is handled by ncu. A check runs automatically every time
npm version is executed but can also be triggered explicitly.
npm run ncu # checks the dependencies in package.json npm run ncu -- -a # updates all dependencies in node_modules and package.json
ncu parameters and flags have to be specified after
The following Elm commands are exposed through npm scripts:
npm run elm
npm run elm-reactor
npm run elm-repl
npm run elm-package
npm run elm-make
npm run elm-test
The parameters to those commands must be specified after
--, for example:
npm run elm-package -- install evancz/elm-effects. See npm run-script.
.editorconfig- configures the white space rules for text editors
.env- defines the default environment variables used by
.gitignore- defines files and directories ignored by
.npmrc- configuration for
npm, currently used to provide a message template for
package.json- defines dependencies and scripts for building, testing and running the application
shippable.yml- configuration of the continuous integration and deployment process based on Shippable
webpack.config.babel.js- webpack configuration used for building and running the application
dist/- built application artifacts produced by
npm run build
elm-package.json- describes the Elm application and its dependencies
src/- Elm source files
src/Main.elm- Elm application entry point
src/Stylesheets.elm- elm-css entry point, lists all the stylesheets which need to be processed
src/App/- the namespace for all application Elm modules
src/App/Etc/- contains configuration modules
src/App/Etc/Config.elm- the Elm app configuration
src/App/Etc/Style.elm- the configuration for stylesheets, including the color palette, device breakpoints, font sizes, etc
src/App/Section/- contains all sections. A section groups related pages and manages routing within its group
src/App/Section/<SomeSection>/Route.elm- contains route mappings and helpers for
src/App/Page/- contains all pages. Page are responsible for the main contents of their sections
src/App/Widget/- contains all reusable widgets
src/App/**/<SomeModule>/Css.elm- contains the CSS rules for
src/App/**/<SomeModule>/Style.elm- contains style-related types and definitions for
<SomeModule>, which are shared between the application and the Elm CSS modules
tests/elm-package.json- defines dependencies for running tests
tests/App/**/<SomeModule>Test.elm- contains tests for
html-minifier.json- configuration file used by the
html/index.html- overall application entry point
Use a BEM-like methodology for styling.
Because the CSS class names are generated from the Elm class names, it is not feasible to follow the BEM class name format. So, here's an alternative:
- Using the
namespace's, prefix the CSS class names with a letter "p", "s", "w" corresponding to the folder in which the component is located - "Page", "Section", "Widget" respectively. It allows to quickly find the Elm components based on the CSS class names during debugging.
- Specify longer
namespaces when you're creating specializations of other components. For example, the
Menucomponent uses "w" prefix by default. The
MainMenucomponent is a specialization of the
Menucomponent, so it uses "wMain" prefix. When combined with the
CssClass'es, the generated CSS class names correspond to the
MainMenucomponent name, that is, block-level class is
- Separate the blocks, elements and modifiers with a single underscore.
- Use PascalCase for the block and element names.
- Use camelCase for the modifier names.
- Avoid passing parameters to
CssClassconstructors as much as possible, because they limit the safety guarantees afforded by
elm-css. If the parameters are really necessary, try to limit yourself to Int only.
Here's an example - using the following Elm definitions:
namespace = withNamespace "w" type CssClass = Block | Block_modifier | Block_modifierWithParam Int | Block_Element | Block_Element_modifier | Block_Element_modifierWithParam Int
we can get CSS class names like these:
.wBlock .wBlock_modifier .wBlock_modifierWithParam-1 .wBlock_modifierWithParam-2 .wBlock_modifierWithParam-3 .wBlock_Element .wBlock_Element_modifier .wBlock_Element_modifierWithParam-1 .wBlock_Element_modifierWithParam-2 .wBlock_Element_modifierWithParam-3