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

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:** If you import an import line with `with` params in multiple JS files but the query string is not exactly the same, parcel will treat it as a different asset and duplicate the content.
+
+To avoid those pitfalls, it's recommended to use [this extra resolver package](https://www.npmjs.com/package/parcel-resolver-elm-bundle), when making heavy use of with params (i.e. importing the bundles in more than 1 JS file, using the `with` more than 2 times)
+
 ## 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.