Tip

React-style Components are now added tomiso as of version1.9. This has not yet been released, we recommend developing againstmaster if you'd like to use latest features.

Table of Contents

History 📜

Quick start

Tip

For new Haskell users we recommend usingGHCup to acquire bothGHC andcabal

Setup 🏗️

cabal.project

packages:.source-repository-packagetype:gitlocation:https://github.com/dmjio/misobranch:master

app.cabal

cabal-version:2.2name:appversion:0.1.0.0synopsis:Sample miso appcategory:Webcommon wasmif arch(wasm32)ghc-options:-no-hs-main-optl-mexec-model=reactor"-optl-Wl,--export=hs_start"cpp-options:-DWASMexecutable appimport:wasmmain-is:Main.hsbuild-depends:base, misodefault-language:Haskell2010

Main.hs

----------------------------------------------------------------------------{-#LANGUAGE OverloadedStrings #-}{-#LANGUAGE RecordWildCards   #-}{-#LANGUAGE LambdaCase        #-}{-#LANGUAGE CPP               #-}----------------------------------------------------------------------------moduleMainwhere----------------------------------------------------------------------------importMisoimportMiso.StringimportMiso.Lens------------------------------------------------------------------------------| Component model statenewtypeModel=Model{_counter::Int}deriving (Show,Eq)----------------------------------------------------------------------------counter::LensModelIntcounter= lens _counter$\record field-> record { _counter= field }------------------------------------------------------------------------------| Sum type for Component eventsdataAction=AddOne  |SubtractOne  |SayHelloWorldderiving (Show,Eq)------------------------------------------------------------------------------| Entry point for a miso applicationmain::IO()main= run (startComponent app)------------------------------------------------------------------------------| WASM export, required when compiling w/ the WASM backend.#ifdef WASMforeignexport javascript"hs_start" main::IO()#endif------------------------------------------------------------------------------| `component` takes as arguments the initial model, update function, view functionapp::ComponentModelActionapp= component emptyModel updateModel viewModel------------------------------------------------------------------------------| Empty application stateemptyModel::ModelemptyModel=Model0------------------------------------------------------------------------------| Updates model, optionally introduces side effectsupdateModel::Action->EffectModelActionupdateModel=\caseAddOne-> counter+=1SubtractOne-> counter-=1SayHelloWorld-> io_$do    consoleLog"Hello World"    alert"Hello World"------------------------------------------------------------------------------| Constructs a virtual DOM from a modelviewModel::Model->ViewActionviewModel x= div_[]  [ button_ [ onClickAddOne ] [ text"+" ]  , text$ ms (x^. counter)  , button_ [ onClickSubtractOne ] [ text"-" ]  , button_ [ onClickSayHelloWorld ] [ text"Alert Hello World!" ]  ]----------------------------------------------------------------------------

Hot Reload 🔥

$ cabal repl

[1 of 2] Compiling Main             ( Main.hs, interpreted )Ok, one module loaded.ghci>

ghci> mainRunning on port 8008...<a href="http://localhost:8008">run</a>ghci>

Note

The code running in this example is not compiled to JavaScript or WebAssembly, rather it is running the client side application on the server. It works by sending commands to a small javascript interpreter over a websocket to render elements on the page. This is provided by thejsaddle library.

Note

Instead of typing:r andmain manually inside ofGHCi on every file change, you can useghcid orghciwatch tools to do it automatically.

Tip

For users accustomed to a react.js worfklow, we highly recommend using eitherghcid orghciwatch.

$ ghcid -c'cabal repl app' -T=Main.main

Compilation

Tip

For new Haskell users we recommend usingGHCup to acquire theWASM andJS backends.

Web Assembly

Tip

The Haskellmiso team currently recommends using the WASM backend as the default backend for compilation.

Tip

ForNix users it is possible to acquire the WASM backend via aNix flake

$ nix shell'gitlab:haskell-wasm/ghc-wasm-meta?host=gitlab.haskell.org'

Note

This will putwasm32-wasi-cabal in your$PATH, along withwasm32-wasi-ghc. Since the WASM backend is relatively new, the ecosystem is not entirely patched to support it. Therefore, we will need to use patched packages from time to time.

Tip

Instead of using anix shell, it's possible to install the GHC WASM Flake into your environment so it will always be present on$PATH

$ nix profile install'gitlab:haskell-wasm/ghc-wasm-meta?host=gitlab.haskell.org'

packages:.with-compiler:wasm32-wasi-ghcwith-hc-pkg:wasm32-wasi-ghc-pkgsource-repository-packagetype:gitlocation:https://github.com/dmjio/misobranch:masterif arch(wasm32)-- Required for TemplateHaskell. When using wasm32-wasi-cabal from-- ghc-wasm-meta, this is superseded by the global cabal.config.shared:True

$ wasm32-wasi-cabal update$ wasm32-wasi-cabal build --allow-newer

Configuration is affected by the following files:- cabal.projectResolving dependencies...Build profile: -w ghc-9.12.2.20250327 -O1In order, the following will be built (use -vfor more details): - app-0.1.0.0 (exe:app) (configuration changed)Configuring executable'app'for app-0.1.0.0...Preprocessing executable'app'for app-0.1.0.0...Building executable'app'for app-0.1.0.0...[1 of 1] Compiling Main             ( Main.hs, dist-newstyle/build/wasm32-wasi/ghc-9.12.2.20250327/app-0.1.0.0/x/app/build/app/app-tmp/Main.o )[2 of 2] Linking dist-newstyle/build/wasm32-wasi/ghc-9.12.2.20250327/app-0.1.0.0/x/app/build/app/app.wasm

Note

The GHC WASM backend can execute any Haskell program in a WASI-compliant runtime (e.g.wasmtime)See theofficial documentation for more information.

Tip

We recommend using an up-to-datenode version (currently tested withv24.2.0) to ensurepost-link.mjs works properly.

# Creates the directory for hosting$ mkdir -v app.wasmexemkdir: created directory'app.wasmexe'# This command produces `ghc_wasm_jsffi.js`, which ensures our FFI works properly.$$(wasm32-wasi-ghc --print-libdir)/post-link.mjs \   --input$(wasm32-wasi-cabal list-bin app --allow-newer) \   --output app.wasmexe/ghc_wasm_jsffi.js# This copies the `app.wasm` payload into `app.wasmexe`$ cp -v$(wasm32-wasi-cabal list-bin app --allow-newer) app.wasmexeConfiguration is affected by the following files:- cabal.project'/home/dmjio/Desktop/miso/sample-app/dist-newstyle/build/wasm32-wasi/ghc-9.12.2.20250327/app-0.1.0.0/x/app/build/app/app.wasm' ->'app.wasmexe'

Note

Along with the aboveghc_wasm_jsffi.js andapp.wasm artifacts, we also need to include anindex.html and anindex.js for loading the WASM payload into the browser.

<!DOCTYPE html><html><head><metacharset="utf-8"><metaname="viewport"content="width=device-width, initial-scale=1"><title>Sample miso WASM counter app</title></head><body><scriptsrc="index.js"type="module"></script></body></html>

import{WASI,OpenFile,File,ConsoleStdout}from"https://cdn.jsdelivr.net/npm/@bjorn3/browser_wasi_shim@0.3.0/dist/index.js";importghc_wasm_jsffifrom"./ghc_wasm_jsffi.js";constargs=[];constenv=["GHCRTS=-H64m"];constfds=[newOpenFile(newFile([])),// stdinConsoleStdout.lineBuffered((msg)=>console.log(`[WASI stdout] ''${msg}`)),ConsoleStdout.lineBuffered((msg)=>console.warn(`[WASI stderr] ''${msg}`)),];constoptions={debug:false};constwasi=newWASI(args,env,fds,options);constinstance_exports={};const{ instance}=awaitWebAssembly.instantiateStreaming(fetch("app.wasm"),{wasi_snapshot_preview1:wasi.wasiImport,ghc_wasm_jsffi:ghc_wasm_jsffi(instance_exports),});Object.assign(instance_exports,instance.exports);wasi.initialize(instance);awaitinstance.exports.hs_start(globalThis.example);

❯ ls app.wasmexe app.wasm ghc_wasm_jsffi.js index.html index.js

$ http-server app.wasmexe

Tip

You can inspect the WASM payload in theSources tab of your browser by right-clicking and then clickingInspect.

JavaScript

Tip

ForNix users it is possible to acquire the latest JS backend (thatmiso uses) via Nix.Usecachix to ensure you're not building dependencies unnecessarilycachix use haskell-miso-cachix

nix-shell -p pkgs.pkgsCross.ghcjs.haskell.packages.ghc9122.ghc -I nixpkgs=https://github.com/NixOS/nixpkgs/archive/65f179f903e8bbeff3215cd613bdc570940c0eab.tar.gz

Note

This will putjavascript-unknown-ghcjs-ghc in your$PATH, along withjavascript-unknown-ghcjs-ghc-pkg. You might also need to specify in yourcabal.project file that you are using the JS backend.

Tip

Alternatively, if you'd like to install the compiler into your global environment (so you don't need to develop inside abash shell) you can use the following command.

nix-env -iA pkgs.pkgsCross.ghcjs.haskell.packages.ghc9122.ghc -f https://github.com/NixOS/nixpkgs/archive/65f179f903e8bbeff3215cd613bdc570940c0eab.tar.gz

packages:.source-repository-packagetype:gitlocation:https://github.com/dmjio/misobranch:masterwith-compiler:javascript-unknown-ghcjs-ghcwith-hc-pkg:javascript-unknown-ghcjs-ghc-pkg

Note

cabal will use theghc specified above inwith-compiler

$ cabal update&& cabal build --allow-newer

Configuring executable'app'for app-0.1.0.0...Preprocessing executable'app'for app-0.1.0.0...Building executable'app'for app-0.1.0.0...[1 of 1] Compiling Main             ( Main.hs, dist-newstyle/build/javascript-ghcjs/ghc-9.12.2/app-0.1.0.0/x/app/build/app/app-tmp/Main.o )[2 of 2] Linking dist-newstyle/build/javascript-ghcjs/ghc-9.12.2/app-0.1.0.0/x/app/build/app/app.jsexe

Tip

To view the JavaScript in your browser, you can usecabal list-bin andhttp-server

$ http-server$(cabal list-bin app --allow-newer).jsexeConfiguration is affected by the following files:- cabal.projectStarting up http-server, serving /home/dmjio/Desktop/miso/sample-app/dist-newstyle/build/javascript-ghcjs/ghc-9.12.2/app-0.1.0.0/x/app/build/app/app.jsexehttp-server version: 14.1.1http-server settings:CORS: disabledCache: 3600 secondsConnection Timeout: 120 secondsDirectory Listings: visibleAutoIndex: visibleServe GZIP Files:falseServe Brotli Files:falseDefault File Extension: noneAvailable on:  http://127.0.0.1:8080  http://192.168.1.114:8080Hit CTRL-C to stop the server

Haddocks

Architecture

Tip

For more information on how to usenix with aclient/server setup, see thenix scripts forhttps://haskell-miso.org.

Internals ⚙️

Examples

Building examples

Tip

Usecachix to ensure you're not building dependencies unnecessarilycachix use haskell-miso-cachix

$ git clone https://github.com/dmjio/miso$ cd miso$ nix-build -A miso-examples

➜ tree -d ./result/bin./result/bin|-- canvas2d.jsexe|-- file-reader.jsexe|-- mario.jsexe|   `-- imgs|-- mathml.jsexe|-- router.jsexe|-- simple.jsexe|-- svg.jsexe|-- tests.jsexe|-- threejs.jsexe|-- todo-mvc.jsexe|-- websocket.jsexe`-- fetch.jsexe

Note

To see examples, we recommend hosting them with a web server (we usehttp-server)

cd result/bin/todo-mvc.jsexe && http-severServing HTTP on 0.0.0.0 port 8000 ...

Interacting with HTTP APIs 🔌

Coverage ✅

Note

To run the tests and build the coverage report ensurebun is installed.

$ curl -fsSL https://bun.sh/install| bash

$ nix-env -iA bun -f'<nixpkgs>'

$ bun install&& bun runtest

--------------------|---------|---------|-------------------File| % Funcs| % Lines| Uncovered Line#s--------------------|---------|---------|-------------------All files|   92.37|   85.48| ts/happydom.ts|  100.00|  100.00| ts/miso/dom.ts|  100.00|  100.00| ts/miso/event.ts|   90.91|   81.62| ts/miso/hydrate.ts|   80.00|   91.24| ts/miso/smart.ts|  100.00|  100.00| ts/miso/util.ts|   83.33|   40.00|--------------------|---------|---------|------------------- 84 pass 0 fail

Isomorphic ☯️

Note

Themiso function is used to facilitate the pointer-copying behavior client-side.

Native📱

Benchmarks 🏎️

Nix

Tip

If unfamiliar withnix, we recommend@Gabriella439's"Nix and Haskell in production" guide.

Pinning nixpkgs 📌

Note

miso also maintains a legacy version of nixpkgs known aslegacyPkgs so we can use tools likenixops for deployment and to buildmiso with the originalGHCJS 8.6 backend.

Binary cache

Tip

We highly recommend nix users consume thecachix cache.cachix use haskell-miso-cachix.

$ cachix use haskell-miso-cachix

Community 🫶

Maintainers

Contributing

Contributors 🦾

Note

This project exists thanks to all the people whocontribute

Partnerships 🤝

Backers

Organizations

License