Skip to content

1.15.0

Latest

Choose a tag to compare

@dmjio dmjio released this 10 Nov 23:11
5edff10

🍜 1.15.0

This release introduces the MicroHs backend (alpha) and the new miso CLI: a single binary with MicroHs built in, so a miso application can be created, built and hot-reloaded without GHC or Nix.

It also makes event handlers synchronous on every backend, makes MisoString behave like Data.Text on WASM and MicroHs, fixes a batch of Miso.Router URI printing and parsing bugs, and adds Miso.UUID, rAFLoop and CSS.content. There are a few breaking changes: uriFragment no longer includes the leading #, GHCJS 8.6 is no longer supported, OnStatic exists only under the native flag, and the deprecated mountStaticWithProps is removed. See the migration notes below.

✨ Special thanks

✨ Highlights

  • MicroHs backend (alpha). miso now compiles with MicroHs, to WebAssembly or JavaScript via emscripten. It passes miso's integration test suite on both targets. MicroHs and a MicroHs-built miso are distributed through miso's flake.nix.
  • The miso CLI. curl -fsSL https://haskell-miso.org/download | sh, then miso new my-app && cd my-app && miso dev. One binary for Linux, macOS and Windows that scaffolds, builds, serves, hot-reloads, tests and manages dependencies. See the section below.
  • ⚠️ Event handlers run synchronously, during dispatch, on every backend. On WASM they were asynchronous, so a handler could run after the browser had finished dispatching the event: preventDefault / stopPropagation then did nothing, and data that only exists during dispatch (a DataTransfer) was gone. A callback passed to addEventListener must no longer block. Migration below.
  • ⚠️ MisoString behaves like Data.Text on WASM and MicroHs, which is what it is on the server, so client and server agree: positions and lengths count code points, lines / words / strip / replace / split / chunksOf match Data.Text, and Ord uses code point order. It is also much faster: nothing works one character at a time over the FFI any more (lines over 110 KB took minutes).
  • ⚠️ Miso.Router: uriFragment no longer includes the leading #, and the fragment lexer now takes everything after the # (/#/users/1?tab=2 has fragment /users/1?tab=2).
  • Miso.Router query strings. One ? with entries joined by & (was ?a=1?flag); empty values parse (?q= is Just ""); QueryParam Nothing is left out of the URL; a generic Index route keeps its query fields when encoded; ToMisoString (QueryParam p a) no longer prints key and value swapped.
  • Miso.UUID. A UUID type backed by MisoString with an API that mirrors Data.UUID; nextRandom uses the browser's crypto.randomUUID(). Instances for ToJSON / FromJSON, ToJSVal / FromJSVal, ToMisoString / FromMisoString and Router (as a route capture).
  • rAFLoop. A self re-scheduling requestAnimationFrame loop as a Sub: rAFLoop :: IO (Double -> IO ()) -> Sub model action. rAFSub, rAFSubElapsed and canvasSub are built on it, and calling stopSub from one of their actions no longer crashes on WASM.
  • Functor instances for View and Attribute are back (non-native builds), so a sub-view written against one action type can be embedded in another: ChildAction <$> Child.view m.
  • Miso.Canvas is faster. Every straight-line canvas operation calls a dedicated foreign import instead of the generic path, and fillStyle / strokeStyle / shadowColor with an RGB / RGBA colour pass the channels as numbers. The public API is unchanged.
  • JSON and server rendering. eitherDecode / decode return Left / Nothing on invalid JSON instead of throwing (WASM, JS backend, MicroHs). toHtml escapes attribute values and renders a textarea's value as its content.
  • Runtime fixes. The JS backend releases callbacks in freeFunction (every freed handler used to leak for the lifetime of the page); on WASM, startApp no longer evaluates miso.js a second time after withJS, and renderApp no longer throws; a tab or newline in a class_ string no longer breaks rendering; createSub keeps its thread's delay within a 32-bit Int.
  • CSS.content for the content property.
  • ⚠️ GHCJS 8.6 is no longer supported. The GHC JavaScript backend is the only JS target.
  • Native (Lynx). Toolchain bumped (@lynx-js/rspeedy 0.18.4, @lynx-js/react 0.129.1) and the sample native hosts share one SDK version, 4.0.3.
  • Nix / CI. HLS for GHC 9.14 in the hls shell (built in CI); the JS cross compiler is in the ghcjs and native shells; ghc-wasm-meta bumped for the ghc#27447 codegen fix.

