wc-compiler

wcc

Experimental Web Components compiler. It's Web Components all the way down! 🐢

Overview

Web Components Compiler (WCC) is a NodeJS package designed to make server-side rendering (SSR) of native Web Components easier. It can render (within reason 😅) your Web Component into static HTML leveraging Declarative Shadow DOM.

It is not a static site generator or framework. It is focused on producing raw HTML from Web Components with the intent of being easily integrated into a site generator or framework.

The original motivation for this project was to create a purpose built, lighter weight, alternative to puppeteer for SSR of HTMLElement for the project Greenwood.

In addition, WCC hopes to provide a surface area to explore patterns around streaming and serverless rendering, as well as acting as a test bed for the Web Components Community Groups discussions around community protocols, like hydration.

Key Features

1. Supports the following HTMLElement lifecycles and methods on the server side
   • constructor
   • connectedCallback
   • attachShadow
   • innerHTML
   • [get|set|has]Attribute
2. Recursive rendering of nested custom elements
3. Optional Declarative Shadow DOM (for producing purely content driven static pages)
4. Metadata and runtime hints to support progressive hydration and lazy loading strategies

Installation

wcc can be installed from npm.

$ npm install wc-compiler --save-dev

Usage

WCC exposes a few utilities to render your Web Components. Below is one example, with full docs and more examples available on the website.

1. Given a custom element like so:

   const template = document.createElement('template');
   
   template.innerHTML = `
     <style>
       .footer {
         color: white;
         background-color: #192a27;
       }
     </style>
   
     <footer class="footer">
       <h4>My Blog &copy; ${new Date().getFullYear()}</h4>
     </footer>
   `;
   
   class Footer extends HTMLElement {
     connectedCallback() {
       if (!this.shadowRoot) {
         this.attachShadow({ mode: 'open' });
         this.shadowRoot.appendChild(template.content.cloneNode(true));
       }
     }
   }
   
   export default Footer;
   
   customElements.define('wcc-footer', Footer);
   

2. Using NodeJS, create a file that imports renderToString and provide it the path to your web component

   import { renderToString } from 'wc-compiler';
   
   const { html } = await renderToString(new URL('./path/to/footer.js', import.meta.url));
   
   console.debug({ html })
   

3. You will get the following HTML output that can be used in conjunction with your preferred site framework or templating solution.

   <wcc-footer>
     <template shadowroot="open">
       <style>
         .footer {
           color: white;
           background-color: #192a27;
         }
       </style>
   
       <footer class="footer">
         <h4>My Blog &copy; 2022</h4>
       </footer>
     </template>
   </wcc-footer>
   

Make sure to test in Chrome, or other Declarative Shadow DOM compatible browser, otherwise you will need to include the DSD polyfill.