Elm.mk

A fast, close-to-zero dependencies toolchain for Elm-based single page applications.

Philosophy

The main goal of this boilerplate is to minimise the needs for external dependencies while providing an effective development environment. This means that it tries as much as possible to bundle pre-compiled utilities to accomplish the needed tasks.

Features

Cross-platform (OS X + Linux 64bit - help with Windows would be nice)
Elm StartApp installation
Project scaffold generation
Elm compilation with warnings
Scss compilation via Wellington
Watch and recompile via modd
Live reload via devd
File generators based on templates
Optional support for elm test

Setup from scratch

mkdir my_new_project && cd my_new_project
curl -o elm.mk https://raw.githubusercontent.com/cloud8421/elm.mk/master/elm.mk
make -f elm.mk

This will generate the needed folder structure and files. Note that at the end of make -f elm.mk, you're left with an empty Makefile that includes elm.mk, so that you can extend it for your needs and/or override its behaviour.

Project workflow

Main commands:

make: compiles the project into build (installing dependencies if needed)
make dist: compiles the project into dist with production optimisations
make serve: serves the build folder with a local http server
make watch: starts the file watcher and the http server, recompiling files on save
make help: shows all main tasks
make config: shows paths used for project files
make tests: runs the entire test suite
make tests-watch: starts the test watcher, which reruns tests when files change

Some guidelines:

Files generated into build should not be edited manually.
Files generated into dist should not be edited manually. In addition, they're passed through optimisation steps which make them very difficult to read.
All other files can be modified.
Source .elm files should be placed in src.
Use boot.js to start your Elm application and define all ports-related glue code with the external world. The file gets copied automatically to build.
scss/main.scss is the stylesheet main file.
index.html gets copied the way it is into build.

It may also be worth checking out the documentation for the software used in this boilerplate (like Devd or Modd), as they provide functionality that it's not covered here.

Elm.mk development

If you're interested in contributing, please make sure you keep tests up to date.

After cloning this repository, just run make test (requires Ruby 2.x in your path, no extra dependencies).

Tests are maintained in tests.rb.

FAQs/Comments

Looking for a different version

Try the legacy branch.

I don't think this should use X, Y is a better fit.

As long as it's easy to install in portable format (i.e. download in the project folder and run), please feel free to state the case for a replacement

Why is feature X missing?

Probably because I haven't thought about it.

Why Make?

Make is ubiquitous, mostly pre-installed (or very easy to install) and language-agnostic. It takes some time to adjust to it, but it's fast, effective and modular.

This make task is not optimal, it's much better if you change it like this!

Please submit a PR, I'm happy to learn

cloud8421/elm.mk