DEV Community: Stephen Belovarich

Server Side Rendering a Blog with Web Components

Stephen Belovarich — Wed, 19 Apr 2023 04:31:22 +0000

This blog post supports a Youtube Livestream scheduled for Wednesday 4/19 at 12pm EST / 9am PST. You can watch the livestream here on Youtube.

Introduction

It has never been easier to server side render a website. Years ago it took server side technologies like PHP and Java, requiring web developers to learn another language besides JavaScript. With the introduction of Node.js, web developers got a JavaScript runtime on the server and tools such as Express that could handle HTTP requests and return HTML to the client. Meta-frameworks for server side rendering sprang up that supported popular libraries and frameworks like React, Angular, Vue, or Svelte.

Meta-frameworks had to consider React a first-class citizen because of how React utilizes Virtual DOM, an abstraction around DOM that enables the library to "diff" changes and update the view. React and Virtual DOM promised efficiency, but what we got was a toolchain that made the learning curve for web development more difficult. The ecosystem surrounding JavaScript libraries promised a boost in developer experience. What we got was dependency hell.

Hydration became part of the vocabulary of several web developers in recent years. Hydration being the process of using client-side JavaScript to add state and interactivity to server-rendered HTML. React popularized many of the concepts web developers think of when we say "server-side rendering" today.

What if I told you there was a way to server-side render HTML with less tooling, using a syntax that you don't need to learn another library to code? The solution just uses HTML, CSS, and JavaScript, with a bit of library code on the server. Would that be enticing?

Shameless plug. I'm Stephen Belovarich, the author of FullStack Web Components, a book about coding UI libraries with custom elements. If you like what you are reading in thispost consider purchasing a copy of my book Fullstack Web Components available at newline.co. Details following this post.

In this guide, I'll demonstrate how to server-side render autonomous custom elements using only browser specifications and Express middleware. In the middleware, I'll show you how to work with an open source package developed by Google to server-side render Declarative Shadow DOM templates. @lit-labs/ssr is a library package under active development by the team that maintains Lit, a popular library for developing custom elements. @lit-labs/ssr is part of the Lit Labs family of experimental packages. Even though the package is in "experimental" status, the core offering is quite stable for use with "vanilla" custom elements.

You can render custom elements today server-side with @lit-labs/ssr by binding the render function exported by the package to Express middleware. @lit-labs/ssr supports rendering custom elements that extend from LitElement first and foremost, although LitElement itself is based off web standards, the class is extended from HTMLElement. @lit-labs/ssr relies on a lit-html template to render content server-side, but lit-html happens to be compatible with another web standard named Declarative Shadow DOM.

Declarative Shadow DOM

Declarative Shadow DOM is the web specification what makes server-side rendering custom elements possible. Prior to this standard, the only way to develop custom elements was imperatively. You had to define a class and inside of the constructor construct a shadow root. In the below example, we have a custom element named AppCard that imperatively constructs a shadow root. The benefit of a shadow root is that we gain encapsulation. CSS and HTML defined in the context of the shadow root can't leak out into the rest of the page. Styling and template remains scoped to the instance of the custom element.

class AppCard extends HTMLElement {
  constructor() {
    super();
    if (!this.shadowRoot) {
      const shadowRoot = this.attachShadow({ mode: 'open' });
      const template = document.createElement('template');
      template.innerHTML = `
      <style>
      ${styles}
      </style>
      <header>
        <slot name="header"></slot>
      </header>
      <section>
        <slot name="content"></slot>
      </section>
      <footer>
        <slot name="footer"></slot>
      </footer>
      `;
      shadowRoot.appendChild(template.content.cloneNode(true));
    }
  }
}

customElements.define('app-card', AppCard);

The above example demonstrates how an autonomous custom element named AppCard declares it's shadow root imperatively in the constructor.

Declarative Shadow DOM allows you to define the same template for the custom element declaratively. Here is an example of the same shadow root for AppCard defined with Declarative Shadow DOM.

<app-card>
  <template shadowrootmode="open"> 
    <style>
      ${styles}
    </style>
    <header>
      <slot name="header"></slot>
    </header>
    <section>
      <slot name="content"></slot>
    </section>
    <footer>
      <slot name="footer"></slot>
    </footer> 
  </template>
  <img slot="header" src="${thumbnail}" alt="${alt}" />
  <h2 slot="header">${headline}</h2>
  <p slot="content">${content}</p>
  <a href="/post/${link}" slot="footer">Read Post</a>
</app-card>

Declarative Shadow DOM introduces the shadowrootmode attribute to HTML templates. This attribute is detected by the HTML parser and applied as the shadow root of it's parent element (<app-card>). The above example uses template slots to dynamically inject content into a custom element template. With Declarative Shadow DOM, any HTML defined outside of the HTML template is considered "Light DOM" that can be projected through the slot to "Shadow DOM". The usage of ${} syntax is merely for the example. This isn't some kind of data-binding technique. Since the template is now defined declaratively, you can reduce the definition to a String. ES2015 template strings are well suited for this purpose. In the demo, we'll use template strings to define each component's template declaratively using the Declarative Shadow DOM specification.

But wait? If the component's template is reduced to a string how do you inject interactivity into the component client-side? You still have to define the component imperatively for the client, but since Shadow DOM is already instantiated (the browser already parsed the Declarative Shadow DOM template), you no longer need to instantiate the template. You may still imperatively instantiate Shadow DOM if the shadow root doesn't already exist.

