hypnode
v1.3.1
Published
A super fast, lightweight (roughly **1kb** gzipped) and reactive series of utility functions, used to build HTML node trees and stateful functional components. Can be used either directly via the `h` function, or from transpiled `JSX`.
Downloads
55
Readme
A super fast, lightweight (roughly 1kb gzipped) and reactive series of utility functions, used to build HTML node trees and stateful functional components. Can be used either directly via the h
function, or from transpiled JSX
.
Due to it's size, hypnode
is a useful companion utility for writing WebComponents, simplifying HTML
structures, element references and state management. See section entitled "WebComponents" for an example, click to jump there.
Getting Started
To install hypnode
, you can use one of the following in your project:
yarn add hypnode
or npm install hypnode
hypode
can be used in one of two ways, either as a target for JSX
transpilation, or directly using the exposed h
function. It's exported as ES6, so if you need to support older environments, you'll need to transpile down to ES5 in your build tasks.
The h
function can be imported in one of the following ways:
import { h } from 'hypnode';
const { h } = require('hypnode');
Direct Usage
Once imported, use the function to generate your tree of DOM Nodes. The function takes 3 arguments, the last two of which are optional:
h([type]: string | Function, [attributes]?: object, [children]?: array[]);
Simple Example
The code below:
import { h, render } from 'hypnode';
/*[...]*/
const result = render(
h('div', { title: 'A DIV!' }, [
h('h1', { class: 'title' }, 'Hypnode'),
h('p', { id: 'text'}, 'My text value'),
)
);
console.log(result.outerHTML);
Will produce the following:
<div title="A DIV!">
<h1 class="title">Hypnode</h1>
<p id="text">My text value</p>
</div>
JSX Elements
hypnode
can be used with JSX
to provide a more familiar API when building DOM structures. This will need a transpilation step, see below for examples.
TypeScript
Transpilation of JSX
is provided out of the box by custom factories (TypeScript 1.8+), to apply this, add the following to your tsconfig.json
file:
"compilerOptions": {
"jsx": "react",
"jsxFactory": "h",
/*[...]*/
}
This tells the TypeScript compiler to convert all JSX
elements into function calls, in this case using our exported h
function. You'll still need to import the h
function in every file where you're using JSX
.
To apply the correct types, all files that contain JSX
must have the extension .tsx
.
Simple Example
The code below:
import { h, render } from 'hypnode';
/*[...]*/
const root = document.getElementId('root');
const result = render(
<div class="wrapper">
<a id="link" onClick={(ev = console.log(ev))}>
Click here
</a>
</div>
);
root.appendChild(result);
Will produce the following:
<div class="wrapper">
<a id="link">
Click here
</a>
</div>
Rendering
As the render()
function exported by hypnode
returns a fully formed HTMLElement
, you can handle it's output easily using native DOM
API's like root.appendChild
or root.replaceChild
. There is, however, an optional secondary argument that can handle this for you, e.g:
const result = h('div', { class: 'wrapper' }, 'Lorem ipsum');
/*[...]*/
render(result, document.getElementById('root'));
or, with JSX
:
const result = <div class="wrapper">Lorem ipsum</div>;
/*[...]*/
render(result, document.getElementById('root'));
Event Binding
hypnode
provides a set of properties for you to apply DOM events. All native events are supported, formatted in camelCase and prefixed with on
. For example:
h('a', { onClick: (ev) => console.log(ev) }, 'Click Here');
or, with JSX
:
<input onKeyUp={(ev) => console.log(ev)} />
Element References
If you need access to a particular node in your tree, use the ref
property. For example:
let myElement;
/*[...]*/
h('div', { id: 'container' }, [
h('p', { ref: (el) => (myElement = el) }, 'Lorem ipsum dolor sit amet, consectetur'),
]);
or with JSX
:
let myElement;
/*[...]*/
<div class="wrapper">
<a href="//link.co" ref={(el) => (myElement = el)}>
Click here
</a>
</div>;
Components
hypnode
can be used to create re-usable, functional components, below is a simple example:
import { h, render } from 'hypnode';
/*[...]*/
function Button({ className = '', children }) {
return h('a', { class: `button ${className}` }, children);
}
/*[...]*/
const button = h(Button, { className: 'big' }, buttonText));
render(button, document.getElementById('root'))
or with JSX
:
import { h, render } from 'hypnode';
/*[...]*/
function Button({ className = '', children }) {
return <a class={`button ${className}`}>{children}</a>;
}
/*[...]*/
const button = <Button className="big">Click here</Button>;
render(button, document.getElementById('root'));
WebComponents
Creating and managing complex HTML structures using WebComponents can become tricky as their size increases. hypnode
simplifies this by incorporating a familiar component and state pattern into your custom elements. You can find more info on WebComponents here. As hypnode
is fast and lightweight, WebComponents can be more easily shared between projects without significant dependency overhead.
A quick example can be found below:
// myComponent.tsx (TypeScript + JSX)
import { h, render, useState, State } from 'hypnode';
/*[...]*/
class MyComponent extends HTMLElement {
private state: State<number>;
public connectedCallback() {
const Button = () => this.renderButton();
this.appendChild(render(<Button />));
}
private renderButton = () => {
const [counter] = (this.state = useState(0));
return (
<div class="my-component">
<p>Counter: {counter}</p>
<button onClick={this.onClick}>Click Here</button>
</div>
);
}
private onClick = (ev: Event) => {
const [counter, setState] = this.state;
setState(counter + 1);
}
}
State
hypnode
exposes a simple, declarative hook to provide state into your functional application.
First, you'll need to import the hook function:
import { h, useState } from 'hypnode';
Once imported, you can initialize a state registry in your components by doing the following:
const [state, setState] = useState(([value]: any));
The useState
function takes a single argument, the initial value you wish to assign to the state. This can be anything, a primitive or something more complex like an object. For example:
function Button({ buttonText }) {
const [state, setState] = useState(10);
return h('button', { onClick: () => setState(state + 1) }, `${buttonText}: ${state}`);
}
You provide mutations to your state via the setState
function, this accepts a new value you wish to assign. Whenever this function is called, the component will be re-rendered with the replaced state value.
Effects
hypnode
exports a simple effect hook, useEffect
. This takes a callback as it's only argument which will be called on "mount". You can optionally return another function from it that will be called on "un-mount". The lifecycle of this function works in a similar way to React's hook by the same name.
See example below:
import { h, useEffect } from 'hypnode';
/*[...]*/
function Banner({ children }) {
useEffect(() => {
console.log('onMount');
return () => console.log('onUnMount (optional)');
});
return h('div', { class: 'banner' }, children);
}
Server Side Rendering
hypnode
provides a Virtual DOM
representation for server side rendering (universal rendering). You can use this output to generate a complete HTML
representation of your app. A prebuilt utility that can convert this into an HTML
string can be found here: hypnode-server
TypeScript
This utility was created with TypeScript and comes pre-bundled with a definition file.