@matry/dom
v0.0.5
Published
A web framework for imperative JSX
Downloads
15
Readme
@matry/dom
A web framework for imperative JSX - a new way to think about UI engineering.
I initially created this for the Matry editor,
but I saw that it could be generally useful, so I'm releasing it under the MIT license.
Right now it's brand new, under active development, and pretty under-powered.
Do not use it in production until it reaches v1.0.0.
To see examples of it in action, I've created a repo with recipes
Overview
I love React, but it has issues:
- The diffing behavior can be conceptually difficult to understand
- It can be awkward to work with inherently imperative constructs such as
setTimeoutandautofocus - Context, hooks, and signals are all required to pass state around the UI tree
- The structure of your application state ends up being shaped by the UI, when it should be the other way around
- React takes total control over anything in its tree, meaning most UI packages must have React-specific integrations to work correctly
- Getting React to work with SSR has caused lots of headaches
- It creates a barrier between the developer and the DOM, leading to a generation of devs missing out on core platform features
- There's a ceiling to how performant a React application can be, and maximizing performance requires deep understanding of React's rendering model
- Because of React's one-way data flow, there are no built-in features for reading the state of the UI
If we accept the fact that the web is inherently imperative, then I believe we can resolve most if not all of the above problems. We don't need to throw the baby out with the bathwater though, because JSX is fantastic.
Matry exposes a handful of simple, standalone functions that allow you to use JSX to imperatively create and update the DOM. This is a significant departure from how JSX is traditionally used, but the benefit of this approach is that your UI remains declarative, while your business logic remains imperative. This means no more hooks, no more context, no more prop drilling.
Below are the functions provided by @matry/dom:
- Replace - replaces one or more elements' children
- Append - appends new elements
- Remove - removes elements
- Swap - swaps two elements
- Set Content - sets the text content of one or more elements
- Set Attributes - sets attributes of one or more elements
- Remove Attributes - removes attributes from one or more elements
- Add Event Listeners - adds event listeners to one or more elements
- Remove Event Listeners - removes event listeners from one or more elements
Quick Tour
Below is a simple counter demo.
<!-- initial html -->
<html>
<head>
<title>My Counter App</title>
</head>
<body>
<main></main>
</body>
</html>// set our initial value
let count = 0;
// perform our initial render
replace(
<main>
<p key="counter">The count is {count}</p>
<button onclick={add}>add 1</button>
</main>
);
// replace the text content
function add() {
count++;
setContent(<p key="counter">The count is {count}</p>);
}In the above example,
we call replace to render our UI into the main element.
Then we use setContent to update the content of the p element.
Notice when updating the DOM, we only need to pass in just enough JSX to identify which elements we want to modify.
This puts you in complete control of your apps performance.
Tradeoffs
As with all technology, there are advantages and disadvantages of this approach. In the interest of being transparent, I'll list the disadvantages first.
disadvantages
- Since JSX is acting as a query, the queries have limited expressive power. For instance, in order to match against a node in the DOM, it must be an exact match, i.e. there can be no "contains" queries as it would introduce too many edge cases.
- There will be duplication of html content, at least in terms of code. While this can be reduced by various strategies, it's kind of unavoidable.
- You have to really think about the UI, which is something you may not be used to if you're used to React. I'd argue this is a good thing, but it won't be everyone's cup of tea.
- It doesn't define how you procure your state, whereas React tends to be a bit more opinionated. This can lead to more architectural work needed for developers. I'd again argue this is a net good, but you can decide for yourself whether this is something you want.
advantages
- You have complete control over the rendering process, and can make Matry applications as performant as you want.
- Matry doesn't "own" the UI you pass to JSX, so you can easily use common libraries (e.g. the Google Maps SDK) without worry. Heck, you can even render to the
html,head, andbodyelements! - The functions offered by Matry -
write(),append(),setAttributes()and others - are mirror counterparts to native DOM methods, meaning you can think about the platform. There's no such thing as "thinking in Matry", it's just "thinking in the web." - Unlike React, Matry is truly a "UI library." It has no side effects that require you to structure your code or your data in any particular way.
Getting Started
First, install the package. Vite is recommended, mostly because that's what I've used to test it with :p
npm create vite whatever # choose Vanilla, then JavaScript (for now)
cd whatever
npm install @matry/domNext, configure Vite so that you can use Matry's JSX runtime:
// vite.config.js
import { defineConfig } from "vite";
export default defineConfig({
esbuild: {
jsx: "transform",
jsxDev: false,
jsxInject: `import { jsx } from '@matry/dom'`,
jsxFactory: "jsx.component",
},
});Voila! You're good to go!
Current State
Matry should not be considered stable until 1.0.0,
so do not use it in production until then.
There are lots of features yet to be implemented - stay tuned!
Roadmap
Some things I have planned for the library:
- TypeScript support
reverse()for reversing lists of elementspaint()for updating the CSSOMserialize()for rendering JSX to a string (primarily for SSR)deserialize()for rendering a string (will be used in respones from SSR updates)read()for loading data from static html into JS memory