Middleware
One of the primary ways of extending diffHTML is to write middleware.
Middleware are added using the top-level
use()
API. This
injects functions into the render pipeline, which grants access the state
before and after a sync/patch render.
Additionally, you can hook into when diffHTML creates new elements, elements are released, and handle these events. You can change how elements are created, and much more. Middleware should be designed to allow being enabled and disabled, as this enables DevTools to toggle your plugin.
Writing middleware
Authoring middleware with diffHTML should not feel daunting; it was designed to be straightforward for simple things like tracking when renders occur, what the previous and next (X)HTML trees look like, and what the given set of DOM updates were for the render.
While simple things are easy to access, the API allows for significantly more complex operations, such as:
- Creating new elements
- Changing the DOM synchronization logic
- Adopt elements/components from other frameworks
- XML transformations
- React to DevTools changes
Lastly, middleware can be used with the toString method. So if you are extra ambitious you can get your middleware to be fully cross-platform even during Server-Side-Rendering.
The code for a basic middleware looks as simple as:
import { use } from 'diffhtml';
use(transaction => {
console.log('Render transaction is starting');
return () => {
console.log('Render transaction is ending');
transaction.onceEnded(() => {
console.log('Render transaction has completed');
});
};
});
There are several core middleware modules already written that you could use as a reference. A good starting one to look at is the Logger if you're interested in logging the render transaction flow.
If you wanted to track when an element enters and leaves the DOM you could use the attached and detached transition states . You could also check the transaction when rendering is complete to see what is being attached and removed.
use(() => ({ patches }) => {
console.log(patches);
});
Inline Transitions
Tiny module to support binding/unbinding declarative diffHTML transition hooks.
npm install diffhtml-middleware-inline-transitions
Full events and args list:
Event Name | Args |
---|---|
onattached | (eventTarget, domNode) |
ondetached | (eventTarget, domNode) |
onreplaced | (eventTarget, oldNode, newNode) |
onattributechanged | (eventTarget, oldNode, attributeName, oldValue, newValue) |
ontextchanged | (eventTarget, oldNode, oldValue, newValue) |
Example
Apply to an element by passing the function to the associated state name:
import $ from 'jquery';
import { innerHTML, html, use } from 'diffhtml';
import inlineTransitions from 'diffhtml-middleware-inline-transitions';
// Enable the monitoring of attributes for changes.
use(inlineTransitions());
// Use jQuery to return a promise and fade in the body and paragraph.
function fadeIn(body, domNode) {
return $(domNode).fadeOut(0).fadeIn(1000).promise();
}
innerHTML(document.body, html`<body onattached=${fadeIn}>
<p>Watch me fade in slowly!</p>
</body>`);
Logger
Use with diffHTML to console.log
out render
Transaction
operations. This will nest
sub-component renders if they happen during a parent render.
npm install diffhtml-middleware-logger

Example
import { use } from 'diffhtml';
import logger from 'diffhtml-middleware-logger';
use(logger());
This is not a very performant middleware, so please do not use this in production where performance is critical. Use only in development or behind a flag.
Service Worker
While this does not really benefit from being a middleware, I made it as such since it looks nice in the use and can be disabled if the middleware is unsubscribed. I've added some developer niceties, like auto clearing the caches for development. It's also possible to disable the worker completely if you get annoyed with some behavior.
npm install diffhtml-middleware-service-worker
Example
import { use } from 'diffhtml';
import serviceWorker from 'diffhtml-middleware-service-worker';
// Defaults shown, these are all optional values.
use(serviceWorker({
url: '/service-worker.js',
scope: '/',
autoClearCaches: location.search.includes('diff_autoclear'),
disable: location.search.includes('diff_disable'),
quiet: location.search.includes('diff_quiet'),
options: {},
}));
Synthetic Events
Changes the event binding from inline event handlers like onclick = fn
to use
addEventListener
. Hooks are attached to the body
element and coordinated
using event delegation.
npm install diffhtml-middleware-synthetic-events
Example
import { use, html, innerHTML } from 'diffhtml';
import syntheticEvents from 'diffhtml-middleware-synthetic-events';
use(syntheticEvents());
function render() {
return html`
<div onclick=${e => console.log(e)} />
`;
}
// Binds the event on div using `addEventListener`.
innerHTML(document.body, render());
A good use case for this middleware is building a Chrome Extension where using
inline event handlers is not possible. Supports non-bubbling events via the
useCapture
flag.
Verify State
Asserts that a render properly updated the old Virtual Tree and the DOM. Will recursively search for inconsistencies, displays warnings unless debugging is enabled, then it throws errors instead.
npm install diffhtml-middleware-verify-state

Example
import { use } from 'diffhtml';
import verifyState from 'diffhtml-middleware-verify-state';
// Throw when debug is truthy (when location.search has `?debug`)
use(verifyState({ debug: location.search.includes('debug') }));
HTML Linter
Validates your passed in markup against rules established in the HTMLHint project.
npm install diffhtml-middleware-linter
Example
import { use } from 'diffhtml';
import linter from 'diffhtml-middleware-linter';
use(linter({
// Supported rules and their defaults.
rules: {
"tagname-lowercase": true,
"attr-lowercase": true,
"attr-value-not-empty": false,
"id-unique": true,
"src-not-empty": true,
"title-require": true,
"alt-require": true,
"id-class-value": "dash",
"style-disabled": false,
"inline-style-disabled": false,
"inline-script-disabled": false,
"attr-unsafe-chars": true,
"head-script-disabled": true,
},
renderErrors: true // by default is false
}));