⚠️ Breaking changes & migration

1. uriFragment has no leading #. parseURI (and so getURI, uriSub and FromJSON URI) stored the fragment as "#cool", contrary to the documented contract. It is now stored bare, and prettyURI adds the # when the fragment is non-empty:

uriFragment uri == "#top"   -- 1.14
uriFragment uri == "top"    -- 1.15

Stop stripping # from a parsed uriFragment. Fragments written with a leading # (uri { uriFragment = "#top" }) still print correctly. URIs printed from parsed input are unchanged.

2. Printed query strings. Entries are listed in key order after a single ?, joined with &, and a QueryParam Nothing prints nothing (it printed a bare flag). Code that matches on the exact output of prettyURI, prettyRoute or href_ may need updating. parseURI still accepts the old form.

3. Event callbacks must not block. on / onWithOptions, event delegation and addEventListener (and the subscriptions built on it: windowSub, keyboardSub, arrowsSub, onLineSub, uriSub, …) call their callback synchronously. Handlers written with on are unaffected. A callback you pass to addEventListener yourself must not threadDelay, await or takeMVar: on WASM that raises WouldBlockException, on the JS backend the callback is silently abandoned. Hand blocking work to the sink, or forkIO it.

4. MisoString on WASM and MicroHs follows Data.Text. The differences most likely to be noticed:

lines "a\n"                    -- ["a"]         (was ["a", ""])
replace "a" "b" "aa"           -- "bb"          (replaced only the first)
words "a\tb"                   -- ["a", "b"]    (split on spaces only)
commonPrefixes "foo" "foobar"  -- Just ("foo", "", "bar")   (was Nothing)

length, index, head, last, takeEnd, … count code points, so an emoji is one character. compare uses code point order, so Map MisoString keys order the same on client and server. The GHC JavaScript backend, whose JSString comes from ghcjs-base, still compares code units. The changelog has the full list.

5. toHtml escapes attribute values. If you escaped attribute values yourself to work around this, stop: they will now be escaped twice (&amp; renders as &amp;amp;).

6. eitherDecode's error message. On invalid JSON it returns Left "eitherDecode: <message>" with JSON.parse's message, where it used to put the input string.

7. OnStatic exists only under the native flag. Elsewhere event dereferences the StaticPtr itself and builds a plain On. Runtime behavior is unchanged; code that pattern-matches on OnStatic must be guarded with #ifdef NATIVE (or match On instead).

8. GHCJS 8.6 is gone. The GHCJS_OLD code paths, impl(ghcjs) conditionals and the ghcjs-prim dependency are removed, along with the legacy nixpkgs pin and its GHCJS 8.6 / GHC 8.6.5 Nix targets. Use the GHC JavaScript backend (arch(javascript)).

9. mountStaticWithProps is removed. It was a deprecated synonym for mountStatic since 1.14. Replace it with mountStatic; call sites are otherwise unchanged.

πŸ”‹ The miso CLI

The miso CLI is a single binary with the MicroHs compiler and MicroCabal inside, and miso and its dependencies already installed. It runs on Linux and macOS (x86_64 and aarch64) and on Windows (x86_64, via an MSYS2 shell).

# Install the miso CLI
curl -fsSL https://haskell-miso.org/download | sh

# Create, build and serve a new project (rebuilds and reloads on changes)
miso new my-app && cd my-app
miso dev

The installer downloads the release for your OS and architecture, verifies its sha256 checksum, and unpacks it into ~/.miso (or $MISO_HOME). It asks before changing your PATH. With nix: nix profile install github:haskell-miso/cli#release.

From nothing to a running app:

