elm-watch

• Fixed: If elm-watch make fails while installing dependencies and you have postprocess in elm-watch.json, elm-watch now exits instead of hanging.

• Built-in HTTPS has been removed.
• You can now execute elm-watch from a Node.js script, and pass in a custom the HTTP server. This allows for setting up HTTPS, or adding proxying.
• The static file server can no longer be tricked into serving files outside the static file directory via percentage escaped double dots.

elm-watch now has built in support for CSS hot reloading!

When .css files in the static files directory that is served changes, elm-watch reloads them in the browser.

I think it makes sense to have in elm-watch, since Elm does not offer a definitive styling answer. CSS can be a pretty nice language, and due to its stateless nature it’s very easy to hot reload. It’s a small, fully reliable and configuration free feature. And it’s gonna make getting started with a little side project much more fun!

• Changed: The static file server is no longer enabled by default. Add "serve": "." to elm-watch.json to enable it like it was by default in 1.2.0-beta.1. Or set it to a different directory if you would like to serve some other directory.
• Added: Set the environment variable ELM_WATCH_HOST=127.0.0.1 to restrict the server to only your computer. By default, the server runs on 0.0.0.0 which exposes the server on the local network (so you can test on a phone on the same Wi-Fi for example).

This release adds a simple HTTP static file server.

In fact, elm-watch has always had an HTTP server. An HTTP server is needed for a WebSocket connection to be created. This is the reason elm-watch has had an HTTP server at all. WebSockets start with an HTTP request and then “upgrade” to the WebSocket protocol.

Since there’s an HTTP server anyway, it could just as well do something useful apart from handling WebSocket connections. So elm-watch implements a very simple static file server, letting you easily get started with your Elm development.

The idea is to keep this HTTP server simple. For anything more advanced, use your own server instead, just like before.

This makes elm-watch an alternative to elm-live and elm-go in many situations.

Thanks for @joakin for talking to me about this and getting the ball rolling!

Improved: When a new port is added after hot reloading, elm-watch used to log a message to the console using console.info(), saying that you might want to reload the page. What I’ve learned from using elm-watch in real projects though, is that I’d rather want elm-watch to just reload the page for me in that case (like it does in some other cases), to give JavaScript code a chance to set those ports up.

Here’s a use case for reloading:

1. Start elm-watch, but don’t open any tabs in the browser, so no target is connected via WebSocket to elm-watch.
2. Add a new port in Elm. elm-watch just typechecks the code, but does not compile it to JS.
3. Use that port in JavaScript.
4. Go to the app in the browser.

State: The JavaScript is ready for the new port already, but the compiled JS for Elm is old.

What happens: elm-watch starts compiling for real since the target connected via WebSocket, and sends over the new JS. We detect the new port and reload the page. The JavaScript code now gets to set that port up for real.

This is especially helpful if your JavaScript code results in some kind of error when it expects certain ports but those not being available from Elm at page load (since elm-watch compiles lazily until first opened in the browser). I used to be confused why there were errors. Now, the page is automatically reloaded and the errors go away by themselves.

• Fixed: The error overlay in the browser now always displays the errors (for a given target) in the same order as in the terminal. Previously, errors not already present in the overlay would be added at the very end.

• Fixed: Previously, if you had a Platform.worker program (worker programs don’t support the Elm debugger) and for example a Browser.element program (which does support the Elm debugger) in the same output JS file, enabling debug mode resulted in a runtime error. (elm-watch tried running debugger functions for the worker program.) That has now been fixed.

• Fixed: When you switch to optimize mode, hot reloading becomes a bit more tricky. In optimize mode, Elm shortens record fields. For example, view might become G. If you have a lot of record fields, view might become longer, such as a$. I had missed accounting for that the shortened names can contain the dollar sign, so if view (or update or subscriptions, or other interesting “program fields”) happened to get a shortened name with a dollar sign in it, there would be a runtime crash in the browser. This has now been fixed.

• Fixed: Platform.worker programs can be run both in the browser, and in Node.js. Previously, trying to run a worker program in Node.js during development would fail though, due to WebSocket not being defined. (elm-watch injects code that uses WebSocket to do hot reloading.) Now, the injected elm-watch code simply does nothing if WebSocket is not available. (So, no hot reloading!) This is useful if you need to run a Platform.worker program both in the browser and in Node.js. (Note, though, that currently your worker program won’t be fully compiled until it has connected via WebSocket once – because that’s an optimization elm-watch uses in general – which is why this only is useful if you load your worker program both in the browser and in Node.js.)

