DEV Community: Bryan Ollendyke

Web component Q&A with.. well. me.

Bryan Ollendyke — Tue, 26 Aug 2025 18:30:24 +0000

https://hax.psu.edu is built entirely using web components, as well as the whole hax ecosystem. All of our "apps" are web components, haxcms being the biggest one which is entirely web components. I often get asked, how is this possible. So here's the questions asked as well as my answers from a recent Slack message in Apereo.

how do you manage state across an app made up of plenty of web components?

We only use web components. hard stop. "apps" become:

more and more web components State is managed by MobX for a larger data store as in the case of hax editor or haxcms as app router is vaadin-router so it's also a web component in a singleton pattern
Singleton patterns are used for things that would be good to check in with. For example dialog, tooltip, toast as obvious ones but less obvious would be translation engine, text editor highlight selection menu. Screenshot shows several sub-system style singletons that are in haxcms
Theme are in effect web components that boil up to a single tag, you can actually modify them in any hax site by inspecting the DOM and typing the name of another known element and watch the state management not be impacted. It is a lot of abstraction of theme from store to make work but it's awesome 🙂 . The CMS is in effect, storing all the mobx / state work and ensuring that the router is talked to to generate the CMS content for the site
Theme development gets into mobx in our docs - https://haxtheweb.org/documentation/developers/haxsite/data-store

how do you manage communication, if a web component instance used by another which is used by another (e.g. an form in a feed shown in a content area) needs to communicate with a web component that is a deep decendant of another (e.g. a statusbar inside a footer)

If things need to talk to each other the two common patterns we use above come into play. If it's integral to the app then a prop in a mobx store. Singletons can be called directly via requestAvailability call on the global window, or we'll use events for bubble up / communication sorta stuff. Click a button, button emits the simple-modal-show event, the singleton is listening on the window and reacts to the event. This can also just be collapsed items that bubble up a message with parents listening. When the elements are completely disconnected from one another, singleton has worked great so that we can keep things abstracted.

You can read more about our i18n singleton here -- https://dev.to/btopro/i18n-in-web-components-2gii micro front-ends in our setup are also talked to via a singleton so - might be interesting stuff here -- https://dev.to/btopro/building-micro-frontends-with-vercel-lit-45oe

if you want to use lots of web components in your page and they are made up of web components, but 2 of them happen to have dependencies which use html snippets that use a tag, but both web components mean different web components with that tag... basically a name clash

You are correct. We have ensured we don't make clashing name space elements. There's patching to allow this in the spec and future spec work to make it native, but regardless we just don't get into name clashes. In part because of how we don't bundle our assets so we only ship 1 copy of (for example) lit. There are not multiple copies of lit in what sits on the CDN / local unbundled copy of assets.

magic script talks about this process; we've enhanced it but use the same methodology invented in 2020 https://dev.to/btopro/part-1-how-penn-state-unbundles-web-components-for-cdn-deployments-20di
Our monorepo helps make sure everything keeps in sync as well as our build scripts which compile everything in place using a fork of polymer CLI tools (deprecated but only thing I can find that provides the functionality) and then terser to minify in place - https://github.com/haxtheweb/webcomponents

Let's make a custom theme in hax

Bryan Ollendyke — Thu, 03 Apr 2025 19:22:30 +0000

Site created in the tutorial: https://haxcli-customthemetutorialfdsdfs.surge.sh/

In this tutorial I'll walk through the process of building a custom theme in HAX. HAX allows you to visually edit web component based content in a flat-file site.

Get the CLI

First let's install the hax command-line interface tool

npm install --global @haxtheweb/create

Next, run hax start to see available options and select "Create a HAXsite"
Answer where you want the project to live, it's name, author, and then select "Create Custom Theme"
Name your theme, one will be suggested that starts with custom-NAMEOFYOURSITE-theme. It is not required to start with custom- or end in -theme at this time but it recommended for name spacing.
After this select the template you want to use. We recommend the Vanilla Theme if this is your first time. Then Launch your project.

Your prompt should look like this for our tutorial:

Next time if you wanted to script all that automatically you could have run:

hax site customthemetutorial --theme "custom-theme" --custom-theme-name "custom-tutorial-theme" --custom-theme-template "base" --y

After it has finished creating the files you should get a browser window that opens and looks like this:

Now the fun part

Open VSCode to the location you created your site
Open a new terminal window and do cd custom followed by npm start
You now have 2 terminals running. 1 that is monitoring files for changes to your custom theme (building it), and another that is serving the site so that you can edit it
Navigate to custom/src/custom-tutorial-theme.js and edit as desired

