haskell-miso

v0.0.9

Published

7 days ago

miso: A tasty Haskell web and mobile framework

0High
0Medium
0Low

Miso is a small, production-ready, component-oriented, reactive, isomorphic Haskell front-end framework for quickly building highly interactive single-page web and mobile applications. It features a virtual-dom, recursive diffing / patching algorithm, attribute and property normalization, event delegation, event batching, SVG, 2D/3D Canvas (WebGL), Server-sent events (SSE), Websockets, type-safe servant-style routing and an extensible Subscription-based subsystem. Inspired by Elm and React. Miso is pure by default, but side effects can be introduced into the system via the Effect data type.

Miso makes heavy use of the GHC Javascript FFI and therefore has minimal dependencies. Miso can be considered a shallow embedded domain-specific language for modern web programming.

Miso supports compilation to both JavaScript and WebAssembly using GHC. For hot-reload, miso uses WASM browser mode. When used with ghciwatch this enables a rapid development workflow.

[!IMPORTANT] Check out the new Haskell miso Organization 🍜

History 📜

miso is a play on the words micro and isomorphic.

miso began in 2016 as research in:

Expressing the Elm architecture in GHCJS as an embedded domain-specific language.
Implementing modern JavaScript frontend techniques as found in react (e.g. Reconciliation, isomorphic)

Miso aims to bridge the gap between modern JavaScript frameworks (such as React, Vue.js, etc.) and functional programming in Haskell. It has since grown to encompass more features from the JavaScript community like Components and Renderers. Miso also now supports native development for iOS, Android and HarmonyOS devices via LynxJS and targets additional backends like Web Assembly.

[!Note] React-style Components are now added to miso as of version 1.9. This has not yet been released, we recommend developing against master if you'd like to use latest features.

Docs 📚

See the Miso module.

Quick start ⚡

[!TIP] We have a template repository that includes a sample counter application and build scripts for all platforms.

# Install nix 
curl -L https://nixos.org/nix/install | sh

# Enable flakes
echo 'experimental-features = nix-command flakes' >> ~/.config/nix/config.nix

# Clone, build and host
git clone https://github.com/haskell-miso/miso-sampler && cd miso-sampler
nix develop .#wasm --command bash -c 'make && make serve'

The fastest way to get started is to clone and build the miso sampler repository 🍱 This has build scripts for Web Assembly, JS and vanilla GHC. This requires Nix Flakes usage. See also the section on using miso's binary cache.

Getting started

To start developing applications with miso you will need to acquire GHC and cabal. This can be done via GHCup or Nix.

[!TIP] For new Haskell users we recommend using GHCup to acquire both GHC and cabal

Setup 🏗️

To develop and build your first miso application you will need 3 files:

cabal.project
app.cabal
Main.hs

`cabal.project`

packages:
  .

source-repository-package
  type: git
  location: https://github.com/dmjio/miso
  branch: master

`app.cabal`

We recommend using at least cabal-version: 2.2, this will give you the common sections feature which we will use later to allow multiple compilers to build our project (so we can target WASM and JS backends)

cabal-version: 2.2
name: app
version: 0.1.0.0
synopsis: Sample miso app
category: Web

common options
  if arch(wasm32)
    ghc-options:
      -no-hs-main
      -optl-mexec-model=reactor
      "-optl-Wl,--export=hs_start"
    cpp-options:
      -DWASM

  if arch(javascript)
     ld-options:
       -sEXPORTED_RUNTIME_METHODS=HEAP8

executable app
  import:
    options
  main-is:
    Main.hs
  build-depends:
    base, miso
  default-language:
    Haskell2010

`Main.hs`

This file contains a simple miso counter application.