β”Œβ”€ install ────────────────────────────────────────────────────────────────────┐
β”‚ $ curl -fsSL https://haskell-miso.org/download | sh                          β”‚
β”‚                                                                              β”‚
β”‚ miso: build miso apps with MicroHs (x86_64-linux)                            β”‚
β”‚                                                                              β”‚
β”‚ ==> Downloading miso (latest) for x86_64-linux                               β”‚
β”‚ ######################################################################## 100%β”‚
β”‚   βœ“ sha256 7741356dac9db503... matches miso-x86_64-linux.tar.gz.sha256       β”‚
β”‚ ==> miso 0.1.0 (MicroHs 0.16.12.0) will be installed in ~/.miso:             β”‚
β”‚       create   ~/.miso/bin/cpphs  (480K)                                     β”‚
β”‚       create   ~/.miso/bin/miso  (1.5M)                                      β”‚
β”‚       create   ~/.miso/mhs-0.16.12.0/  (the package database, 7.1M)          β”‚
β”‚ ? Install miso? [Y/n] y                                                      β”‚
β”‚ ==> Installed miso 0.1.0 (MicroHs 0.16.12.0) in ~/.miso:                     β”‚
β”‚       ~/.miso/bin/cpphs                        480K                          β”‚
β”‚       ~/.miso/bin/miso                         1.5M                          β”‚
β”‚       ~/.miso/mhs-0.16.12.0/                   7.1M                          β”‚
β”‚                                                                              β”‚
β”‚ ? Add miso to your PATH in ~/.zshrc? [Y/n] y                                 β”‚
β”‚ ==> Added these lines to the end of ~/.zshrc:                                β”‚
β”‚                                                                              β”‚
β”‚       # miso (https://haskell-miso.org)                                      β”‚
β”‚       export PATH="$HOME/.miso/bin:$PATH"                                    β”‚
β”‚                                                                              β”‚
β”‚ ==> Checking the installation (miso doctor)                                  β”‚
β”‚   βœ“ package database ~/.miso/mhs-0.16.12.0                                   β”‚
β”‚   βœ“ base                                                                     β”‚
β”‚   βœ“ miso                                                                     β”‚
β”‚   ...                                                                        β”‚
β”‚                                                                              β”‚
β”‚ Next:                                                                        β”‚
β”‚                                                                              β”‚
β”‚     miso new hello && cd hello && miso dev                                   β”‚
β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜
                                       β”‚
                                       β–Ό
β”Œβ”€ create ─────────────────────────────────────────────────────────────────────┐
β”‚ $ miso new my-app                                                            β”‚
β”‚ ==> Creating my-app (counter)                                                β”‚
β”‚   -> my-app/miso.yml                                                         β”‚
β”‚   -> my-app/app/Main.hs                                                      β”‚
β”‚   -> my-app/static/index.html                                                β”‚
β”‚   -> my-app/.gitignore                                                       β”‚
β”‚   -> my-app/README.md                                                        β”‚
β”‚ ==> Created my-app: cd my-app && miso dev                                    β”‚
β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜
                                       β”‚
                                       β–Ό
β”Œβ”€ develop ────────────────────────────────────────────────────────────────────┐
β”‚ $ cd my-app && miso dev                                                      β”‚
β”‚ ==> Serving public/ at http://localhost:8000/ (Ctrl-C to stop)               β”‚
β”‚ ==> Building my-app                                                          β”‚
β”‚ ==> Built my-app, reloading the page                                         β”‚
β”‚ ==> Watching app static cbits jsbits include miso.yml for changes            β”‚
β”‚                                                                              β”‚
β”‚      ... edit app/Main.hs and save ...                                       β”‚
β”‚                                                                              β”‚
β”‚ ==> Changed: app/Main.hs                                                     β”‚
β”‚ ==> Building my-app                                                          β”‚
β”‚ ==> Built my-app, reloading the page                                         β”‚
β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜

miso dev is a loop: save a file, and the page in the browser reloads with the new build.

     β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”  save   β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”  build   β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
     β”‚ app/Main.hs  β”‚ ──────▢ β”‚ miso dev β”‚ ───────▢ β”‚   public/     β”‚
     β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜         β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜          β”‚  index.html   β”‚
            β–²                                       β”‚  index.js     β”‚
            β”‚                                       β”‚  app.comb     β”‚
            β”‚ edit                                  β””β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”˜
            β”‚                                               β”‚ reload
     β”Œβ”€β”€β”€β”€β”€β”€β”΄β”€β”€β”€β”€β”€β”€β”€β”                                       β–Ό
     β”‚     you      β”‚ ◀──────────────────────────  http://localhost:8000/
     β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜            see the change

Other templates: miso new my-app --template router (pages with URLs) and --template canvas (drawing on a canvas, driven by the model). miso templates lists them.