Things of note

This is boilerplate, but is a custom theme. You can remove and add whatever as well as create additional elements if it makes it easier to develop your theme. The best way to learn theme development is to read through our documentation on theme development, especially around MobX, considerations for any HAXsite theme, and the available reusable site- elements that already exist to simplify the process of creating new themes.

Publishing to surge.sh

Due to this being so new, we have to manually edit 1 file in order to have our site work on surge.sh with it's custom theme. You can find documentation on this here.

Edit index.html and change the following line:

      "@haxtheweb/": "./build/es6/node_modules/@haxtheweb/"

to say

      "@haxtheweb/": "https://cdn.hax.cloud/cdn/build/es6/node_modules/@haxtheweb/"

Then run surge . If it says command not found, first install surge by running npm install --global surge

After this is published and you have an address, switch that line in the index.html back to what it was. This is a problem we are actively looking for a solution to but involves wrapping publishing into the CLI which is a larger task to script right now.

Source of that file

/**
 * Copyright 2025 btopro
 * @license Apache-2.0, see License.md for full text.
 */
import { HAXCMSLitElementTheme, css, unsafeCSS, html, store, autorun, toJS } from "@haxtheweb/haxcms-elements/lib/core/HAXCMSLitElementTheme.js";
import "@haxtheweb/haxcms-elements/lib/ui-components/navigation/site-menu-button.js";
import "@haxtheweb/haxcms-elements/lib/ui-components/site/site-title.js";
import "@haxtheweb/haxcms-elements/lib/ui-components/active-item/site-active-title.js";

/**
 * `CustomTutorialTheme`
 * `CustomTutorialTheme based on HAXCMS theming ecosystem`
 * `This theme is an example of extending an existing theme component`
 *
 * @microcopy - language worth noting:
 *  - HAXcms - A headless content management system
 *  - HAXCMSLitElementTheme - A class that provides correct baseline wiring to build a new theme that HAX can use
 *
 * @documentation - see HAX docs to learn more about theming
 *  - Custom theme development - https://haxtheweb.org/documentation/developers/haxsite/custom-theme-development
 *  - Theme Blocks - https://haxtheweb.org/documentation/developers/theme-blocks
 *  - DDD - https://haxtheweb.org/documentation/ddd
 *  - Data Store - https://haxtheweb.org/documentation/developers/haxsite/data-store
 * @element custom-tutorial-theme
 */
class CustomTutorialTheme extends HAXCMSLitElementTheme {
  /**
   * Store the tag name to make it easier to obtain directly.
   * @notice function name must be here for tooling to operate correctly
   */
  static get tag() {
    return "custom-tutorial-theme";
  }

  // set defaults or tie into the store
  constructor() {
    super();
    this._items = [];
    this.activeId = null;
    autorun(() => {
      this.activeId = toJS(store.activeId);
      this._items = toJS(store.manifest.items);
    });
  }

  // properties to respond to the activeID and list of items
  static get properties() {
    return {
      ...super.properties,
      activeId: { type: String },
      _items: { type: Array },
    };
  }

  // allows for global styles to be set against the entire document
  // you can also use this to cascade styles down to the theme
  // but the more common reason is to influence the body or other things
  // put into the global index.html context by the system itself
  HAXCMSGlobalStyleSheetContent() {
    return [
      ...super.HAXCMSGlobalStyleSheetContent(),
      css`
      :root {
        --my-theme-low-tone: var(--ddd-theme-default-slateMaxLight);
        --my-theme-high-tone: var(--ddd-theme-default-coalyGray);
      }
      body {
        padding: var(--ddd-spacing-0);
        margin: var(--ddd-spacing-0);
        background-color: var(--my-theme-low-tone);
      }
      body.dark-mode {
        background-color: var(--my-theme-high-tone);
      }
      `,
    ];
  }