Note: If you use elm-watch together with run-pty, make sure to update run-pty to 4.0.2 or later!

New features

• Added: An opt-in error overlay in the browser, with clickable error locations. When elm-watch’s browser UI shows “🚨 Compilation error”, click the UI to expand it and then click the “Show errors” button. That opens an overlay which shows the compilation errors. The overlay is visible until you close it again, or until you fix all errors. elm-watch remembers your choice to show errors in the browser per target, and opens the overlay again when there are new errors if you had previously opted to show it. Cool detail: The overlay uses the color theme from your terminal if possible! (That’s why run-pty needs to be updated – to support extracting the colors.)

• Added: Buttons for moving the browser UI to another corner. If you’ve ever felt that the elm-watch browser UI was in the way, you can now move it. The position is remembered per target across page reloads.

• Added: Support for running elm-watch in a Web Worker. Web Workers have no DOM, so you won’t get elm-watch’s browser UI. Instead, elm-watch gives you updates through browser console logs.

• Added: Better support for HTTPS.

• Added: You can now set the ELM_WATCH_EXIT_ON_STDIN_END environment variable (to any value) to have elm-watch end when stdin ends. This is useful to Phoenix users.

Improvements

• Improved: Elm can crash while printing JSON. If you run into such an Elm bug, elm-watch output is now easier to understand: It mentions that “Elm crashed” and shows Elm’s crash message, rather than text about the JSON unexpectedly being cut off.
• Improved: The error message for when window.Elm is undefined.
• Improved: Don’t expand the browser UI when a page reload is needed. That was pretty distracting.
• Changed: The WebSocket URL now uses /elm-watch as path, which helps people running elm-watch behind a proxy and need to do path matching to route to elm-watch and other origins.
• Added: elm-watch now prints a message while it is shutting down, asking you to press ctrl+c (again) to close it more forcefully. Usually you won’t see it, but if you do it helps.
• Fixed: Catch syntax errors when hot reloading.
• Fixed: On the iPhone, if the phone locks while elm-watch is waiting for compilation to finish, the elm-watch browser UI used to be stuck in the “⏳ Waiting for compilation” state. Now, the browser UI should always update when coming back to the page.
• Fixed: Various edge cases around “elm.json related errors”.
• Fixed: If you accidentally run your dev server with HTTP caching, elm-watch no longer gets stuck in a reload loop and instead shows you a helpful error message.
• Fixed: If you rename a target after you have opened it in the browser, elm-watch no longer gets stuck in a weird state. elm-watch used to just complain about target names not matching up, and the only way to fix it was to remove the output JavaScript file. Now the error message tells you to reload the page, and once you do it starts working again with the new target name.
• Fixed: ../ in "source-directories" in elm.json is now supported. Previously, elm-watch would never react to changes to files above elm.json.

(Note: If you installed the 1.1.0 beta versions – there are no changes since 1.1.0-beta.5, and the above is a summary of all changes since 1.0.2.)

• Added: You can now set the ELM_WATCH_EXIT_ON_STDIN_END environment variable (to any value) to have elm-watch end when stdin ends. This is useful to Phoenix users.
• Fixed: Regressions from earlier betas where elm-watch wouldn’t exit in certain cases.
• Added: elm-watch now prints a message while it is shutting down, asking you to press ctrl+c (again) to close it more forcefully. Usually you won’t see it, but if you do it helps.
• Improved: Don’t expand the browser UI when a page reload is needed. That was pretty distracting.

• Changed: The WebSocket URL now uses /elm-watch as path, which helps people running elm-watch behind a proxy and need to do path matching to route to elm-watch and other origins.

• Improved: Documentation links now go to https://lydell.github.io/elm-watch/ instead of to the readme.

• Fixed: ../ in "source-directories" in elm.json is now supported. Previously, elm-watch would never react to changes to files above elm.json.

Note: If you use elm-watch together with run-pty, make sure to update run-pty to 4.0.2 or later!

