# miso native

> Target iOS and Android by driving the Lynx runtime with the same components you write for the web.

Source: https://haskell-miso.org/docs/native/overview/

Your program runs in two JS interpreters at once: the *main thread* (MTS), which owns the drawing facilities, and the *background thread* (BTS), which owns the [native modules](https://lynxjs.org/guide/use-native-modules.html). miso runs on both and keeps them in sync. See [the dual-thread architecture](https://haskell-miso.org/docs/native/dual-thread/).

Miso.Native targets **native mobile devices** by driving the [Lynx](https://lynxjs.org) runtime instead of the browser DOM. The same MVU programming model, Component API, event delegation, and virtual-DOM diffing carry over unchanged from the web; only the element vocabulary differs (view\_ and text\_ instead of div\_ and span\_), and rendering goes through Lynx's [element PAPI](https://lynxjs.org/api/engine/element-api) instead of a browser DOM.

This module is the native analogue of the `miso` / `startApp` entry points: `native` (and `nativeWithContext`) boot a root component onto the Lynx runtime.

## Anatomy of a native miso app

Keep scrolling and the phone comes apart into the dual-thread architecture that runs miso on iOS and Android.

A miso app on your phone.

It all lives in one iOS process.

Lynx hosts two JavaScript interpreters: the main thread renders, the background thread thinks.

Each interpreter loads the same bundle: JavaScript, CSS, assets.

And inside the JS: two GHC runtimes, one application, one miso.

## Enabling native

The native backend is gated behind the `native` cabal flag. It must be enabled to bring `Miso.Native` and the `Miso.Native.*` element / event / FFI modules into scope (build with `-fnative`). Web / WASM builds are unaffected — all cross-thread machinery lives behind the `NATIVE` CPP guard.

```shell
$ nix develop github:dmjio/miso#native
$ cabal build -f native \
    --with-compiler=javascript-unknown-ghcjs-ghc \
    --with-hc-pkg=javascript-unknown-ghcjs-ghc-pkg
```

The JavaScript output is bundled for Lynx with [rspeedy](https://lynxjs.org/rspeedy) and loaded by the Lynx Explorer app or your own iOS / Android shell. The [miso-lynx](https://github.com/haskell-miso/miso-lynx) repository has the tooling, and [miso-lynx-gallery](https://github.com/haskell-miso/miso-lynx-gallery) a gallery of native components.

## Building a bundle with Nix

miso's flake exports everything needed to produce a `main.lynx.bundle` reproducibly. `miso.lib.${system}.ghcNative` is the GHC-JS package set with `miso-native` preinstalled — `callCabal2nix` your own app into it — and `pkgs.mkLynxBundle` (also exported as `miso.lib.${system}.mkLynxBundle`) turns that JS derivation into a Lynx bundle:

```haskell
{
  inputs.miso.url = "github:dmjio/miso";

  outputs = { miso, ... }:
    let system = "x86_64-linux";
        # or aarch64-darwin, …
        lib = miso.lib.${system};
    in {
      packages.${system}.bundle = lib.mkLynxBundle {
        name = "my-app-bundle";
        jsDrv =
          lib.ghcNative.callCabal2nix "my-app" ./. { };
        exeName = "my-app";
        styles = ./styles.css;
      };
    };
}
```

`nix build .#bundle` then leaves `result/main.lynx.bundle` ready to load in the Lynx Explorer app. For interactive work, `nix develop github:dmjio/miso#native` provides the GHC-JS compiler (the `ghcNative` package set), `rspeedy` and `bun`.

To ship a standalone iOS app, the [miso-lynx-gallery](https://github.com/haskell-miso/miso-lynx-gallery) example includes an `ios/` folder: copy the bundle the Nix derivation produced (the `/nix/store` output symlinked at `./result`) into the assets in `ios/` and build with Xcode. See [miso-lynx-gallery](https://github.com/haskell-miso/miso-lynx-gallery) for more information.

## Gallery

The UI stack miso drives natively, in the flesh — screens from Lynx's example apps. The [miso-lynx-gallery](https://github.com/haskell-miso/miso-lynx-gallery) repository builds a gallery of these components in miso.

![An image card with a like button, built on Lynx](https://haskell-miso.org/assets/lynx/lynx-demo-card.webp)![A two-column waterfall gallery built on Lynx, scrolling](https://haskell-miso.org/assets/lynx/lynx-demo-gallery.webp)![A swiper carousel with a page indicator, built on Lynx](https://haskell-miso.org/assets/lynx/lynx-demo-swiper.webp)

*Screens from the [Lynx](https://lynxjs.org) examples (CC BY 4.0) — see [haskell-miso/miso-lynx-gallery](https://github.com/haskell-miso/miso-lynx-gallery) for the miso versions.*

## In this section

- [The dual-thread architecture](https://haskell-miso.org/docs/native/dual-thread/) — BTS vs MTS, what crosses the boundary, the instant first frame.
- [Static mounting](https://haskell-miso.org/docs/native/static-mounting/) — why constructors cross threads as static pointers.
- [Effects, subscriptions and threads](https://haskell-miso.org/docs/native/effects-and-threads/) — `runOnBG`, `runOnMain` and guarding subs.
- [Main-thread events](https://haskell-miso.org/docs/native/main-thread-events/) — low-latency `*Main` handlers.
- [Main-thread-local state](https://haskell-miso.org/docs/native/main-thread-state/) — `MainThreadRef` and `eachFrame`.
- [Platform APIs](https://haskell-miso.org/docs/native/platform-apis/) — which APIs exist on which thread.
- [A minimal native component](https://haskell-miso.org/docs/native/minimal-component/) — the counter, natively.
