{"id":13726306,"url":"https://github.com/revery-ui/reason-reactify","last_synced_at":"2025-05-07T21:32:07.690Z","repository":{"id":76212680,"uuid":"149905761","full_name":"revery-ui/reason-reactify","owner":"revery-ui","description":":rocket: Transform a mutable tree into a functional React-like API","archived":true,"fork":false,"pushed_at":"2019-05-10T05:50:47.000Z","size":216,"stargazers_count":103,"open_issues_count":10,"forks_count":8,"subscribers_count":9,"default_branch":"master","last_synced_at":"2024-04-14T13:00:47.998Z","etag":null,"topics":["hooks","jsx","ocaml","react","reactify","reason","reasonml","reconciler","ui"],"latest_commit_sha":null,"homepage":"","language":"OCaml","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/revery-ui.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null}},"created_at":"2018-09-22T18:34:26.000Z","updated_at":"2023-12-21T12:45:24.000Z","dependencies_parsed_at":null,"dependency_job_id":"d70be9b4-e4ff-48cb-a5c2-c4113218c67f","html_url":"https://github.com/revery-ui/reason-reactify","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/revery-ui%2Freason-reactify","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/revery-ui%2Freason-reactify/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/revery-ui%2Freason-reactify/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/revery-ui%2Freason-reactify/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/revery-ui","download_url":"https://codeload.github.com/revery-ui/reason-reactify/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":224654214,"owners_count":17347697,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["hooks","jsx","ocaml","react","reactify","reason","reasonml","reconciler","ui"],"created_at":"2024-08-03T01:02:58.712Z","updated_at":"2024-11-14T16:33:39.273Z","avatar_url":"https://github.com/revery-ui.png","language":"OCaml","funding_links":[],"categories":["OCaml"],"sub_categories":[],"readme":"[![Build Status](https://dev.azure.com/revery-ui/revery/_apis/build/status/revery-ui.reason-reactify?branchName=master)](https://dev.azure.com/revery-ui/revery/_build/latest?definitionId=3?branchName=master)\n[![npm version](https://badge.fury.io/js/reason-reactify.svg)](https://badge.fury.io/js/reason-reactify)\n\n# :rocket: Reactify\n\n#### Transform a mutable tree into a functional React-like API, in native Reason!\n\n## Why?\n\nReason is \"react as originally intended\", and the language provides excellent faculty for expressing a react-like function API, with built-in JSX support.\n\nI often think of React purely in the context of web technologies / DOM, but the abstraction is really useful in other domains, too.\n\nThere are often cases where we either inherit some sort of mutable state tree (ie, the DOM), or when we create such a mutable structure for performance reasons (ie, a scene graph in a game engine). Having a functional API that always renders the entire tree is a way to reduce cognitive load, but for the DOM or a scene graph, it'd be too expensive to rebuild it all the time. So a react-like reconciler is useful for being able to express the tree in a stateless, purely functional way, but also reap the performance benefits of only mutating what needs to change.\n\n## Let's build a reconciler!\n\n### Quickstart\n\nThe way the library works is you implement a Module that implements some basic functionality:\n\nThis will be familiar if you've ever created a React reconciler before!\n\n### Step 1: Tell us about your primitives\n\nFirst, let's pretend we're building a reconciler for a familiar domain - the HTML DOM. (You wouldn't really want to do this for production - you're better off using ReasonReact in that case!). But it's a good example of how a reconciler works end-to-end.\n\nWe'll start with an empty module:\n```diff\n+ module WebReconciler {\n+\n+ }\n```\n\nAnd we'll create a type `t` that is a [__variant__](https://reasonml.github.io/docs/en/variant) specifying the different types of primitives. Primitives are the _core building blocks_ of your reconciler - these correspond to raw dom nodes, or whatever base type you need for your reconciler.\n\nLet's start it up with a few simple tags:\n```diff\nmodule WebReconciler {\n+    type imageProps = {\n+       src: string;\n+    };\n+\n+    type t =\n+    | Div\n+    | Span\n+    | Image(imageProps);\n}\n```\n\n### Step 2: Tell us your node type\n\nThe `node` is the type of the actual object we'll be working with in our mutable state tree. If we're using [`js_of_ocaml`](https://ocsigen.org/js_of_ocaml), we'd get access to the DOM elements via [`Dom_html.element`](https://ocsigen.org/js_of_ocaml/3.1.0/api/Dom_html) - that's the type we'll use for our node.\n\n```diff\nmodule WebReconciler {\n    type imageProps = {\n       src: string;\n    };\n\n    type t =\n    | Div\n    | Span\n    | Image(imageProps);\n\n+    module Html = Dom_html;\n+    type node = Dom_html.element;\n}\n```\n\nNot too bad so far!\n\n### Step 3: Implement a create function\n\nOne of the most important jobs our reconciler has is to turn the _primitive_ objects into real, living _nodes_. Let's implement that now!\n\n```diff\nmodule WebReconciler {\n    type imageProps = {\n       src: string;\n    };\n\n    type t =\n    | Div\n    | Span\n    | Image(imageProps);\n\n    type node = Dom_html.element;\n\n+    let document = Html.window##.document;\n+\n+    let createInstance: t =\u003e node = (primitive) =\u003e {\n+        switch(primitive) {\n+        | Div =\u003e Html.createDiv(document);\n+        | Span =\u003e Html.createSpan(document);\n+        | Image(p) =\u003e \n+           let img = Html.createImage(document);\n+           img.src = p.src;\n+           img;\n+        };\n+    };\n}\n```\n\nNote how easy [pattern matching](https://reasonml.github.io/docs/en/pattern-matching) makes it to go from primitives to nodes.\n\n### Step 4: Implement remaining tree operations \n\nFor our reconciler to work, we also need to implement these operations:\n- `updateInstance`\n- `appendChild`\n- `removeChild`\n- `replaceChild`\n\nLet's set those up!\n\n```diff\nmodule WebReconciler {\n    type imageProps = {\n       src: string;\n    };\n\n    type t =\n    | Div\n    | Span(string)\n    | Image(imageProps);\n\n    type node = Dom_html.element;\n\n    let document = Html.window##.document;\n\n    let createInstance: t =\u003e node = (primitive) =\u003e {\n        switch(primitive) {\n        | Div =\u003e Html.createDiv(document);\n        | Span(t) =\u003e \n            let span = Html.createSpan(document);\n            span##textContent = t;\n        | Image(p) =\u003e \n           let img = Html.createImage(document);\n           img##src = p.src;\n           img;\n        };\n    };\n\n+   let updateInstance = (node, oldPrimitive, newPrimitive) =\u003e {\n+       switch ((oldState, newState)) =\u003e {\n+       /* The only update operation we handle today is updating src for an image! */\n+       | (Image(old), Image(new)) =\u003e node.src = new.src;\n+       | _ =\u003e ();\n+       };\n+   };\n+\n+   let appendChild = (parentNode, childNode) =\u003e {\n+       parentNode.appendChild(childNode);\n+   };\n+\n+   let removeChild = (parentNode, childNode) =\u003e {\n+       parentNode.removeChild(childNode);\n+   };\n+\n+   let replaceChild = (parentNode, oldChild, newChild) =\u003e {\n+       parentNode.replaceChild(oldChild, newChild);\n+   };\n}\n```\n\nPhew! That was a lot. Note that `createInstance` and `updateInstance` are operations that use _primitives_ to pass around some context. In this case, we carry around a `src` property for Image, and we set it on `createInstance` and `updateInstance`. The other operations - `appendChild`, `removeChild`, and `replaceChild` are purely _node_ operations. The internals of the reconciler handle the details of associating a `primitive` -\u003e `node`.\n\n### Step 5: Hook it up\n\n`reactify` provides a [functor](https://reasonml.github.io/docs/en/module#module-functions-functors) for building a React API from your reconciler:\n\n```diff\n+ module MyReact = Reactify.Make(WebReconciler);\n```\n\nWe'll also want to define some _primitive components_:\n\n```diff\n+ let div = (~children, ()) =\u003e primitiveComponent(Div, ~children);\n+ let span = (~children, ~text, ()) =\u003e primitiveComponent(Span(text), ~children);\n+ let image = (~children, ~src, ()) =\u003e primitiveComponent(Image(src), ~children);\n```\n\nThese primitives are the building blocks that we can start composing to build interesting things.\n\nCool!\n\n### Step 6: Use your API!\n\nWe have everything we need to start building things. Every Reactify'd API needs a container - this stores the current reconciliation state and allows us to do delta updates. We can create one like so:\n\n#### Create / update a container\n\n```diff\n+ let container = MyReact.createContainer(Html.window##.document##body())\n+ MyReact.updateContainer(container, \u003cspan text=\"Hello World\" /\u003e):\n```\n\n#### Create custom components\n\n## API\n\n- Custom Components\n    - Hooks\n        - useState\n        - useEffect\n    - Context\n\n### Examples\n- [Lambda_term](examples/lambda-term/Lambda_term.re)\n\n### Usages\n\n- [Revery](https://github.com/bryphe/revery)\n\n## Development\n\n### Install [esy](https://esy.sh/)\n\n`esy` is like `npm` for native code. If you don't have it already, install it by running:\n```\nnpm install -g esy\n```\n\n### Building\n\n- `esy install`\n- `esy build`\n\nor build JS:\n- `esy build:js`\n\n### Running Examples\n\n- `esy b dune build @examples`\n\n\u003e You can then run `Lambda_term.exe` in `_build/default/examples`\n\n### Running Tests\n\n__Native tests:__\n- `esy test:native`\n\n__JS tests:__\n- `esy test:js`\n\n## Limitations\n\n- This project is not using a __fiber-based__ renderer. In particular, that means the following limitations:\n    - Custom components are constrained to returning a single element, to simplify reconciliation.\n    - Updates are not suspendable / resumable. This may not be necessary with native-performance, but it would be nice to have.\n\n## License\n\nThis project is provided under the [MIT License](LICENSE).\n\nCopyright 2018 Bryan Phelps.\n\n## Additional Resources\n\n- The API surface was inspired by the [react-reconciler](https://github.com/facebook/react/tree/master/packages/react-reconciler) package. If you've worked with that before, the `createContainer` and `updateContainer` will be familiar.\n- Related / helpful projects:\n    - [Didact: A DIY React Renderer](https://engineering.hexacta.com/didact-learning-how-react-works-by-building-it-from-scratch-51007984e5c5) - was really useful for learning!\n    - [ReactMini](https://github.com/reasonml/reason-react/tree/master/ReactMini/src)\n    - [BriskML](https://github.com/briskml/brisk) has an expanded implementation of ReactMini: https://github.com/briskml/brisk/blob/master/core/lib/ReactCore_Internal.re\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frevery-ui%2Freason-reactify","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frevery-ui%2Freason-reactify","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frevery-ui%2Freason-reactify/lists"}