elm-watch.json

An elm-watch.json file is required to be able to use elm-watch. There’s not that much to know about it.

You can place it anywhere, basically. elm-watch uses the closest elm-watch.json file it finds up the directory tree. You can have a single elm-watch.json for several apps with different elm.json if you want.

The contents of elm-watch.json looks like this (TypeScript definition):

type NonEmptyArray<T> = [T, ...Array<T>];

type ElmWatchJson = {
  postprocess?: NonEmptyArray<string>;
  port?: number;
  webSocketUrl?: string; // ⚠️ elm-watch@beta only
  serve?: string; // ⚠️ elm-watch@beta only
  targets: {
    [name: string]: {
      inputs: NonEmptyArray<string>;
      output: string;
    };
  };
};

Example:

{
    "postprocess": ["elm-watch-node", "postprocess.js"],
    "port": 9876,
    "targets": {
        "My target name": {
            "inputs": [
                "src/Main.elm"
            ],
            "output": "build/main.js"
        },
        "😎 My other target": {
            "inputs": [
                "src/One.elm",
                "src/Two.elm"
            ],
            "output": "build/other/dist.js"
        }
    }
}

Property	Type	Default	Description
targets	`Record<string, object>`	Required	The input Elm files to compile and the output JavaScript files to write to. At least one target is required.
postprocess	`NonEmptyArray<string>`	No postprocessing.	A command to run after each `elm make` to transform Elm’s JavaScript output.
port	`number`	An arbitrary available port. Tries to re-use the same port as last time you ran elm-watch.	The port for elm-watch’s HTTP and WebSocket server, used for hot reloading and as a simple file server. In case you have to have the exact same port every time. Note that some ports cannot be used.
⚠️ webSocketUrl	`string`	`ws://${currentHostname}:${port}/elm-watch` (sort of)	Only available in `elm-watch@beta`. This lets you customize how the elm-watch client connects its WebSocket for advanced use cases. You can also use the `ELM_WATCH_WEBSOCKET_URL` environment variable for dynamically setting it (the environment variable takes precedence). The value must be a valid URL starting with `ws:` or `wss:`.
⚠️ serve	`string`	unset	Only available in `elm-watch@beta`. A directory of static files to serve.

targets

There isn’t much to say about "targets" really. You define what elm-watch should compile.

It’s an object. The keys can be whatever you want, basically. They’re displayed in the terminal UI. They’re passed to your postprocess script. You can also filter by target substring: elm-watch make app 🇸🇪 would build only targets containing “app” or “🇸🇪”.

For each target, provide the following:

inputs: NonEmptyArray<string>. List of .elm files, relative to elm-watch.json. You probably only need one input, but if you’ve ever used elm make with multiple inputs – you can do that with elm-watch as well.
output: string. A .js file, relative to elm-watch.json. Unlike elm make, only .js is supported (and .html isn’t). Once you reach for elm-watch, you’re ready to be in charge of your own HTML file.