Forem: Ben Read

Testing Web Components

Ben Read — Tue, 23 Apr 2024 00:00:00 +0000

I've been taking a deep dive into Web Components recently: building a complex application. I have really enjoyed it. However, as with any project I want to deliver something that is proven to work by means of static, unit and end-to-end tests. I've run in to some issues with existing test suites.

When I deliver a new application I want it to be as well documented as possible so that any changes to it can be made as easily as possible, and by people who don't know the codebase as well as I would.

To that end, making sure that what I hand over is reasonably tested is paramount to my own sense of professionalism. It's only this that gives me a strong sense of accomplishment because I know it stands a good chance of lasting a long time, and it'll be easy for other people with less prior knowledge to work with.

When I deliver code based on Web Components, I want to deliver on that same level of quality. I know I'm leaning on newer browser-native technologies, but they're not that new.

I was therefore very surprised to find no adequate way to provide unit tests for Web Components.

My Testing Trophy

I've decided to adopt a standardised set of tools across all of our codebases so that non-specialist developers can drop into any of them with the least amount of friction that include the following:

Static analysis via JSDoc
Unit testing via Vitest
E2E testing via Cypress
Manual testing with Storybook

Most of these tools work really well, but one definitely doesn't...

Abstractions, abstractions everywhere

I think one of the problems is that for a large proportion of people adopting Web Components, they're here after having had experience with another framework, and looking for something equivalent.

That's definitely not true in my case. I was a little annoyed at the way React forces you to think about JavaScript, and I wanted to work more closely with the browser instead of seeming to force JavaScript into a certain pattern.

Fundamentally that meant that I wanted to remove the abstractions of a framework.

There have been well meaning attempts to make a framework out of Web Components. And I see why: If you're used to a framework, which a lot of people will be saying "here's another framework, but for Web Components".

The good thing about those frameworks is that they try to make something look a little more familiar, even when it's not. I looked at Lit Element extensively, and it definitely feels more like Vue. And they've got their ecosystem of tools and testing libraries and tutorials, which certainly helps adoption.

Again, though, that's not what I'm after.

I am a little freaked out going back to classes instead of purely functional components like in React. However there are benefits; understanding inheritance much clearer when you're writing something like

class MyComponent extends HTMLElement {}

There are other pros and cons, but I want to focus on the subject at hand.

Cypress: A Hidden Option

Ok well, not really hidden, but I did not realise I had to manually turn on a setting to enable Cypress to recognise the shadow DOM:

// in cypress.config.js

const config = defineConfig({
  // ...other config
  e2e: {
    includeShadowDom: true,
  },
});

Now I can write tests that include shadow dom selectors:

describe("template spec", () => {
  beforeEach(() => {
    cy.visit("http://localhost:5173");
  });
  it("should play", () => {
    cy.get("media-player#my-player")
      .shadow()
      .find('media-control-bar')
      .find("media-play-button").
      click();
    cy.get("media-player#my-player")
      .should("have.attr", "mediaplaying", "true");
  });
});

Great! Annoying if you don't know about it, but works fine once you do.

Storybook: Works fine

I've found Storybook particularly useful for manually testing that each argument I pass to the component works properly. And since Storybook re-renders the component when you change an input, you can see the player reacting to the arguments you pass it.

It is quite verbose. I have to pass my arguments around several times, but it does a good job once you've got those in:


// basic setup
export default {
  title: 'Media Embeds',
  // these allow controls to render for the arguments
  // here's the first time I'm declaring them
  argTypes: {
    videourl: { 
      control: 'text',
    },
    posterurl: {
      control: 'text',
    },
  }
};

// I found arguments needed to be destructured and
// passed explicitly into my component
// That's 2 and 3
const Template = ({
  videourl,
  posterurl
}) => `
  <media-player 
    videourl="${videourl}"
    posterurl="${posterurl}"
  ></media-player>
`;

export const Player = Template.bind({});

// Now actually declaring defaults for those arguments, 5th time

/**
 * @type {UserOptions}
 */
Player.args = {
  videourl: 'https://stream.mux.com/A3VXy02VoUinw01pwyomEO3bHnG4P32xzV7u1j1FSzjNg/high.mp4',
  posterurl: 'https://image.mux.com/A3VXy02VoUinw01pwyomEO3bHnG4P32xzV7u1j1FSzjNg/thumbnail.jpg',
}

There could be a way to reduce this, hopefully I'll be able to investigate before I hand the project over.

Vitest .. you're on your own

I shouldn't really say this is a Vitest problem. It would be the same if you were using Jest or anything else.

The problem really lies with DOM mocking libraries. None of them allow you to extend the HTML Element.

I have found a library of helpers that got me way further than I had with anything else.

Ficus is billed as a lightweight abstraction of Web Components. There's that word again. But they do have a range of other tools that have been helpful: paticularly a wrapper around JSDom that includes favourable setup for Web Components.

import { describe, it, beforeEach, expect } from 'vitest';
import { init } from '@ficusjs/testing'

import '../src/app.js';

describe("<media-player> ", () => {
  beforeEach(() => {
    init();
  });
  it("should render", async () => {
    document.body.innerHTML = '<media-player></media-player>';
    expect(document.querySelector('media-player')).to.exist;
  });
});

This still meant I have to mock a whole bunch of stuff to even get it to render. And this is as far as I have got. Not even the venerable, cross-framework testing-library covers the Shadow Dom.

I do have a lot of stuff I can unit test with Vitest. But there's so much more I want to do with it.

If you know anything that might help, please let me know.

I've also created a GitHub repo with examples if you're coming across this and are looking for resources for testing Web Components:

https://github.com/endymion1818/example-web-component-test-suite

Conclusion

More than anything, it's been a liberating, fun experience to see how far the web has come in the last few years. I hope I get to work with Web Components for a long time to come.

And I hope more developers can start using them too.

Thanks for reading this article via RSS. Let me know what you think by sending me an email.

Using Aria States To Toggle Tailwind Classes

Ben Read — Mon, 04 Mar 2024 11:13:35 +0000

I maintain an internal UI library for a number of large sites. It's got a number of JavaScript interactions for menus, search buttons and similar.

In my first iteration of the project I used event handlers to add and remove classes directly in the code base, like this:

desktopSearchButton?.addEventListener("click", event => {
        // Show the search box
        desktopWrapper?.classList.toggle("hidden");

        // Add active state to button
        let button = event.target.closest("button");
        button?.classList.toggle("bg-blue-800");
        button?.classList.toggle("rounded-tr-none");
        button?.classList.toggle("rounded-br-none");

        if (!desktopWrapper?.classList.contains("hidden")) {
                desktopWrapper?.querySelector("input[type=search]")?.focus();
        }
});

Apart from being verbose this is quite fragile code. I'm looking for a style class and initializing an interactive state that is fixed inside the JS.

This means if the style of the button changed, I would also have to change the JS. Also it could break the JavaScript if you weren't very careful.

Second iteration

I started to refactor the code to instead use data attributes:

desktopSearchButton?.addEventListener("click", event => {
        // Show the search box
        if(desktopWrapper) {
                desktopWrapper.dataset.open = desktopWrapper.dataset.open === "true" ? "false" : "true";
        }

        // Add active state to button
        let button = event.target.closest("button");
        if(button) {
                button.dataset.open = button.dataset.open === "true" ? "false" : "true";
        }

        if (desktopWrapper?.dataset.open === "true") {
                desktopWrapper.querySelector("input[type=search]")?.focus();
        }
});

This is a lot more robust and easily re-useable. Now I can use Tailwind arbitrary selectors in the template to toggle the states:

<button data-open="false" class="hidden data-[open]:block" ...>

Third iteration

With this one, I really wanted to make sure that accessibility was intrinsic to the project, and not an optional extra. To that end, instead of data attributes wherever possible I used aria states to toggle the visuals.

desktopSearchButton?.addEventListener("click", event => {
        // Show the search box
        if(desktopWrapper) {
                desktopWrapper.ariaExpanded = desktopWrapper.ariaExpanded === "true" ? "false" : "true";
        }

        // Add active state to button
        let button = event.target.closest("button");
        if(button) {
                button.ariaPressed = button.ariaPressed === "true" ? "false" : "true";
        }

        if (desktopWrapper?.ariaExpanded === "false") {
                desktopWrapper.querySelector("input[type=search]")?.focus();
        }
});

<button aria-pressed="false" class="hidden aria-pressed:block" ...>

The only disadvantage here is just an inconvenience: they have to add the aria state to the DOM. And to be honest, that is a positive friction to make them more aware of how aria states work.

Also my compiler complains when I try to make left-hand assignments with optional chaining:

button?.ariapressed = "true"
// The left-hand side of an assignment expression may not be an optional property access.ts(2779)

I could escape this rule but instead opted for an if statement rather than risk making my entire codebase less type safe.

This way, any developers using my library would need to use aria states too, making it at least a bit better for all of our users.

How to scope Tailwind CSS

Ben Read — Fri, 23 Feb 2024 11:46:21 +0000

I have a React app that uses Tailwind that gets embedded into a PHP app which also uses Tailwind. For that reason, I have two different builds of Tailwind that get injected into one page.

You probably don't want to do this. But in my case it was unavoidable: the React app and the PHP app are totally separate. The React app gets injected into several different PHP projects to provide extra functionality that they don't provide, but it's also a fairly complex form that needs to fit in to the UI of my company and also look like it's part of the parent application.

Both have a compilation step that is exclusive, so I could use the parent app's Tailwind CSS for some components, but I couldn't guarantee it will always contain what I need.

Didn't work: prefixing Tailwind classes

Tailwind itself provides a useful prefix utility that you would think scopes all of it's classes for you. However it doesn't do that. It's very useful if you're using Tailwind classes as well as other classes (say for separate JavaScript functionality).

Didn't work: Removing "preflight"

Tailwind also has a sort of CSS reset which you can also leave out of your builds. Whilst this is very useful to know about, I still got leakage, plus some of my UI elements looked awful without it.

Worked: Using css layers

In my main CSS file I wrapped a CSS layer around my Tailwind imports:

@layer myapp;

@layer myapp {
  @tailwind base;
  @tailwind components;
  @tailwind utilities;
}

This worked. I was no longer seeing any styles removed in my parent application.

A few times I had to use an !important declaration to trump the reset, but that was fairly minor tradeoff and I think in the end I only used it on two classes.

<button class="!bg-sky-600 tw-m-2 !tw-p-2">

Horrible but tolerable.

Hope this is helpful to someone!

A Collection of Tailwind UI Loading States

Ben Read — Thu, 16 Nov 2023 22:48:55 +0000

I made a collection of loading states for Tailwind. It was relatively easy exercise, and I'm surprised I didn't find anything like it out there already.

You might recognise the first element from the Tailwind Docs, which demonstrates how to use the animate-pulse class to make it look like it's in the process of loading in.

Here's the CodePen:

Feel free to copy or remix this pen, I'm not precious about it and just wanted a collection I could reference for some other work I was doing.

Let's build a carousel with Tailwind and JavaScript!

Ben Read — Wed, 21 Jun 2023 10:05:32 +0000

Before building this, first we need to carefully consider whether a carousel is the best option for what we need to display. Carousels are very often not the solution you want: please check out this site for some relevant statistics.

If you have decided a carousel is best for your UI, then read on.

HTML setup

I'll start with explaining the HTML layout here. I'm using Tailwind because that is what I was using at the time, but you can use whatever CSS you like.

First, we have an opening tag:

<div id="animation-carousel" class="tw-relative tw-w-full tw-h-36 md:tw-h-96 tw-my-8" data-carousel>

A few things of note: We're going to use a lot of relative and absolute positioning here. To make sure that is scoped to this container, we're making sure the position is relative. And because each item is going to be positioned in this way, we're setting a specific height too.

Lastly, we're setting a data attribute. This is what we're going to pick up in the JavaScript. I could just as easily have used a class name.

Next, I've got the inner wrapper. This will contain the images, previous and next buttons, and indicators (the little navigation pips you sometimes see).

  <div class="tw-relative tw-overflow-hidden tw-rounded-lg tw-h-36 md:tw-h-96">

Indicators

Indicators are optional in this setup. If they're not in the DOM, we won't render them. To facilitate that, I've used a template tag so they don't render initially, rather, we can clone this template's inner HTML as many times as we need to render the pips:

 <div id="indicator-container" class="tw-absolute tw-z-30 tw-flex tw-space-x-3 tw--translate-x-1/2 tw-bottom-5 tw-left-1/2">
  <template id="carousel-indicator">
    <button type="button" class="tw-w-3 tw-h-3 tw-rounded-full tw-border tw-border-white" aria-current="false" aria-label="Slide 1" data-carousel-slide-to="0">
      <svg viewBox="0 0 100 100" class="tw-text-white" xmlns="http://www.w3.org/2000/svg">
        <circle cx="50" cy="50" r="50" fill="currentColor" stroke="white" stroke-width="3"/>
      </svg>
    </button>
  </template>