class AppCard extends HTMLElement {
  constructor() {
    super();
    if (!this.shadowRoot) {
      // instantiate the template imperatively
      // if a shadow root doesn't exist 
    }
    ...

Optionally, you can hydrate the component client-side differently when a shadow root is detected.

class AppCard extends HTMLElement {
  constructor() {
    super();
    if (this.shadowRoot) {
      // bind event listeners here
      // or handle other client-side interactivity
    }
    ...

The architects in the crowd may notice one flaw with this approach. Won't the same template need to defined twice? Once for Declarative Shadow DOM and a second time for the declaration in the custom element's constructor. Sure, but we can mitigate this by using ES2015 template strings. By implementing the template through composition, we can inject the template typically defined imperatively into the other defined declaratively. We'll make sure to reuse partial templates in each custom element developed in this workshop.

What You Will Build

In this workshop, you'll server-side render four custom elements necessary to display a blog:

AppCard displays a card
AppHeader displays the site header
MainView displays the site header and several cards
PostView displays the site header and a blog post

Acceptance Criteria

The blog should have two routes. One that displays a list of the latest posts, another that displays the content of a single post.

When the user visits http://localhost:4444 the user should view the site header and several cards (MainView).
When the user visits http://localhost:4444/post/:slug the user should view the site header and blog post content (PostView). The route includes a variable "slug" which is dynamically supported by the blog post.

Project Structure

The workspace is a monorepo consisting of 4 project directories:

client: Custom elements rendered client and server-side
server: Express server that handles server-side rendering
shim: Custom shim for browser specifications not found in Node.js, provided by Lit
style: Global styles for the blog site

Lerna and Nx handle building the project, while nodemon handles watching for changes and rebuilding the project.

The project is mainly coded with TypeScript. You'll be developing mostly server-side in this workshop which maybe a change for some people. When you run console.log this log will happen on the server, not in the browser, for instance.

For the workshop, you'll focus primarily on a single file found at /packages/server/src/middleware/ssr.ts. This file contains the middleware that handles server-side rendering. For the remainder of the workshop, you'll edit custom elements found in packages/client/src/. Each file includes some boilerplate to bootstrap the experience.

Architecture

In this workshop you'll develop methods for asynchronously rendering Declarative Shadow DOM templates. Each view is mapped to a Route. Both Route listed in the acceptance criteria are defined in this file: packages/client/src/routes.ts.

export const routes: Routes = [
  {
    path: "/",
    component: "main",
    tag: "main-view",
    template: mainTemplate,
  },
  {
    pathMatch: /\/post\/([a-zA-Z0-9-]*)/,
    component: "post",
    tag: "post-view",
    template: postTemplate,
  },
];

We need a static definition of the routes somewhere. Putting the definition in an Array exported from a file is an opinion. Some meta-frameworks obfuscate this definition with the name of directories parsed at build or runtime. In the middleware, we'll reference this Array to check if a route exists at the path the user is requesting the route. Above the routes are defined with an identifier: path. path: "/", matches the root, i.e. http://localhost:4444. The second example uses pathMatch instead. The route used to display each post is dynamic, it should display a blog post by slug. Each route also corresponds to a template, which we'll define in each "view" file as a function that returns a template string. An example of a template is below.

export const mainTemplate = () => `<style>
    ${styles}
  </style>
  <div class="container">
  <!-- put content here -->
  </div>`;

During the workshop, we'll display a static route, but soon after make each view dependent on API requests. The JSON returned from local REST API endpoints will be used as a model for the view. We'll export a named function called fetchModel from each view file that fetches the data and returns the model. An example of this is below.

function fetchModel(): Promise<DataModel> {
  return Promise.all([
    fetch("http://localhost:4444/api/meta"),
    fetch("http://localhost:4444/api/posts"),
  ])
    .then((responses) => Promise.all(responses.map((res) => res.json())))
    .then((jsonResponses) => {
      const meta = jsonResponses[0];
      const posts = jsonResponses[1].posts;
      return {
        meta,
        posts,
      };
    });
}

In the above example, two calls to fetch request the metadata for the site and an Array of recent blog posts from two different API endpoints. The responses are mapped to the model needed to display the view.

A description of each API endpoint is below, but first let's look at the flow of information.

Markdown -> JSON w/ embedded Markdown -> HTML -> Declarative Shadow DOM Template

Blog posts are stored in markdown format in the directory packages/server/data/posts/. Two API endpoints (/api/posts and /api/post/:slug) fetch the markdown from each file and return that markdown in the format of a Post. The type definition of a Post is as-follows:

export type Post = {
  content: string;
  slug: string;
  title: string;
  thumbnail: string;
  author: string;
  excerpt: string;
};

Another endpoint handles metadata for the entire page. The interface for the data returned by this endpoint is simplified for the workshop and could be expanded for SEO purposes.

export type Meta = {
  author: string;
  title: string;
};

During the workshop, you'll rely on three local API endpoints to fetch the metadata of the site and the data associated with each blog post. A description of each endpoint is below.

http://localhost:4444/api/meta returns the metadata necessary to display the site header in JSON format.

http://localhost:4444/api/post/:slug returns a single blog post by it's "slug", a string delineated by - in JSON format.

http://localhost:4444/api/posts returns an array of blog posts in JSON format.

You'll make requests to these endpoints and use the JSON responses to populate the content for each Declarative Shadow DOM template. In each file that requires data, a type definition for Meta and Post schema is already provided in packages/server/src/db/index.ts. These type definitions are imported into relevant files to ease in development.

In addition to the three provided local endpoints, you'll be making a request to the Github API to parse the markdown returned from the included blog post files. This API is necessary because it provides the simplest way to parse code snippets found in markdown files and convert them to HTML.

Getting Started

You'll need a GitHub account. You can use GitHub to sign-in to StackBlitz and later, you'll need GitHub to generate a token.

If you don't already have a GitHub account, signup for Github here.

If you want to follow along with this tutorial, fork the StackBlitz or Github repo.

When using Stackblitz, the development environment will immediately install dependencies and load an embedded browser. VS Code is available in browser for development. Stackblitz works best in Google Chrome.

If using Github, fork the repository and clone the repo locally. Run npm install and npm run dev. Begin coding in your IDE of choice.

Important Note About Tokens

During the workshop, we'll be using the Github API known as Octokit to generate client-side HTML from Markdown for each blog post. If you're using Stackblitz, an API token is provided for the workshop but will be revoked soon after. If you've cloned the repo or the token is revoked, login to GitHub and generate a new token on Github for use in the workshop.

Never store tokens statically in code. The only reason the token is injected this way for the workshop is to bootstrap making requests with Octokit.

Important Note About Support

If you are following along with StackBlitz, make sure you are using Google Chrome.

Examples included in this workshop will work in every mainstream browser except Firefox. The code should work in Google Chrome, Microsoft Edge, and Apple Safari.

Although Mozilla has signaled support for implementing Declarative Shadow DOM, the browser vender has yet to provide support in a stable release. A lightweight ponyfill is available to address the lack of support in Firefox.

Support for Declarative Shadow DOM is subject to change in Firefox. I have faith the standard will become cross-browser compatible in the near future because Mozilla recently changed it's position on Declarative Shadow DOM. I've been using the ponyfill for over a year without issues in browsers that lack support for the standard.

Server Side Rendering Custom Elements with @lit-labs/ssr

Let's get started coding, shall we?

The first task is declaring a Declarative Shadow DOM template for the component named MainView found in packages/client/src/view/main/index.ts. This view will ultimately replace the boilerplate currently displaying "Web Component Blog Starter" in the browser at the path http://localhost:4444/.

Supporting Declarative Shadow DOM in MainView

Open packages/client/src/view/main/index.ts in your IDE and find the Shadow DOM template that is defined imperatively in the constructor of the MainView class. We're going to declare this template instead as an ES2015 template string returned by a function named shadowTemplate. Cut and paste the current template into the template string returned by shadowTemplate.

const shadowTemplate = () => html`<style>
    ${styles}
  </style>
  <div class="post-container">
    <app-header></app-header>
  </div>`;

For your convenience, html is imported into this file, which you can use to tag the template literal. This html shouldn't be confused with the function exported from lit-html. It's a custom implementation of a tagged template literal that enables syntax highlighting of the string, if you have that enabled in your IDE.

If you opted for GitHub and cloned the repo locally, you can enable this VSCode extension that offers syntax highlighting of HTML and CSS inside tagged template literals. That's really the only purpose of html for now, although you could exploit this function and parse the template string in different ways if you wanted.

Update the imperative logic to call shadowTemplate which should return the same String as before.

template.innerHTML = shadowTemplate();

In an effort to reuse the template, we can pass it to the next function we'll declare named template. The format is the same, although this time the template normally declared imperatively is encapsulated by the HTML tag associated with the component (<main-view>) and a HTML template with the attribute shadowrootmode set to open. Inject the shadowTemplate() we defined earlier inside of the <template> tags.

const template = () => html`<main-view>
  <template shadowrootmode="open">
    ${shadowTemplate()}
  </template>
  </main-view>`;

You just declared your first Declarative Shadow DOM template. Some benefits of this approach is that we can reuse the typical shadow root template declared imperatively and since we're using function, inject arguments that can be passed to the ES2015 template string. This will come in handy when we want to populate the template with data returned from API endpoints.

Finally, be sure to export the template from the file. More on why we're exporting the MainView class and template function later.

export { MainView, template };

This is a good start, but we'll run into an issue if we keep the code as-is. While it is possible to reuse template partials, the above example is kind of an exaggeration. You'll rarely be able to inject the entire shadow root into the Declarative Shadow DOM template like we did, especially when there are child custom elements that also need to be rendered server-side with Declarative Shadow DOM. In the above example, <app-header> can't currently be rendered on the server because we haven't declared that component's template with Declarative Shadow DOM. Let's do that now.

Supporting Declarative Shadow DOM in Header

To declare a new template to server-side render the AppHeader component, open packages/client/src/component/header/Header.ts.

Just like in the last example, cut and paste the template that is defined imperatively in the AppHeader constructor into a new function named shadowTemplate that returns the same string. This time, inject a single argument into the function that destructs an Object with two properties: styles and title and pass those to the template.

const shadowTemplate = ({ styles, title }) => html`
  <style>
    ${styles}
  </style>
  <h1>${title}</h1>
`;

Call shadowTemplate with the first argument, setting the two properties that are currently found globally in the file: styles and title

template.innerHTML = shadowTemplate({ styles, title });

It's quite alright to define arguments in this way that later populate the template. It will offer some flexibility later on when we need to map the response of an API endpoint to what the template function expects. To declare the Declarative Shadow DOM template, define a new function named template, this time encapsulating the call to shadowTemplate with the <app-header> tag and HTML template.

const template = ({ styles, title }) => html`<app-header>
  <template shadowrootmode="open">
  ${shadowTemplate({ styles, title })}
  </template>
</app-header>`;

We can reuse the shadow root template used declaratively in this case because AppHeader is a leaf node, that is to say, it has no direct descendants that need to also be rendered server-side with Declarative Shadow DOM.

Finally, export all the necessary parts in MainView.

export { styles, title, template, AppHeader };

Updating MainView with the Declarative Header

Open packages/client/src/view/main/index.ts again and import the parts from Header.js needed to render the template this time renamed as appHeaderTemplate. Notice how styles as appHeaderStyles is used with as so they don't conflict with this local styles declaration in packages/client/src/view/main/index.ts.

import {
  styles as appHeaderStyles,
  template as appHeaderTemplate,
  title,
  AppHeader,
} from '../../component/header/Header.js';

Update the template function, replacing the shadowTemplate call with appHeaderTemplate, being sure to pass in the styles and title.

const template = () => html`<main-view>
  <template shadowrootmode="open">
    ${appHeaderTemplate({ styles: appHeaderStyles, title})}
  </template>
  </main-view>`;

Keen observers may notice an opportunity here. We don't have to always use the styles and title prescribed in Header.ts, but use the call to appHeaderTemplate as a means to override styling or set the title dynamically. We'll do the latter in a later section of this workshop.

Supporting Declarative Shadow DOM in PostView

Before we code the Express middleware needed to server-side render these Declarative Shadow DOM templates, we have some housekeeping to do. The second view component defined in packages/client/src/view/post/index.ts also needs a function named template exported from the file. This component is responsible for displaying a single blog post.

Notice a pattern that is forming? Patterns are very helpful when server-side rendering components. If each component reliably exports the same named template, we can ensure the middleware reliably interprets each Declarative Shadow DOM template. Standardization is helpful here.

Open packages/client/src/view/post/index.ts. Cut and copy the template declared imperatively into a function named shadowTemplate, just like you did in the last two components.

const shadowTemplate = () => html`<style>
    ${styles}
  </style>
  <div class="post-container">
    <app-header></app-header>
    <div class="post-content">
      <h2>Author: </h2>
      <footer>
        <a href="/">👈 Back</a>
      </footer>
    </div>
  </div>`;

Call shadowTemplate() in the constructor of PostView.

template.innerHTML = shadowTemplate();

Declare a new function named template and make sure to encapsulate the shadowTemplate with Declarative Shadow DOM.

const template = () => html`<post-view>
  <template shadowrootmode="open">
    ${shadowTemplate()}
  </template>
</post-view>`;

Export template from packages/client/src/view/post/index.ts.

export { PostView, template };

We'll return to this file later, but for now that should be enough to display a bit of text and a link that navigates the user back to MainView.

Onto the middleware...

Express Middleware

@lit-labs/ssr is an npm package distributed by Lit at Google for server-side rendering Lit templates and components. The package is for use in the context of Node.js and can be used in conjunction with Express middleware. Express is a popular HTTP server for Node.js that is largely based on middleware.

Express middleware are functions that intercept HTTP requests and handle HTTP responses. We'll code an Express middleware that handles requests to http://localhost:4444 and http://localhost:4444/post/:slug Whenever a user lists these two routes, Express will calls a custom middleware function already exported as ssr. The algorithm in that function is what you'll be working on.

The middleware you'll be working with is imported and set on two routes in packages/server/src/index.ts.

import ssr from "./middleware/ssr.js";
...
app.get("/", ssr);
app.get("/post/:slug", ssr);

When the user visits http://localhost:4444/ or http://localhost:4444/post/, the middleware is activated. The notation :slug in the second route for the post view denotes the middleware should expect a path segment named "slug" that will now appear on the request params passed into the middleware function.

If you've never coded Node.js, have no fear. We'll go step-by-step to code the Express middleware.

Open packages/server/src/middleware/ssr.ts to get started coding the middleware. Browse the file to acquaint yourself with the available import and declared const.

Notice how different files from the monorepo are injected into the HTML declared in renderApp. Relative paths are used here with the readFileSync to find the path of the global styles file named style.css and then minify the styles (for increased performance). The minification could be turned off by dynamically setting the minifyCSS with the env variable, which is used to determine if the code is running in "development" or "production" environments.

const stylePath = (filename) =>
  resolve(`${process.cwd()}../../style/${filename}`);
const readStyleFile = (filename) =>
  readFileSync(stylePath(filename)).toString();

const styles = await minify(readStyleFile('style.css'), {
  minifyCSS: env === "production",
  removeComments: true,
  collapseWhitespace: true,
});

In the above example, the global styles of the blog are read from a file in the monorepo and then minified depending on the environment.

The middleware function is found at the bottom of the file. Currently, the middleware calls renderApp() and responds to the HTTP request (req) by calling res.status(200), which is the HTTP response code for "success" and then .send() with the ES2015 template string returned from renderApp.

export default async (req, res) => {
  const ssrResult = renderApp();
  res.status(200).send(ssrResult);
};

Select the boilerplate shown in the below image and remove the <script>.

Insert a new string in the template to reveal a change in the browser window. In the below example, we inject "Hello World" into the template. This will be temporary, as the renderApp function will become dynamic soon.

function renderApp() {
  return `<!DOCTYPE html>
  <html lang="en">
    <head>
        <meta name="viewport" content="width=device-width, initial-scale=1">
        <meta name="description" content="Web Components Blog">
        <style rel="stylesheet" type="text/css">${styles}</style>
    </head>
    <body> 
      <div id="root">${'Hello World'}</div>
  </body></html>`;
}

Handling Routes in Middleware

Since this middleware will handle multiple routes in Express, we need a way to detect if a route should be served. When a route isn't available, the middleware should throw a 404 Not Found error. HTML should only be served if a route is declared.

In packages/client/src/routes.js each route is declared in an Array. You can import this Array directly from the file, ensuring to use the file extension ".js". This is how imports are handled with ES2015 modules in Node.js, which mirrors the way browsers expect imports to be declared. Eventhough we're coding in TypeScript files, ".js" is still used in the path.

import { routes } from '../../../client/src/routes.js';

Each Route is typed as follows. You can reference this type to code an algorithm that returns the Route based on the HTTP request. You may also rely on your IDE intellisense.

export type Route = {
  component: string;
  path?: string;
  pathMatch?: RegExp;
  tag: string;
  template: (data?: any) => string;
  title?: string;
  params?: any;
};

In the middleware function, write an algorithm that handles two different use cases:

If the route declares a "path", match the route exactly to the current originalUrl on the HTTP request.
If the your declares a "pathMatch", which is a way to match routes by RegExp, call test on the RegExp to determine if the regular expression matches the originalUrl on the HTTP request.

When you are finished, log the matched route. It should log the Route in your Terminal. An edge case should be accounted for when the user visits http://localhost:4444 instead of http://localhost:4444/ and the path is declared as /, there should still be a match.

export default async (req, res) => {
  let route = routes.find((r) => {
    // handle base url
    if (
      (r.path === '/' && req.originalUrl == '') ||
      (r.path && r.path === req.originalUrl)
    ) {
      return r;
    }
    // handle other routes
    if (r.pathMatch?.test(req.originalUrl)) {
      return r;
    }
  });

  console.log(route);
  ...

If there isn't a match, Array.prototype.find will return undefined, so account for this by redirecting the user to a "404" route. We won't actually work on this route now, but for bonus points you could later server-side render a 404 page.

  if (route === undefined) {
    res.redirect(301, '/404');
    return;
  }

Next, add the current HTTP request params to the Route. This will be necessary for the single post view which has a single param :slug which can now be accessed via route.params.slug.

  route = {
    ...route,
    params: req.params,
  };

Now that you have a matched route, you should have access to the route's template stored on the Route, but we first have to "build" the route in development like it were built in production. When the routes are built in the client package, each route is deployed to packages/client/dist as a separate JavaScript bundle. We can simulate this deployment in the development environment by using esbuild programmatically to build the JavaScript bundle that matches each route.

First, define a new function named clientPath that returns the path to the either the view's source in the src directory or the bundle in the dist directory of the client package. We'll need both paths because during development we'll build each view from the src directory to dist. Return a String using resolve and process.cwd() to find the path of the custom element bundle.

To be clear, the function needs to return either of these paths:

packages/client/src/view/main/index.js
packages/client/dist/view/main/index.js
packages/client/src/view/post/index.js
packages/client/dist/view/post/index.js

The first argument of the function should denote the directory, while the second should provide a means to identify the file (stored as route.component).

const clientPath = (directory: 'src' | 'dist', route: any) => {
  return resolve(
`${process.cwd()}../../client/${directory}/view/${route.component}/index.js`
  );
};

Use the new clientPath function in the context of the middleware to build the JavaScript for the route, calling esbuild.build with the path to the source file mapped to entryPoints and the outfile mapped to the path to the distributed bundle in the dist directory. Every time the middleware gets called and matches a route, the appropriate bundle will be built. This will simulate how the bundles are distributed for production and utilize esbuild for development which should be fast and efficient.

 if (env === 'development') {
    await esbuild.build({
      entryPoints: [clientPath('src', route)],
      outfile: clientPath('dist', route),
      format: 'esm',
      minify: env !== 'development',
      bundle: true,
    });
}

Rendering the Template

To render the Declarative Shadow DOM template exported from each bundle, we need to dynamically import the JavaScript from the bundle. Reuse the clientPath function, this time in the context of a dynamic import statement to set a new const named module. This will give us access to whatever is exported from the view's JavaScript bundle.

  const module = await import(clientPath('dist', route));

Declare another const named compiledTemplate that calls template function exported from module. template returns the Declarative Shadow DOM template we defined earlier in packages/client/src/view/main/index.ts.

  const compiledTemplate = module.template();

Before we pass the String returned by the template function to another function named render exported from @lit-labs/ssr, we need to sanitize the HTML. render will ultimately be the function that parses and streams the Declarative Shadow DOM template for the HTML response. We could also provide a custom sanitization algorithm. Whatever the outcome we need to pass the template through the unsafeHTML function exported from @lit-labs/ssr. You could think of this function like dangerouslySetInnerHTML from React. The render function exported from @lit-labs/ssr expects any HTML template to be sanitized through unsafeHTML prior to calling render.

Make a new function named sanitizeTemplate that should be marked async because unsafeHTML itself is asynchronous. html in this example is exported from the lit package, it's the function used by the Lit library for handling HTML templates. It's very similar in nature to the html we tagged the template literals with earlier in the client code, but works well within the Lit ecosystem.

export const sanitizeTemplate = async (template) => {
  return await html`${unsafeHTML(template)}`;
};

In the middleware function, make a new const and set it to a call to sanitizeTemplate, passing in the compiledTemplate. Finally, pass template to renderApp.

const template = await sanitizeTemplate(compiledTemplate);
const ssrResult = renderApp(template);

Add a first argument to renderApp appropriately named template. Replace the "Hello World" from earlier with a call to render, passing in the template. render is the function exported from @lit-labs/ssr that is responsible for rendering the Declarative Shadow DOM template for the entire view. There is some logic render for handling components built with Lit, but it can also accept vanilla Declarative Shadow DOM templates.

function renderApp(template) {
  return `<!DOCTYPE html>
  <html lang="en">
    <head>
        <meta name="viewport" content="width=device-width, initial-scale=1">
        <meta name="description" content="Web Components Blog">
        <style rel="stylesheet" type="text/css">${styles}</style>
    </head>
    <body> 
      <div id="root">${render(template)}</div>
  </body></html>`;
}

If you use intellisense to reveal more about render, you'll learn render accepts any template that can be parsed my lit-html, another package in the Lit ecosystem. You'll also find out the function returns a "string iterator".

By now you'll notice the template doesn't render correctly. Instead [object Generator] is printed in the browser. What is going on here? The hint comes from what render returns: a "string iterator". Generator was introduced in ES2015 and it's an often under appreciated, yet powerful aspect of the JavaScript language. Lit is using Generators to support streaming the value over the request/response lifecycle of a HTTP request.

Handling The Generator

An easy way to support the output of render is to convert renderApp to a Generator function. That is rather easy. Generator can be defined using the function* syntax, which defines a function that returns a Generator. Calling a Generator does not immediately execute the algorithm defined in the function* body. You must define yield expressions, that specify a value returned by the iterator. Generator are just one kind of Iterator. yield* delegates something to another Generator, in our example render.

Convert renderApp to a Generator function, breaking up the HTML document into logical yield or yield* expressions, like in the below example.

function* renderApp(template) {
  yield `<!DOCTYPE html>
  <html lang="en">
    <head>
        <meta name="viewport" content="width=device-width, initial-scale=1">
        <meta name="description" content="Web Components Blog">
        <style rel="stylesheet" type="text/css">${styles}</style>
    </head>
    <body> 
      <div id="root">`;
  yield* render(template);
  yield `</div>
  </body></html>`;
}

Once you're complete, the output in the browser window should change. Rather anticlimactic, huh?

There is a hint for the reason this is happening in the documentation for render. That function "streams" the result and we haven't yet handled the stream. Before we do, update the bottom of the middleware function, being sure to await the result of renderApp, which is now asynchronous due to being a Generator function.

  const ssrResult = await renderApp(template);

Streaming the Result

Streams in Node.js can be expressed as Buffer. Ultimately what we need to do is convert the stream to a String that can be sent to the client in the HTTP response as an HTML document. Buffer can be converted to a String by calling toString, which also accepts utf-8 formatting as an argument. UTF-8 is necessary because it is defined as the default character encoding for HTML.

Streams are asynchronous. We can use a for combined with an await to push each "chunk" of the stream to a Buffer, then combine all the Buffer using Buffer.concat and convert the result to a UTF-8 encoded String. Make a new function named streamToString that does that, giving it an argument named stream. streamToString return the String.

async function streamToString(stream) {
  const chunks = [];
  for await (let chunk of stream) {
    chunks.push(Buffer.from(chunk));
  }
  return Buffer.concat(chunks).toString('utf-8');
}

The above seems like it would just accept our stream returned from renderApp, but we first should pass the stream through Readable, a utility in Node.js that allows us to read the stream. Make another async function named renderStream.

async function renderStream(stream) {
  return await streamToString(Readable.from(stream));
}

Finally, in the middleware function make another variable named stream and call renderStream, passing in the ssrResult. Then, call res.send with the stream.

 let stream = await renderStream(ssrResult);
 res.status(200).send(stream);

Voilà! The title defined in the Declarative Shadow DOM template is now visible in the browser.

If you inspect the HTML you'll notice artifacts left over from the render function. These comments are left behind by Lit and they seem useful possibly for parsing library specific code. Since we just used browser spec, our code may not use them really.

*Declarative Shadow DOM template has successfully been server-side rendered. *

The hard part is over. We'll return to the middleware to enhance parts of it later, but a large majority of the work is done. The middleware you just coded can now be used to render Declarative Shadow DOM templates.

Let's add some content to the view. Next, you'll update the Card custom element to export a Declarative Shadow DOM template, then import the template into the MainView custom element. Then, you'll populate the view with cards that display metadata about each blog post.

Updating Card with Declarative Shadow DOM

In this section, you'll learn how to handle HTML template slots with Delcarative Shadow DOM templates after working on the most complex template yet, a reusable card that only accept content through HTML template slots.

To update the Card open packages/client/src/component/card/Card.ts. Just like in previous examples, cut and paste the template that is declared imperatively in the constructor to a template string returned by a new function named shadowTemplate. Add a single argument to this function that allows you to pass in the styling for the template. Notice how the header, content, footer layout of each Card accepts a named HTML template slot.

const shadowTemplate = ({ styles }) => html`
  <style>
    ${styles}
  </style>
  <header>
    <slot name="header"></slot>
  </header>
  <section>
    <slot name="content"></slot>
  </section>
  <footer>
    <slot name="footer"></slot>
  </footer>
`;

Set the innerHTML in the custom element constructor to the new shadowTemplate function.

template.innerHTML = shadowTemplate({ styles });

Link in the example of Header, Card is a leaf-node, so we can reuse the shadowTemplate wholesale within the Declarative Shadow DOM template. Make a new function named template that passes in a single argument and encapsulate the shadowTemplate with the proper syntax.

const template = ({ styles }) => html`<app-card>
  <template shadowrootmode="open"> 
  ${shadowTemplate({ styles })}
  </template>
</app-card>`;

Cards should display a thumbnail, the blog post title, a short description, and link. Declare new properties on the first argument of the template function that account for content, headline, link, and thumbnail, in addition to styles.

We can still project content into the slots in a Declarative Shadow DOM template. Shadow DOM is contained within the shadowTemplate function. Whatever elements are placed outside of the <template> are considered Light DOM and can be projected through the slots using the slot attribute.

For each of the properties on the model, make a new element. A new <img> tag with a slot attribute set to header will project into the custom element's <header>. Set the src attribute to an interpolated ${thumbnail} and the alt to an interpolated ${content}, to describe the image for screen readers. Additionally define a <h2> and <p>. If any part of the template becomes too complex, you can wrap the entire template partial in string interpolation. This is the case with setting the href attribute on the <a> tag, which displays a "Read Post" link for the user.

const template = ({
  content,
  headline,
  link,
  thumbnail,
  styles,
}) => html`<app-card>
  <template shadowrootmode="open"> ${shadowTemplate({ styles })} </template>
  <img slot="header" src="${thumbnail}" alt="${content}" />
  <h2 slot="header">${headline}</h2>
  <p slot="content">${content}</p>
  ${html`<a href="/post/${link}" slot="footer">Read Post</a>`}
</app-card>`;

Since each element utilizes a named HTML template slot that matches a slot found in Shadow DOM for this custom element, each element will be project into Shadow DOM. If two elements share a named slot, they will be projected in the order they are defined.

Finally, export styles and template from the file.

export { styles, template, AppCard };

We'll switch our attention now to packages/client/src/view/main/index.ts where we need to update the Declarative Shadow DOM template to accept the new template exported from Card.ts.

Fetching the Data Model

Views in modern websites are rarely static. Usually a view must be populated with content from a database. In our project, data is stored in markdown files for each blog post. Either way, a REST API could be used to fetch data from an endpoint and populate the view with content. In this next section, we'll develop a pattern for fetching data from a REST API and integrating the resulting JSON with the middleware you coded in a pervious section.

You'll inject the data from two endpoints into the MainView Declarative Shadow DOM template. JSON returned from 'http://localhost:4444/api/meta can be used to render AppHeader, while the Array of Post returned from http://localhost:4444/api/posts will be used to render a list of AppCard.

Open packages/client/src/view/main/index.ts to begin coding this section.

Just like we did with template, we are standardizing a new pattern. This time for declaring asynchronous API calls that fetch data for the purpose of injecting that data into each Declarative Shadow DOM template. Essentially, we're talking about the "model" for the "view", so we'll call the new function "fetchModel".

This function should return a Promise. With TypeScript, we can strictly type define the Promise and match that definition with the first argument of template. Eventually this data model will get passed to template, enabling us to hydrate the view with content.

function fetchModel(): Promise<DataModel> {}

const template = (data: DataModel) => string;

This may seem disconnected at first, because nowhere in index.ts do these two function work together. In the Express middleware we have access to exports from the bundle, so if we export fetchModel, we can also call the function in the context of the middleware and pass the result to template, which expects the same DataModel. This is why we need a standardized pattern!

An implementation of fetchModel for MainView would be as follows. Use Promise.all to call each endpoint with fetch, then map each response to the JSON returned from the endpoints, and finally call then again to map the resulting JSON to the schema expected in DataModel. The JSON response from http://localhost:4444/api/meta will be used to populate AppHeader, while http://localhost:4444/api/posts will be used to populate content for a list of AppCard.

function fetchModel(): Promise<DataModel> {
  return Promise.all([
    fetch('http://localhost:4444/api/meta'),
    fetch('http://localhost:4444/api/posts'),
  ])
    .then((responses) => Promise.all(responses.map((res) => res.json())))
    .then((jsonResponses) => {
      const meta = jsonResponses[0];
      const posts = jsonResponses[1].posts;
      return {
        meta,
        posts,
      };
    });
}

Update template with a new argument named data and type define it as DataModel. Update the appHeaderTemplate title with the title accessed by data.meta.title.

const template = (data: DataModel) => html`<main-view>
  <template shadowrootmode="open">
    ${appHeaderTemplate({ styles: appHeaderStyles, title: data.meta.title })}
  </template>
  </main-view>`;

We need to integrate the cards that display a preview of each blog post. Import AppCard, styles and template from Card.js, being sure to rename imports where appropriate so they don't clash with any local variables.

import {
  styles as appCardStyles,
  template as appCardTemplate,
  AppCard,
} from '../../component/card/Card.js';

Integrate appCardTemplate into the template function, mapping the Array found at data.posts to the model necessary to display each Card. You need to convert the Array to a String, so call join with an empty String as the argument to convert the Array to a String. Optionally, use the utility named joinTemplates imported into the file instead of calling join directly. Also inject the styles for each Card here.

const template = (data: DataModel) => html`<main-view>
  <template shadowrootmode="open">
    <style>
      ${styles}
    </style>
    <div class="post-container">
    ${appHeaderTemplate({ styles: appHeaderStyles, title: data.meta.title })}
    ${data.posts
      .map(
        (post) =>
          `${appCardTemplate({
            styles: appCardStyles,
            headline: post.title,
            content: post.excerpt,
            thumbnail: post.thumbnail,
            link: post.slug,
          })}`
      )
      .join('')}
     </div>
  </template>
  </main-view>`;

Export all of the following from index.ts.

export { template, fetchModel, AppCard, AppHeader, MainView };

Handling fetchModel in Middleware

To integrate the fetchModel exported from the bundle into the middleware, open packages/server/src/middleware/ssr.ts.

At the top of the middleware function declare a new variable named fetchedData. Declare a let here because sometimes fetchedData may be populated with a function, for static routes, possibly not.

export default async (req, res) => {
  let fetchedData;

After the line where we import the bundle, check if the ES2015 module exports fetchModel with a conditional expression. If truthy, set fetchedData to the result of module.fetchModel() using an await because fetchModel returns a Promise. We don't necessarily want to make fetchModel required for any hypothetical static layouts.

Anticipating the next route that displays a single post, pass in the route to fetchModel. Our existing implementation will effectively ignore this argument, but we need information on the route.params in the next example. Finally, pass fetchedData into the call for module.template.

  const module = await import(clientPath('dist', route));

  if (module.fetchModel) {
    fetchedData = await module.fetchModel(route);
  }

  const compiledTemplate = module.template(fetchedData);

You should now be able to view a server-side rendered header and list of cards at http://localhost:4444. This view is rendered entirely server-side. Network requests are made server-side, the Declarative Shadow DOM template is constructed and then iterated upon by @lit-labs/ssr render Generator. Next, you'll take what you've learned and render a single post view using the same methods.

Rendering A Single Post

If you click on any "Read More" links you'll be greeted with a rather unimpressive layout. A blank "Author:" field and a hand pointing "Back" should greet you. This is the result of the boilerplate we worked on earlier.

Upon navigation to this view, you should notice the Terminal update with a different Route if you still have the console.log enabled.

In this section we're going to populate the single post view with the content of a blog post. Each blog post is written in markdown and stored in the packages/server/data/posts directory. Each post can be accessed via a REST API endpoint at http://localhost:4444/api/post/:slug. If there is a post with a matching "slug", the endpoint returns the blog post in JSON, with the markdown found on the JSON response.

Open packages/client/src/view/post/index.ts to begin coding against the single post view.

import {
  styles as appHeaderStyles,
  template as appHeaderTemplate,
  AppHeader,
} from '../../component/header/Header.js';

  const template = (data: DataModel) => html`<post-view>
  <template shadowrootmode="open">
    <style>
      ${styles}
    </style>
    <div class="post-container">
      ${appHeaderTemplate({ styles: appHeaderStyles, title: data.post.title })}
      <div class="post-content">
        <h2>Author: ${data.post.author}</h2>
        ${data.html}
        <footer>
          <a href="/">👈 Back</a>
        </footer>
      </div>
    </div>
  </template>
</post-view>`;

We can take the fetchModel function from the main view and modify it for the single post view. Copy and paste the function from main/index.ts to post/index.ts, modifying it to accept a new argument. Remember when we passed the route to fetchModel in the middleware? This is why. We need the slug property found on route.params to make the request to http://localhost:4444/api/post/:slug. Modify the fetchModel function until you get a working example, like below.

After we receive the markdown, convert the markdown into useable HTML. The GitHub API is provided in this file to help with this purpose. The blog posts contain code snippets and Octokit is a convenient utility for parsing the markdown and converting it into HTML. Set a new const named request with the response from both local API endpoints and then await another HTTP request to the OctoKit API by calling octokit.request. We want to make a POST request to the /markdown endpoint, passing in the request.post.content to the text property on the body of the request, while making sure to specific the API version in the headers.


function fetchModel({ params }): Promise<any> {
  const res = async () => {
    const request = await Promise.all([
      fetch('http://localhost:4444/api/meta'),
      fetch(`http://localhost:4444/api/post/${params['slug']}`),
    ])
      .then((responses) => Promise.all(responses.map((res) => res.json())))
      .then((jsonResponses) => {
        return {
          meta: jsonResponses[0],
          post: jsonResponses[1].post,
        };
      });

    const postContentTemplate = await octokit.request('POST /markdown', {
      text: request.post.content,
      headers: {
        'X-GitHub-Api-Version': '2022-11-28',
      },
    });
    return {
      ...request,
      html: postContentTemplate.data,
    };
  };
  return res();
}

postContentTemplate will return the converted Markdown into HTML via the data property. Return that in the fetchModel function, along with the meta and post on a new property named html. When you are finished, export all the relevant parts for the middleware.

export { template, fetchModel, AppHeader, PostView };

If you refresh or navigate back to /, then click "Read More" on any card, you now should be able to view a single blog post. You just completed your second server-side rendered view with Declarative Shadow DOM! This is the last view of the workshop. Remaining sections will cover additional content for handling SEO, hydration, and more.

Handling Metadata for SEO

In this particular scenario, a lot can be gleaned from the blog post content for SEO. Each markdown file has a header which contains metadata that could be used for SEO purposes.

---
title: "Form-associated custom elements FTW!"
slug: form-associated-custom-elements-ftw
thumbnail: /assets/form-associated.jpg
author: Myself
excerpt: Form-associated custom elements is a web specification that allows engineers to code custom form controls that report value and validity to `HTMLFormElement`...
---

This header gets transformed by the http://localhost:4444/api/post API endpoint into JSON using the matter package. You can review for yourself in packages/server/src/route/post.ts.

You could expand upon this content, delivering relevant metadata for JSON-LD or setting <meta> tags in the HTML document. For the purposes of this workshop, we'll only set one aspect of the document.head, the page <title>, but you can extrapolate on this further and modify renderApp to project specifications.

Open packages/server/src/middleware/ssr.ts to get started for coding for this section and navigate to the middleware function. Some point before the multiple await, we can pass relevant SEO metadata to the Route. If we wanted to override the route.title with the title of each blog post, we could do that by setting the property with the value returned from fetchedData.meta.title.

  route.title = route.title ? route.title : fetchedData.meta.title;

Pass route into the renderApp function.

  const ssrResult = await renderApp(template, route);

Set the <title> tag with the route.title.

function* renderApp(template, route) {
  yield `<!DOCTYPE html>
  <html lang="en">
    <head>
        <title>${route.title}</title>
   ...

Wherever you derive SEO metadata could vary per project, but in our case we can store this metadata on each markdown file. Since we have repeatable patterns like Route and fetchModel, we can reliably deliver metadata to each HTML document server-side rendered in the middleware.

Hydration

So far all the coding you've done has been completely server-side. Any JavaScript that ran happened on the server and each Declarative Shadow DOM template was parsed by the browser. If there's any other JavaScript in the custom element that needs to run in the browser, like binding a callback to a click listener, that isn't happening yet. We need to hydrate the custom elements.

There's an easy and performant fix. We could host the bundle for each route locally and add a script tag to the HTML document that makes the request, but a more performant solution would be to inline the JavaScript, eliminating the network request entirely.

readFileSync is a Node.js utility that allows us to read the bundle from a file and convert the content to a String. Set the String to a new const named script.

  const module = await import(clientPath('dist', route));
  const script = await readFileSync(clientPath('dist', route)).toString();

Pass the script to the renderApp function in a third argument.

const ssrResult = await renderApp(template, route, script);

Add a <script> tag to the end of the HTML document, setting the content with the String named script.

function* renderApp(route, template, script) {
  yield `<!DOCTYPE html>
  <html lang="en">
    <head>
        <title>${route.title}</title>
        <meta name="viewport" content="width=device-width, initial-scale=1">
        <meta name="description" content="Web Components Blog">
        <style rel="stylesheet" type="text/css">${styles}</style>
    </head>
    <body> 
      <div id="root">`;
  yield* render(template);
  yield `</div>
    <script type="module">${script}</script>
  </body></html>`;
}

We can test hydration is now available in AppHeader. Open
packages/client/src/component/header/Header.ts.

Add an else statement to the conditional already defined in the constructor. This conditional if (!this.shadowRoot) is checking if a shadow root doesn't exist and if truthy, imperatively declares a new shadow root. Since the custom element has a template declared with Declarative Shadow DOM, the content inside the if won't run. We can use an else to run additional logic, client-side only. Modify the <h1> that already exists (because it was server-side rendered) by appending Hydrated to the element innerText.

class AppHeader extends HTMLElement {
  constructor() {
    super();
    if (!this.shadowRoot) {
      const shadowRoot = this.attachShadow({ mode: 'open' });
      const template = document.createElement('template');
      template.innerHTML = shadowTemplate({ styles, title });
      shadowRoot.appendChild(template.content.cloneNode(true));
    } else {
      const title = this.shadowRoot.querySelector('h1').innerText;
      this.shadowRoot.querySelector('h1').innerText = `${title} Hydrated`;
    }
  }
}

Remove the else once your test is complete. This section demoed how to hydrate custom elements client-side, but how does the server understand any of this JavaScript? Some of you maybe wondering how did the server interpret class AppHeader extends HTMLElement when HTMLElement doesn't exist in Node.js. This final section is an explainer of how this works with @lit-labs/ssr. Coding is complete. Congratulations! You've finished the workshop.

Shimming Browser Spec

Lit shims browser specifications it needs to run on the server via a function exported from @lit-labs/ssr/lib/dom-shim.js named installWindowOnGlobal. If all your project relies on is autonomous custom elements extended from HTMLElement you can get by just with calling this function prior to anything else in Node.js.

A custom implementation of the shim is found at packages/shim/src/index.ts. I used this custom shim for the chapters in the book Fullstack Web Components because the views we server-side render in the book contain Customized built-in elements, which are not shimmed by default. Lit was thoughtful enough to allow engineers to extend the shim with other mocks necessary to server-side render browser specifications. Use this file as an example of how you could shim browser spec in your server-side rendered project.

installShimOnGlobal is exported from this package in the monorepo and imported into packages/server/src/index.ts where it's called before any other code.

import { installShimOnGlobal } from "../../shim/dist/index.js";

installShimOnGlobal();

It's necessary to shim browser specifications before any other code runs in Node.js. That's why the shim is executed first.

Conclusion

In this workshop, you server-side rendered a blog using Declarative Shadow DOM and the @lit-labs/ssr package with Express middleware. You took autonomous custom elements that declared a shadow root imperatively and made reusable templates that also support Declarative Shadow DOM. Declarative Shadow DOM is a standard that allows web developers to encapsulate styling and template with a special HTML template, declaratively. The "special" part of the HTML template is the element must use the shadowrootmode attribute.

You learned how to use the render Generator exported from @lit-labs/ssr to server-side render template partials in a HTML document. We only rendered one template, but you could take what you learned to render multiple template partials, depending on the needs of the project.

The usage of a static configuration for each Route, exporting template and fetchModel from each view bundle were opinions. This is just one way of working. The main takeaway is for server-side rendering, you should standardize portions of the system to streamline development and ease with integration.

We didn't cover the entire build system in this workshop. Under the hood, nodemon was watching for changes while esbuild is responsible for building for production. If you build for production, you will find the output is 100% minified and scores 100% for performance in Lighthouse. Someone could streamline development further with Vite, the main benefit one would gain is hot module reloading.

We also didn't cover how to use @lit-labs/ssr with LitElement and that was on purpose. Lit is a wonderful library. Use it at your discretion. I find it much more interesting that Lit, because it is built from browser specifications, can operate with browser spec like Declarative Shadow DOM without coding directly with Lit. I hope you find this interesting as well. There is another aspect to this I would like to highlight.

When I started in web development in the 90s, I appreciated the egalitarian nature of HTML and JavaScript. Anyone could code a website, like anyone could read and write a book. Over time, front end web development has gotten way too complicated. Frameworks and libraries that sought to simplify developer experience did so at the cost of user experience, while also making the barrier to entry far greater for anyone wanting to learn how to code a site. I demonstrated how to server-side render a website using only browser standards and leveraging a few tools from Lit. Anyone can learn how to code Declarative Shadow DOM, just like decades ago anyone could learn how to code HTML.

I hope you found it easy to accomplish server-side rendering with Declarative Shadow DOM and can't wait to see what you build. Comment below with a link so we can see those 100% performance scores in Lighthouse.

If you liked this tutorial, you will find many more like it in my book about Web Components.

Fullstack Web Components

Are you looking to code Web Components now, but don't know where to get started? I wrote a book titled Fullstack Web Components, a hands-on guide to coding UI libraries and web applications with custom elements. In Fullstack Web Components, you'll...

Code several components using autonomous, customized built-in, and form-associated custom elements, Shadow DOM, HTML templates, CSS variables, and Declarative Shadow DOM
Develop a micro-library with TypeScript decorators that streamlines UI component development
Learn best practices for maintaining a UI library of Web Components with Storybook
Code an application using Web Components and TypeScript

Fullstack Web Components is available now at newline.co

The Problem With React

Stephen Belovarich — Fri, 17 Mar 2023 16:23:48 +0000

In this post I'll tell the other side of the story. The parts the React Documentary failed to mention.

The recent React documentary was not a good look, but you wouldn't know it looking at the comments on Youtube. Some may refrain from posting anything critical, fearing retribution by members of the community. It's a real thing. Haters gonna hate.

An ethical way to make a documentary is to be objective, but the narrator is clearly crafting a narrative that is biased toward React. Why do we even need a narrator? Are we caught in a cult of personality? The documentary is a warped take on reality. There is no counterpoint, a complete lack of diverse perspectives, so we don't get the complete story.

Who am I to tell you anything about React? I'm not a React maintainer. I'm a web developer that used React in an enterprise org, someone who taught functional programming with React to others, implemented a large React UI library, and coded a React app. I've been developing for the web for over 20 years. At least I'm not begging you to subscribe to my Youtube channel.

What's the problem with React?

Churn

My time with React involved engineers migrating class components to functional, enzyme to react testing library, fixing issues with build configurations, tracking a multitude of dependencies, patching security exploits. Time that could have been spent coding features and enhancements wasted. The job of an engineer at a corporation isn't to merely maintain the codebase, our job is to deliver value for the business, to delivering features and bug fixes for customers.

After many months of work, React finally upgraded their documentation. If you haven't already migrated your class components to functional, you soon will because in the React docs class components are now deprecated and will be removed in a later version. This is just one example of the churn.

Several developers first learned how to code React using the help of Create React App, but probably found they had to roll their own build with Rollup, Webpack or Vite while working at a corporation. There is no mention of how to bootstrap client-side React apps in the new React documentation. Create React App is gone from the docs, probably for good reason because the project was unmaintained. React doesn't even recommend client-side development in the new docs, favoring several server-side implementations including Next.js, Gatsby, Expo, and React Server Components.

If the recommendation is now all React development should be done with a meta framework, the problem with going all-in server-side is that some front end engineers at corporations have no control over the server. I was one of these engineers. No argument could pull Java away from the stack in favor of Node.js, an often more performant tool that could have even saved the corporation operational costs. React has effectively abandoned engineers like me. We have no guidance for bootstrapping a React app solely for the client.

This is what happened to me after trying to convince others at a large enterprise organization to move some logic to the server.

This problem of valuing DX over UX isn't unique to React, other libraries and frameworks suffer from the same thing. What's possibly unique to React is revealed by that famous quote from Mark Zuckerberg. "Move fast and break things." I'm sorry, but at this won't fly at other corporations. It's not like React even gets the DX right. DX is a hot mess, especially when multiple parts of the ecosystem are ever changing.

So What?

Just because React is popular now doesn't mean it always will be. I think we already hit peak React, but haven't seen any conclusive analytical evidence to validate that, just a curve trending downward the last couple years in the State of JS survey.

The job market is heavily React, but it won't always be this way. A decade ago, before React even gained popularity, KnockoutJS jobs were a rare opportunity in a sea of jQuery. It's happened before and it's happening again.

There is a great sea change happening in web development. Several libraries are springing up to support UI component development with Web Components. Frameworks like Qwik are changing the game by removing hydration and moving a majority of work to the server. Change is happening now. React engineers rode a wild wave that is about to come crashing down.

By the way, I realize jQuery is still around. I just dipped into a codebase that uses jQuery. React will most likely be around in a decade. I'm not saying React is going away entirely, I'm saying React in ten years will be regarded like jQuery is today. The two libraries have similar faults. jQuery’s faults were a lack of framework and failure to coordinate the open source community. React repeated similar mistakes and how everyone in the community has to cope with those mistakes. It’s time to start preparing because React is in decline. That’s not to say there won’t always be novel use cases for React: React Native or even using Virtual DOM to provide an XML like interface for complex libraries like three.js. React will still be around, but not nearly as popular as it is today.

How To Cope With Change

If you hope to make it for a long time in this profession, it's time to start learning concepts outside of the React ecosystem. Make sure you learn the fundamentals that apply to every library and framework. That means HTML, CSS, and JavaScript. Go beyond functional programming to understand prototypical inheritance and Object-Oriented programming, which also have applications in front-end development. Take some time to learn new standards landing in the browsers. Learn TypeScript, because it's here to stay, whether as an extension of the language or at some point, types baked into the specification. Learn how servers work, http, WebSocket, and so forth. These fundamentals help you fix issues, contribute to open source, spur innovation.

It's time to start thinking, "OK, how would I do that without React?"

P.S. If you have had a great experience with React so far, I’m happy for you. This post is more about how engineering decisions effect a business. This isn’t an attack on your choice of using React. On the contrary, this is a warning. The ecosystem is too brittle to survive, causes too much churn for businesses that have invested in it. React is the victim of it’s own eventual demise, much like jQuery. It’s coming, so be prepared. If I’m wrong in ten years, I’ll admit I’m wrong, but have a hard time believing history won’t repeat itself with so many signs it already is.

I Asked ChatGPT to Code Web Components and This is What Happened

Stephen Belovarich — Wed, 18 Jan 2023 08:00:00 +0000

The past couple months and I've heard of web engineers tinkering with ChatGPT while another engineer told me they relied on the output for the basis of every coding decision at work. I found myself in the first camp, poking at ChatGPT to generate anything from code examples to blog outlines, ideas for novels, or generative artwork. I was genuinely curious. A.I. will write the code for me? You mean I don't have to think? Sign me up.

I was primarily interested if ChatGPT could be used to generate anything close to production-ready code. I had talked with an engineer using ChatGPT as a basis for coding anything at their job. I wanted to understand what that experience was like. Granted, I'm a ChatGPT novice, so this article won't get overly technical about using ChatGPT by any means. I highly doubt I unlocked the tool's full potential.

I'm a front-end web engineer that codes Web Components and have coded applications with several JavaScript frameworks. I asked ChatGPT to generate some Web Components, because that's what I know extremely well. I wanted to see how precise ChatGPT could produce a simple view comprised of Web Components. I wrote a book about Web Components recently, so I know first-hand how the code should be formatted.

Getting Started

I logged into https://chat.openai.com and prompted ChatGPT with a simple request to generate an application login form with Web Components.

ChatGPT responded with the following code snippet that used the popular Web Components library Lit. I didn't specifically ask for ChatGPT to use a JavaScript library, but here we are.

<template>
  <form>
    <label for="username">Username:</label>
    <input type="text" id="username" @input="${this._onUsernameInput}">
    <br>
    <label for="password">Password:</label>
    <input type="password" id="password" @input="${this._onPasswordInput}">
    <br>
    <button @click="${this._onLoginButtonClick}">Login</button>
  </form>
</template>

<script>
  import { LitElement, html } from 'lit-element';

  class LoginForm extends LitElement {
    static get properties() {
      return {
        username: { type: String },
        password: { type: String }
      };
    }

    constructor() {
      super();
      this.username = '';
      this.password = '';
    }

    _onUsernameInput(event) {
      this.username = event.target.value;
    }

    _onPasswordInput(event) {
      this.password = event.target.value;
    }

    _onLoginButtonClick() {
      // Send a login request with the username and password
      console.log(`Attempting to login with username: ${this.username} and password: ${this.password}`);
    }

    render() {
      return html`
        <form>
          <label for="username">Username:</label>
          <input type="text" id="username" @input="${this._onUsernameInput}">
          <br>
          <label for="password">Password:</label>
          <input type="password" id="password" @input="${this._onPasswordInput}">
          <br>
          <button @click="${this._onLoginButtonClick}">Login</button>
        </form>
      `;
    }
  }

  customElements.define('login-form', LoginForm);
</script>

The duplicate templates surprised me and seem like an error. One declared as a HTML template, the other declared in the render method. The HTML template seems superfluous.

ChatGPT followed the code snippet with an explanation and example of how to implement the LoginForm custom element defined in the <script>. Most of that explanation describing how LitElement behaves is omitted here for sake of brevity. The last bit of the explanation was interesting. A callout the form needed further measures to address security, to keep the transmission of the password secure.

ChatGPT generated a boilerplate example with Lit. It's interesting that was the first choice, given I hadn't prompted ChatGPT to generate any code with a library, just Web Components which are a set of browser specifications.

I wasn't satisfied with the example using LitElement. Nothing against Lit. Lit is actually the first library I would adopt for Web Components that need to be developed at scale. I merely don't want any dependencies in a login view, which should be highly performant. Zero dependencies is a benefit of coding Web Components, especially for a view application like a login form which could be code split from the main bundle.

I prompted ChatGPT to produce the same example but without a JavaScript library.

<template id="login-form-template">
  <form>
    <label for="username">Username:</label>
    <input type="text" id="username">
    <br>
    <label for="password">Password:</label>
    <input type="password" id="password">
    <br>
    <button id="login-button">Login</button>
  </form>
</template>

<script>
  class LoginForm extends HTMLElement {
    constructor() {
      super();

      // Attach the template to the element
      const template = document.getElementById('login-form-template');
      const templateContent = template.content;
      this.appendChild(templateContent.cloneNode(true));

      // Get references to the form elements
      this._usernameInput = this.querySelector('#username');
      this._passwordInput = this.querySelector('#password');
      this._loginButton = this.querySelector('#login-button');

      // Add event listeners
      this._usernameInput.addEventListener('input', this._onUsernameInput.bind(this));
      this._passwordInput.addEventListener('input', this._onPasswordInput.bind(this));
      this._loginButton.addEventListener('click', this._onLoginButtonClick.bind(this));
    }

    _onUsernameInput(event) {
      this._username = event.target.value;
    }

    _onPasswordInput(event) {
      this._password = event.target.value;
    }

    _onLoginButtonClick() {
      // Send a login request with the username and password
      console.log(`Attempting to login with username: ${this._username} and password: ${this._password}`);
    }
  }

  customElements.define('login-form', LoginForm);
</script>

The usage of HTML templates in this example make a lot more sense. LoginForm references each HTML template to append the username and password inputs and the button to display a login form. Event listeners are attached to methods on the class that store the username and password as private properties, denoted by the underscore. A call to customElements.define registers the component class with the browser.

ChatGPT followed the code example with a similar explanation (omitted here).

The above example is alright, although I wanted to follow best practices of making the input and button separate components from the login form. This promotes reusability. The input and button could be exported from a UI library. I asked ChatGPT to generate the same code but this time allowing for a separation of concerns.

ChatGPT produced three separate HTML templates and classes for the form, input, and button.

<template id="login-form-template">
  <form>
    <login-input label="Username"></login-input>
    <login-input label="Password" type="password"></login-input>
    <login-button>Login</login-button>
  </form>
</template>

<template id="login-input-template">
  <label for="input"></label>
  <input id="input">
</template>

<template id="login-button-template">
  <button></button>
</template>

<script>
  class LoginForm extends HTMLElement {
    constructor() {
      super();

      // Attach the template to the element
      const template = document.getElementById('login-form-template');
      const templateContent = template.content;
      this.appendChild(templateContent.cloneNode(true));

      // Get references to the form elements
      this._usernameInput = this.querySelector('login-input[label="Username"]');
      this._passwordInput = this.querySelector('login-input[label="Password"]');
      this._loginButton = this.querySelector('login-button');

      // Add event listeners
      this._usernameInput.addEventListener('input', this._onUsernameInput.bind(this));
      this._passwordInput.addEventListener('input', this._onPasswordInput.bind(this));
      this._loginButton.addEventListener('click', this._onLoginButtonClick.bind(this));
    }

    _onUsernameInput(event) {
      this._username = event.target.value;
    }

    _onPasswordInput(event) {
      this._password = event.target.value;
    }

    _onLoginButtonClick() {
      // Send a login request with the username and password
      console.log(`Attempting to login with username: ${this._username} and password: ${this._password}`);
    }
  }

  customElements.define('login-form', LoginForm);

  class LoginInput extends HTMLElement {
    constructor() {
      super();

      // Attach the template to the element
      const template = document.getElementById('login-input-template');
      const templateContent = template.content;
      this.appendChild(templateContent.cloneNode(true));

      // Get references to the input element
      this._input = this.querySelector('#input');
      this._label = this.querySelector('label');

      // Set attributes
      this._input.name = this.getAttribute('label');
      this._input.type = this.getAttribute('type') || 'text';
      this._label.innerText = this.getAttribute('label');
    }
  }
  customElements.define('login-input', LoginInput);

  class LoginButton extends HTMLElement {
    constructor() {
      super();

      // Attach the template to the element
      const template = document.getElementById('login-button-template');
      const templateContent = template.content;
      this.appendChild(templateContent.cloneNode(true));

      this.innerText = this.textContent;
    }
  }
  customElements.define('login-button', LoginButton);

Interesting callouts from the above code.

LoginInput sets the label using attributes, but doesn't utilize observedAttributes or attributeChangedCallback, two methods available to every custom element that enable engineers to effectively respond to changes in attribute values. Using those callbacks are the only reliable means to track changes in attribute values.
LoginButton sets in the label of the button using a strange line: this.innerText = this.textContent; I would have preferred a method that set the content with a <slot> via the HTML template or an attribute.

Some engineers may be put off by the usage of HTML templates here, but I appreciate how ChatGPT used specifications in this case to provide a stable template for each component. Instead you would declare the templates in the constructor of each component class, a lot like many examples out there.

Adding TypeScript

Next, I asked ChatGPT to produce the same code, but this time with TypeScript. This would give me an idea of how to make the components type safe.

class LoginForm extends HTMLElement {
  private _usernameInput: HTMLInputElement;
  private _passwordInput: HTMLInputElement;
  private _loginButton: HTMLButtonElement;
  private _username: string;
  private _password: string;

  constructor() {
    super();

    // Attach the template to the element
    const template = document.getElementById('login-form-template') as HTMLTemplateElement;
    const templateContent = template.content;
    this.appendChild(templateContent.cloneNode(true));

    // Get references to the form elements
    this._usernameInput = this.querySelector('#username') as HTMLInputElement;
    this._passwordInput = this.querySelector('#password') as HTMLInputElement;
    this._loginButton = this.querySelector('#login-button') as HTMLButtonElement;

    // Add event listeners
    this._usernameInput.addEventListener('input', this._onUsernameInput.bind(this));
    this._passwordInput.addEventListener('input', this._onPasswordInput.bind(this));
    this._loginButton.addEventListener('click', this._onLoginButtonClick.bind(this));
  }

  private _onUsernameInput(event: Event) {
    this._username = (event.target as HTMLInputElement).value;
  }

  private _onPasswordInput(event: Event) {
    this._password = (event.target as HTMLInputElement).value;
  }

  private _onLoginButtonClick() {
    // Send a login request with the username and password
    console.log(`Attempting to login with username: ${this._username} and password: ${this._password}`);
  }
}

customElements.define('login-form', LoginForm);

ChatGPT only output the LoginForm class and failed to generate the other components in Typescript, so I asked again. There were a few other instances where I had to prompt ChatGPT a second, or even third time, to get an acceptable answer. ChatGPT struggled with large code examples. Finally ChatGPT delivered a full TypeScript implementation.

class LoginInput extends HTMLElement {
  private _input: HTMLInputElement;
  private _label: HTMLLabelElement;

  constructor() {
    super();

    // Attach the template to the element
    const template = document.getElementById('login-input-template') as HTMLTemplateElement;
    const templateContent = template.content;
    this.appendChild(templateContent.cloneNode(true));

    // Get references to the input element
    this._input = this.querySelector('#input') as HTMLInputElement;
    this._label = this.querySelector('label') as HTMLLabelElement;

    // Set attributes
    this._input.name = this.getAttribute('label');
    this._input.type = this.getAttribute('type') || 'text';
    this._label.innerText = this.getAttribute('label');
  }
}
customElements.define('login-input', LoginInput);

class LoginButton extends HTMLElement {
  constructor() {
    super();

    // Attach the template to the element
    const template = document.getElementById('login-button-template') as HTMLTemplateElement;
    const templateContent = template.content;
    this.appendChild(templateContent.cloneNode(true));

    this.innerText = this.textContent;
  }
}
customElements.define('login-button', LoginButton);

class LoginForm extends HTMLElement {
  private _usernameInput: HTMLInputElement;
  private _passwordInput: HTMLInputElement;
  private _loginButton: HTMLButtonElement;
  private _username: string;
  private _password: string;

  constructor() {
    super();

    // Attach the template to the element
    const template = document.getElementById('login-form-template') as HTMLTemplateElement;
    const templateContent = template.content;
    this.appendChild(templateContent.cloneNode(true));

    // Get references to the form elements
    this._usernameInput = this.querySelector('login-input[label="Username"]') as HTMLInputElement;
    this._passwordInput = this.querySelector('login-input[label="Password"]') as HTMLInputElement;
    this._loginButton = this.querySelector('login-button') as HTMLButtonElement;

    // Add event listeners
    this._usernameInput.addEventListener('input', this._onUsernameInput.bind(this));
    this._passwordInput.addEventListener('input', this._onPasswordInput.bind(this));
    this._loginButton.addEventListener('click', this._onLoginButtonClick.bind(this));
  }

  private _onUsernameInput(event: Event) {
    this._username = (event.target as HTMLInputElement).value;
  }

  private _onPasswordInput(event: Event) {
    this._password = (event.target as HTMLInputElement).value;
  }

  private _onLoginButtonClick() {
    // Send a login request with the username and password
    console.log(`Attempting to login with username: ${this._username} and password: ${this._password}`);
  }
}

customElements.define('login-form', LoginForm);

The TypeScript output was spot on. I was particularly glad to see strict typing of the event.target in a style that was familiar. Pertinent properties on each class are labeled private and typed appropriately.

Styling The Components

I wanted to add styling to the input and button so I prompted ChatGPT to add CSS to the components, although it kept setting styling through this.style and not by injecting CSS through the <style> tag which I am accustomed. This is due to the assumption the code examples relied on the previous generated HTML templates. The styling could be provided in the HTML templates, although ChatGPT never chose to place the styles there. I generally prefer declaring CSS in the constructor of each class.

I started a new prompt, this time leading with the styling and ChatGPT generated a completely different solution that aligned to my expectations. To achieve this I was more descriptive.

ChatGPT chose to default to LitElement again for this request despite the instruction to "not require a JavaScript library".

I asked again, this time calling out LitElement and ChatGPT responded accordingly even though I had a slight typo.

ChatGPT output three separate code samples, one for each component this time around. This made the output way more reliable than when ChatGPT generated one long code snippet with everything.

export class MyInput extends HTMLElement {
    constructor() {
        super();
        this.attachShadow({ mode: 'open' });
        this.shadowRoot.innerHTML = `
            <style>
                :host {
                    display: block;
                    background-color: #333;
                    color: #fff;
                }
            </style>
            <input type="text" />
        `;
    }
}
customElements.define('my-input', MyInput);

Each component declares the specified styles in the constructor, setting the innerHTML of each shadowRoot to include a <style> tag. I greatly prefer this format over setting this.style. The following MyButton class even sets the cursor: pointer to enhance accessibility.

export class MyButton extends HTMLButtonElement {
    constructor() {
        super();
        this.attachShadow({ mode: 'open' });
        this.shadowRoot.innerHTML = `
            <style>
                :host {
                    background-color: #868e96;
                    color: #000;
                    padding: 0.5em 1em;
                    border: none;
                    border-radius: 0.25em;
                    cursor: pointer;
                }
            </style>
            <slot></slot>
        `;
    }
}
customElements.define('my-button', MyButton, { extends: 'button' });

ChatGPT chose to extend HTMLButtonElement, making the above component a customized built-in element. This allows any instance of MyButton to take on the characteristics of HTMLButtonElement, meaning you don't have to declare event listeners for accessibility because they are baked in. The styling declared in the host that selects :host won’t work because ShadowDOM isn’t available to customized built-ins that extend from HTMLButtonElement. ChatGPT failed to provide an example of how to use MyButton in HTML, which differs from any custom element extended from HTMLElement because of the is attribute. ChatGPT didn't also call out this code would be inoperable in Safari due to WebKit's stance that blocks customized built-ins from working in Safari (which is currently being reconsidered for inclusion, although WebKit has not signaled support).

Finally, ChatGPT declared a custom element for the form itself, setting the shadowRoot with boilerplate styling for the labels, although omitting the is attribute from the instance of <button>, which is required of customized built-in elements.

export class MyFormLayout extends HTMLElement {
    constructor() {
        super();
        this.attachShadow({ mode: 'open' });
        this.shadowRoot.innerHTML = `
            <style>
                :host {
                    display: block;
                }
                label {
                    display: block;
                    font-size: 0.8em;
                    margin-bottom: 0.5em;
                }
            </style>
            <form>
                <label>Username</label>
                <my-input></my-input>
                <label>Password</label>
                <my-input type="password"></my-input>
                <button>
                    <slot name="submit"></slot>
                </button>
            </form>
        `;
    }
}
customElements.define('my-form-layout', MyFormLayout);

The above examples were derived from a request to ChatGPT to generate a separation of concerns between the components and style them. One problem is found on the last line of the MyFormLayout example. Element tag names can only include one dash according to spec, so my-form-layout should be my-formlayout to be parsable by the browser. Otherwise, the HTMLButtonElement doesn't employ the is attribute which is necessary due to MyButton being declared as a customized built-in element.

The logic for authentication is missing from the prior examples. I ask ChatGPT to add the functionality to MyFormLayout and was surprised the output was different than before.

export class MyFormLayout extends HTMLElement {
    constructor() {
        super();
        this.attachShadow({ mode: 'open' });
        this.shadowRoot.innerHTML = `
            <style>
                :host {
                    display: block;
                }
                label {
                    display: block;
                    font-size: 0.8em;
                    margin-bottom: 0.5em;
                }
            </style>
            <form>
                <label>Username</label>
                <my-input id="username"></my-input>
                <label>Password</label>
                <my-input type="password" id="password"></my-input>
                <button id="submit-button">
                    <slot name="submit"></slot>
                </button>
            </form>
        `;
    }
    connectedCallback() {
        this.shadowRoot.getElementById("submit-button").addEventListener("click", (e) => this.handleSubmit(e));
    }
    handleSubmit(e: Event) {
        e.preventDefault();
        let username = this.shadowRoot.getElementById("username") as HTMLInputElement;
        let password = this.shadowRoot.getElementById("password") as HTMLInputElement;

        // logic to check the entered credentials against a user database or API
        // if the credentials are valid, redirect the user to the home page
        // else display an error message
        if (username.value === "user" && password.value === "password") {
            window.location.href = "home.html";
        } else {
            alert("Invalid username or password");
        }
    }
}
customElements.define('my-form-layout', MyFormLayout);

ChatGPT added a single event listener for the submit button, then read the value of the username and password from each input, and implemented some boilerplate validation that checks the value of username and password fields, along with inline documentation to explain the changes. Additional documentation followed the code snippet.

It's nice there is a warning the example "is not recommended for production" considering the boilerplate code doesn't secure the password with any sort of hashing algorithm. The description of the code is suitable to gain a basic understanding of how everything works.

The pseudo code validating the username and password doesn't make much sense. There would most likely be much more robust validation logic here. You could coax ChatGPT into producing an algorithm close to your intended business logic, but it's unlikely to get it just right.

Conclusion

When I heard an engineer was using ChatGPT to generate code everyday for his job, I was interested to see what that was like. Tools like this are no substitute for the knowledge gained by coding something from scratch. While it's entirely possible to generate boilerplate code with ChatGPT, I can't recommend it. Like other responses for "factual" content, ChatGPT will often answer with either completely wrong information or base part of an answer on incorrect assumptions. The same is true of code snippets. As we observed, ChatGPT omitted valuable information about the generated code and generated incorrectly formatted code. Overall, ChatGPT did an alright job at generating Web Components. With some alterations the generated code could be used as the basis for coding a login view. For code generation ChatGPT possibly doesn't replace tools like plop or Nx, which give you consistent control over boilerplate.

There's possibly more advanced queries I could have made to generate the login view code. I'm just a novice.

It's fairly interesting that ChatGPT defaulted to generating Web Components with LitElement. This is a testament to how synonymous the library is becoming with Web Components.

In another query (not featured here), I prompted ChatGPT to make the input and button form-associated custom elements which the service promptly ignored. In a separate query from that, ChatGPT struggled to generate a single example that implemented formAssociated or ElementInternals.

ChatGPT could get better over time, but for now I feel quite secure in my job as a front-end web developer. If I were completely new to Web Components, the incorrect and omitted code would be awfully confusing. Due to the inaccuracy of the code samples, In the future, maybe our robot overloads will take our jobs, but I don't think we will be replaced by A.I. anytime soon.

OK, now what I really think. We are doomed, at least in the immediate future. Bloggers will use the ChatGPT to generate posts. The rest of us won't get the content we so desperately deserve. We'll be forced to sift through cursory explanations of code that are incorrect or malformed. I suppose that was already happening before ChatGPT, but I'm predicting it's only going to be worse. Luckily there's entire books devoted to the topic of Web Components.

Fullstack Web Components Book

Want to learn how to code UI Libraries and Web Applications with Web Components?

Fullstack Web Components is the complete guide to building UI Libraries with Web Components. Through ten chapters of hands-on exercises, you'll learn every aspect to the set of specifications in the context of developing a UI Library and Web Application.

Purchase a copy of Fullstack Web Components today and begin your journey into the wonderful world of front-end development with Web Components.

Form-associated custom elements FTW!

Stephen Belovarich — Tue, 14 Jun 2022 15:30:40 +0000

Before Shadow DOM, you needed a framework to encapsulate component templates or styling. Shadow DOM was a game-changer because it allows you to code UI components without their logic clashing with other components using just the web platform. Shadow DOM poses challenges when HTML elements encapsulated by Shadow DOM need to participate in a form.

In this post, I'll provide an overview of form-associated custom elements. Form-associated custom elements is a web specification that allows engineers to code custom form controls that report value and validity to HTMLFormElement, while also promoting a fully accessible user experience.

The Problem

With the encapsulation provided by Shadow DOM, engineers can code UI components where the CSS styling doesn't collide with other components. Shadow DOM provides a DOM tree for an element separated from the rest of the Document Object Model (DOM). The separation of concerns promoted by Shadow DOM is a boon for coding reusable UI components.

While Shadow DOM has several benefits, there are some complications when elements embedded in Shadow DOM have to interact with HTMLFormElement. Suppose you wanted to code a custom checkbox component using Shadow DOM. Checkboxes usually require a significant amount of CSS styling that overrides the browser defaults to match a given mockup. You code an autonomous custom element and style the HTMLInputElement with type="checkbox" in the context of Shadow DOM so the styling doesn't conflict with other elements. You give the component a tag name of my-checkbox. Just when you think you're following best practices, you place an instance of the custom element as a child of HTMLFormElement.

<form>
  <my-checkbox></my-checkbox>
</form>

Upon inspection in Dev Tools, you may notice the HTMLInputElement cannot participate with the form. You can inspect this phenomenon in this CodeSandbox.

HTMLInputElement by design can report value and validity back to HTMLFormElement, but only when HTMLInputElement is a direct descendent of HTMLFormElement.

<form>
  <input type="checkbox" />
</form>

When coding reusable components it's a good idea to provide an interface for web engineers that's familiar. It's typical for HTMLInputElement that are direct descendants of HTMLFormElement to have access to the parent form directly on the element. You can inspect this behavior in the following CodeSandbox.

Since the HTMLInputElement is found in an entirely different DOM tree (Shadow DOM), the HTMLFormElement doesn't recognize the HTMLInputElement.

In short, HTMLInputElement embedded in Shadow DOM can't participate in the form.

Enter Form-associated custom elements

In 2019, a new specification was proposed that solves this issue. Form-associated custom elements allow web engineers to use the benefits of Shadow DOM while providing an API that enables custom elements to participate in HTMLFormElement. Form-associated custom elements have all the benefits of autonomous custom elements. They can implement Shadow DOM and use the typical custom lifecycle hooks because they inherit from HTMLElement.

If you've coded autonomous custom elements, learning how to code form-associated custom elements is fairly similar. In the following examples, I'll demonstrate how a checkbox embedded in Shadow DOM can participate in an HTML form by implementing formAssociated and ElementInternals.

Before I mentioned that form controls that are native to the browser like HTMLInputElement automatically participate in HTMLFormElement. The form control is added to an Array-like interface on HTMLFormElement, allowing web engineers to loop through the form controls to handle common tasks like validation.

For the Checkbox component to participate in HTMLFormElement the same way, you simply need to set the value of a static property named formAssociated to true. the below example written with TypeScript does just that.

If you wish to follow along, fork this CodeSandbox and start coding.

export class Checkbox extends HTMLElement {
  static formAssociated = true;
  constructor() {
    ....

Inversely, if you wish to reference HTMLFormElement on instances of Checkbox, similar to how HTMLInputElement behaves when it's a direct descendant of HTMLFormElement, a method inherited from HTMLElement called attachInternals can be called with provides the same interface, along with the Accessibility Object Model (AOM). By setting a property on Checkbox named _internals to what's returned by attachInternals, you effectively add the ElementInternals interface to Checkbox.

export class Checkbox extends HTMLElement {
  _internals: ElementInternals;
  static formAssociated = true;
  constructor() {
    super();
    this._internals = this.attachInternals();

Parity

Later in this post, I'll provide an example of how you can reference a method on the ElementInternals interface that aids with validation. Before that, we should resolve some discrepancies between Checkbox and a typical HTMLInputElement. If we expect engineers to reuse this component, it should behave similarly to HTMLInputElement, which has a well-known interface. To provide parity between HTMLInputElement and Checkbox, let's define some getters and setters on Checkbox. First, make a getter that returns a reference of the HTMLInputElement so you can easily reference the element with this.checkbox throughout the logic of the component.

  get checkbox(): HTMLInputElement {
    return this.shadowRoot?.querySelector("input") as HTMLInputElement;
  }

Next, define a getter and setter for the state of the checkbox. It's probably a good idea to make the HTMLInputElement the single source of truth here. Any getter and setter defined on Checkbox either returns the value or sets the value of checked on this.checkbox.

  get checked(): boolean {
    return this.checkbox.checked;
  }
  set checked(state: boolean) {
    this.checkbox.checked = true;
  }

We could introduce several more properties on Checkbox to provide parity between it and a typical HTMLInputElement, but we'll stop there for now.

Lessons Learned

While coding a UI library filled with form-associated custom elements, I found a couple of challenges in making the components reusable. Suppose you wanted to add validation logic to Checkbox and have the class another method called onValidate, including all the logic there. In the below example, I call setValidity on the ElementInternals interface, which reports the validity of the input to HTMLFormElement. This is convenient, however placing this logic here doesn't give a web engineer the ability to configure validations per business logic in different scenarios.

  onValidate(state: boolean) {
    if (!state) {
      this._internals.setValidity({ customError: true }, "required");
    } else if (state === true) {
      this._internals.setValidity({});
    }
  }

A higher-level validation pattern is required that would allow engineers to loop through form controls and validate an entire form.

Another challenge had to do with making inline validation messages accessible. Getting screen readers to interpret validation messages as errors that should be read aloud at first seems tricky because of Shadow DOM, although is possible using WAI-ARIA attributes. Suppose this were the template instead of just the input. If the form control is invalid, custom logic could populate the <div class="message"> with relevant content. WAI-ARIA attributes provide an immediate response for screen readers.

   <div class="control">
      <input type="checkbox" aria-describedby="message" />
    </div>
    <div class="message"
         aria-role="alert"
         aria-live="assertive"
         id="message"
    ></div>

Autonomous custom elements that employ Shadow DOM provide encapsulation for component template and styling. Form-associated custom elements level up custom elements by allowing them to participate in a HTML form much like the "native" HTMLInputElement. Form-associated custom elements open the doors for custom user experiences like this joystick component, which reports it's value to HTMLFormElement like any other form control.

Form-associated custom elements are both practical and transformative, allowing engineers to code reusable form controls without the need for JavaScript frameworks and libraries. If you want to code a highly performant user interface that depends heavily on forms, form-associated custom elements are where it's at!

Fullstack Web Components

Code several components using autonomous, customized built-in, and form-associated custom elements, Shadow DOM, HTML templates, CSS variables, and Declarative Shadow DOM
Develop a micro-library with TypeScript decorators that streamlines UI component development
Learn best practices for maintaining a UI library of Web Components with Storybook
Code an application using Web Components and TypeScript
Server-side render Web Components with Node.js and @lit-labs/ssr

Fullstack Web Components is available now on newline.co.

The State Of Web Components in 2022

Stephen Belovarich — Sat, 07 May 2022 03:13:41 +0000

While writing a book about Web Components, I found nothing in my research that described the current state of the Web Components ecosystem. In this post, I hope to clear up any misconceptions about Web Components and provide several links to resources about Web Components. I'll review the current level of adoption, the top libraries and tooling available, and the browser support for the set of specifications known as Web Components.

TLDR;

~18% of page loads tracked by Google contain a Web Component
Stencil is the most downloaded library for developing Web Components
Custom Elements Manifest powers documentation for Storybook where Web Components became a first-class citizen in 2021
Several online communities about Web Components sprung up during the pandemic including this Forem instance devoted to Web Components

Adoption

Web Components have been growing in popularity among web developers ever since Custom Elements v1 became available in every evergreen browser: Chrome, Safari, Firefox, and Edge. According to Google, in 2019 “> 5% of page loads use a Web Component”. Today, Chrome Platform Status reveals that ~18% of page loads tracked by Google contain a Web Component. This statistic is derived by pages that register a custom element on the CustomElementRegistry.

Libraries and Tooling

Over the years several libraries that enable Web Component development have appeared. https://webcomponents.dev tracks 61 variants of a single component coded with Web Component specifications. divriots, a company that "builds great software to empower front-end teams", analyzes bundle size and performance of several Web Component libraries and publishes the findings in a semi-annual blog post titled "All the Ways to Make a Web Component".

4 variants render faster than the same component coded with Svelte
5 variants have a bundle size smaller than the same component coded with Svelte
54 variants coded with custom elements have a bundle-size smaller and render faster than the same component coded with React or Vue

Top Five Web Component Libraries By Downloads

The following JavaScript libraries are ranked by weekly npm downloads. These libraries either use Web Components "under the hood" or compile down to Web Components.

Stencil - 357,795
Lit - 282,068
FAST - 37,489
Lightning Web Components - 35,452
Solid - 26,261

Weekly downloads sourced from npm on June 24, 2022.

Tooling

In the past year, Web Components became a first-class citizen in Storybook.

Custom Elements Manifest is "a file format that describes custom elements". The @custom-elements-manifest/analyzer package generates a JSON file that can provide rich information about Web Components. Storybook uses this tool to generate documentation of Web Components.

Browser Support

Every major browser supports custom elements according to caniuse.com, with the exception that Apple Safari doesn't support customized built-in elements. Web Components is a set of specifications that include custom elements, Shadow DOM, and HTML templates. caniuse.com uses an outdated marketing term (custom elements v1) for the specifications that allow new HTML tags to be defined, which should probably be known as "custom elements". v1 differentiates the specifications from the prototypical version of custom elements (v0) that have been deprecated since 2014. This marketing term is confusing, mostly because HTML is a living document. caniuse.com also doesn't track some specifications related to Web Components, which may confuse newcomers.

The HTML Living Standard provides documentation for custom elements, including the three main types: autonomous, customized built-in, and form-associated custom elements. Custom elements are one part of the specifications that comprise Web Components, along with Shadow DOM and HTML templates. Other specifications enhance Web Components in some way, like CSS custom properties, but are not under the umbrella of Web Components. Below each specification is described, along with the level of browser support.

Autonomous custom elements allow engineers to define custom HTML elements. Autonomous custom elements have shipped in every modern browser.

Customized built-in elements allow reuse of behaviors from existing HTML elements, which can be a boon for Accessibility in some use cases. Customized built-in elements are available in every modern browser except Apple Safari. A WebKit representative has said in the past WebKit will never support customized built-in elements. WebKit has supported autonomous custom elements and other Web Components specifications including HTML templates and Shadow DOM since 2019. Despite marketing that suggests Safari is either on par or leading in support for specifications, WebKit drags behind other browsers in terms of supporting Web Components. A polyfill exists for customized built-ins that is necessary for Apple Safari.

Form-associated custom elements enable custom elements to participate in the HTML form lifecycle. This specification allows developers to make entirely new form controls, or when inputs are embedded or Shadow DOM, overcome issues that block form controls from reporting validity and value to HTMLFormElement, while also enabling Accessibility. form-associated custom elements are available in Chrome, Edge, and Firefox Developer Edition. There is some evidence form-associated custom elements will be available in WebKit in the future. A polyfill exists for browsers that have not implemented form-associated custom elements.

Shadow DOM provides encapsulation for HTML markup and styling for custom elements. Shadow DOM is available in every modern browser.

HTML Templates is a way to cache HTML in DOM that isn't immediately rendered but can be reused for use in the document. HTML templates are available in every modern browser.

CSS custom properties, otherwise known as CSS variables, are a viable means to provide "design tokens" that cross the Shadow boundary. While not necessarily considered a Web Component specification, CSS custom properties allow engineers to essentially reuse styling in custom elements that employ Shadow DOM. CSS custom properties are found in every modern browser.

CSS Shadow Parts allow shadow hosts to "selectively expose chosen elements from their shadow tree to the outside page for styling purposes." CSS Shadow Parts are useful for theming or other style customizations in custom elements that use Shadow DOM. CSS Shadow Parts are in every modern browser.

Specification Proposals

Web Components are a set of browser specifications. Spec is introduced over time: proposed, iteration upon, developed, and integrated into browsers. Web Components specifications are maintained and proposed in several places. An index is found on Web Incubator CG Github repository README.md.

Various specifications are in some stage of the proposal process that impacts Web Components. Those specifications are described below.

Declarative Shadow DOM

In early 2020, an explainer for Declarative Shadow DOM was introduced, a specification that enables Shadow DOM to be declared in an HTML template, rather than imperatively in a JavaScript class definition. Declarative Shadow DOM enables the server-side rendering of custom elements. Since then, Google Chrome and Microsoft Edge have implemented Declarative Shadow DOM. A ponyfill is required for the specification in Mozilla Firefox and Apple Safari.

In Mozilla's vision for the evolution of the web, the foundation sees "room for improving or adding primitives that provide declarative alternatives for situations that currently require JavaScript". This indicates Mozilla is likely to implement specifications such as Declarative Shadow DOM, as do comments like this one, although Mozilla has been critical of the specification in the past. WebKit has not signaled support for Declarative Shadow DOM. Progress on Declarative Shadow DOM can be tracked here and here.

It is worth noting that Lit has moved forward with providing a package named @lit-labs/ssr that server-side renders custom elements and makes heavy use of Declarative Shadow DOM.

Constructable Stylesheets

In 2018, an explainer was introduced for Constructable Stylesheets. Constructable Stylesheets allow users to compose CSS styles programmatically without the need for a <style> tag. This promotes the reuse of CSS styles, helping to solve a problem common in UI library development where the same CSS is repeated throughout the codebase. Constructable Stylesheets operate across shadow boundaries, replacing the need for CSS selectors in earlier versions of Web Components specifications (/deep/, >>> and ::shadow). Constructable Stylesheets are currently available in Google Chrome and Microsoft Edge. A polyfill exists for browsers that omit the spec.

Mozilla is currently implementing Constructable Stylesheets for Mozilla Firefox. WebKit has not signaled support for the specification.

HTML Template Instantiation

HTML Template Instantiation was proposed by Apple in 2017. HTML Template Instantiation would allow HTML templates to instantiate "with some parts of it substituted, conditionally included, or repeated based on JavaScript values", similar to the syntax available in Angular, Vue, or Ember. A ponyfill exists, despite a complete lack of browser support.

Other Specifications

Web Components specifications early in the proposal process include Partial Hydration, Pending Task Protocol, and Context Protocol.

For further reading about upcoming specifications, read the Web Components Community Group 2021 Spec / API Status Document.

Community

Despite a global pandemic, the growing popularity of Web Components has spurred a community surrounding Web Components to start forming.

The Web Components Community Group aids with "collaboration between people working on web components libraries, tools, documentation, and standards". This group helps advance standards, organize conferences and meetups, and much more. A Slack organization exists for Web Components where engineers can organize.

A Forem instance devoted to Web Components became available in 2022.

This Web Components Twitter Community was formed in 2022.

Reddit has featured a Web Component community for some time.

Fullstack Web Components

Code several components using autonomous, customized built-in, and form-associated custom elements, Shadow DOM, HTML templates, CSS variables, and Declarative Shadow DOM
Develop a micro-library with TypeScript decorators that streamlines UI component development
Learn best practices for maintaining a UI library of Web Components with Storybook
Code an application using Web Components and TypeScript

Fullstack Web Components is available now at newline.co

I spent 48 Hours coding in Nova and forgot about VS Code

Stephen Belovarich — Fri, 30 Oct 2020 15:30:38 +0000

I spent 48 hours with Nova, a new native IDE for MacOS released by Panic on September 14th.

Two days ago I downloaded the free trial of Nova, installed the TypeScript extension, snagged a theme, opened a TypeScript project and started coding.

Nova is fast. Files open with haste. Find in Project... delivers search results fast. There's no visible slowdown editing large files. When I open multiple text editor panes and terminals Nova doesn't skip a beat. The native IDE just works. Not everything is straight out of MacOS. According to Panic, their engineers coded the text editor from scratch after discovering some bugs in Apple’s text layout engine and ended up with a more performant experience.

Nova's text editor is delightful. There’s multiline editing, intuitive autocompletion, code hints. The TypeScript extension features some refactoring functionality for all those code smells. Panic found some novel uses for the MacBook Pro Touch Bar including running your npm script at the press of a button, as if typing npm run start took too long.

The design is clean and intuitive, very familiar to anyone using MacOS. Finding stuff is easy. When I click on the whimsical iconography there’s subtle user feedback. I open a dialog and find myself staring into the depths of outer space. Nova is honestly a little weird. Panic is the same company that released a handheld game device with a hand crank... because they could. It's part of the charm.

Nova has all the things you've come to expect from a modern IDE for JavaScript development. There’s extensions for TypeScript, Prettier and ESLint, Git integration, integrated terminal and development server. You can connect to a variety of servers including Amazon S3, Azure, and Rackspace, or via protocols like SSH, FTP, WebDAV HTTPS. I appreciate this feature for small projects. Panic syncs your server configurations across workstations. The nova command line tool opens files and workspaces from the MacOS Terminal.

VS Code definitely has some advantages over Nova including better Git integration, a robust debugging experience, large extension ecosystem. Despite all those wonderful features, VS Code pauses briefly before opening some files. VS Code doesn't tokenize large files because it bogs down the application. VS Code feels out of place on MacOS. Nova UI is snappy in comparison. Nova is a very capable JavaScript IDE. The performance of a native app alone is worth it, but the MacOS feel prompted me to switch.

At $99 ($49 yearly subscription after the first year), Nova is reasonably priced. If you have a serial number from Panic’s legacy IDE Coda, the initial price drops to $79. Nova is a ground up rewrite of Coda.

If you’re looking for an alternative to VS Code, download the free trial of Nova. You may be surprised how a native IDE can really improve developer experience.

Disclaimer: I’m not paid by or affiliated with Panic.

Coding Is About People Too... Ya Know?

Stephen Belovarich — Wed, 03 Jun 2020 18:22:25 +0000

We are experiencing an inflection point in American society. Gubernatorial orders to shelter in place have kept us indoors. Those of us fortunate enough to have a job despite 25% unemployment are working from home. We blasted off astronauts in a corporate engineered capsule to the International Space Station while Black Lives Matter protestors flee blasts of flash bang grenades. 2020 is an election year where the President is facing the highest disapproval rating of any President in the history of America. We must fill the void left by our leaders with the voices of the community.

With so much going on, I beg web developers to take some time away from coding and consider how their words and actions affect other people. So much of the time we are downright myopic, focusing only on syntax, frameworks, and tooling. I truly believe our silence concerning the welfare of fellow Americans makes us complicit in their misfortune. Black people have endured far too many atrocities to bare. Black mothers have to fear their children are next to be murdered facing the lens of an iPhone camera.

Will the legacy of tech in the lives of black people be the devices that record their murder?

// Detect dark theme var iframe = document.getElementById('tweet-1265326913016528900-68'); if (document.body.className.includes('dark-theme')) { iframe.src = "https://platform.twitter.com/embed/Tweet.html?id=1265326913016528900&theme=dark" }

Black Lives Matter is about gaining equity for black people. Why are we creating barriers to entry in tech for people of color? How can we change hiring practices to reverse this?

// Detect dark theme var iframe = document.getElementById('tweet-1268019656096350210-63'); if (document.body.className.includes('dark-theme')) { iframe.src = "https://platform.twitter.com/embed/Tweet.html?id=1268019656096350210&theme=dark" }

What happens when leaders in technology don't recognize they are part of the problem?

// Detect dark theme var iframe = document.getElementById('tweet-1267944290770128896-93'); if (document.body.className.includes('dark-theme')) { iframe.src = "https://platform.twitter.com/embed/Tweet.html?id=1267944290770128896&theme=dark" }

Coding is about people. Coding provides upward mobility for those who participate. Code is for the benefit of people!

I'm a teacher. One of my students came up to me after graduation a few years back almost in tears. I asked what was wrong but it turns out these were tears of joy. He explained how he just received a job offer, the first in his family to make over $100,000 salary. This remains a profound moment in my life when I realized there is more to coding.

How we use the power of the hire is up to us. We have an opportunity to change lives and I fear we'll squander it.

How can we change hiring practices to be more inclusive of minorities in America? How do we effectively challenge our leaders to enact change? What do you have to contribute to the discussion?

The system is broken. What are you going to do about it?

Fetching API Data with Web Components and SSR

Stephen Belovarich — Tue, 12 May 2020 16:50:44 +0000

I recently launched a site built entirely with Web Components. Several views where static, meaning I could just server side render them wholesale without must hassle. When it came to the blog I felt stuck. The blog is dependent on the asynchronous response from a REST API. How was I going to server side render this view?

The solution turned out to be easy!

The BlogComponent shown in the code snippet below is a custom element that represents the view. During the connectedCallback the method getModel is called.



class BlogComponent extends HTMLElement {
...
connectedCallback() {
    this.getModel();
}
getModel() {
  return new Promise((res, rej) => {
    fetch('http://localhost:4444/api/blog')
      .then(data => data.json())
      .then((json) => {
        this.renderPosts(json);
        res();
      })
      .catch((error) => rej(error));
  })
}
renderPosts(data) {
   ...code for rendering DOM elements
   ...lots of createElement, appendChild, yada yada
}

The getModel method returns a Promise so when the component is server side rendered the Express middleware can wait for getModel to finish before responding with the rendered view. The important thing to consider here is when server side rendering Express will need to wait for the HTTP request to finish before responding to a client with the rendered HTML for the page.

In the Promise, I used fetch to make the HTTP request to /api/blog. I call res() after the component renders the view using the data from the JSON response. In this example, renderPosts is a blocking function. You may use any pattern you see fit. Perhaps you want to implement MVC or service pattern for your components. Go ahead! There just needs to be a way at the component level server side rendering can analyze the class and determine "Does this component require data before I render it?"

During a build step this component is bundled with every other component and route configuration for server side rendering. I map a reference to each component to the path the user will visit, along with a title that can be viewed in the browser window.



export const routes = [
  { path: '/', component: HomeComponent, title: 'Home' },
  { path: '/blog', component: BlogComponent, title: 'Blog' },
  { path: '/404', component: FileNotFoundComponent, title: 'File Not Found' }
]

The bundle is imported into Express middleware that handles the server side rendering. For server side rendering custom elements I used the @skatejs/ssr package. The middleware is below.



require('@skatejs/ssr/register');
const render = require('@skatejs/ssr');

const url = require('url');
const path = require('path');
const fs = require('fs');
const { routes } = require('path/to/bundle.js');

const indexPath = path.resolve('path/to/index.html');
const dom = fs.readFileSync(indexPath).toString();

function generateHTML(template, route, dom){
  return dom
  .replace(`<title></title>`, `<title>${route.title}</title>`)
  .replace(`<div id="root"></div>`, `<div id="root">${template}</div>`)
  .replace(/__ssr\(\)/g, '')
}

export default async(req, res, next) => {
  let component = {};
  const route = routes.find(rt => rt.path === url.parse(req.url).pathname);
  if (route == undefined) {
    res.redirect(301, '/404');
    return;
  } else {
    component = route.component;
  }
  if (component) {
    const preRender = new component();
    if (preRender.getModel) {
      try {
        await preRender.getModel();
      } catch(e) {
        next(e);
      }
    }
    const template = await render(preRender);
    res.send(generateIndex(template, route, dom));
  } else {
    res.send(dom);
  }
}

async/await made this code somewhat compact. After the middleware establishes a component is mapped to this route by parsing the request url and checking against a route in the imported config, the component is instantiated. If a route doesn't match, the browser will be redirected to a 404 route.



const route = routes.find(rt => rt.path === url.parse(req.url).pathname);
if (route == undefined) {
    res.redirect(301, '/404');
    return;
} else {
    component = route.component;
}
if (component) {
    const preRender = new component();

If a class passes through this middleware has the getModel method, getModel is called using the await keyword. The getModel method returns a Promise that ensures the component has rendered the template after successfully making the HTTP request. The code is wrapped in a try / catch in case something fails (either the HTTP request or the render method in the component).



if (preRender.getModel) {
  try {
    await preRender.getModel();
  } 
  catch(e) {
    next(e);
  }
}

But wait, you are calling fetch from node, but inside code that is normally client side?

Remember how I said the components are bundled specifically for server side rendering in a build step? In the entry point for that bundle, I imported node-fetch and put it on the global namespace.



import fetch from 'node-fetch';
global['fetch'] = fetch;

I put objects on the global namespace here normally when I want to mock browser based APIs for server side rendering. node-fetch is an implementation of the fetch API that allows the component to make the HTTP request in node.

The next await that follows is @skatejs/ssr method for rendering Web Components server side. @skatejs/ssr is the magic sauce. The render method takes the component in the first argument and returns the HTML. This HTML will be in the response from the server, but first I have to inject the component HTML into the DOM.



const template = await render(preRender);
res.send(generateIndex(template, route, dom));

The generateIndex method takes the HTML that was retriever earlier in the code from a static file and places the server side rendered HTML in the #root element. I had to massage the output of the render method a bit and remove any calls to a __ssr function that it was injecting for @skatejs formatted components. The generateHTML method also sets the content of the title tag for SEO purposes.



function generateHTML(template, route, dom){
  return dom
  .replace(`<title></title>`, `<title>${route.title}</title>`)
  .replace(`<div id="root"></div>`, `<div id="root">${template}</div>`)
  .replace(/__ssr\(\)/g, '')
}

The results are impressive. Express responds with the server side rendered blog posts on the initial request from the browser.

Easy Rant

A few months ago I read somewhere it can't be done. "You can't server side render web components" they said, justifying reasoning for sticking with React rather than adopting custom elements v1. One of my latest projects demonstrates you can not only SSR static pages with custom elements, but also components that are dependent on asynchronous data from a REST API.

You can do anything with custom elements you can do with component based JavaScript libraries and frameworks, with less code and possibly more performant than Virtual DOM. It really comes down to implementation. In this example I demoed a simple implementation for server side rendering a web component using a class method. You're free to use any pattern. Free as a bird. Don't you want to be a bird?

I Coded My Personal Site With Web Components

Stephen Belovarich — Wed, 06 May 2020 19:43:00 +0000

Ugh. The chore of refactoring a personal site. We all should do it but who has the time? This is the seventh iteration of my personal site, so I was in dire need of some inspiration. I'm looking for a part-time job teaching web development, so that was some motivation.

I needed more to get me excited. All it took was solving problems with vanilla JavaScript and CSS. I'm over JavaScript frameworks. I’m done trying to wrangle all the tooling needed to develop modern JavaScript anything. I kept it simple. I designed the site mainly in browser which led to some fits and starts but the payoff was worth it. Little things like the way the nav animates made me excited to keep going. It was nice getting back to my roots. A decade ago I was a one man full service agency, designing and developing marketing sites and e-commerce solutions for small businesses. It helped I was also building something fun.

The last iteration of the site was very different. At the time in 2015 I wanted to showcase my mastery over AngularJS and WebGL. The site drained your battery due to all the graphics processing, was not very SEO friendly (SPA), and well we know how well AngularJS has aged. Any modern JavaScript framework is a better alternative, however for a site that is mostly static content I decided to move in a different direction.

Nope, this is not Gatsby. Sorry folks. I don't believe in the hype. I do believe in spec. I decided to implement my entire site with the custom elements v1 spec. As long as the solution could meet several criteria I would be fine.

be viable five years into the future
demonstrate my ability to architect and implement UI
SEO friendly
fun and easy to update, minimal maintenance

I chose Web Components instead of a modern JavaScript UI framework for several reasons. Spec is relatively future proof. Browsers will continue to implement the custom elements v1 spec for years to come, while JavaScript frameworks go in and out of fashion. I don't want to be in the same place in five years, regretting that I implemented my site with a JavaScript framework that is no longer supported. No... I want to look back and think "I made it so I only have myself to blame." 🤣

Last year I developed a microlibrary for coding Web Components with TypeScript decorators called Readymade. I used this library throughout the project, implementing each view and component with Readymade. Readymade is a thin layer around the custom elements spec, reducing some of the typical boilerplate while adding some features with minimal overhead. If I went with another library I would have used Stencil or LitElement, but I chose to stay the course with Readymade despite some shortcomings.

Coding my personal site with Web Components just feels right. I honestly don't understand the JavaScript community's aversion to custom elements. I definitely prefer this way of working compared to React. There are some quirks when it comes to styling custom elements, but when isn't there? I feel like abstracting CSS to make styles reusable is always a problem no matter what you are doing. With Readymade I get one-way data binding, but the library doesn't have the equivalent of ngFor in Angular: a way to loop over a data model and bind it to template. That would be handy for dynamic layouts. To be honest that is the only feature I miss from frameworks. I don't miss the dependency management. I don't miss the tooling. I don't miss Virtual DOM. This is a fantastic way to work!

To make my new site SEO friendly, I needed to server side render each view. Server side rendering Web Components was a breeze. One of the few third party packages I used in the project was @skatejs/ssr, a package that enables SSR in node.js for the custom elements v1 spec.

SkateJS needs to interpret the JavaScript for each component, so I bundled the components for the server, exporting each custom element tied to a route. Some of the components act as a view, while other components are smaller units of functionality. I devised a route config that could be injected into the server-side code, which is also Express middleware. When a user visits a particular route, SkateJS renders the components on the server and then Express responds to the request for the route with the compiled HTML. One of the pain points for this project was when I ended up having to implement a Router that was compatible with both Readymade and SkateJS. It turned out not to be so bad. 76 lines of code later and I had a router that worked.

I used Parcel for a development environment, coupled with a separate node process running an Express server that hosts a REST API. The API is only for the blog page. I display post thumbnails and descriptions from my posts on dev.to. To limit the amount of requests going to the DEV API, I setup my environment to query for the posts and then store them locally in production. I implemented a simple JSON database with LowDB which seems to be proficient for this project.

Web Components will be supported in web browsers well into the future, so when deciding which client-side technology would be viable in five to ten years custom elements seemed like a no-brainer. I can still do all the things I could have with a JavaScript library, only with a smaller footprint and less tooling. My hands touched virtually everything end to end. I feel like I learned a lot. I had a lot of control over the stack, so I could pivot easily.

Possibly the best story to come out of this project is about performance. The site when bundled for production weighs in around 23Kb (gzipped). That includes the microlibrary, router, the HTML, CSS, and JavaScript that actually displays content on the page. 23Kb is smaller than some JavaScript libraries. I consider that a huge win. Users don't have to download a ton of JavaScript. The homepage can load ~3.5sec over the "Fast 3G" network emulation in Chrome Dev Tools.

The site was just released so there are probably some minimal production bugs lurking around in some responsive states and devices. I decided to ship the MVP and circle back later to fix some of these issues.

Visit stephenbelovarich.com if you're interested in viewing my new personal site. The code is public on Github for anyone interested in what the development environment looks like.

What do you think?

Are You a Developer or Engineer? Why?

Stephen Belovarich — Wed, 29 Apr 2020 23:23:09 +0000

I consider myself a web engineer, but I'm curious how others perceive their role. Do you consider yourself a developer or engineer (or maybe some other title) and why? Does it matter?

Community Is Everything Right Now

Stephen Belovarich — Mon, 16 Mar 2020 19:35:07 +0000

The DEV community has the opportunity to maintain the status quo during the crisis. DEV can give us a sense of normalcy in the midst of a worldwide pandemic. A lot of us need that. While we adjust to this new reality, we need to consider our local community too. This may not seem evident in a time of panic buying, social distancing and self-quarantines, but community is everything right now.

While we are advised to refrain from congregating in large groups, to self-quarantine and practice social distancing, we can't forget about our local community. We can't afford to have the mindset: "let someone else take care of the less fortunate". Government will most likely fail to bail us out. We need to band together to make it through the pandemic.

I urge you to do whatever you can to help your local community. There are several things you can do. Approach a local non-profit or community organization and ask how you can be helpful. Don't assume you know.

I'm not advocating going out into your community without precaution. I'm not telling you to defy government mandates. Keep calm. Practice social distancing. Use every precaution you can. Most importantly, stay healthy. If you're sick, stay home. Self quarantine.

What happens when the people who are not prepared whatsoever have to self quarantine? What happens when all the restaurant workers living paycheck to paycheck have to go without pay? There are people in our communities who will need help and have no one to help them.

This crisis will test what we are made of. Let's not look back on this moment and remember the panic buying. Instead let's remember how we came together to help each other.

I just made a donation of canned goods to the local food pantry. Now I am taking some time to consider how else I can be helpful.

What are you doing to help your community?

How can we use our skills to help others in this crisis?

The hidden cost of “don’t reinvent the wheel”

Stephen Belovarich — Fri, 28 Feb 2020 18:48:14 +0000

There’s a catchphrase I’ve heard from the even the most experienced web engineers in the past few years.

Don’t reinvent the wheel

Most of the time when I hear this argument “don’t reinvent the wheel”, it sounds like it comes from a place of comfort. Engineers are comfortable using the existing tool even when it causes bloat, is badly architected, or could be a cause of poor performance experienced by the end user. The user is who really loses when engineers make decisions in their own best interests.

Maybe the engineer is heavily invested in a framework and doesn’t want to learn something new. The problem could be more systemic. Maybe your company hasn’t moved away from the same stack in several years. These are much harder obstacles to overcome.

When you have to implement a new feature, more often than not there is a solution already built by the open source community. It seems like a no brainer. Use the tool. There are some things you ought to consider before pulling a library off the shelf.

The learning curve

When you adopt open source tools you often don't know what you are getting. The README highlights all the wonderful things you will get.

Installing the package is the first step. You follow the instructions step by step in the README until you run into a problem where the code doesn’t work. You look for documentation. It’s not really there. You google it. Nothing. You dig through the issues on Github. Nada. Finally you decide to look at the source code to scan for issues. The coding style is foreign to you. Stepping through the code you notice it has been optimized.

Never underestimate the time it takes to learn a new tool. Sometimes it takes awhile before you fully understand the impact of using an open source package. You can hit roadblocks you didn’t anticipate.

Customization can be difficult

Even when a npm package does the job extremely well, there are parts of the tool that don't fit with the company's business logic or design patterns. Forking an open source project could be an option, but who want's to maintain that? You might think the feature your team needs could be contributed back to the open source project, but sometimes that contribution could be met with opposition.

A lot of the time engineers use open source tools to implement UI, thinking it fast tracks development in some way. This could mean using a chart library or bootstrap. I have heard engineers say "tough luck if it doesn't conform to the design styleguide, we need to push out a feature this sprint". That's just not cool. As engineers we should be working together with design and UX professionals to implement solutions for the end user. The decision to buy instead of build could come at the cost of collaboration. The tool could speed up delivery, but how will it look in front of leadership when you have to explain you didn't listen to design and UX?

Innovation is stifled

The heavy adoption of open source tools comes at another cost. We are stifling innovation. When nearly everyone is learning the hottest new JavaScript library instead of fundamentals, we lose the skills required to build something from scratch. We lose our connection to the language itself because we are always interacting with an abstraction: the JavaScript framework. The industry is stuck the patterns of the library. We have the entire history of computer science to draw from and opportunities to design new patterns, but all I hear is "redux".

Some of us poke our heads out every once in awhile and say "we can do it different", but do the rest of us hear their message?

Bloat

A more obvious cost of bundling libraries with our applications is the resulting bloat. Several third party libraries cannot be treeshaken. You can't pull in only the parts of the library you want to use. Instead you have to bundle the entire library with your application.

The more dependencies, the larger the bundle, the longer it takes the end user to download the JavaScript. This is particularly important for mobile users that make up roughly 50% of global traffic. It's highly possible a homegrown solution means less code and a lighter bundle.

Conclusion

"Don't reinvent the wheel" is a phrase I've heard countless times over the years. I am told if a library exists, use it. Then I go and implement a custom solution anyways. The result usually means less code, customized for a set the business logic. I write documentation so the learning curve is shallow. The willingness to architect and implement a custom solution maybe one key difference between Senior and Junior engineers or even Principal and Senior engineers.

In the past few years browser APIs have evolved. We have several tools baked into the browser that JavaScript libraries ignore. As evergreen browsers become more prevalent, it's time we start using these APIs more.

Last year when I was coding Readymade, I implemented one-way data binding with a minimal amount of code using ES2015 Proxy. The library overcomes limitations of DOM events by using the BroadcastChannel API for events. A "hello world" to generate a Readymade component is ~1Kb, gzipped. When implementing all the Readymade features, the bundle is slightly larger. This is just one example of how vanilla JavaScript and browser API can reduce the bundle size. Without a custom solution, I would have very few options for custom element development that didn't generate more library code. I wouldn't have been able to define the developer experience and make the API easy to use.

I can hear it now. "Why didn't you use Svelte?"

I'm confident if more people in our industry took the time to learn browser API and JavaScript we could further innovation. Instead of focusing all of your energy mastering libraries, consider how you would implement a library without dependencies. Maybe the result will be something lighter, faster, and delightful to use.