  //styles function
  static get styles() {
    return [
      super.styles,
      css`
        :host {
          display: block;
          padding: var(--ddd-spacing-10) var(--ddd-spacing-20);
          max-width: 960px;
          min-width: 400px;
          margin: var(--ddd-spacing-0) auto;
          border: var(--ddd-border-lg);
          border-width: var(--ddd-spacing-5);
          border-radius: var(--ddd-radius-lg);
          background-color: light-dark(var(--my-theme-low-tone), var(--my-theme-high-tone));
          color: light-dark(var(--my-theme-high-tone), var(--my-theme-low-tone));
        }
        .wrapper {
          border-radius: var(--ddd-radius-lg);
        }

        site-title {
          font-size: var(--ddd-font-size-l);
        }

        header {
          display: flex;
        }
        ul {
          margin: var(--ddd-spacing-0);
          padding: var(--ddd-spacing-0);
        }
        ul li {
          display: inline-block;
          margin: var(--ddd-spacing-0);
          padding: var(--ddd-spacing-0);
          list-style-type: none;
          vertical-align: top;
        }
        ul li a {
          display: block;
        }

        button {
          height: var(--ddd-spacing-8);
          width: var(--ddd-spacing-8);
          margin: var(--ddd-spacing-0);
          padding: 0;
          font-size: var(--ddd-font-size-sm);
          cursor: pointer;
        }

        .active button {
          background-color: light-dark(var(--my-theme-low-tone), var(--my-theme-high-tone));
          color: light-dark(var(--my-theme-high-tone), var(--my-theme-low-tone));
          font-weight: bold;
        }

        site-menu-button {
          display: inline-block;
          vertical-align: top;
        }
      `,
    ];
  }

  render() {
    return html`
    <div class="wrapper">
    <header>
      <ul>
        <li>
          <site-menu-button
            type="prev"
            position="top"
          ></site-menu-button>
        </li>
    ${this._items.map((item, index) => {
      return html`
        <li class="${item.id === this.activeId ? "active" : ""}">
          <a href="${item.slug}"><button title="${item.title}">${(index+1)}</button></a>
        </li>
      `;
    }
    )}
        <li>
          <site-menu-button
            type="next"
            position="top"
          ></site-menu-button>
        </li>
      </ul>
    </header>
    <main>
      <site-active-title></site-active-title>
      <article>
        <!-- this block and names are required for HAX to edit the content of the page. contentcontainer, slot, and wrapping the slot. -->
        <div id="contentcontainer"><div id="slot"><slot></slot></div></div>
      </article>
    </main>
    <footer>
      <slot name="footer"></slot>
    </footer>
  </div>
    `;
  }

}
globalThis.customElements.define(CustomTutorialTheme.tag, CustomTutorialTheme);
export { CustomTutorialTheme };

link-preview-card

Bryan Ollendyke — Tue, 01 Apr 2025 20:03:52 +0000

Web component

link-preview-card

Scope

Hit an open-api web service and render the metadata of the link in order to preview it. Common in text editors / social media sites.

Github Issue

https://github.com/haxtheweb/issues/issues/1764

Demo

https://link-preview-card-one.vercel.app/

Student submission

https://github.com/AlexM-117/link-preview-card

Accepted Solution

https://github.com/haxtheweb/webcomponents/blob/master/elements/rich-text-editor/lib/open-apis/link-preview-card.js

github-rpg-contributors

Bryan Ollendyke — Wed, 26 Mar 2025 20:59:16 +0000

Web component

github-rpg-contributors

Scope

hit the open github API and return a list of users that contribute to a project in an organization. Render these using the @haxtheweb/rpg-character element

Github Issue

https://github.com/haxtheweb/issues/issues/1464

Demo

https://github-rpg-contributors-navy.vercel.app/

Student submission

https://github.com/Tushar1906/github-rpg-contributor

Video discussing the process and cleaning up

Accepted Solution

https://github.com/haxtheweb/webcomponents/blob/master/elements/github-preview/lib/github-rpg-contributors.js

HAX Student Innovation Pipeline (11)

Bryan Ollendyke — Wed, 26 Mar 2025 20:53:11 +0000

I teach modern web development at Penn State. As part of that, students learn about HTML,CSS and JS using the webcomponent standard as the ultimate vehicle for doing so. We start at the basic three and work our way into web components using the HAX ecosystem and tooling as a backdrop.

npm install --global @haxtheweb/create

As we learn the standards and do example projects to get a feel for modern development, we then turn toward solving real problems in the HAX ecosystem. These typically are small in scope, individual web components that we need to make using our design system or other criteria.

This dev.to series will document the projects that get added to the HAX ecosystem primarily through teaching students how to do modern web development.

You can learn more about the project:

Web Component shadow roots x design system. Constructable style sheets?

Bryan Ollendyke — Thu, 06 Mar 2025 16:16:08 +0000

Recently I fielded a question issue from a student about how we handle "global styles" when working in the HAXcms theme layer. This question is a common one I've found across developers of all experience levels due to the nature of two seemingly conflicting concepts:

CSS. Cascading, Style, Sheets.
Design systems leveraging the above
ShadowRoot - a controversial aspect of web components that breaks the cascade to allow locally scoped styles

As HAX project lead, our platform works exclusively through the building and nesting of 1,000s of Web Components and most (~95%) use ShadowRoots via Lit / LitElement.