----------------------------------------------------------------------------
{-# LANGUAGE OverloadedStrings #-}
{-# LANGUAGE LambdaCase        #-}
{-# LANGUAGE CPP               #-}
----------------------------------------------------------------------------
module Main where
----------------------------------------------------------------------------
import           Miso
import qualified Miso.Html as H
import qualified Miso.Html.Property as P
import           Miso.Lens
----------------------------------------------------------------------------
-- | Sum type for App events
data Action
  = AddOne
  | SubtractOne
  | SayHelloWorld
  deriving (Show, Eq)
----------------------------------------------------------------------------
-- | Entry point for a miso application
main :: IO ()
main = startApp defaultEvents app
----------------------------------------------------------------------------
-- | WASM export, required when compiling w/ the WASM backend.
#ifdef WASM
foreign export javascript "hs_start" main :: IO ()
#endif
----------------------------------------------------------------------------
-- | `component` takes as arguments the initial model, update function, view function
app :: App Int Action
app = component 0 updateModel viewModel
----------------------------------------------------------------------------
-- | Updates model, optionally introduces side effects
updateModel :: Action -> Effect parent Int Action
updateModel = \case
  AddOne        -> this += 1
  SubtractOne   -> this -= 1
  SayHelloWorld -> io_ $ do
    alert "Hello World"
    consoleLog "Hello World"
----------------------------------------------------------------------------
-- | Constructs a virtual DOM from a model
viewModel :: Int -> View Int Action
viewModel x =
  H.div_
    [ P.className "counter"
    ]
    [ H.button_ [ H.onClick AddOne ] [ text "+" ]
    , text $ ms (x ^. counter)
    , H.button_ [ H.onClick SubtractOne ] [ text "-" ]
    , H.br_ []
    , H.button_ [ H.onClick SayHelloWorld ] [ text "Alert Hello World!" ]
    ]
----------------------------------------------------------------------------

Now that your project files are populated, development can begin.

Hot Reload 🔥

See the WASM browser mode section of the miso-sampler repository for usage of hot reload development w/ ghciwatch. Also see this blog post.

Installation

See Installation for more information.

Haddocks

Offical Haskell documentation of the Miso web framework.

| Platform | URL | |------|-------------| | GHCJS | Link | | GHC | Link |

Wiki

See the DeepWiki entry to explore the source code.

Architecture

For constructing client and server applications, we recommend using one cabal file with two executable sections, where the buildable attribute set is contingent on the compiler. An example of this layout is here.

[!TIP] For more information on how to use nix with a client/server setup, see the nix scripts for https://haskell-miso.org.

Examples

For real-world examples of Haskell miso applications, see below.

| Name |-----------------------| | TodoMVC | 2048 | Flatris | Plane | Snake | SVG | Fetch | File Reader | Mario | WebSocket | Router | Canvas 2D | MathML | Simple | SSE | Three.js | Space Invaders | Audio | Video | WebVR | Reactivity | Description | Source Link | Live Demo Link | Author | -------------------------------------------|---------------------------------------------------------------|-----------------------------------------------------------|---------------------------------------------------| | A classic TodoMVC implementation | Source | Demo | @dmjio | | A clone of the 2048 game | Source | Demo | @ptigwe | | A Tetris-like game | Source | Demo | @ptigwe | | A flappy-birds-like game | Source | Demo | @Lermex | | The classic Snake game | Source | Demo | @lbonn | | An example showcasing SVG rendering | Source | Demo | @dmjio | | An example demonstrating AJAX requests | Source | Demo | @dmjio | | A FileReader API example | Source | Demo | @dmjio | | A Super Mario physics example | Source | Demo | @dmjio | | A simple WebSocket example | Source | Demo | @dmjio | | A client-side routing example | Source | Demo | @dmjio | | A 2D Canvas rendering example | Source | Demo | @dmjio | | A MathML example | Source | Demo | @dmjio | | A simple counter example | Source | Demo | @dmjio | | SSE (Server-sent events) Example | Source | Demo | @dmjio | | A 3D rendering example using Three.JS | Source | Demo | @juliendehos | | A Space-Invaders-like game | Source | Demo | @juliendehos | | Audio examples | Source | Demo | @juliendehos | | Video examples | Source | Demo | @juliendehos | | WebVR examples | Source | Demo | @dmjio | | Reactive examples | Source | Demo | @dmjio |

Building examples

The easiest way to build the examples is with the nix package manager.

[!TIP] Use cachix to ensure you're not building dependencies unnecessarily cachix use haskell-miso-cachix

See the @HaskellMiso organization for all examples, and how to build then.

Interacting with HTTP APIs 🔌

If you want to interact with an HTTP API, we recommend one of the following approaches:

For a simple JSON-based API, you can use Miso's Fetch module.
In more complex cases, you can define a Servant API and automatically obtain client functions via servant-miso-client.
The Fetch example (Source, Demo) demonstrates the necessary ingredients. Make sure to add the following to your cabal.project:
```
source-repository-package
  type: git
  location: https://github.com/haskell-miso/servant-miso-client
  tag: master
```

Coverage ✅

The core engine of miso is the diff function. It is responsible for all DOM manipulation that occurs in a miso application and has 100% code coverage. Tests and coverage made possible using bun.

[!NOTE] To run the tests and build the coverage report ensure bun is installed.

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

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

and

$ bun install && bun run test

--------------------------|---------|---------|-------------------
File                      | % Funcs | % Lines | Uncovered Line #s
--------------------------|---------|---------|-------------------
All files                 |   93.50 |   92.28 |
 ts/happydom.ts           |  100.00 |  100.00 |
 ts/miso/context/dom.ts   |  100.00 |  100.00 |
 ts/miso/context/patch.ts |   75.00 |   81.17 | 68-76,79-84,87-93,99-107,193-202
 ts/miso/dom.ts           |  100.00 |   98.86 | 41,302-303
 ts/miso/event.ts         |  100.00 |   92.75 | 28-30,52,81,85-90,116,161
 ts/miso/hydrate.ts       |  100.00 |   98.15 | 11-12
 ts/miso/patch.ts         |  100.00 |   80.00 | 26-32,36,38,42-43,85-86,91,93
 ts/miso/smart.ts         |   85.00 |   93.33 | 45-48
 ts/miso/types.ts         |  100.00 |  100.00 |
 ts/miso/util.ts          |   75.00 |   78.53 | 79,83,122,137,169,172,175-186,197-202,223-229,233-236,249-254
--------------------------|---------|---------|-------------------

 223 pass
 0 fail
 7598 expect() calls
Ran 223 tests across 9 files. [497.00ms]

Native📱

Miso supports the creation of iOS and Android applications via LynxJS. See the miso-lynx repository for more information.

Benchmarks 🏎️

According to benchmarks miso is competitive. miso.js depicted below is how miso performs with its JS engine relative to vanilla JS. The miso column shows performance using the GHC JS backend. We're currently researching staged meta-programming as a way to remove excess allocations in our DSL and to increase performance when compiling from Haskell.

Nix

Nix is a powerful option for building web applications with miso since it encompasses development workflow, configuration management, and deployment. The source code for haskell-miso.org is an example of this.

[!TIP] If unfamiliar with nix, we recommend @Gabriella439's "Nix and Haskell in production" guide.

Pinning nixpkgs 📌

By default miso uses a known-to-work, pinned version of nixpkgs known as pkgs.

[!NOTE] miso also maintains a legacy version of nixpkgs known as legacyPkgs so we can use tools like nixops for deployment and to build miso with the original GHCJS 8.6 backend.

Binary cache

nix users on a Linux or OSX distros can take advantage of a binary cache for faster builds. To use the binary cache follow the instructions on cachix.

[!TIP] We highly recommend nix users consume the cachix cache. cachix use haskell-miso-cachix.

$ cachix use haskell-miso-cachix

When building miso projects w/ GitHub workflow CI, we recommend the Cachix GitHub action

- name: Install cachix
  uses: cachix/cachix-action@v16
  with:
    name: haskell-miso-cachix

Community :octocat:

Maintainers

@dmjio

Commercial 🚀

Since it's launch, miso has been used in a variety of industries, including but not limited to:

Quantitative finance
Network security
Defense research
Academia
SaaS companies
Public sector
Non-profit sector
etc.

The largest miso installation known was ~200,000 lines of miso code with 10,000+ users.

Contributing

Feel free to dive in! Open an issue or a submit Pull Request.

See CONTRIBUTING for more info.

Contributors 🦾

[!NOTE] This project exists thanks to all the people who contribute

Partnerships 🤝

If you'd like to support this project financially, be it through requesting feature development, or a corporate partnership, please drop us a line and we will be in touch shortly. [email protected]

Backers

Become a financial contributor and help us sustain our project and community. We are very grateful and thankful for our individual sponsors.

Moses Tschanz
@MaxGabriel
@maybetonyfu
@jhrcek
etc.

Organizations

Support this project with your organization. Your logo will show up here with a link to your website. We are also very grateful and thankful for our corporate sponsors.

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

Table of Contents

History 📜

Docs 📚

Quick start ⚡

Getting started

Setup 🏗️

cabal.project

app.cabal

Main.hs

Hot Reload 🔥

Installation

Haddocks

Wiki

Architecture

Examples

Building examples

Interacting with HTTP APIs 🔌

Coverage ✅

Native📱

Benchmarks 🏎️

Nix

Pinning nixpkgs 📌

Binary cache

Community :octocat:

Maintainers

Commercial 🚀

Contributing

Contributors 🦾

Partnerships 🤝

Backers

Organizations

License

`cabal.project`

`app.cabal`

`Main.hs`