Wondering what’s next for npm?Check out our public roadmap! »


    2.0.3 • Public • Published

    heresy logo heresy SSR

    Don't simulate the DOM. Be the DOM.

    Social Media Photo by Thomas Kelley on Unsplash

    WebReflection status License: ISC Build Status Greenkeeper badge

    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}>
          <title>🔥 heresy SSR 🔥</title>
          <script defer src="//unpkg.com/heresy"></script>
          <script type="module" src="definitions.js"></script>
        <Body data-hostname=${hostname}/>

    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


    npm i heresy-ssr

    DownloadsWeekly Downloads






    Unpacked Size

    16.1 kB

    Total Files


    Last publish


    • avatar