How we manage local scoping vs global scoping

Constructable style sheets is an API that allows for not just treating the style sheet as text which is then leveraged as text in a <style> tag to be applied as CSS; it treats the style sheet as a full JavaScript class / object.

This allows for programmatically producing and sharing the style sheet around as a singular object. Lit / Google have some great articles about this so I'll link to these for background reading / more code detail:

So what does it look like?

In HAX, we have a designs system called Development, Design, Destroy (DDD). This design system needs to:

Ensure that individual web components / blocks look like DDD
Ensure our editing environment (h-a-x, a shadowRoot controlled authoring experience) looks like DDD
Ensure that our theme layer looks like DDD
Ensure the top level document looks like DDD (so things in the LightDom / entry file / HTML document)

Styles

We have all of our styles as exported variables from a single file. These styles are decorated via Lit's css styling based template literate tag. You can see a sample of one here as well as the source.

DDDStyles.js

Full file, code sample below

export const DDDVariables = css`
  :root {
    color-scheme: light dark;
  }
  :root,
  html,
  body,
  :host {
    /* base colors */
    --ddd-theme-default-beaverBlue: #1e407c;
    --ddd-theme-default-beaver70: rgba(30, 64, 124, 0.7);
    --ddd-theme-default-beaver80: rgba(30, 64, 124, 0.8);
    --ddd-theme-default-landgrantBrown: #6a3028;
}
`;

We then take this variable and all other style decorated variables, export them but then also combine them into an Array to be able to ingest the entire library. This allows for DX downstream of adopting a portion of DDD or the entire thing. If an element only needs access to our borders or font sizes, then it can leverage just DDDBorders or DDDFontSizing to obtain just these references.

Code sample of the Array export

// export that has all of them for easy stamping as a single sheet
export const DDDAllStyles = [
  DDDVariables,
  ...DDDDataAttributes,
  DDDReset,
  DDDBreadcrumb,
  DDDExtra,
  DDDBorders,
  DDDMarginPadding,
  DDDLetterSpacing,
  DDDLineHeight,
  DDDBoxShadow,
  DDDBorderRadius,
  DDDBackground,
  DDDFontClasses,
  DDDFontWeight,
  DDDFontSizing,
  DDDAnimations,
];

Note the comment at the top of the code block; we now have all of these style tokens in one Array so that we can build a style sheet that has all of them!

Individual element

DDD then ships with two ways we can implement it in individual web components. Method one gets everything + our legacy color system (called Simple Colors) + LitElement. This is common for when we go "ya it's going to need everything" or especially when augmenting work that pre-dates DDD (so it used our old Color library, allowing us to transition).

Method two, just applies the Reset via a SuperClass / mix-in approach. You'll note it also does a "is this awesome thing your making needing to be presented in the terrible things called Safari" ;)

Right with that though is this line:

globalThis.DDDSharedStyles.requestAvailability();

Global document / html / Constructable Style Sheet

This requestAvailability() approach is how we handle Singleton Paradigms, especially important in an unbundled worldview. Singleton is 10 things need access to 1 thing, you don't know when they'll load, make a method that bridges that only one copy resides in the entire system regardless.

You can see the full call below which I'll then step through what it's doing:
Code in question

globalThis.DDDSharedStyles.requestAvailability = () => {
  if (
    globalThis.DDDSharedStyles.instance == null &&
    globalThis.document &&
    globalThis.document.head
  ) {
    // convert css into text content of arrays mashed together
    // this way we can inject it into a global style sheet
    let globalStyles = DDDAllStyles.map((st) =>
      st.cssText ? st.cssText : "",
    ).join("");
    try {
      const adoptableDDD = new CSSStyleSheet();
      adoptableDDD.replaceSync(globalStyles);
      // THIS FLAG MAKES HAX LOAD IT IN ITS SHADOW ROOT!!!!
      adoptableDDD.hax = true;
      // Combine the existing adopted sheets if we need to but these will work everywhere
      // and are very fast
      globalThis.document.adoptedStyleSheets = [
        ...globalThis.document.adoptedStyleSheets,
        adoptableDDD,
      ];
      loadDDDFonts();
      globalThis.document.onload = dddCSSFeatureDetection();
      globalThis.DDDSharedStyles.instance = adoptableDDD;
    } catch (e) {
      const oldStyleSafariBs = globalThis.document.createElement("style");
      oldStyleSafariBs.innerHTML = globalStyles;
      globalThis.document.head.appendChild(oldStyleSafariBs);
      loadDDDFonts();
      globalThis.document.onload = dddCSSFeatureDetection();
      globalThis.DDDSharedStyles.instance = oldStyleSafariBs;
    }
  }
  return globalThis.DDDSharedStyles.instance;
};
// self-appending on call
export const DDDSharedStylesGlobal =
  globalThis.DDDSharedStyles.requestAvailability();