command
miso new NAME [--template T] a new project from a template (counter, router, canvas); miso init does the same in the current directory
miso dev build a browser program, serve public/, and rebuild and reload the page when the sources change
miso build / miso run / miso test build every program of miso.yml; build and run a native program; build and run the tests
miso watch type check on every change and show the first error, as ghcid does
miso repl MicroHs, interactively, with the project's sources and packages
miso add PKG / miso remove PKG add or remove Hackage dependencies in miso.yml
miso lock / miso update / miso vendor pin dependencies in miso.lock, refresh them, or copy their sources to vendor/
miso lint run hlint on the project's source dirs
miso doctor check the installation and the tools miso needs, and say how to fix what is missing
miso upgrade / miso uninstall install the latest release in place; remove miso's files

A project is described by a miso.yml:

name: counter
version: 0.1.0
main: Main
source-dirs: [app]
target: browser            # browser (WebAssembly), browser_js (JavaScript) or native
dependencies:
  - split

Prerequisites:

  • A C compiler (cc), since MicroHs compiles programs to C
  • emscripten (emcc) for browser targets. New projects target the browser (WebAssembly) by default. Without emscripten, set target: native in miso.yml and use miso run.
  • curl, tar, sha256sum or shasum, and git

Moving a CLI project to 1.15. The CLI ships its own miso, so 1.15 arrives with the next CLI release. miso upgrade installs that release in place. A project that has a miso.lock keeps the miso it locked; run miso update in the project to move it to 1.15, then see the migration notes above.

Run miso help to list all commands. See the miso CLI docs for the full reference.

What's Changed

  • nix: bump ghc-wasm-meta for the ghc#27447 codegen fix by @dmjio in #1658
  • nix: drop the dead 9.12 wasm overlay, fix dangling sampleWasm by @dmjio in #1659
  • createSub: keep the Sub thread's delay below 2^31 microseconds by @dmjio in #1662
  • MicroHs backend for miso (JS + WASM) β€” alpha by @dmjio in #1663
  • nix: put the JS cross compiler in the ghcjs and native shells by @dmjio in #1666
  • Bump MicroHs to c8fc0d85 by @dmjio in #1665
  • JS backend: release callbacks in freeFunction_ffi by @dmjio in #1667
  • Restore Functor View / Attribute on non-native builds by @dmjio in #1669
  • feat: Miso.UUID by @ners in #1670
  • Drop GHCJS 8.6 and the legacy nixpkgs pin by @dmjio in #1672
  • Format Miso.UUID and match the Data.UUID API by @dmjio in #1671
  • Miso.Canvas: direct JavaScript imports for canvas operations and rgb()/rgba() colours by @dmjio in #1673
  • Align type-parameter pointer diagrams in Miso haddocks by @dmjio in #1674
  • Bump MicroHs to 1d84237d (0.16.10) by @dmjio in #1676
  • playwright.ts: do not log failed requests by @dmjio in #1677
  • Data.JSString: no per-character FFI, Data.Text semantics (GHC and MicroHs) by @dmjio in #1680
  • Synchronous event callbacks on every backend; run the WASM scheduler after them by @dmjio in #1684
  • populateClass: split class strings on ASCII whitespace, not just spaces by @dmjio in #1685
  • WASM: load miso.js once; let renderApp load it before using the global by @dmjio in #1686
  • nix: build HLS for GHC 9.14 for the hls shell (own package set), and build it in CI by @dmjio in #1687
  • Add CSS.content property by @pmiddend in #1688
  • MicroHs: bump to jsval 5fc13363 and drop the U+FEFF workaround by @dmjio in #1691
  • eitherDecode returns Left on invalid JSON; toHtml escapes attributes and renders textarea values by @dmjio in #1695
  • MicroHs: bump to jsval 1a0ce4ba by @dmjio in #1694
  • Store uriFragment without the leading # (#1696) by @dmjio in #1697
  • Join query params and flags with & in prettyQueryString by @dmjio in #1698
  • Keep fields of a generic Index route when encoding by @dmjio in #1699
  • Lex the URI fragment to the end of the URI by @dmjio in #1700
  • Bump Lynx toolchain (rspeedy 0.18.4) and native SDK to 4.0.3 by @dmjio in #1702
  • rAFLoop: one self-owning rAF loop for rAFSub, rAFSubElapsed and canvasSub by @dmjio in #1706
  • README: add MicroHs installation instructions by @dmjio in #1708
  • release: bump to 1.15.0.0 by @dmjio in #1709
  • Remove mountStaticWithProps; fill in the 1.15.0.0 changelog by @dmjio in #1710

New Contributors

Full Changelog: 1.14.0...1.15.0