Giter Club home page Giter Club logo

elm.mk's Introduction

Elm.mk

Build Status

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

I don't know Make, but I'd like to help. Where can I learn more?

elm.mk's People

Contributors

cloud8421 avatar mburri avatar

Stargazers

 avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar

Watchers

 avatar  avatar  avatar  avatar  avatar

Forkers

sjfloat c11z mburri

elm.mk's Issues

Tests not passing

after PR #25 tests do not pass with output

elm.mk$ make
...
./tests.sh
test #15 "ls dummy/build/images/test.jpg" failed:
	program terminated with code 2 instead of 0
test #16 "ls dummy/build/images/test.png" failed:
	program terminated with code 2 instead of 0
2 of 20 examples tests failed in 0.017s.
Makefile:4: recipe for target 'test' failed
make: *** [test] Error 1

It looks like build and build/images are part of the INSTALL_TARGETS. Calling make after make install results in the images being cp'd to build/images/images which breaks the test. The dist is unaffected because it is not part of the INSTALL_TARGETS and images are cp'd directly from the root images folder.

Removing build and build/images from the INSTALL_TARGETS solves the problem.

I am opening a PR, and would love your feedback. Great project by the way.

Replace goat

Goat doesn't show proper output for failed tasks, making it difficult to debug compilation errors.

Other alternatives, like https://facebook.github.io/watchman/, do a better job, but they're tricky to include as they need to be compiled.

Support images

Add a basic task that copies images to the build folder, possibly doing some basic optimisation.

Separate generated elm files

After using this a few times, I always find myself separating the generated Main.elm file into Main.elm, View.elm, State.elm and Types.elm. Should just generate separate files from the start.

Update for Elm 0.17

This includes:

  • Check if current compile flags are still valid
  • Update src/Main.elm template
  • Update interop.js template
  • Check make test to confirm it still works as expected

Revise interop layer

Currently there's some confusion on the interop layer side of things, particularly around file naming.

The current interop boilerplate is used to boot the app and handle all interop-related code, but this is not clear.

A good change would be to rename interop to app: that way elm.mk generates 2 files:

  • a main.js file, from Elm compilation, which is the compiled Elm Main module.
  • a app.js file, which boots the Elm app and handles ports.

This way we can also revise the target resolution logic, so that if a file is called app.js is considered a pure js file, while anything else would be considered an Elm target.

Investigate installing Elm if not present

Elm is currently available either as a standalone download or as a npm package. It would be interesting to see if it's possible/feasible/reasonable to integrate this with elm.mk.

include elm-format as dev tool

It would be nice to include elm-format in the dev-tools - even if it's not used to build the project I usually set up my editor to use elm-format on save but i don't want to install it globally.

It would also help beginners to setup their dev environment

Won't compile if all .elm files are in main src/ dir

Heya, saw this on elm-discuss. I think this project is a great idea! I replaced my simple Makefile with yours, and tried it out. First issue I ran into was that it requires you two have at least one directory of .elm files inside your /src dir. The project I tried it out in is very simple, and all .elm files are directly in the "root" /src dir. Here's some output demonstrating the issue:

$ make
test -s src/Main.elm || echo "$main_elm" > src/Main.elm
make: *** No rule to make target 'src/**/*.elm', needed by 'build/main.js'.  Stop.
$ mkdir src/asdf
$ touch src/asdf/asdf.elm
$ make
test -s src/Main.elm || echo "$main_elm" > src/Main.elm
elm make src/Main.elm --yes --warn --output build/main.js
Success! Compiled 1 modules.                                        
Successfully generated build/main.js
...

This would be a PR, but I don't really know make well enough!

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    ๐Ÿ–– Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. ๐Ÿ“Š๐Ÿ“ˆ๐ŸŽ‰

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google โค๏ธ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.