Heresy-ssr NPM

heresy SSR

Don't simulate the DOM. Be the DOM.

Social Media Photo by Thomas Kelley on Unsplash

WebReflection status

It's pretty much the same heresy, but for the server, and with extra features.

📣 Community Announcement

Please ask questions in the dedicated discussions repository, to help the community around this project grow ♥

V2 Breaking Changes

Please be sure you understand the breaking changes landed in lighterhtml.

How To Install With Canvas

If you need/want to use the <canvas> element, which is a dev dependency of basicHTML, you explicitly need to type:

# install heresy-ssr with canvas
npm i heresy-ssr canvas

Otherwise heresy-ssr will ship without canvas via simply typing:

# install heresy-ssr without canvas
npm i heresy-ssr

Extra Features

dedicated onSSRInit/AttributeChanged/Connected/Disconnected methods to override client side oninit/attributechanged/connected/disconnected, in order to fine-tune, whenever necessary, the layout and behavior via SSR
an already available <CustomELement/> tag to put in the header, whenever polyfills for legacy or WebKit/Safari are needed. The component accepts modern and legacy attributes as pointers to polyfills, loaded only after feature detection to leave Chrome, Firefox, and Edge on Chromium free of bloat.
components style automatically minified via csso
global customElements or document, swappable on the window with any local instance of Document or CustomElementRegistry

Basic Example

You can see inside the test folder a similar example you can run via npm run build or just npm test, after the first build.

const {document, render, html} = require('heresy-ssr');

const Body = require('./body.js');
define('Body', Body);

const lang = 'en';
const {hostname} = require('os');
const {readFileSync} = require('fs');

render(document, html`
  <html lang=${lang}>
    <head>
      <title>🔥 heresy SSR 🔥</title>
      <CustomElements/>
      <script defer src="//unpkg.com/heresy"></script>
      <script type="module" src="definitions.js"></script>
    </head>
    <Body data-hostname=${hostname}/>
  </html>
`);

You can also try node test/twitter-share.js to see an example of a component served through the same definition crystal clean via SSR, but still re-hydrated on the client whenever the definition lands on the page.

Multiple Documents

The default document is ideal for Single Page Applications but not optimal for sites distributed through various pages.

In latter scenario, you can use a new document per each render.

const {Document, render, html} = require('heresy-ssr');

// create a new document related to this page only
const document = new Document;

render(document, html`<h1>Hello</h1>`);

Project Goals

reuse exact same components on client as well as on the server, with the ability to provide cleaner layouts via SSR
hydration on the fly without even thinking about it, whenever the definition lands on the client, it just works™️
Custom Elements and built-in extends out of the box for any sort of client/server need
you work on the server with same DOM primitives you know on the client, but you can also create as many documents you want, so that each page is reflected by a different, always clean document

Differences from viperHTML

There are tons of differences with viperHTML at this stage:

the template literal parser is exactly the same one used on the client (slower cold bootstrap, but damn fast hot renders)
the code is exactly the same one used by the client library, with minor tweaks specific for SSR usage only
viperHTML never really provided proper re-hydration for hyperHTML, while here this is provided natively by the Web platform, and it works better than anything else, specially with custom elements builtin