• Added: An opt-in error overlay in the browser, with clickable error locations. When elm-watch’s browser UI shows “🚨 Compilation error”, click the UI to expand it and then click the “Show errors” button. That opens an overlay which shows the compilation errors. The overlay is visible until you close it again, or until you fix all errors. elm-watch remembers your choice to show errors in the browser per target, and opens the overlay again when there are new errors if you had previously opted to show it. Cool detail: The overlay uses the color theme from your terminal if possible! (That’s why run-pty needs to be updated – to support extracting the colors.)
• Added: Buttons for moving the browser UI to another corner. If you’ve ever felt that the elm-watch browser UI was in the way, you can now move it to another corner. The position is remembered per target across page reloads.
• Added: Support for running elm-watch in a Web Worker. Web Workers have no DOM, so you won’t get elm-watch’s browser UI. Instead, elm-watch gives you updates through browser console logs.
• Added: Better support for HTTPS.
• Fixed: Catch syntax errors when hot reloading.
• Fixed: On the iPhone, if the phone locks while elm-watch is waiting for compilation to finish, the elm-watch browser UI used to be stuck in the “⏳ Waiting for compilation” state. Now, the browser UI should always update when coming back to the page.
• Fixed: Various edge cases around “elm.json related errors”.
• Improved: If you accidentally run your dev server with HTTP caching, elm-watch no longer gets stuck in a reload loop and instead shows you a helpful error message.
• Fixed: If you rename a target after you have opened it in the browser, elm-watch no longer gets stuck in a weird state. elm-watch used to just complain about target names not matching up, and the only way to fix it was to remove the output JavaScript file. Now the error message tells you to reload the page, and once you do it starts working again with the new target name.
• Improved: Elm can crash while printing JSON. If you run into such an Elm bug, elm-watch output is now easier to understand: It mentions that “Elm crashed” and shows Elm’s crash message, rather than text about the JSON unexpectedly being cut off.
• Improved: The error message for when window.Elm is undefined.

Install the latest beta:

npm install elm-watch@beta

Or install this version specifically:

npm install [email protected]

Install latest run-pty (if you use it):

npm install run-pty@latest

• Improved: Tweaked the --help text to be a little bit more clear.

• Improved: The error message for a missing default export in a elm-watch-node postprocess script now includes example code that you can copy paste to get started.

🎉 elm-watch is now out of beta!

• Fixed: elm-watch now reconnects the Web Socket properly on iOS after locking the device for a while, or switching to the home screen or another app for a while. Previously, it sometimes looked as if elm-watch was connected, but you never got any hot reloading and switching compilation mode did not work.

• Added: An animation indicating that there are compilation errors, as well as one indicating that a successful hot reload went through.

• Improved: elm-watch now detects Windows Terminal and gives fancier output there. Previously, it treated all terminals on Windows as if they were as bad as elm.exe.
• Improved: The CSS of the browser UI. If you move the browser UI using CSS to a top corner, it now looks better (no missing borders). It even detects that you’re on the top half of the screen and expands the UI downwards instead of upwards!

• Improved: elm-watch used to wait for elm make to finish, no matter how long it takes. Due to compiler bugs, certain input can cause elm make to hang. If you then changed your code to avoid the compiler bugs, elm-watch would notice your change but still wait for that previous elm make invocation to finish. In this version, elm-watch kills elm make after 10 seconds if you make a new change while it’s running. The idea is to avoid killing elm make to avoid corrupting the elm-stuff folder, but after 10 seconds it should have been done long ago.
• Improved: If you delete the elm-stuff folder (like some compiler error messages suggest), elm-watch now automatically re-runs.
• Improved: Compilation is now atomic. elm-watch used to run elm make --output=your/output.js and then read your/output.js and add the extra hot reloading code and run postprocessing. However, I managed to refresh the page in the browser while that was happening, so I got just Elm’s JS loaded and I was confused why the elm-watch UI wasn’t there. In this version, elm-watch runs elm make --output=elm-stuff/elm-watch/0.js instead – it first writes to a temporary file, and then writes to your real output path once everything is ready. Note: This also moves elm-stuff/elm-watch-stuff.json to elm-stuff/elm-watch/stuff.json, since the temporary files are written in elm-stuff/elm-watch/ and I wanted everything in there. Since elm-watch is a beta and elm-watch-stuff.json contains nothing essential I didn’t bother with any migration or so of it.
• Improved: A tiny little performance boost by avoiding unnecessary string/buffer conversions internally.

• Fixed: A bug on Windows where long running postprocess commands weren’t killed as they are supposed to when compilation is interrupted by a new code change.
• Improved: All tests now pass on Windows (locally, not in CI yet) and there are no known Windows issues.