Steps / checks / happenings:

Do we already exist
Look at all the styles, .map the Array and join together all the cssText as a single string
Use a CSSStyleSheet() and add it to the document's adoptedStyleSheets array, ensuring that DDD is applied last
load fonts which get added as link's appended to <head>

You'll also note the "fun" Safari check to fallback and create a singular style element. Whis should probably say "older browsers" but I digress in my trolling.

Why do any of this?

Performance. performance. performance! While what we are doing operates like this:

1 sheet for the document made out of the textual representation of the other style objects
1 object reference across n number of elements to the same object in LitElement based shadowRoots

It used to work like this prior to Lit and our own adoption of this methodology:

css is text
apply that css as text across n number of elements

In other words, this started to completely brick the performance of our ecosystem. Constructable stylesheets ensured that if there's a CSS variable called --ddd-spacing-12 that it at most is in memory 2x (1 for the global document, 1 across all elements that use DDD).

In fact if you notice we put this in the global document which gives us 1 copy of the CSS variables, and then the default behavior of DDDSuper is simply to apply a CSS reset. This implies none of the variables are loaded directly into these elements (even in memory) and thus will take on the css variable values from their global application.

We are certainly not perfect in our usage of these things, but we've had great success with this approach. Our ecosystem of 658 web components loads with a high level of performance thanks to lit, the approaches mentioned here, and sweat equity.

HAX

If you'd like to learn more about the HAX ecosystem and how Penn State is building a Ubiquitous Web Authoring platform hit up the links below:

hax cli: publish on surge.sh fast!

Bryan Ollendyke — Mon, 03 Mar 2025 17:18:34 +0000

HAX is a moonshot technology developed by Penn State faculty, students and staff to make web publishing and ownership ubiquitous.

Publish using `hax` cli

See the full list of example commands or copy and paste the blocks below to get building.

# install the cli
npm install --global @haxtheweb/create
# create a new site called zombocom
hax site zombocom --theme "clean-one" --y --no-i
# add a page
hax site --root ./zombocom node:add --title "My docs" --content "<p>This is all about our doc process</p>" --y
# start publishing process to surge.sh, confirm name manually
hax site --root ./zombocom site:surge

The above command run produced the following site! There are many different themes with workflows coming to script and automate the creation of new ones.

goals / features

rapid publishing
easy to move format
click and build UI
built in CDN to allow for publishing sites on static hosts without hosting all assets

limitations

surge blocks indexing by search engines
platform incentives multi-page / system visits over initial paint (always getting faster)
SSR experimental / not possible w/ current reality
Theme development workflows still being documented (Mar 2025)

Video tutorial

Here's a video stepping through different commands in the CLI as well as building out and adding content through the UI tools.

Learn more

Our why

While writing here on dev.to is great, and in a simple, clean format. It is still limited relative to what the web offers. It still uses "tokens" and code in order to bring content to the web. I can't take it and publish it on my own without knowing about how to leverage the web.

We envision a world where you own every aspect of production of the web, without ever needing to know the web. Start on a PHP based system, move to CLI driven one, move to desktop or SaaS or nodejs driven one; you should not need to care about all these decision trees. Want to start in a Word / Google doc? Do that. Want to start from an existing site, copy the URL.

We seek a world where publishing flows like water. Join us today on Discord. One web component at a time, we will change web authoring forever.

Github + Stickblitz + HAX = free web publishing

Bryan Ollendyke — Fri, 09 Aug 2024 17:41:37 +0000

Video of the process followed below.

In this tutorial I will show you how to Build and manage a web publishing workflow using free accounts and installing no tools by using Github, Stackblitz, and the haxtheweb/haxsite repo.

Getting started

First, start by getting an account on github
Next an account on stackblitz

Step 1: Setup Github Pages workflow

Now navigate to the haxtheweb/haxsite repo
Click the Create a new repository option found under the Use this template button (image below)
Next, name your repository and select Create repository
This will take a few seconds and then you have a copy of the repo!
Now it's time for enabling Github's "Pages" capability. Click settings
On the left under Code and automation click the Pages button
Click the word that says "None" under Branch and select the main branch
You should see main / (root); click "Save"
Wait a minute or so and refresh the page and you should now see "Your site is live at"

