Thoughts on best practice for distributing examples with packages?

Learn
1

The first thing I do when I try out a significant new package is to try out its examples. If this experience sucks, it definitely clouds my view of the package.

It used to be that you could make code in an /example folder run under elm-reactor with a custom index.html file and using the _compile directory, but no longer.

It would be nice to be able to distribute examples with a working build and instructions on how to run it, that lets some one get it up and running with zero hassle, and to be able to do this even when the example requires ports, imported CSS, 3rd party javascript libs etc.

The canonical (yet unofficial) way to do that in Elm 0.18 would be to use the _compile directory, and rely one elm-reactor to serve assets from the filesystem. Instructions were always:

cd example ; elm-reactor

Then browse to localhost:8000/index.html

What do you think the best way of presenting hassle-free examples is with 0.19?

1 Like
2

I’m not sure what is considered “hassle-free” but I’m used to put each example in it’s own folder with an elm.json, a Main.elm, anindex.html loading a Main.js result of elm make Main.elm --output Main.js. So, I just put something like this in the readme:

# To start any of the examples
$ elm make Main.elm --output Main.js
$ python3 -m http.server 8888

Trying the examples is then as easy as go in that directory, and copy paste 2 lines (second line can change to your favorite static server). I don’t think that’s very complicated.

3

For smaller examples, linking to an Ellie can be a nice way to show off a package. It lets potential users try it out without needing to download.

3 Likes
4

I want to add that this is something that rust got right. There are standard conventions for packaging examples and the package manager supports running examples. e.g. cargo run --example name-of-example

I would love to see first class support for this, or at the very least, well-defined conventions.

3 Likes
5

By hassle-free I mean that someone can download and run it without having to follow a long and complex set of instructions. For example, on Linux you might expect that to install a package (from source) this should work:

./configure
make

I usually give up if that doesn’t work, or at least try out the alternatives to see if there is something better.

That is kind of the attraction of elm reactor and examples based on it.

6

This topic was automatically closed 10 days after the last reply. New replies are no longer allowed.