add section about compiling multiple elm modules into the same output… (

#1038)

src/languages/elm.md

@@ -75,6 +75,39 @@ view model =
 
 {% endsample %}
 
+## Compiling multiple files into a single JS output
+
+You can use the `with` query param to compile multiple Elm sources into the same bundle. This can help you keep the bundle size smaller, because things like the runtime and common code are shared.
+
+{% sample null, "column" %}
+{% samplefile "index.js" %}
+
+```js
+import { Elm } from "./Main.elm?with=./MainB.elm&with=./MainC.elm";
+
+Elm.Main.init({ node: document.getElementById("root") });
+Elm.MainB.init({ node: document.getElementById("rootB") });
+Elm.MainC.init({ node: document.getElementById("rootC") });
+```
+
+{% endsamplefile %}
+{% endsample %}
+
+This will do the equivalent of this command:
+
+```
+elm make Main.elm MainB.elm MainC.elm
+```
+
+The `with` param can be used multiple times to include multiple extra Elm programs.
+
+Beware of 2 things:
+
+1. **Path base:** The paths given in the `with` param values are relative to the directory of the first file in the `import` statement (in this case `Main.elm`), NOT relative to the JS file that contains the `import` statement.
+2. **Unintentional Duplication:** Multiple imports that effectively specify the same Elm files but in a different order (or differ regarding leading `./`, etc.) are treated as different assets (and will therefore be duplicated)
+
+To avoid those pitfalls when making heavy use of `with` params (i.e. importing some combination in more than one place), it's recommended to use something like [this third-party resolver package](https://www.npmjs.com/package/parcel-resolver-elm-bundle) which allows specifying some shorthands for commonly used Elm file combinations.
+
 ## Time-travelling debugger
 
 Elm's debug mode is automatically enabled when not building for production (it is disabled automatically with `parcel build`). You can set the environment variable `PARCEL_ELM_NO_DEBUG=1` to disable it even in development mode.