You can see the tutorial's live site at https://btopro.github.io/jubilant-spoon/ and now we've set things in motion so that when changes are made on github, it will automatically rebuid the site and our address will reflect the changes. Now it's time to use HAX to edit our files in the cloud!

Step 2: Use HAX to edit the site on Stackblitz

Go to https://stackblitz.com and click the "Open Github repository [beta]" button
Select your repository after authorizing the connection between github and stackblitz and click "Open repository"
It will think for a bit, do some installation and then you will see a broken window to the right like below (don't panic this is normal!)
Click the Plug icon on the left for "Ports in use" and then click the "Open in browser" icon
A message will say "You're almost there!", click the "Connect to Project" button

Step 3: JACKPOT - HAX time

Congratulations, you now can edit a website in the cloud using HAX!

Click "Edit" on the top bar to get started HAX'ing the web!
Add blocks, edit content, administer the site outline using the outline designer, go. to. town! You have a full working copy of HAX running on stackblitz

Step 4 - HAX quick tutorial

After clicking Edit, click on the page content to activate it. The right panel will show you configuration options
Markdown shorthand like # and > and - can be used to write rapidly
Merlin is the command discovery system. If you are trying to do something, start typing the word you are thinking of and merlin may be able to help jump you to that action. It's great for inserting Blocks in the page by writing and typing / to start a blank paragraph
Outline Designer allows you to rapidly administer the site hierarchy and can be found under Site actions -> Outline designer
You can change the theme and site details under Site actions -> Edit settings

Step 5 - Publish changes to github

By now you've modified content, added blocks, maybe some pages, and it's time to get our content updated on github. Easy Pease!

Close the browser tab that has HAX running in the cloud and go back to the Stackblitz repo
Click "Source Control" on the left as shown
You will see a blue "Sync Changes" button with the number of changes. Thanks to HAX + Stackblitz, every operation you saved = a commit in the repo under the hood!
It will ask you about pull and push, hit "OK" as shown
The first time you do this you will be asked to authorize Stackblitz to talk to Github. Accept the permissions for this connection
Go back to the github repo and you should see the build starting. In a minute or so, refresh the github pages link to see your changes

CONGRATULATIONS!

You now have a HAX publishing workflow that requires installing nothing and paying nothing in order to host your content online!

We'll get into the technical considerations of HAX in future posts but the tldr;

This site's CONTENT is stored with the site always under the pages/ directory so that it can all work as a stand alone package
The JavaScript / system assets powering the site are coming from our network of CDNs using the Magic Script. If you want to run those assets locally you can copy wc-registry.json and the build directory from our CDN into the top level of your site
You are able to pull this site into other HAX tech like the Node-js, PHP, desktop, HAXiam and other implementations to work on it.

Learn more about HAX

With the right tools, you can build anything

Bryan Ollendyke — Fri, 13 Oct 2023 15:32:50 +0000

16 years in the making, the story of my thesis, turned into action and the platforms built. This is the backstory to HAX; where it started, when, and what I hope it will accomplish with my time here.

HAX

The authoring experience of HAX and the ability to make fast, static file backed websites rapidly.

HAX seeks to be the smallest possible back-end CMS to make HAX work and be able to build websites with it. Leveraging JSON Outline Schema, HAX is able to author multiple pages, which it then writes onto the file system. This way a slim server layer is just for basic authentication, knowing how to save files, and placing them in version control.

Watch and Read more about HAX here:

Youtube channel - https://www.youtube.com/@haxtheweb
HAXCellence https://oer.hax.psu.edu/bto108/sites/haxcellence/what-is-hax

Issues / Support / Community

Discord Channel - https://bit.ly/hax-discord
Unified issue queue - https://github.com/elmsln/issues/issues
Using Merlin directly in any HAX spaces and type "Issue" to jump start a report!

Writing an HTML to HAXcms site importer with Vercel

Bryan Ollendyke — Thu, 21 Sep 2023 19:37:38 +0000

This is a live coding session where I show the process of creating a new endpoint in Vercel and wiring it up for importing site content into HAXcms in order to build a brand new site! I've been overwhelmed by the interest in our importers, as well as how fast they've been to develop thanks to Vercel. When someone approached us recently about importing Drupal based content into HAXcms, I thought "what if it was just HTML on one page?". Sure enough, Drupal's book module, popular in education, can output the site's content for 'print' all on one page. This demonstrates me debugging and implementing end to end this new functionality to a beta state by reusing code we already have.

How we automated storybook documentation for our web components

Bryan Ollendyke — Thu, 25 Aug 2022 14:59:33 +0000

We recently updated our storybook in a few dramatic ways that I wanted to share the process we used to improve them.

I audited what we were communicating and removed dead leaves
I added things we were missing
I revamped our docs to include a simple way to supply developer shortcuts to get started with our elements
I added in custom-elements.json details for advanced devs

Here's what it looks like if you didn't navigate to the vercel driven storybook.

How we handle stories

Most of how we've automated storybook stories can be attributed to:

My coworker Nikki is an Evil Genius and syphons off the class properties to generate knobs automatically!
custom-elements.json is auto built by our tooling using the web-component-analyzer package with it's wca command
Our elements almost all have static get tag() for the name of the element and export their class to make it easier to build out
We wire many elements to our HAXSchema that supplies custom demo content

Here's an example of how our RPG character page works as it's a typical implementation.

import { withKnobs } from "@open-wc/demoing-storybook";
import { StorybookUtilities } from "@lrnwebcomponents/storybook-utilities/storybook-utilities.js";
import { RpgCharacter } from "./rpg-character.js";

export default {
  title: "System|RPG Character",
  component: "rpg-character",
  decorators: [withKnobs],
  parameters: {
    options: { selectedPanel: "storybookjs/knobs/panel" },
  },
};
const utils = new StorybookUtilities();
export const RpgCharacterStory = () =>
  utils.makeUsageDocs(
    RpgCharacter,
    import.meta.url,
    utils.makeElementFromHaxDemo(RpgCharacter)
  );

storybook-utilities

npm install @lrnwebcomponents/storybook-utilities
NPM page

The makeElementFromHaxDemo can also be swapped out for makeElementFromClass to be used more broadly in any web component storybook!

utils.makeElementFromClass(GitCorner,
      {
        source: 'https://github.com/elmsln/lrnwebcomponents',
        alt: "Our monorepo of all the things you see here",
        corner: true,
        size: "large"
      })

Our pattern follows that we pass in the class for the element (it should work with any library as our Vanilla and LitElement bases both work well)

makeUsageDocs

This is where the quality stepped up a notch. By passing the template for our demo through this function, as well as import.meta.url we've got everything we need in order to build our standard doc page that includes:

how to install via npm, yarn or pnpm
how to use in your project
deep API details from custom-elements.json
links to github / npm

How we get custom-elements.json

So this probably has better ways of handling it but I went with a simple fetch relative to import.meta.url and then stored it in a localStorage variable. Why? Because Storybook didn't enjoy rendering out async. As a result, there are 2 features that sorta "show up" as you use the stories more (we get our haxProperties in a similar way if its in a remote file).

Here's what the code looks like for that specific custom-elements.json section:

    const url = new URL(path);
    let entryFile = el.tag;
    let importPath = url.pathname.replace('/elements/','@lrnwebcomponents/').replace('.stories.js','.js');
    packageName = packageName || `${importPath.split('/')[0]}/${importPath.split('/')[1]}`;
    var description = window.localStorage.getItem(`${entryFile}-description`);
    setTimeout( async () => {
      // pull from the custom-elements json file since our tooling rebuilds this
      const d = await fetch(`${url.pathname}/../custom-elements.json`.replace('/lib/','/')).then((e) => e.json()).then(async (d) => {
        let allD = '';
        if (d.tags) {
          await d.tags.forEach((item) => {
            // ignore source versions
            if (!item.path || !item.path.startsWith('./src/')) {
              allD += item.name + "\n" + (item.path ? item.path + "\n" : '') + (item.description ? item.description + "\n" : '') + "\n";
            }
          })
        }
        return allD;
      })
      window.localStorage.setItem(`${entryFile}-description`, d);
    }, 0);

Here we can see that we use import.meta.url from the rpg-character.stories.js file requesting. This gives us the path to the file that loaded the story so that we can then base the path to custom-elements.json off of that. As our tooling runs in that same directory we just take the pathname from a new URL(), go back a directory (/../) which is a hack that can be used to move out of file names (could have replaced it but meh) and target custom-elements.json from there.

After getting that file we walk through the json and use pre to print the contents that we care about. wca did all the hard work of documenting tags, descriptions, and properties; now we're just printing it out in-case people want to see that at a glance without digging into the source.

I hope this helps give you ideas on how to automate your web component monorepos!

Targeting CSS Shadow Parts via URL search params

Bryan Ollendyke — Tue, 23 Aug 2022 20:08:00 +0000

Yeah I know; your jelly you didn't think to mash those words together for great SEO. No, I assure you it's a real thing courtesy of this fun issue came as an idea from Paul Hibbits, an educator who loves Doxify / GravCMS. The idea was to be able to let users (or the developer) send links to people with parts of the UI disabled. This has a few possible use-cases:

Quick A/B test of thing vs not thing
Allow removing share links and other distractions
Allow for removing parts of the UI when embedding in an iframe

In order to achieve this, I mixed together some interesting solutions. First, we allow a URL search parameter like this welcome-page?disable-features=footer,site-menu-content. We can parse this into a string like so

const urlParams = new URLSearchParams(window.location.search);
const disableFeatures = urlParams.get("disable-features");
if (disableFeatures != null) {
  this.disableFeatures = disableFeatures;
}

This allows us to set the internal disableFeatures property in our web component based on the URL's search location. In LitElement we then reflect that attribute so that we can do CSS selectors like this haxcms-site-builder[disable-features="thing"].

Understanding *=

Reading the Moz Doc page on attribute selectors we see a *= selector which says:

Represents elements with an attribute name of attr whose value contains at least one occurrence of value within the string.

This means that if we have things,and,stuff we can match on *="and" successfully. Using this knowledge, We can create a selector like: haxcms-site-builder[disable-features*="site-menu-content"] and successfully target that URL condition.

Show me the Shadow Parts

The ::part syntax + attribute, is a relative newcomer to HTML spec. It allows for targeting parts of elements that lay within shadowRoots of other elements in order to provide specific styling.

haxcms-site-builder[disable-features*="site-menu"] .haxcms-theme-element::part(site-menu)

Combining these approaches we get a solution like so which can successfully allow (smart) users to target and disable parts of the UI via the URL parameter while safely only allowing the targeting of ones we allow.

TLDR the fun video

You got it

The full CSS selector

haxcms-site-builder[disable-features*="site-menu"] .haxcms-theme-element::part(site-menu),
haxcms-site-builder[disable-features*="page-breadcrumb"] .haxcms-theme-element::part(page-breadcrumb),
haxcms-site-builder[disable-features*="print-branch-btn"] .haxcms-theme-element::part(print-branch-btn),
haxcms-site-builder[disable-features*="rss-btn"] .haxcms-theme-element::part(rss-btn),
haxcms-site-builder[disable-features*="git-corner-btn"] .haxcms-theme-element::part(git-corner-btn),
haxcms-site-builder[disable-features*="search-btn"] .haxcms-theme-element::part(search-btn),
haxcms-site-builder[disable-features*="site-menu-content"] .haxcms-theme-element::part(site-menu-content),
haxcms-site-builder[disable-features*="footer"] .haxcms-theme-element::part(footer),
haxcms-site-builder[disable-features*="qr-code-btn"] .haxcms-theme-element::part(qr-code-btn),
haxcms-site-builder[disable-features*="right-col"] .haxcms-theme-element::part(right-col),
haxcms-site-builder[disable-features*="left-col"] .haxcms-theme-element::part(left-col)
{
  display: none !important;
}

DEV Community: Bryan Ollendyke

Web component Q&A with.. well. me.

Let's make a custom theme in hax

Get the CLI

Now the fun part

Things of note

Publishing to surge.sh

Source of that file

link-preview-card

Web component

Scope

Github Issue

Demo

Student submission

Accepted Solution

github-rpg-contributors

Web component

Scope

Github Issue

Demo

Student submission

Video discussing the process and cleaning up

Accepted Solution

HAX Student Innovation Pipeline (11)

Web Component shadow roots x design system. Constructable style sheets?

How we manage local scoping vs global scoping

So what does it look like?

Styles

DDDStyles.js

Code sample of the Array export

Individual element

Global document / html / Constructable Style Sheet

Why do any of this?

HAX

hax cli: publish on surge.sh fast!

Publish using hax cli

goals / features

limitations

Video tutorial

Learn more

Our why

Github + Stickblitz + HAX = free web publishing

Getting started

Step 1: Setup Github Pages workflow

Step 2: Use HAX to edit the site on Stackblitz

Step 3: JACKPOT - HAX time

Step 4 - HAX quick tutorial

Step 5 - Publish changes to github

CONGRATULATIONS!

Learn more about HAX

With the right tools, you can build anything

HAX

Issues / Support / Community

Writing an HTML to HAXcms site importer with Vercel

How we automated storybook documentation for our web components

How we handle stories

storybook-utilities

makeUsageDocs

How we get custom-elements.json

Targeting CSS Shadow Parts via URL search params

Understanding *=

Show me the Shadow Parts

TLDR the fun video

The full CSS selector

Publish using `hax` cli