Getting started

1. Installation
2. Quick start
3. HTML and other files

Installation

npm install --save-dev elm-watch

ℹ️ You need to install Elm itself separately, in whatever way you prefer (installer, npm, unofficial npm, elm-tooling).

ℹ️ Node.js 16 or newer is required.

npx elm-watch --help

Quick start

📽 Video showing how to get started

ℹ️ If you don’t already have an Elm project, create one by running elm init.

ℹ️ Also make sure you have an HTML file. If it works with plain elm make, it works with elm-watch. See the next section for inspiration.

Create a file called elm-watch.json:

npx elm-watch init

{
    "targets": {
        "My target name": {
            "inputs": [
                "src/Main.elm"
            ],
            "output": "build/main.js"
        }
    }
}

Start watching with hot reloading:

npx elm-watch hot

The command prints the link to a local development HTTP server (which is completely optional to use, but easy to get started with).

To build for production:

npx elm-watch make --optimize

HTML and other files

elm-watch is only responsible for turning your Elm files into JS files. Like running elm make src/Main.elm --output build/main.js yourself. So that’s the mindset you need to have.

You are responsible for creating an HTML file, linking to the built JS and initializing the app.

Here’s some HTML to get you started.

• For Browser.sandbox and Browser.element:

  <!-- Absolute URL to the built JS. -->
  <script src="/build/main.js"></script>
  <div id="root"></div>
  <script>
    var app = Elm.Main.init({ node: document.getElementById("root") });
  </script>
  

  👉 Minimal example

• For Browser.document and Browser.application:

  <!-- Absolute URL to the built JS. -->
  <script src="/build/main.js"></script>
  <script>
    var app = Elm.Main.init();
  </script>
  

• If you need TypeScript and CSS compilation, you need to set up another build tool alongside elm-watch.

  <!-- Separate script tag for Elm. -->
  <script src="/build/main.js"></script>
  <!-- Another script tag for JS built by another tool. -->
  <script src="/build/bundle.js"></script>
  

  👉 Example with esbuild

ℹ️ elm-watch requires window.Elm to exist!