# Thoughts on best practice for distributing examples with packages?

**URL:** <https://discourse.elm-lang.org/t/thoughts-on-best-practice-for-distributing-examples-with-packages/1832>\
**Category:** Learn\
**Created:** [August 31, 2018, 1:14pm UTC](https://discourse.elm-lang.org/t/thoughts-on-best-practice-for-distributing-examples-with-packages/1832 "2018-08-31T13:14:57Z")\
**Posts on this page:** 6\
**Page:** 1

<div class="post-metadata">

**Author:** ![rupert](https://yyz1.discourse-cdn.com/flex035/user_avatar/discourse.elm-lang.org/rupert/32/1775_2.png) [@rupert](https://discourse.elm-lang.org/u/rupert)\
**Post date:** [August 31, 2018, 1:14pm UTC](https://discourse.elm-lang.org/t/thoughts-on-best-practice-for-distributing-examples-with-packages/1832/1 "2018-08-31T13:14:57Z")

</div>

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?

---

<div class="post-metadata">

**Author:** ![mattpiz](https://yyz1.discourse-cdn.com/flex035/user_avatar/discourse.elm-lang.org/mattpiz/32/860_2.png) [@mattpiz](https://discourse.elm-lang.org/u/mattpiz)\
**Post date:** [August 31, 2018, 4:35pm UTC](https://discourse.elm-lang.org/t/thoughts-on-best-practice-for-distributing-examples-with-packages/1832/2 "2018-08-31T16:35:23Z")

</div>

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`, an`index.html` loading a `Main.js` result of `elm make Main.elm --output Main.js`. So, I just put something like this in the readme:

```auto
# 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.

---

<div class="post-metadata">

**Author:** ![joelq](https://yyz1.discourse-cdn.com/flex035/user_avatar/discourse.elm-lang.org/joelq/32/445_2.png) [@joelq](https://discourse.elm-lang.org/u/joelq)\
**Post date:** [August 31, 2018, 5:10pm UTC](https://discourse.elm-lang.org/t/thoughts-on-best-practice-for-distributing-examples-with-packages/1832/3 "2018-08-31T17:10:12Z")

</div>

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.

---

<div class="post-metadata">

**Author:** ![wbrian](https://yyz1.discourse-cdn.com/flex035/user_avatar/discourse.elm-lang.org/wbrian/32/119_2.png) [@wbrian](https://discourse.elm-lang.org/u/wbrian)\
**Post date:** [August 31, 2018, 5:26pm UTC](https://discourse.elm-lang.org/t/thoughts-on-best-practice-for-distributing-examples-with-packages/1832/4 "2018-08-31T17:26:15Z")

</div>

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.

---

<div class="post-metadata">

**Author:** ![rupert](https://yyz1.discourse-cdn.com/flex035/user_avatar/discourse.elm-lang.org/rupert/32/1775_2.png) [@rupert](https://discourse.elm-lang.org/u/rupert)\
**Post date:** [August 31, 2018, 6:37pm UTC](https://discourse.elm-lang.org/t/thoughts-on-best-practice-for-distributing-examples-with-packages/1832/5 "2018-08-31T18:37:59Z")

</div>

> [@mattpiz](#):
>
> I’m not sure what is considered “hassle-free”

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.

---

<div class="post-metadata">

**Author:** ![system](https://canada1.discourse-cdn.com/flex035/uploads/elm_lang/original/1X/50a05e53677a2c3b47776d7abd0f113eb50193a1.png) [@system](https://discourse.elm-lang.org/u/system)\
**Post date:** [September 10, 2018, 6:38pm UTC](https://discourse.elm-lang.org/t/thoughts-on-best-practice-for-distributing-examples-with-packages/1832/6 "2018-09-10T18:38:04Z")

</div>

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