elm-optimize-level-2/README.md

Elm Optimize

NOT FOR SHARING YET - Please wait for the announcement before sharing widely, it should be coming soon :)

Note, Experimental - This project is just starting. While we currently believe every adjustment to the resulting javascript should be safe and make things explicitly faster, it's hard to be 100% certain until we have a large number of projects using it successfully. So, beware!

And let us know how it goes by leaving a comment in this issue. 😃

Elm is fast.

Can we make it faster?

Turns out, yes! 🚀

Elm Optimize is a project for exploring different optimizations that are specific to elm-generated javascript.

There are two parts to this.

1. Explore different javascript representations for Elm code. This means gathering data on what a given representation would mean on realworld projects, and across browsers.

2. A tool you can use right now to compile elm using the adjustments that have given us the most speed!

Note This work was given a massive headstart by Robin Heggelund Hansen's article on areas where the Elm Compiler's output could be improved. Go read it! It's great.

Installation and Usage

npm install -g elm-optimize

Then you can use elm-optimize just as you would elm-make --optimize.

elm-optimize Main.elm

will generate an elm.js file.

The only configurable option is what to name the generated js file.

elm-optimize Main.elm --output app.js

Note — elm-optimize only generates a js file, it doesn't support generating HTML.

Another Note — Before deploying your app, you should also minify it and gzip it. elm-optimize does not do that for you. Check out this doc for a recommended setup.

What's actually happening?

This might seem a bit like magic. ✨

If you're interested in getting to know what's happening, here's an overview of all the JS transformations we are exploring!

Not all of them are included in the CLI tool because not all of them turned out to be beneficial. Part of this endeavor is a science project :bowtie:, where we capture data so we can know which transformations turn out to be worthwhile.

A few are listed there as either incomplete or not attempted. That's future work!

Benchmarks

Note — These results are really exciting! However, it's not totally obvious that your project will see similar gains. Performance is a tricky beast! If you do see significant speedups in your project, leave a comment here on this issue, we love to see realworld cases.

In an effort to quantify these transformations, we've put together a number of benchmarks, including some from exisiting Elm packages such as dillonkearns/elm-markdown, w0rm/elm-obj-file, and mdgriffith/elm-ui.

Our goal is to have benchmarks that track performance on code where performance is meaningful.

Here's the most recent, comprehensive run of the benchmarks.

Though here are a few highlights:

Note — keep in mind that these numbers have all the caveats that benchmarks usually have. You may not see similar numbers depending on your machine, your browser, subtle differences in your code, etc.

Another Note — From what we've seen, given that you're minifying and gzipping your JS, these transformations should either have no effect on asset size, or may even make your app slightly smaller.

Html

Name	Transformtions	Browser	Ops/Second	% Change
create a 4 level nested html tree		safari	34,899
create a 4 level nested html tree	final	safari	39,631	(114%)
create a 4 level nested html tree		firefox	15,909
create a 4 level nested html tree	final	firefox	22,361	(141%)
create a 4 level nested html tree		chrome	28,959
create a 4 level nested html tree	final	chrome	72,753	(251%)

Elm Markdown

Name	Transformtions	Browser	Ops/Second	% Change
dillonkearns/elm-markdown		safari	2,428
dillonkearns/elm-markdown	final	safari	3,196	(132%)
dillonkearns/elm-markdown		firefox	1,096
dillonkearns/elm-markdown	final	firefox	2,194	(200%)
dillonkearns/elm-markdown		chrome	2,489
dillonkearns/elm-markdown	final	chrome	3,572	(144%)

Running Benchmarks Locally

1. Clone this repo
2. Run npm install
3. Run npm run report and a simple benchmark will hopefully run and print results to the terminal.

Note you can control which benchmark runs with which transformation by adjusting src/benchmarks/run.ts.

Contributing

For this project, contributions always start with communication before code!

That being said, there are a few areas that might be opportunities for contribution.

1. Try elm-optimize on any current Elm project you have!

   We'd love to hear your results whether they be success, no effect, or caused a regression.

   If your project saw an explicit improvement or performance regression, leave a comment on this issue.

   For more serious issues, feel free to file a separate issue.

2. Are there more interesting benchmarks we could track?

   We want the benchmarking suite to be as comprehensive as possible, though we have to weigh that against having a million benchmarks that essentially test the same thing.

3. Know of an interesting transformation to try out?

   Let us know! Either open an issue, or make a PR adding it to notes/transformations.md.

4. Know of an article, paper, or project we might be interested in?

   Let us know! We're keeping a list of relevant resources in notes/resources.md