Repository navigation
π 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
misoCLI.curl -fsSL https://haskell-miso.org/download | sh, thenmiso 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/stopPropagationthen did nothing, and data that only exists during dispatch (aDataTransfer) was gone. A callback passed toaddEventListenermust no longer block. Migration below.β οΈ MisoStringbehaves likeData.Texton 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/chunksOfmatchData.Text, andOrduses code point order. It is also much faster: nothing works one character at a time over the FFI any more (linesover 110 KB took minutes).β οΈ Miso.Router:uriFragmentno longer includes the leading#, and the fragment lexer now takes everything after the#(/#/users/1?tab=2has fragment/users/1?tab=2).Miso.Routerquery strings. One?with entries joined by&(was?a=1?flag); empty values parse (?q=isJust "");QueryParam Nothingis left out of the URL; a genericIndexroute keeps its query fields when encoded;ToMisoString (QueryParam p a)no longer prints key and value swapped.Miso.UUID. AUUIDtype backed byMisoStringwith an API that mirrorsData.UUID;nextRandomuses the browser'scrypto.randomUUID(). Instances forToJSON/FromJSON,ToJSVal/FromJSVal,ToMisoString/FromMisoStringandRouter(as a route capture).rAFLoop. A self re-schedulingrequestAnimationFrameloop as aSub:rAFLoop :: IO (Double -> IO ()) -> Sub model action.rAFSub,rAFSubElapsedandcanvasSubare built on it, and callingstopSubfrom one of their actions no longer crashes on WASM.Functorinstances forViewandAttributeare back (non-nativebuilds), so a sub-view written against oneactiontype can be embedded in another:ChildAction <$> Child.view m.Miso.Canvasis faster. Every straight-line canvas operation calls a dedicated foreign import instead of the generic path, andfillStyle/strokeStyle/shadowColorwith anRGB/RGBAcolour pass the channels as numbers. The public API is unchanged.- JSON and server rendering.
eitherDecode/decodereturnLeft/Nothingon invalid JSON instead of throwing (WASM, JS backend, MicroHs).toHtmlescapes attribute values and renders atextarea'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,startAppno longer evaluatesmiso.jsa second time afterwithJS, andrenderAppno longer throws; a tab or newline in aclass_string no longer breaks rendering;createSubkeeps its thread's delay within a 32-bitInt. CSS.contentfor thecontentproperty.β οΈ GHCJS 8.6 is no longer supported. The GHC JavaScript backend is the only JS target.- Native (Lynx). Toolchain bumped (
@lynx-js/rspeedy0.18.4,@lynx-js/react0.129.1) and the sample native hosts share one SDK version, 4.0.3. - Nix / CI. HLS for GHC 9.14 in the
hlsshell (built in CI); the JS cross compiler is in theghcjsandnativeshells;ghc-wasm-metabumped 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.15Stop 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 (& renders as &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 devThe 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:
- splitPrerequisites:
- 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, settarget: nativeinmiso.ymland usemiso run. curl,tar,sha256sumorshasum, andgit
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.UUIDand match theData.UUIDAPI by @dmjio in #1671 Miso.Canvas: direct JavaScript imports for canvas operations andrgb()/rgba()colours by @dmjio in #1673- Align type-parameter pointer diagrams in
Misohaddocks 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 forrAFSub,rAFSubElapsedandcanvasSubby @dmjio in #1706- README: add MicroHs installation instructions by @dmjio in #1708
- release: bump to
1.15.0.0by @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