miso

A tasty Haskell front-end framework

' ``` To be put into a shell w/ `GHCJS` and all the dependencies for this project present, use `nix-shell`. ``` nix-shell -A env ``` To view the dependencies for your project, call `ghcjs-pkg list` when inside the shell. ``` nix-shell -A env --run 'ghcjs-pkg list' ``` To build the project with `cabal` after entering the `nix-shell` ``` nix-shell -A env --run 'cabal configure --ghcjs && cabal build` ``` For incremental development inside of the `nix-shell` we recommend using a tool like [`entr`](http://eradman.com/entrproject/) to automatically rebuild on file changes, or roll your own solution with `inotify`. ``` ag -l | entr 'cabal build' ``` ### 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](https://github.com/dmjio/miso/blob/master/examples/haskell-miso.org/haskell-miso.cabal#L16-L60). For more info on how to use `stack` with a `client`/`server` setup, see this [link](https://docs.haskellstack.org/en/stable/ghcjs/#project-with-both-client-and-server). For more information on how to use `nix` with a `client`/`server` setup, see the [nix scripts](https://github.com/dmjio/miso/blob/master/examples/haskell-miso.org/default.nix) for [https://haskell-miso.org](https://haskell-miso.org). ## Examples ### TodoMVC - [Link](https://todo-mvc.haskell-miso.org/) / [Source](https://github.com/dmjio/miso/blob/master/examples/todo-mvc/Main.hs) ### Flatris - [Link](https://flatris.haskell-miso.org/) / [Source](https://github.com/ptigwe/hs-flatris/) ### 2048 - [Link](http://2048.haskell-miso.org/) / [Source](https://github.com/ptigwe/hs2048/) ### Snake - [Link](http://snake.haskell-miso.org/) / [Source](https://github.com/lbonn/miso-snake) ### Mario - [Link](https://mario.haskell-miso.org/) / [Source](https://github.com/dmjio/miso/blob/master/examples/mario/Main.hs) ### Miso Plane (Flappy Birds) - [Link](https://miso-plane.lermex.net/) / [Source](https://github.com/Lermex/miso-plane) ### Websocket - [Link](https://websocket.haskell-miso.org/) / [Source](https://github.com/dmjio/miso/blob/master/examples/websocket/Main.hs) ### SSE - [Link](https://sse.haskell-miso.org/) / [Client](https://github.com/dmjio/miso/blob/master/examples/sse/client/Main.hs) / [Server](https://github.com/dmjio/miso/blob/master/examples/sse/server/Main.hs) ### XHR - [Link](https://xhr.haskell-miso.org/) / [Source](https://github.com/dmjio/miso/blob/master/examples/xhr/Main.hs) ### Router - [Link](https://router.haskell-miso.org/) / [Source](https://github.com/dmjio/miso/blob/master/examples/router/Main.hs) ### SVG - [Link](https://svg.haskell-miso.org/) / [Source](https://github.com/dmjio/miso/blob/master/examples/svg/Main.hs) ### Canvas 2D - [Link](http://canvas.haskell-miso.org/) / [Source](https://github.com/dmjio/miso/blob/master/examples/canvas2d/Main.hs) ### ThreeJS - [Link](http://threejs.haskell-miso.org/) / [Source](https://github.com/dmjio/miso/blob/master/examples/three/Main.hs) ### Simple - [Link](https://simple.haskell-miso.org/) / [Source](https://github.com/dmjio/miso/blob/master/exe/Main.hs) ### File Reader - [Link](https://file-reader.haskell-miso.org/) / [Source](https://github.com/dmjio/miso/blob/master/examples/file-reader/Main.hs) ### WebVR - [Link](https://fizruk.github.io/fpconf-2017-talk/miso-aframe-demo/dist/demo.jsexe/index.html) / [Source](https://github.com/fizruk/miso-aframe) ## Haddocks ### GHCJS - [Link](https://haddocks.haskell-miso.org/) ### GHC - [Link](http://hackage.haskell.org/package/miso) ## Sample application ```haskell -- | Haskell language pragma {-# LANGUAGE OverloadedStrings #-} {-# LANGUAGE RecordWildCards #-} -- | Haskell module declaration module Main where -- | Miso framework import import Miso import Miso.String -- | Type synonym for an application model type Model = Int -- | Sum type for application events data Action = AddOne | SubtractOne | NoOp | SayHelloWorld deriving (Show, Eq) -- | Entry point for a miso application main :: IO () main = startApp App {..} where initialAction = SayHelloWorld -- initial action to be executed on application load model = 0 -- initial model update = updateModel -- update function view = viewModel -- view function events = defaultEvents -- default delegated events subs = [] -- empty subscription list mountPoint = Nothing -- mount point for application (Nothing defaults to 'body') -- | Updates model, optionally introduces side effects updateModel :: Action -> Model -> Effect Action Model updateModel AddOne m = noEff (m + 1) updateModel SubtractOne m = noEff (m - 1) updateModel NoOp m = noEff m updateModel SayHelloWorld m = m <# do putStrLn "Hello World" >> pure NoOp -- | Constructs a virtual DOM from a model viewModel :: Model -> View Action viewModel x = div_ [] [ button_ [ onClick AddOne ] [ text "+" ] , text (ms x) , button_ [ onClick SubtractOne ] [ text "-" ] ] ``` ## Building examples The easiest way to build the examples is with the [`nix`](https://nixos.org/nix/) package manager ``` git clone https://github.com/dmjio/miso && cd miso && nix-build -A miso-ghcjs ``` This will build all examples and documentation into a folder named `result` ``` ➜ miso git:(master) ✗ tree -d ./result/bin ./result/bin |-- canvas2d.jsexe |-- compose-update.jsexe |-- file-reader.jsexe |-- mario.jsexe | `-- imgs |-- mathml.jsexe |-- router.jsexe |-- simple.jsexe |-- svg.jsexe |-- tests.jsexe |-- threejs.jsexe |-- todo-mvc.jsexe |-- websocket.jsexe `-- xhr.jsexe ``` To see examples, we recommend hosting them with a webserver ``` cd result/bin/todo-mvc.jsexe && nix-shell -p python --run 'python -m SimpleHTTPServer' Serving HTTP on 0.0.0.0 port 8000 ... ``` ## Coverage The core algorithmic component of miso is [diff.js](https://github.com/dmjio/miso/blob/master/jsbits/diff.js). It is responsible for all DOM manipulation that occurs in a miso application and has [100% code coverage](http://coverage.haskell-miso.org). Tests and coverage made possible using [jsdom](https://github.com/jsdom/jsdom) and [jest](https://github.com/facebook/jest). To run the tests and build the coverage report: ```bash cd miso/tests npm i npm run test ## Or by using `yarn` instead of `npm`: # yarn # yarn test ``` ## Isomorphic [Isomorphic javascript](https://en.wikipedia.org/wiki/Isomorphic_JavaScript) is a technique for increased SEO, code-sharing and perceived page load times. It works in two parts. First, the server sends a pre-rendered HTML body to the client's browser. Second, after the client javascript application loads, the pointers of the pre-rendered DOM are copied into the virtual DOM, and the application proceeds as normal. All subsequent page navigation is handled locally by the client, avoiding full-page postbacks as necessary. The `miso` function is used to perform the pointer-copying behavior client-side. For more information on how `miso` handles isomorphic javascript, we recommend [this tutorial](https://github.com/FPtje/miso-isomorphic-example). ## Pinning nixpkgs By default `miso` uses a known-to-work, pinned version of [`nixpkgs`](https://github.com/dmjio/miso/blob/master/nixpkgs.json). ## Binary cache `nix` users on a Linux or OSX distro can take advantage of a [binary cache](https://haskell-miso.cachix.org) for faster builds. To use the binary cache follow the instructions on [cachix](https://haskell-miso.cachix.org/). ```bash cachix use haskell-miso ``` ## Benchmarks [According to benchmarks](https://rawgit.com/krausest/js-framework-benchmark/master/webdriver-ts-results/table.html), `miso` is among the fastest functional programming web frameworks, second only to [Elm](http://elm-lang.org). ## Maintainers [@dmjio](https://github.com/dmjio) ## Contributing Feel free to dive in! [Open an issue](https://github.com/dmjio/miso/issues/new) or submit [PRs](https://github.com/dmjio/miso/pulls). See [CONTRIBUTING](https://github.com/dmjio/miso/blob/master/CONTRIBUTING.md) for more info. ## License [BSD3](LICENSE) © David Johnson