</div>

Template tags aren't rendered by the DOM tree but we can still select them with JavaScript. This is a handy feature as you'll see later. We've got a button with an SVG circle in there so we can click to select a certain slide.

Each of these has an aria label to indicate which item is focused on. I could have used a visually hidden text label.

Next come the items themselves.

Slides

By default I want each of the slides to render stacked on top of each other; this is so that if there's a problem with the JavaScript, all parts of this UI element will still be visible to the user. We'll be hiding the slides and positioning them using JavaScript later.

<div class="tw-h-36 md:tw-h-96" data-carousel-item="active">
  <img src="https://placehold.co/600x400/orange/blue" alt="..."  class="tw-absolute tw-block tw-w-full tw--translate-x-1/2 tw--translate-y-1/2 tw-top-1/2 tw-left-1/2 tw-h-36 md:tw-h-96">
  <div class="tw-absolute tw-inset-0 tw-flex">
    <blockquote class="tw-m-auto tw-z-40 tw-font-bold tw-text-4xl tw-max-w-xl tw-text-center tw-text-zinc-50">
        The
        <span class="tw-text-primary-400">more I learn</span>, the more I realise how much I don't know
        <p class="tw-mt-6 tw-text-sm tw-font-normal tw-italic">
          Albert Einstein
        </p>
    </blockquote>
  </div>
</div>
<div class="tw-hidden tw-h-36 md:tw-h-96" data-carousel-item="active">
  <img src="https://placehold.co/600x400/orange/white" alt="..." class="tw-absolute tw-block tw-w-full tw--translate-x-1/2 tw--translate-y-1/2 tw-top-1/2 tw-left-1/2 tw-h-36 md:tw-h-96">
</div>
<div class="tw-hidden tw-h-36 md:tw-h-96" data-carousel-item>
  <img src="https://placehold.co/600x400/red/white" alt="..." class="tw-absolute tw-block tw-w-full tw--translate-x-1/2 tw--translate-y-1/2 tw-top-1/2 tw-left-1/2 tw-h-36 md:tw-h-96">
</div>
</div>

As you'll notice, as well as images, each slide can contain a text caption too. I could've used a figure and figcaption element pair for this, but in my case, the image is purely decorative so I opted for a blockquote for the quotation.

We're going to be using the data-carousel-item attribute again in the JavaScript, and attach a value of active to the current slide.

Previous & Next Controls

These controls render to the left and right of the slider and allow users to cycle through the images in order or reverse order. They have icons indicating the direction they're cycling in when they're clicked and a visually hidden label to aid assistive technology users.

<button type="button" class="tw-absolute tw-top-0 tw-left-0 tw-z-30 tw-flex tw-items-center tw-justify-center tw-h-full tw-px-4 tw-cursor-pointer tw-group focus:tw-outline-none" data-carousel-prev>
    <span class="tw-inline-flex tw-items-center tw-justify-center tw-w-8 tw-h-8 tw-rounded-full sm:tw-w-10 sm:tw-h-10 tw-bg-white/30 tw-dark:bg-gray-800/30 group-hover:tw-bg-white/50 dark:group-hover:tw-bg-gray-800/60 group-focus:tw-ring-4 group-focus:tw-ring-white dark:group-focus:tw-ring-gray-800/70 group-focus:tw-outline-none tw-transition-all tw-ease-in-out">
        <svg aria-hidden="true" class="tw-w-5 tw-h-5 tw-text-zinc-400 hover:tw-text-zinc-800 sm:tw-w-6 sm:tw-h-6 tw-dark:text-gray-800 tw-transition-all tw-ease-in-out" fill="none" stroke="currentColor" viewBox="0 0 24 24" xmlns="http://www.w3.org/2000/svg"><path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M15 19l-7-7 7-7"></path></svg>
        <span class="tw-sr-only">Previous</span>
    </span>
</button>
<button type="button" class="tw-absolute tw-top-0 tw-right-0 tw-z-30 tw-flex tw-items-center tw-justify-center tw-h-full tw-px-4 tw-cursor-pointer tw-group focus:tw-outline-none" data-carousel-next>
    <span class="tw-inline-flex tw-items-center tw-justify-center tw-w-8 tw-h-8 tw-rounded-full sm:tw-w-10 sm:tw-h-10 bg-white/30 dark:tw-bg-gray-800/30 group-hover:tw-bg-white/50 dark:tw-group-hover:tw-bg-gray-800/60 group-focus:tw-ring-4 group-focus:tw-ring-white dark:tw-group-focus:tw-ring-gray-800/70 group-focus:tw-outline-none tw-transition-all tw-ease-in-out">
        <svg aria-hidden="true" class="tw-w-5 tw-h-5 tw-text-zinc-400 hover:tw-text-zinc-800 sm:tw-w-6 sm:tw-h-6 dark:tw-text-gray-800 tw-transition-all tw-ease-in-out" fill="none" stroke="currentColor" viewBox="0 0 24 24" xmlns="http://www.w3.org/2000/svg"><path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M9 5l7 7-7 7"></path></svg>
        <span class="tw-sr-only">Next</span>
    </span>
</button>

That's the HTML, now the fun part.

JavaScript

Firstly, we have to ensure that the DOM has fully loaded before trying to select our elements, so we wrap the function like this:

window.addEventListener("DOMContentLoaded", () => {
  // our code goes here
});

More about this here

Next, let's define our createCarousel function, and just return early in case of some easy to detect errors, for example, if there isn't a window object, or the selector (the HTML element we want to create a carousel with) hasn't been passed to the function:

function createCarousel(selector) {
  if (typeof window === 'undefined') {
    return;
  }
  if(!selector) {
    console.error("cannot find element to create a carousel into");
    return;
  }

Now let's pick up some HTML elements relative to the selector that we're going to need shortly:

  const carouselItems = selector.querySelectorAll('[data-carousel-item]');
  const carouselItemsArray = Array.from(carouselItems);
  const indicatorTemplate = selector.querySelector('#carousel-indicator');
  // define interval timer so we can clear it later
  let intervalInstance = null;

In this bit of code we're getting the slides themselves. But using querySelector() returns a NodeList collection instead of an Array, so I'm making it into an Array that'll be handy later on. We're also getting the indicator template, and also setting an interval, which is a timer we use to know how long we should wait before scrolling to the next slide. I want to define it here but set it as null so we can assign it and reference it in other functions.

Helper functions

Now for some helper functions:

function getActiveItem() {
    return selector.querySelector('[data-carousel-item="active"]');
  }
  function getPositionOfItem(item) {
    return carouselItemsArray.findIndex((carouselItem) => {
        return carouselItem === item;
    });
  }
  function setItemAsActive(item) {
    item.setAttribute('data-carousel-item', 'active');
    item.classList.remove('tw-hidden');
    item.classList.add('tw-block');

    // update the indicators if available
    const currentItemIndex = getPositionOfItem(item);
    const indicators = selector.querySelectorAll('[data-carousel-indicator]');
    indicators.length > 0 && Array.from(indicators).map((indicator, index) => {
      if (index === currentItemIndex) {
        indicator.setAttribute('aria-current', 'true');
        indicator.querySelector('svg').classList.add('tw-text-primary-600');
        indicator.querySelector('svg').classList.remove('tw-text-white');
      } else {
        indicator.querySelector('svg').classList.add('tw-text-white');
        indicator.setAttribute('aria-current', 'false');
        indicator.querySelector('svg').classList.remove('tw-text-primary-600');
        indicator.querySelector('svg').classList.add('tw-text-white');
      }
    });
  }
  function setItemAsInactive(item) {
    item.setAttribute('data-carousel-item', '');
    item.classList.add('tw-hidden');
    item.classList.remove('tw-block');
  }

1. `getActiveItem()` (no parameters)

At several points, we're going to need to get the currently active item. And since that changes frequently, I don't want to store it in a variable in the main function's scope since that will mean it will only be called once and hold the same value. Instead I have made a small function for this so I could more easily determine what the intent of this selector is.

2. `getPositionOfItem(item)`

As it says, this one finds the position of a slide as an index of the array we created earlier.

3. `setItemAsActive(item)`

This one is a bit more complicated but it's name should inform you of what it does. As well as making an item active, it also updates the indicators (if they exist) to identify the index of the slide.

This was tricky because you have to match the index of a slide with the correct index of the indicators, and you have to remove the active classes from other indicators too.

4. `setItemAsInactive(item)`

I could possibly have done this in the function above, but that would combine two intents into one function, which would make it harder to understand. It would also mean adding an extra parameter which complicates things somewhat. This way, both functions that set items active and inactive and, if something else needs to happen when slides change, they're easily identifiable and manageable.

That's it for the helpers, now I want to set up some actions that the carousel will perform:

Actions

Actions define either responses to user interactions or things that happen at a set interval.

function cycle() {
    intervalInstance = window.setInterval(() => {
        next();
    }, 3_000);
  }
  function pause() {
      clearInterval(intervalInstance);
  }
  function slideTo(nextItem) {
    const activeItem = getActiveItem();
    setItemAsInactive(activeItem);
    setItemAsActive(nextItem);
    pause();
    cycle();
  }
  function next() {
    let nextItem = null;
    const activeItem = getActiveItem();
    const activeItemPosition = getPositionOfItem(activeItem);
    if (activeItemPosition === carouselItems.length - 1) {
        // if it is the last item, set first item as next
        nextItem = carouselItems[0];
    } else {
        nextItem = carouselItems[activeItemPosition + 1];
    }
    slideTo(nextItem);
  }
  function prev() {
    let prevItem = null;
    const activeItem = getActiveItem();
    const activeItemPosition = getPositionOfItem(activeItem);

    if (activeItemPosition === 0) {
        prevItem = carouselItems[carouselItems.length -1];
    } else {
        prevItem = carouselItems[activeItemPosition - 1];
    }
    slideTo(prevItem);
  }

1. `cycle()` (no parameters)

Cycle sets up the interval that we defined at the start of the createCarousel function to 3 seconds and then shows the next carousel item.

2. `pause()`

Pause clears the interval so when the next slide shows we start again from 3 seconds instead of whatever was remaining in the timer. I named it pause because I thought I might allow external access to the function so that the slider can be paused. In retrospect, it doesn't do that yet so I should have changed the name to reflect what it does.

3. `slideTo(nextItem)`

Because this function takes the next item we want to set as active as a parameter, we can call this function any time the user clicks on a prev or next button, or the indicators. It uses the two helper functions to change the active item, resets the interval and then cycles the carousel.

4. `next()` (no parameters)

There's a little trick to this one which means we have to find out if we're on the last item, and if so, the next slide to show should be the first item. See how converting the NodeList into an Array came in handy?

5. `prev()` (no parameters)

This is functionally very similar to the next() function except it's only called by someone hitting the "previous" button.

Initialize carousel

I could have put this segment of code into the main closure of the createCarousel() function, but I think having it as a separate body makes it easier to see the intent of what we're doing and it's also clearer to read.

function init() {
    const activeItem = getActiveItem();

    const items = Array.from(carouselItems)
    items.map(item => {
      item.classList.add(
        'tw-absolute',
        'tw-inset-0'
      )
    });
    /**
     * if no active item is set then first position is default
    */
    if(activeItem) {
      slideTo(activeItem);
    } else {
      slideTo(0)
    }
    /**
     * Add event listeners to the buttons if they exist
     */
    const nextButton = selector.querySelector('[data-carousel-next]');
    nextButton && nextButton.addEventListener('click', () => {
      next();
    });
    const prevButton = selector.querySelector('[data-carousel-prev]');
    prevButton && prevButton.addEventListener('click', () => {
      prev();
    });
  }

Here we're leveraging the small helper and action functions we defined above to set some classes on each of the items, making sure the user sees the active item. This also covers the case that the user assigns a slide other than the first slide as the one that should initially be active. It then adds event listeners to the next and previous buttons if they exist in the DOM.

Lastly in the main body of the createCarousel() function we call these functions:

  init();
  // if we have an indicator template, create the indicators
  indicatorTemplate && createIndicators();

Like I said, this last step could've been avoided if I'd put the body of init() and createIndicators() functions in the main function, I merely thought this was better from an organizational point of view.

Create all of the Carousels

Here's the final step, which we'll do outside of our createCarousel() function but still inside the DOMContentLoaded listener:

const allCarousels = document.querySelectorAll('[data-carousel]')
allCarousels?.forEach((carouselElement) => {
    createCarousel(carouselElement);
});

Which is to find all of the DOM elements with data-carousel attributes and create a carousel for them. Now each carousel will have it's own indicators, event listeners and intervals which run independently of each other.

And also, if there are no elements found, the createCarousel function won't be called at all.

Further Improvements

Now that the basic carousel functionality is complete, what could I do to further improve the code?

I've seen a lot that I can do.

For example, there's no API. I would like to allow access to some things such as the interval timer so that the speed with which carousel items cycle can be defined on a per-use basis. I'd also like to allow access to other things such as the prev and next buttons. Perhaps analytics need to be added to these listeners in some cases. Or perhaps someone will need to pause the carousel programmatically for some reason.

There's also no transitional animation, the slides swap quickly without any visual nicety. It would be good to be able to offer a range of animations into the API.

Conclusion

Creating this carousel wasn't just a technical challenge. It was also a communication challenge: how do I build this in a way that is easy to understand for those needing to modify my code? Does it explain itself easily? Does it allow another engineer to focus on their task and not ask too many mental gymnastics of them?

This is what we must aim for when we're writing modules like this; we must be first and foremost kind to both other engineers who will come along later, and our future selves.

Full code here.

Introducing Webiny Enterprise Headless CMS+

Ben Read — Tue, 18 Oct 2022 12:41:25 +0000

We have struggled for a long time on the question of how to position Webiny as a product. From the start, it was clear that we we were building was a feature-rich product that didn't quite sit firmly in the camp of "Headless CMS", yet that is what the majority of our users focused in on.

As a result, we have doubled down on that particular marketing, building more features and explanation around the concept of Webiny as a Headless CMS. However, as I'm sure you realize, it's an extremely crowded space. And we still didn't quite fit in.

You see, Webiny isn't just one product. It's four fundamental ones:

Content management system
File storage and Management
No-code Web Page Builder
Form builder

In reality, it's actually more than even those products: Not every CMS can scale to tens of thousands of users, serve content for millions of website pages and application interfaces, and be as easily customizable as Webiny is.

We frequently hear about teams using Webiny in unique and different ways: from wealth management portals, to BitCoin exchanges, to online course providers, to customer service desks, to a no-code form builder. It's been amazing to watch different teams do all of this with Webiny and more.

Not every CMS can become all — or any — of these things.

But if we were to look at the terminology around the kind of tools on the market that have those features ... well, that's not what we want to be either.

What if you Need More Than a Headless CMS?

Products that we could compete with that are more than a CMS are varied, but the basic premise is the same: allow large, complex, multinational organizations with content creators in different locations and languages to populate their websites with products, blog posts and other information on a regular basis. This might not just involve writing content, but also creating short-lived product launch pages, gaining feedback using a web-based form, or sharing product literature with vendors and potential contractors.

Popular acronyms in this space are WCM ("Web Content Manager"), and DXP ("Digital Experience Platforms").

These systems are often very clunky, with difficult-to-navigate interfaces. Customization options are very limited, and they often require hiring specialized individuals to manage them. Not to mention the fact that they're nearly always hugely expensive SAAS platforms that exist outside the organization's perimeter.

With the features we have, it would be possible to become a competitor in this space. But Webiny is much more nimble, adaptable and on top of that, is also self-hosted.

By Any Other Name

So we stopped and asked ourselves: do tools to manage content on the web really need more acronyms? CMS is a pretty good fit, and even the "headless" part seems to be on it's way to being generally accepted.

And, we thought, if we adopt that terminology, not only would we be alienating the fact that medium and small businesses can also depend on Webiny for their content, other teams might start to get the impression that we are also a clunky system that's prohibitively expensive, not customizable, and overall difficult to use.

No, we don't want to pigeonhole ourselves like that. Yet, Webiny is more than a CMS.

An All-in-one Solution

So we're sticking with "Headless CMS" as a description of Webiny. But opening a conversation on that front can sometimes present a problem: what if the organization approaching us doesn't have the requirement of a content store. Perhaps instead theyre looking for a way to dynamically populating content from the CMS into a no-code page builder? Or Perhaps they need an advanced publishing workflow for their teams to be able to create, edit, update, approve, and publish their content?

Starting off the conversation "We're a Headless CMS" unfortunately leaves out all of the other cool features we've built, or are planning to build in the next few months.

These new features will enable organizations to build dynamic content quickly, ahead of the competition, without the involvement of technical teams past the initial setup, and do so at a fraction of the cost of other providers. And to do it at the scale that enterprise organizations require.

Yes, for those organizations who need that kind of power, Webiny is an all-in-one solution that might be able to replace several costly products that are strung together with digital duct tape, not designed to work together, and are also individually difficult to work with.

For those people, Webiny isn't just a CMS. It's a CMS Plus.

What Is Webiny Enterprise Headless CMS+?

Plus.

It's succinct, minimalistic, but covers a lot of stuff. Webiny is still a Headless CMS. But it's a Headless CMS Plus all of the other features we've talked about.

Adding the word "Plus" to the business and enterprise products opens the discussion around Webiny's other capabilities. It allows us to showcase other features whilst not detracting from the core use that many of our users see value in.

It allows us to start more conversations around the functionality of the Page Builder and Form Builder tools, tools that are going to get some pretty interesting added features in coming months.

We're really hoping that this new initiative will allows us to open more discussions with organizations looking for, not just a Headless CMS, but something that can solve a lot of the issues around producing content in their business.

If this is you, please reach out to us! We'd love to hear about the difficulties you're facing. For our Enterprise customers we provide SLA support and consultancy services tailored to help your teams to build a solution that'll be designed around your workflow and specific needs. And we can build custom SSO implementations with your IDP of choice.

If you're an agency or a smaller business, Webiny is a great fit for you! Use it as a Headless CMS with multi-tenancy built-in, and pay a reasonable cost for each user seat. And add-on optional benefits such as our advanced publishing workflow and headless pages.

Remember, Webiny is an open-source, self-hosted solution: you can use it at no cost under our MIT license today. We hope this will help you to build smaller projects and thoroughly investigate its capabilities before you make a decision.

Try a live demo today to get more background on the product.

🤔 Should I Use Gatsby or Next.js For My Next Project?

Ben Read — Wed, 05 Oct 2022 10:18:58 +0000

Developers tend to get very passionate about their tools. And rightly so: without the best tools for the job at hand, we couldn't achieve our objectives, make something awesome, or build a better world.

React is still a major player in terms of frontend development. There's currently a competition of sorts going on between the two React heavyweight frameworks Next.js and Gatsby. Which one is better? Which should you learn? Is Gatsby better, or Next.js, for building your next project?

At Webiny, we're interested in providing developers a backend Headless CMS to compliment your frontend, so it's of deep interest to us which tools are popular. Knowing which ones you're using ... even which ones you are preferring, influences our product decisions. We think about it when we talk about marketing. And we consider it when we're planning what we build into our open source CMS.

So we decided to do a bit of critical thinking about whether Next.js or Gatsby is better. We came up with these criteria to match them against. Even so, we're going to leave it up to you as to which one you're going to use!

Server Generation and Configuration

Generating React code, or any JavaScript, when an application is built, is a critical metric when it comes to frontend frameworks like Gatsby and Next.js. But we don't think it's speed that's critical. It's certainly important, but it's one of those metrics that the developers of these frameworks are acutely aware of, so they're going to make sure they keep making advancements in this area.

What's more interesting is what APIs you have access to on server generation. Does the tool make it easier or more difficult to do what you need to? That's what we're assessing here.

Whilst Next.js allows access to customize headers, page initialization, add rewrites and redirects with it's config file and custom _App.js component, Gatsby has a config file, a custom html.js document (which is similar to Next.js). It also has files to directly access the server-rendered application and the hydrated application in the browser.

Gatsby certainly has a wider variety of configuration open to developers here. But that can also be daunting or unnecessarily complex for someone who just wants to build with React but also have static generation.

Also, sometimes it's not clear what the files are for. For example, the gatsby-node.js file isn't specifically for APIs that run in the server environment (which would be using Node.js), instead, this is where the internal node transformation happens, allowing you to create dynamic pages and custom GraphQL resolvers to your application.

Admittedly, once you know that, it's great to have access to all of these APIs to customize your data. But we'll get to that a bit more later.

Documentation

Whether Gatsby or Next.js documentation is good or bad seems highly subjective. But sometimes documentation can inadvertently hide things developers need to know under generalizations or by accidentally missing things out. Sometimes an API badly explained is worse than not having it documented at all.

We all know this, which is why we looked at documentation as a marker on whether you should choose Next.js or Gatsby to build your next project.

Whilst Next.js documentation has a cleaner, focused look, Gatsby's is busier with a 3-column layout. Though sometimes that's a good thing. Developers probably won't get as lost contextually in the Gatsby docs as they might in Next.js.

We generally prefer the darker code blocks and higher contrast on the Next.js website. But it could be because we're just getting old and our eyes aren't as good as they used to be.

Next.js' strengths come out clearly in it's focused approach towards lower-level APIs such as the getStaticProps() and getServerSideProps() functions, and these are explained very well. But there are also some things that are not mentioned except succinctly in an "unsupported features" section. This can be frustrating when you find out you've built your application to use a certain feature, only to realize it's not supported in the environment you intended to deploy to.

Routing

Both frameworks take advantage of file-based routing. Next.js and Gatsby have the ability to define dynamic routes as well, but Gatsby doesn't clearly explain how this works, perhaps assuming you're only looking for this feature if you've already used Next.js.

What is great about Next.js is the ability to create API Routes. This could be really useful in a lot of situations, especially if you have a sprawling REST API endpoint and want a minimal set of data returned from it, you could massage that data down to only the content you need on your frontend. In fact, Next.js has it's own express-like server-side framework called Micro.

This turns Next.js into a truly isomorphic application, which is meant to have components server side and on the client, working in tandem to produce a single application.

On the other hand, Gatsby seems to keep these concerns clearly separated, even with their own Gatsby Functions, the emphasis is on a separate backend that communicates with the hydrated frontend application.

Do you like to mix these concerns? Or keep them separate? It depends slightly on what kind of developer you are, and what kind of project you're building, as to which you'll prefer from this point of view.

Conclusion

Gatsby and Next.js are two very different tools with unique value propositions: either low-level tools to provide fundamental APIs and free developers from unnecessary tooling, or an ecosystem full of plugins of varying quality, together with a data layer to stitch your content together.

As we said at the start, this isn't a full roundup of all of their features. Maybe what you're building needs something more specific like Astro, Nuxt or SvelteKit. We only know what we've encountered when building our starters for Next.js and Gatsby.

Oh we didn't tell you? We've built 1-click deploy starters for Webiny headless CMS.

👉 1-click starter for Next.js and Webiny Headless CMS on Vercel

👉 1-click starter for Gatsby and Webiny Headless CMS on Gatsby Cloud

Make sure you check those out. Maybe it'll help you make your mind up ... should you use Gatsby or Next.js? The choice is ultimately yours.

Alternatives to Heroku’s Free Tier

Ben Read — Sat, 27 Aug 2022 20:23:48 +0000

Heroku announced yesterday that it's extremely popular free tier plans are being phased out starting on November 28 this year (2022). It's the end of an era for a lot of people, particularly independent bloggers who have hobby sites, developers evaluating software for use at their organizations, and non-profits who host their Headless CMS backend. But is there an alternative to Heroku?

The Heroku Story

Heroku started as a platform offering hosting to exclusively Ruby-based websites. It's since expanded that option and now a host of "build packs" for other languages exist which can deploy infrastructure to Heroku in one click. This was likely the inspiration for similar "one click deploy" buttons that have been adopted by Netlify, Vercel and others.

The unique thing about the way Heroku was built is that it leveraged AWS' ability to hibernate EC2 instances. So when you deploy your infrastructure to one of the free-tier "dynos" (a dyno is an environment in which your application can run, similar to containers), after a while of inactivity the dyno would hibernate: it would turn off, or go to sleep. The effect of this was that you couldn't contact the application straight away in that state. It would take around 30 seconds for it to activate, or wake up. This was enough time for Heroku to spin up your dyno again so that it can start accepting requests.

This method did come with some complications like ephermeral file storage, meaning you couldn't store things like SQLLite databases or upload images alongside your application. But there were other Heroku services and 3rd party integrations to allow you to use databases and store images and other files.

This was a great help to many people who's main concern was with small blogs built on an open source blogging platform such as Ghost or Strapi. With Heroku you could deploy your application and build a separate, static frontend (which would be hosted on a separate service, such as Netlify or Vercel). That way, you could write an article, rebuild your static site, and afterwards allow the application to hibernate. And it would be free to use.

Alternatives to Heroku

Looking for an alternative to Heroku depends on what you were using for. Many people had used it to host backend services for small hobby apps that didn't make any money, or for proof-of-concept ideas so they could evaluate tools for their organizations to later use in production.

If this is what you're looking for, there are a plethora of services which deploy containerized applications to a managed environment and that offer free tiers with different pricing models depending on what databases persistent storage and other services you require.

Depending on what you were using, it's feasible that you could move your application stack there without too many code changes. In fact, both Fly and Render offer guides for migrating from Heroku:

But some other popular alternatives include

And there are also the following newer alternatives:

You could also get quite far by using the serverless functions that now come with (formerly) static hosting providers like Vercel, Netlify, and Gatsby Cloud. There are even complex frameworks like RedwoodJs that have been built on top of these providers.

If you were using Heroku for a Headless CMS for a static frontend, most of the open-source Headless CMS platforms offer their own cloud-based infrastructure which will avoid having to re-platform to a different CMS altogether.

There is however potentially another problem looming...

Stay in Control of your Application Stack

If Heroku can suddenly turn around and kill it's free-for-starters offering, who's to say it won't happen for these other services? Even Vercel and Netlify leverage the raw computing power of cloud providers such as AWS, Azure and Google Cloud, repackaging those services and selling them at a profitable margin.

For that reason, we think the best alternative is to embrace these foundational computing platforms, instead of standing again on the unsteady ground of a reseller.

AWS and other providers have a free tier which applies to most of its services. These are specific allowances for each of their services that you can use before you start incurring fees.

With this and similar offerings from other cloud providers like Google Cloud Platform and Microsoft Azure, you could set up an EC2 instance (similar to a virtual machine), configure it to hibernate in a similar fashion to what Heroku was doing, and move your application to it manually.

This would take a bit of work, either to SSH in and upload your application, or set up a deployment pipeline.

But there's also another opportunity here that we would like to highlight.

Embrace Serverless

If you notice, the limits on EC2 instances for containerized applications are time-based. You get a certain number of free hours in traditional "always-on" computing models. After that you need to pay for them. Even though this is quite a generous offering, you could still leave yourself with a substantial bill if you're not careful.

However, other services are based on the number of invocations. Why not take advantage of these?

Functions as a service with AWS Lambda: 1 million free requests per month
File storage You get 5GB of S3 static file storage (think images and static website hosting)
AWS' no-sql Database, DynamoDB, comes at 25GB of storage for free

The next time you need to build a proof of concept, or hobby app, you could build your solution using a combination of these and host it indefinitely. It wouldn't need special configuration to hibernate since that is it's natural state.

Why not try serverless in your next proof of concept or hobby project?

To do so, you could leverage a framework which allows you to write infrastructure-as-code, such as AWS Amplify, Serverless Stack, the Serverless framework, or Pulumi. There is a bit of an overhead to learning these tools so you will need to research which one is best for your needs.

But there's an alternative...

Webiny: Leverage the Power of Serverless

For a little over two years, we have been building Webiny. It's a Headless CMS you can use for your personal blog ... but it's not only a Headless CMS: it's a fully-featured application framework that you can use to scaffold unique applications that will have access to the existing setup we have built via plugins.

You don't need to reinvent the wheel of how to store files, or how to build a GraphQL API, or how to build an admin interface because we've already done that for you.

And what is more, you get all of that for free when you choose the DynamoDB-only option in your setup. You will eventually pay for the amount of requests, storage and database usage ... but only if you exceed the free tier on AWS.

Once your proof-of-concept has satisfied it's requirements, you can destroy your Webiny instance ... or leave it there for future tinkering!

And if you want a place to write blog articles, Webiny is built to do that out-of-the-box.

Visit our GitHub repo and give us a star today. And please let us know if you've built something with Webiny, the world's only serverless Headless CMS.

Which Headless CMS Should I Use?

Ben Read — Wed, 08 Jun 2022 12:35:11 +0000

A little while ago I was working on a POC / tender for a new CMS. As part of that process, I investigated what JavaScript CMSes there were out there. I was particularly keen on self-hosted ones because I personally prefer keeping ownership of my own data.

I wrote about my findings on my blog, however times have changed and there are even more now!

This video is an update with a few of the newer ones on the market. Hope it helps someone to evaluate and make a decision for their project!

Here's the video:

http://youtube.com/watch?v=QGVGRqjtx-o

Using Webiny Headless CMS With Our New Starter Kits for Gatsby and NextJS

Ben Read — Fri, 22 Apr 2022 13:59:46 +0000

There's a hidden cost that comes with the majority of self-hosted headless content management systems: the time you must spend initially setting up the project.

Some require you to install Docker and run its cryptic terminal commands. Others ask you to write code to set up content models. With some you have to install and manage MongoDB or SQL servers on your local machine which may keep running in the background, eating valuable resources even when you're not using your CMS.

By contrast, Webiny have always tried to make the experience of getting started with our Headless CMS as easy and quick as possible.

Now it's easier than ever, especially if you're a fan of Gatsby or NextJS, two of the most popular React site builder frameworks.

Official Gatsby Starter for Webiny Headless CMS

Gatsby revolutionised the way frontend development was done. It wasn't the first static site generator, but it was the first to bring React and JavaScript as first-class browser tools along with a unified data layer for generating pages at build time from remote data by using GraphQL schema stitching.

When you partner Gatsby with Webiny, it's an ideal combination! You can spin up a Webiny instance on your own cloud infrastructure in minutes (instead of spending hours wrangling with Docker, MongoDB or other code-specific setup), define your own models and write content in the browser, and pair it with your Gatsby site at the click of a single button.

Read the Documentation or go directly to the Gatsby code for a 1-click deploy button to Gatsby Cloud.

Official NextJS Starter for Webiny Headless CMS

NextJS has revolutionised web development because of it's flexibility. It implements the React framework, along with a custom router, server-side data fetching and other tools, but is unopinionated and allows you to form your code however you wish. For that reason, it's been the tool of choice for organisations and individuals worldwide.

Now it's even easier to get started with Webiny CMS and Next. Install Webiny on your own cloud infrastructure in minutes, which will avoid any issues with setting up MongoDB / Docker or some other tool on your machine, or writing code to generate content models.

Once you're ready, fetch the content on your NextJS site in minutes. Take a look at the documentation or view the starter for a 1-click deploy button to Vercel.

What Starter Should We Build Next?

We don't want to stop there!

Do you like the view from Vue? Do you like to keep your apps svelte with Svelte? Or perhaps it's time to put Remix into the mix.

Please tell us by tweeting to us or via our Community Slack channel what starter you would like to see next!

We hope you enjoy using these tools to get started quickly with Webiny Headless CMS. Please join our community if you get stuck, or to give us feedback you'd like to offer.

Using react-query with NextJS router

Ben Read — Wed, 26 Jan 2022 09:08:53 +0000

Tanner Lindsey's React Query is a fantastic tool which I've really enjoyed using recently. But we found a few times where we have been using it in close conjunction with multiple requests where it seemed to be returning the same dataset for different queries. Here's what was going on.

Here are the two queries I wrote:

    const data = useReactQuery(
        id,
        getData(id)
    );

    const moreData = useReactQuery(
        id,
        getMoreData(id)
    );

In this case, we were fetching data from 2 different endpoints, but when we inspected the data, it seemed to us as if we had made only one API call.

The problem was that we are using the same key for each of the queries:

    const data = useReactQuery(
        'data',
        getData(id)
    );

    const moreData = useReactQuery(
        'moreData',
        getMoreData(id)
    );

Using unique keys for each request is in fact well documented on the docs site.

Query keys and NextJS routing

I encountered a similar problem when using keys similar to the above on two different pages in a NextJS application. After the original query had been run we did a router.push() to a new page, and had another useQuery() on the next page which used the same key as the previous page.

Again the same thing happened, it seemed to us as if we had made a mistake and mixed the fetch requests around. this happened because changing a route in a hydrated NextJS application only changes the application state, not the browser URL, which would have cleared the react-query state. Ensuring that the keys were unique fixed the issue here as well.

How to test React hooks ... by not testing react hooks

Ben Read — Thu, 09 Dec 2021 10:18:09 +0000

React lifecycle methods are a pain to test. How do you know if your component mounted twice? How do you test for that? Why should you, since it's part of React's internal behaviour? Here's how we've started testing React hooks ... by not testing them at all!

Say I have my component written and it updates some messages from my API using a useEffect hook like this:

    useEffect(() => {
    if (data) {
        const messagesToUpdate = getAllMessagesToUpdate(data);
        messagesToUpdate &&
            messagesToUpdate.forEach(edge => {
                updateMessage({
                    variables: {
                        UpdateMessageInput: {
                            id: edge.node.id,
                            read: true,
                        },
                    },
                });
            });
    }
    }, [data, updateMessage]);

How do I test each permutation of this call? I would need to mock the render cycle so that I can ensure that each time useEffect is called, this message does as it's expected.

Here's an alternative. Abstract the useEffect call into its own hook, and abstract the functionality into a separate function.

// in my main component
useUpdateMessages(data, updateMessage);

// in my hook
export function useUpdateMessages(data, updateMessage) {
   useEffect(() => {
        updateMessages(data, updateMessage);
    }, [data, updateMessage]);
}

// in my standalone function
export function updateMessages(data, updateMessage) {
    if (data) {
        const messagesToUpdate = getAllMessagesToUpdate(data);
        messagesToUpdate &&
            messagesToUpdate.forEach(edge => {
                updateMessage({
                    variables: {
                        UpdateMessageInput: {
                            id: edge.node.id,
                            read: true,
                        },
                    },
                });
            });
    }
}

Now I don't need to worry about React lifecycle methods. I can test my hook if I want to, but it hardly seems worth it here. If I would, it would be easier to do so using react-hooks-testing-library

Additionally, I only need to worry about testing my standalone function, and that can be done much more easily now it's separated away from React's internal mechanism.

I like this approach a lot. Separate your code from the framework you're using. Even though there are more moving parts, it can facilitate much easier testing and a lot cleaner code.

Thanks to my colleague Stuart Nichols for this idea!

Forem: Ben Read

Testing Web Components

My Testing Trophy

Abstractions, abstractions everywhere

Cypress: A Hidden Option

Storybook: Works fine

Vitest .. you're on your own

Conclusion

Using Aria States To Toggle Tailwind Classes

Second iteration

Third iteration

How to scope Tailwind CSS

Didn't work: prefixing Tailwind classes

Didn't work: Removing "preflight"

Worked: Using css layers

A Collection of Tailwind UI Loading States

Let's build a carousel with Tailwind and JavaScript!

HTML setup

Indicators

Slides

Previous & Next Controls

JavaScript

Helper functions

1. getActiveItem() (no parameters)

2. getPositionOfItem(item)

3. setItemAsActive(item)

4. setItemAsInactive(item)

Actions

1. cycle() (no parameters)

2. pause()

3. slideTo(nextItem)

4. next() (no parameters)

5. prev() (no parameters)

Initialize carousel

Create all of the Carousels

Further Improvements

Conclusion

Introducing Webiny Enterprise Headless CMS+

What if you Need More Than a Headless CMS?

By Any Other Name

An All-in-one Solution

What Is Webiny Enterprise Headless CMS+?

🤔 Should I Use Gatsby or Next.js For My Next Project?

Server Generation and Configuration

Documentation

Routing

Conclusion

Alternatives to Heroku’s Free Tier

The Heroku Story

Alternatives to Heroku

Stay in Control of your Application Stack

Embrace Serverless

Webiny: Leverage the Power of Serverless

Which Headless CMS Should I Use?

Using Webiny Headless CMS With Our New Starter Kits for Gatsby and NextJS

Official Gatsby Starter for Webiny Headless CMS

Official NextJS Starter for Webiny Headless CMS

What Starter Should We Build Next?

Using react-query with NextJS router

Query keys and NextJS routing

How to test React hooks ... by not testing react hooks

1. `getActiveItem()` (no parameters)

2. `getPositionOfItem(item)`

3. `setItemAsActive(item)`

4. `setItemAsInactive(item)`

1. `cycle()` (no parameters)

2. `pause()`

3. `slideTo(nextItem)`

4. `next()` (no parameters)

5. `prev()` (no parameters)