DEV Community: Begin

Island Architecture with Web Components

Simon MacDonald — Thu, 18 Jul 2024 20:22:10 +0000

Island Architecture is a concept first described by Katie Sylor-Miller and later expanded upon by Jason Miller in his post. Island Architecture, as described by Jason, involves server-rendering HTML and then injecting placeholders or slots around highly dynamic regions. These regions, or "islands," are initially rendered on the server and then upgraded to interactive components on the client side.

🤔 Does that sound like any framework you know?

By breaking down a web page into smaller, independently upgradeable units, Island Architecture achieves a balance between server-side rendering (SSR) and client-side interactivity. This method is akin to progressive enhancement but with a focus on maintaining a clear separation between static and dynamic content.

Let’s use the page you are currently reading as an example.

The majority of the page is static content but we have two islands of interactivity, the header and our “made with” component. Both are server side rendered with default content on the initial page load, then they are upgraded to interactive components when their script tag loads.

Note: go ahead and turn off JavaScript in your browser. The page will continue to function.

Benefits of Using Web Components in an Island Architecture

Web components are a perfect fit for Island Architecture due to their encapsulation, reusability, and ability to function independently. Here's how they enhance the architecture:

Encapsulation and Reusability: Web components allow developers to create custom HTML elements with their own styles and behaviors. This encapsulation ensures that each component can be developed, tested, and maintained independently, aligning perfectly with the principles of Island Architecture.
Progressive Hydration: Web components facilitate progressive hydration, where interactive elements are initialized over time based on their visibility and importance. This technique improves performance by ensuring that only the essential parts of the page are interactive immediately, reducing the initial load time.
SEO and Accessibility: By serving meaningful HTML from the server, Island Architecture ensures that the essential content is accessible to search engines and assistive technologies. Web components enhance this by allowing developers to build interactive elements without compromising the underlying HTML structure.
Improved Performance: Unlike SPAs that require a complete JavaScript bundle to be loaded and parsed before rendering the page, Island Architecture loads smaller JavaScript chunks corresponding to individual components. This leads to faster load times and a better user experience, especially on mobile devices.

Modern JavaScript frameworks contain a lot of JavaScript. However, most web pages/applications fall somewhere between needing no JavaScript (for example: a docs site or blog) and sites that need a lot of JavaScript (like an interactive dashboard or social media site).

Can you imagine sending a modern JS framework over the wire just to create this page when there are only two components that require JavaScript? I checked one major framework blog page and it included 1.4 MB of JavaScript. Contrast that with the 7 kb of JavaScript used on this page.

Creating an Enhance Island

When building a web application with Enhance we default to using elements as the reusable building blocks. Our elements are server side renderable out of the box, offering incredible performance and a seamless path for progressive enhancement.

However, when you are building islands of interactivity with Enhance, components are the solution you are looking for. They offer all the same benefits of elements as they are server side renderable but they also include client side JavaScript so you can add interactivity.

import CustomElement from "@enhance/custom-element"

class MadeWith extends CustomElement {
 constructor() {
   super()
   this.getRandomItem = this.getRandomItem.bind(this)
   this.placeContainer = this.querySelector('.js-made-with-place')
   this.emojiContainer = this.querySelector('.js-made-with-emoji')
   this.swap = this.swap.bind(this)
   this.selectedVariant = null

   this.variants = [
     {
       place: 'Longmont, CO',
       emojis: [
       '&#127957;', // camping
       '&#129452;', // bison
       '&#127784;', // snow cloud
       ],
     },
     … // etc.
   ]
 }

 render({html}) {
   return html`
    Made with <span class="js-made-with-emoji">&#128150;</span>
    <span class="inline-block">in
      <span class='js-made-with-place'>California</span>
    </span>
   `
 }

 getRandomItem(array = []) {
   return array[Math.floor(Math.random() * array.length)]
 }

 async getNewVariant() {
   let selection = this.getRandomItem(this.variants)

   // avoid selecting the same variant twice in a row
   if (selection.place === this.selectedVariant?.place) {
     this.getNewVariant()
   } else {
     this.selectedVariant = selection
     return
   }
 }

 async swap() {
   await this.getNewVariant()
   this.placeContainer.innerHTML = this.selectedVariant.place
   this.emojiContainer.innerHTML = this.getRandomItem(
     this.selectedVariant.emojis
   )
 }

 connectedCallback() {
   this.interval = setInterval(this.swap, 2000)
 }

 disconnectedCallback() {
   window.cancelIterval(this.interval)
 }
}

customElements.define('made-with', MadeWith)

Wrapping Up

Using frameworks like Enhance can simplify the implementation of Island Architecture with web components. Enhance’s approach involves rendering the entire page as static HTML at request time and then selectively hydrating only the necessary components on the client side. This method ensures that the critical content is always available instantly, and interactive parts are progressively enhanced as needed.

In conclusion, combining web components with Island Architecture offers a powerful way to build modern web applications that are fast, scalable, and accessible. By focusing on rendering static content server-side and enhancing it with client-side interactivity, developers can achieve a seamless user experience without the drawbacks of traditional heavyweight JavaScript frameworks.

Component Communication in Enhance

Simon MacDonald — Thu, 18 Jul 2024 20:15:29 +0000

Enhance makes it easy to build applications composed of web components. Each component encapsulates its own UI and functionality. However, under some circumstances you may need to communicate between components to share data or react to changes elsewhere on the page. In this post, we are going to learn a few ways of achieving communication between components.

In our first example we will build a chart component that is composed of three child components (blue border): chart-options, chart-type and reactive-chart and their parent component (orange border) chart-container.

Child to Parent communication

For this type of communication, we leverage the web platform by using Events for communication from child to parent.

In our example app, when the user clicks on the "Show Labels" switch we want to toggle whether or not the labels are displayed on our chart. This means we will need to build a web component that listens to the change event from the switch, marshals up the important data and then fires a CustomEvent that the parent component will listen to.

Here’s the full code listing for you to look over then we’ll point out some of the salient features.

// app/components/chart-options.mjs
import CustomElement from '@enhance/custom-element'
export default class ChartOptions extends CustomElement {
   constructor() {
       super()
       this.optionChanged = this.optionChanged.bind(this)
   }

   connectedCallback() {
       this.addEventListener('change', this.optionChanged)
   }

   disconnectedCallback() {
       this.removeEventListener('change', this.optionChanged)
   }

   optionChanged(evt) {
       this.dispatchEvent(
           new CustomEvent("chartoption", {
             bubbles: true,
             detail: {
               attribute: evt.target.name,
               value: evt.target.checked
              },
           }),
       )
   }

   render({ html }) {
       return html`
         <slot></slot>
       `
   }
}

customElements.define("chart-options", ChartOptions);

In the web component’s constructor method on line 6 you might notice this code:

this.optionChanged = this.optionChanged.bind(this)

We do this so that when the optionsChanged event listener is invoked that this is bound to our web component instead of the default binding which would be undefined.

Next we’ll register/unregister our event listener in our connectedCallback and disconnectedCallback methods.

connectedCallback() {
  this.addEventListener('change', this.optionChanged)
}

disconnectedCallback() {
  this.removeEventListener('change', this.optionChanged)
}

This is my preference for handling event listeners. There is some discussion about whether or not this is a best practice. See Nolan Lawson, Hawk Ticehurst, and Chris Ferdinandi.

Then in our optionsChanged event handler we create a CustomEvent called chartoption which will be dispatched up the DOM to our parent component.

optionChanged(evt) {
    this.dispatchEvent(
        new CustomEvent("chartoption", {
            bubbles: true,
            detail: {
            attribute: evt.target.name,
            value: evt.target.checked
            },
        }),
    )
}

By using a CustomEvent we can differentiate our change event from other change events elsewhere on the page and customize our payload.

Note: You may be wondering why we fire a CustomEvent instead of letting the change event bubble up to our parent component. There are two very good reasons for this. The first is that we want to encapsulate the business logic into our chart-options component. Since the parent component is listening for a chartoption event changing the underlying implementation of the chart-options component can be done without disturbing the parent component. Secondly, we have another component called chart-type which would also be firing a change event and we want to be able to differentiate between the two components easily.

Finally, our render method is quite short:

render({ html }) {
    return html`
        <slot></slot>
    `
}

As we are using the HTML web components pattern. Our web component is just a wrapper around our checkbox input element. For example:

<chart-options>
    <e-input-group field-class="flex justify-content-between align-items-center">
        <fieldset>
            <label>Multiple</label>
            <e-switch>
                <input is="switch" type="checkbox" name="multiple" checked>
            </e-switch>
        </fieldset>
    </e-input-group>
</chart-options>

With all this in place we are now able to communicate state changes from child components to the parent using the native web platform but how does the parent component listen for this chartoption event?

Parent to Child communication

In the previous section our child component was firing a chartoption event. Our parent component needs to listen for this event and communicate down to the child components by setting attributes on the child component.

Once again here is the full code listing. We’ll call out the important bits next.

// app/components/chart-container.mjs
import CustomElement from '@enhance/custom-element'

export default class ChartContainer extends CustomElement {
   constructor() {
       super()
       this.updateOption = this.updateOption.bind(this)
       this.updateType = this.updateType.bind(this)
       this.chart = document.querySelector('reactive-chart')
   }

   connectedCallback() {
       this.addEventListener('chartoption', this.updateOption)
       this.addEventListener('charttype', this.updateType)
   }

   disconnectedCallback() {
       this.removeEventListener('chartoption', this.updateOption)
       this.removeEventListener('charttype', this.updateType)
   }

   updateOption(evt) {
       const { attribute, value } = evt.detail
       if (value) {
           this.chart.setAttribute(attribute, '')
       } else {
           this.chart.removeAttribute(attribute)
       }
   }

   updateType(evt) {
       const { type } = evt.detail
       this.chart.setAttribute('type', type)
   }

   render({ html }) {
       return html`
   <e-box ord="primary">
       <e-row>
           <e-col span="3">
               <h4 class="mar-t-xs">Chart Options</h4>
               <chart-options>
                   <e-input-group field-class="flex justify-content-between align-items-center" >
                       <fieldset>
                           <label>Multiple</label>
                           <e-switch>
                               <input is="switch" type="checkbox" name="multiple" checked>
                           </e-switch>

                       </fieldset>
                   </e-input-group>
                   <e-input-group field-class="flex justify-content-between align-items-center" >
                       <fieldset>
                           <label>Show Labels</label>
                           <e-switch>
                               <input is="switch" type="checkbox" checked name="show-labels" >
                           </e-switch>
                       </fieldset>
                   </e-input-group>
               </chart-options>
       </e-col>
       <e-col>
           <div>
               <reactive-chart
                   data-key="medals"
                   type="bar"
                   heading="2016 Summer Olympics Medal Table"
                   value-key="Country"
                   value-names="Gold,Silver,Bronze"
                   multiple
                   show-labels>
               </reactive-chart>
               <chart-type>
                   <e-input-group enhanced="✨">
                       <legend>Chart Type</legend>
                       <fieldset>
                           <input id="bar" type="radio" name="type" value="bar" checked>
                           <label for="bar">Bar</label>
                           <input id="column" type="radio" name="type" value="column">
                           <label for="column">Column</label>
                           <input id="area" type="radio" name="type" value="area">
                           <label for="area">Area</label>
                           <input id="line" type="radio" name="type" value="line">
                           <label for="line">Line</label>
                       </fieldset>
                   </e-input-group>
               </chart-type>
           </div>
       </e-col>
   </e-row>
   </e-box>
       `
   }
}

customElements.define("chart-container", ChartContainer);

In our connectedCallback method we are listening for two CustomEvents. The first one for chartoption is the only one we’ll be going in depth into for this example.

connectedCallback() {
    this.addEventListener('chartoption', this.updateOption)
    this.addEventListener('charttype', this.updateType)
}

When our chart-container component receives a chartoption event it calls the updateOption method:

updateOption(evt) {
    const { attribute, value } = evt.detail
    if (value) {
        this.chart.setAttribute(attribute, '')
    } else {
        this.chart.removeAttribute(attribute)
    }
}

From the event's details we can pull off the name of the attribute we need to set and whether the switch is on or off. If our value is true we set an attribute on the reactive-chart component. If our value is false, we remove the attribute.

Note: for more details on dealing with binary attributes see MDN.

With this attribute being added or removed from the reactive-chart component, it will be notified via its attributeChangedCallback. Then our chart can re-render itself based on the updated attributes.

Check out the demo and source code for this example.

Shared State or Store

For larger applications, managing state between multiple components can become complex. In such cases, using a shared state management solution can be beneficial and that’s why @enhance/store exists. Store based communication is not limited to a parent-child relation. You can share information between any components.

In our second example we’ll simplify our chart component that is still composed of three child components (blue border): chart-options, chart-type and reactive-chart. We will replace CustomEvents with a shared state so that sibling elements can communicate with each other instead of requiring a parent element to receive events and pass down attribute changes.

@enhance/store is a singleton reactive data store. The store provides an interface that allows components to subscribe to updates to the store or specific properties on the store.

For our example we will create a new file called app/browser/api.mjs. That is where we will initialize our store.

import Store from '@enhance/store'

const store = Store()

export default function API() {
   initialize()

   return {
     store,
     subscribe: store.subscribe,
     unsubscribe: store.unsubscribe
   }
}

This API interface will give components access to our store and a convenient way to subscribe/unsubscribe the changes to data in the store.

For our "position" selection box we will use the chart-options component from the previous example. Switching it from firing a CustomEvent to updating the store. The optionChanged method becomes:

optionChanged(evt) {
    this.api.store.position = evt.target.value
}

Since we are no longer sending CustomEvents the chart-container component becomes purely presentational. You can remove all of the business logic and just have a render method. For example:

// app/components/chart-container.mjs
import CustomElement from '@enhance/custom-element'

export default class ChartContainer extends CustomElement {
   render({ html }) {
       return html`
       <e-row>
       <e-col colspan="12">
           <e-box ord="primary">
               <e-row>
               <e-col>
               <chart-type>
                   <e-input-group>
                       <legend>Sort By</legend>
                       <fieldset>
                           <input id="goals" type="radio" name="type" value="goals">
                           <label for="goals">Goals</label>
                           <input id="assists" type="radio" name="type" value="assists">
                           <label for="assists">Assists</label>
                           <input id="points" type="radio" name="type" value="points" checked>
                           <label for="points">Points</label>
                       </fieldset>
                   </e-input-group>
               </chart-type>
               </e-col>
               <e-col>
               <chart-options>
                   <e-input-group field-class="flex justify-content-between align-items-center" >
                       <fieldset>
                           <select>
                               <option value="all">Position</option>
                               <option value="C">Centre</option>
                               <option value="L">Left Wing</option>
                               <option value="R">Right Wing</option>
                               <option value="D">Defence</option>
                         </select>
                       </fieldset>
                   </e-input-group>
               </chart-options>
               </e-col>
               </e-row>
               <reactive-chart
                   data-key="scorers"
                   type="points"
                   heading="2023 NHL Scoring Leaders"
                   value-key="Points"
                   value-names="Goals,Assists,Points"
                   position="all"
                   multiple
                   show-labels>
               </reactive-chart>
               </e-box>
           </e-col>
       </e-row>
       `
   }
}

customElements.define("chart-container", ChartContainer);

Now in our reactive-chart we’ll subscribe to changes in the store.

connectedCallback() {
    this.api.subscribe(this.update,['chartData', 'position', 'type'])
}

disconnectedCallback() {
    this.api.unsubscribe(this.update)
}

If the chart-options or chart-type component updates the state the update method of reactive-chart will be invoked.

update(payload) {
    if (payload.position) {
        this.setAttribute('position', payload.position)
    }
    if (payload.type) {
        this.setAttribute('type', payload.type)
    }
    if (payload.chartData) {
        // re-render chart with updated data
    }
}

Then the component takes advantage of the attributeChangedCallback to re-render itself based on the position or type filter you set.

Check out the demo and source code for this example.

Final Thoughts

By leveraging what the web platform already provides we can communicate between parent and child components by passing attributes down to the child and events up to the parent. This is enough for most web applications and we caution you not to rush into more complicated solutions. When interactions get more complex, then consider adopting a shared state solution like @enhance/store.

Introducing Enhance Image

Cole Peters — Tue, 12 Mar 2024 16:26:59 +0000

Although we in web development (and certainly those of us at Begin) do a lot of talking about the cost of JavaScript, there’s another type of content on the web that has a huge bearing on performance: images.

In fact, images are by far the largest contributor to page weight, while also being in close competition with JavaScript for the highest number of resource requests per page. Images have a significant impact on multiple aspects of performance, including Cumulative Layout Shift and Largest Contentful Paint. Furthermore, with median image payloads hovering around 1MB, images can also cost end users a lot of data and money to access (and considering that just over 1 in 5 people in the UK still use Pay As You Go — and as of 2020, 2.45 million people in Canada did, too — lowering data access requirements is decidedly not just a problem for emerging cellular markets). This makes images an obvious and important target for performance optimization.

In 2024, we’re fortunate to have more options available to us than ever to reduce the negative impacts of using images on the web. Both the Image and Picture elements now have APIs in place for implementing responsive images, which allow web developers to send the most appropriately sized or formatted image to a particular viewport or device. Using these techniques can greatly reduce the overhead of sending oversized images to a multitude of displays (and users).

Unfortunately, the APIs for implementing responsive images can be difficult to wrap your head around. While these techniques are effective, they’re not exactly a breeze to internalize — as evidenced by this (very good) ten part series of articles on responsive images. Meanwhile, preparing multiple variants (based on size, quality, and image format) of every single image on a website can be time consuming at best, and certainly designers and engineers could imagine spending their time on more enjoyable tasks.

With all this in mind, one of the first side projects I spun up for myself after joining Begin in 2022 was to investigate how we could make responsive images easier for users to author in their Enhance projects. While by no means revolutionary, the core concept was to make a configurable, standards based, single file component available to users, which would simplify the implementation of responsive images in addition to eliminating the need to generate arbitrary image variants by hand. I (and my colleagues at Begin) went through multiple iterations and proposals for this project, weighing everything from the pros, cons, and most compelling use cases of the Image and Picture elements, to different component signatures, options, and patterns for configuration.

Today, we’re excited to announce that the results of this project are now available in the form of our beta release of Enhance Image, the first in a suite of standards based UI components we’re calling Enhance UI.

Simplified authoring

Generally speaking, responsive images solve one of two problems: resolution switching and art direction. ‘Resolution switching’ refers to providing different resolutions of a given image to different viewports (for example: sending small images to mobile devices, and large images to external monitors), while ‘art direction’ refers to providing different aesthetic variants of an image to different viewports (for example: rendering a landscape crop of an image on a shorter, wider screen, and a portrait crop of an image to a taller, narrower screen).

Enhance Image is built for the former use case: providing different resolutions of the same image to different viewports.

This use case is supported primarily via two attributes of the native Image element — those being the srcset and sizes attributes. In short, the srcset attribute allows an author to declare URLs to multiple different variants of an image, each of which must have its width declared with a width descriptor (effectively the image’s width in pixels followed by the letter w). Meanwhile, the sizes attribute allows an author to specify various media conditions for the viewport and the width of the content area that the image should occupy under that condition. With this information from the sizes attribute, the browser will examine the list of images in the srcset attribute and select the image it determines to be the best available option.

Let’s review an example of how this works in practice before demonstrating what Enhance Image brings to the table.

Let’s say we’ve got a nice big hero image we want to render at the top of a web page. We have an asset for this image from our designer all ready to go in our Enhance project. But hero images can be pretty large, and we’d like to render smaller versions of this image on smaller viewports, so as not to send those users more data than needed.

Before implementing this image responsively, our code for our hero section might look something like this:

<section>
  <img
    src="/_public/hero.jpg"
    alt="Axol the axolotl galavanting through the world of Enhance"
  />
</section>

To implement this image responsively, we could have our designer carve out multiple variations of this image in different sizes, and then use the srcset and sizes attributes to provide the browser with the ability to serve the best option to a given display:

<section>
  <img
    src="/_public/hero.jpg"
    srcset="/_public/hero-large.jpg 2400w, /_public/hero-medium.jpg 1200w, /_public/hero-small.jpg 800w"
    sizes="100vw"
    alt="Axol the axolotl galavanting through the world of Enhance"
  />
</section>

A few things are going on in the example above: we’re using the srcset attribute to declare multiple variants of our image, along with a width descriptor for each; we’re leaving the src attribute in place as a fallback for browsers that may not have the srcset attribute available; and we’re setting the sizes attribute to 100vw to tell the browser that it should select an image from the options in srcset that will be best suited for filling up 100% of the current viewport’s width. Note that the browser will make this determination by factoring in not just the pixel width of the viewport and content areas, but also the display’s pixel density and zoom level, and possibly other factors such as network conditions (these factors can vary between browser vendors).

This implementation works great, but the code is admittedly not necessarily the easiest to follow. If we want to provide a larger number of variants in the srscset attribute, things can get gnarly pretty fast (both for authors writing the code and designers creating multiple variants). This is also just a single image on our site — as previously noted, most sites have many more than a single image per page, thus multiplying the amount of work required.

This is where Enhance Image comes in. First, it provides a familiar but simplified component signature — for example, the equivalent of the above code using Enhance Image would look like this:

<section>
  <enhance-image
    src="/_public/hero.jpg"
    alt="Axol the axolotl galavanting through the world of Enhance"
  ></enhance-image>
</section>

Where have our srcset and sizes attributes gone? Well, I’ve been a bit sneaky and previously specified a list of images formatted to Enhance Image’s defaults — that is, Enhance Image will make a 2400px, 1200px, and 800px wide variant available on demand for each source image it’s provided. We also default to 100vw for the sizes attribute, and it can thus be omitted. (The same is true for the native sizes attribute, but it was shown previously for clarity).

Thus, using just the default configuration, every image in your Enhance project can now be delivered responsively by swapping out the img tag for the enhance-image custom element tag.

In the above example, we don’t just deliver the generated variants of your source image in different sizes. By default, we also provide further optimizations by delivering these variants in webp format, at an 80% quality setting. And — like all other Enhance elements — Enhance Image renders its content as HTML on the server, with no client side JavaScript required.

Of course, the defaults that ship with Enhance Image won’t work for everyone — in fact, we strongly encourage you to experiment with these values, which is why we’ve made configuring Enhance Image a breeze.

Configuration options

Enhance Image’s single file component provides a simple but powerful component primitive for authors, but this is only half the story. Enhance Image itself is powered by a versatile, fully configurable, on demand image transformation service that powers the creation of your source image variants. Here, all credit goes to the brains behind this service, fellow Beginner Ryan Bethel.

Our image transformation service allows authors to request generated variants of a given image using three different configuration options, which need to be set in your project’s Preflight file:

widths (optional): The `widths` option takes an array of pixel widths, specified as unitless integers. A variant of your source image will be generated for every width specified, with a height corresponding to the source image's intrinsic aspect ratio. The default widths are 2400, 1200, and 800.
format (optional): The format option takes one of the following format strings: `webp`, `avif`, `jxl`, `jpeg`, `png`, or `gif`. Generated images will be returned in the given format. `webp` is recommended for compatibility and performance, and is the default option. [Read more about image formats on the web here.](https://developer.mozilla.org/en-US/docs/Web/Media/Formats/Image_types)
quality (optional): The quality setting takes a number between 0–100. Generated images will be returned at the quality level specified. It's best to choose a quality level that results in the smallest possible file size without significant degradation in image quality — this can vary based on the content of the images being processed, and you may need to experiment a bit to find the best setting based on your content. The quality option defaults to 80.

For each image passed to the enhance-image single file component, our image transformation service will return one generated variant per width specified in the configuration, formatted and optimized based on the format and quality settings. This saves authors from having to manually create and optimize images ahead of deployment, and allows different variants to be iteratively added or removed as your needs change over time.

Pushing performance further

One important thing to note is that, since Enhance applications don’t have a build step but are rather deployed as cloud functions, the generated variants for each image are created at the time those images are requested by a browser. Each image variant will be cached after its creation; however, you may experience a slight delay when the images are first requested, especially for large or complex images that may take longer to process.

This is why Enhance Image also ships with a cache warming script that can be run either locally or via a CI service like GitHub Actions. This script will recursively scan a directory in your project for image files, and then — based on your configuration options — will make requests for each of your image variants, effectively ‘warming’ their caches before an end user even requests them.

The cache warming script can be run like this:

npx @enhance/image warm --directory /public/images --domain https://example.org

The script takes two arguments:

--directory: The path to the directory in your project containing the images you’ll be using with Enhance Image, for which you’d like variants (and caches) generated, e.g. `/public/images`. This path **must start with `/public`**. The directory will be scanned recursively, so only the top most directory needs to be provided.
--domain: The URL of your application’s deployment, e.g. `https://example.org` or `https://image-4ab.begin.app`.

For further details, see the Enhance Image docs.

Beta available today!

We’ve spent a surprisingly long time working to bring Enhance Image to a public beta, and we’re pretty excited about the results. It’s available for you to try today — check out the docs to get started! If you have any questions, problems, or other feedback, feel free to join us on Discord or open an issue!

Possible breaking changes, however, are in our sights — primarily as concerns the method of providing configuration options, as well as the possibility of using Enhance Image with private S3 buckets (eliminating the need to track image assets in your project’s git repository). While we always aim to make changes additively rather than destructively, we’re not sure how these changes will land once we get to work on them — and it’s for this reason that we’re labelling Enhance Image as a beta release for now.

That said, we’ve been using Enhance Image (first in its alpha form, and more recently in its current beta form) on our own production domains (including this blog) for several weeks now, and we’re confident both in its abilities and its results.

We hope you enjoy using Enhance Image to more easily author responsive images!

A React Developers Guide to Writing Enhance Components

Simon MacDonald — Fri, 08 Mar 2024 18:28:23 +0000

Frequently, we are asked by React developers why patterns they have learned while writing components using JSX do not translate to writing web components. In this post, I'll try to capture some common gotchas that developers coming from React or other JavaScript view frameworks may run into when writing plain vanilla web components. Thanks to Discord user taphill for the inspiration on this post.

Why is there so much confusion?

In my opinion, it is because JSX is not HTML. Some folks may see that as controversial, but it isn't. In fact, legacy React documentation explicitly states that JSX is not HTML.

JSX is not…

HTML
A String
A templating language

JSX is…

A syntax extension to JavaScript

This explains why JSX must be compiled into vanilla JavaScript before it can run in the browser.

In the immortal words of tanaradoublechocolate, “See how this looks like something you've seen before but isn't?"

const element = <h1>{title}</h1>;

Without JSX, you would write this as:

const element = `<h1>${title}</h1>`;

The syntax changes are not significant, but they are enough to trip you up as you transition from writing React components to web components.

Let's take a look at some of the other frequent gotchas that developers are likely to encounter.

Quoting Attributes

In JSX, it is customary to provide the value of an attribute without quotes:

const image = <img src={href} alt={altText} />

This is because properties in React are passed by reference, not by value. This makes a lot of sense when you think about how React handles re-renders. The child component needs to know when the parent component has changed the value of the property.

Writing the same tag using a string template in JavaScript would look like this:

const image = `<img src="${href}" alt="${altText}" />`;

We are using a string template literal to create the tag and the ${} syntax to provide string interpolation, that is, substituting the values of href and altText into our string.

However, this doesn't address why we double quote our attributes. Even the HTML specification says these quotes are optional. Well, they are optional until they aren't. Let's look at an example.

const href = 'https://images.pexels.com/photos/45201/kitty-cat-kitten-pet-45201.jpeg'
const altText = 'white cat'
const image = `<img src="${href}" alt="${altText}" />`

This produces the HTML

<img src="https://images.pexels.com/photos/45201/kitty-cat-kitten-pet-45201.jpeg" alt="white cat" /> \

If we had omitted the double quoting of attributes, we get

<img src=https://images.pexels.com/photos/45201/kitty-cat-kitten-pet-45201.jpeg alt=white cat /> \

Nothing would break, but your HTML would be subtly wrong. The image's alt text would only be white, and there would be this dangling attribute on the image tag with the name of cat. The browser will still display the image correctly, but your alt text will be wrong.

Naming Attributes

It is well known that when you specify CSS class names in a HTML page you use the class attribute. As well, it is commonly known that when you specify CSS class names in a JSX you use the className attribute — but why is that? The answer refers back to the beginning of this post, JSX is not HTML, JSX is an extension of JavaScript and class is a reserved word in JavaScript. This necessitates that when writing JSX you use className instead, just as the JSX attribute htmlFor is used instead of the for attribute.

React recommends that you use camel cased attributes. Once again this is fine when you are writing JavaScript, but in HTML all attributes are lowercased. So when you are writing web components, it's best to default to lowercase attribute names — or use kebab or snake case if you must.

Of particular concern here is that the attributeChangedCallback function will not fire for attributes with uppercase characters (because of the aforementioned parser behavior). Therefore, attributes named with multiple words should be delimited using kebab-casing or snake_casing (or not delimited at all).

case	attribute	JS access	`attributeChangedCallback`
lower	`imagewidth`	`attrs.imagewidth`	✅
kebab	`image-width`	`attrs['image-width']`	✅
snake	`image_width`	`attrs.image_width`	✅
camel	`imageWidth`	`attrs.imageWidth`	❌

Complex Attributes

React developers are used to being able to pass objects into their components via properties. When writing HTML you are limited to using attributes — and in HTML, all attributes are strings. For example:

const person = {
  id: 'user0',
  firstName: 'Axol',
  lastName: 'Lotl'
}

const element = <User person={person} />

function User({ person }) {
  return (…);
}

Then in your User component you can access all the properties of the person object.

However, when writing web components if you wrote:

const person = {
  id: 'user0',
  firstName: 'Axol',
  lastName: 'Lotl'
}

const element = `<user-card person="${person}"></user-card>`

Then inside your user-card component the value of person would be [object Object]. This is to be expected since, once again, all attributes are strings. So, how do we go about passing objects into web components?

If the object is relatively small, you can set multiple attributes on your component:

const element = `<user-card id="${person.id}"  firstname="${person.firstName}"  lastname="${person.lastName}"></user-card>`

However, if your object is very complex, you will want to fetch your data from the component. We use the store to hold complex data when writing an Enhance web component. For example:

// app/elements/user-card.mjs
export default function UserCard({ html, state }) {
  const { attrs, store } = state
  const { id } = attrs
  const { users } = store
  const user = users[id]

  return html`… `
}

// app/pages/card.mjs
const element = `<user-card id="${id}"></user-card>`

Tip: For more information on the Store read the Enhance Docs.

Rendering Markup from Arrays

A common pattern in many apps is looping over some data to create our UI. Quite often in React apps you will see something like this:

const todoList = <ul>
  {todos.map((todo) => (
    <li key={todo.id}>{todo.text}</li>
  ))}
</ul>

When using this pattern in an Enhance app, you might automatically write the web component version of this code like this:

const todoList = `<ul>
  ${todos.map((todo) => (
    `<li key="${todo.id}">${todo.text}</li>`
  ))}
</ul>`

That works, sort of. When viewing your output in the browser, you will notice a comma between each li tag. That is because the map function returns an array. When you convert an array to a string in JavaScript, it adds that comma between each item.

In order to prevent this default behavior, we use the join method.

const todoList = `<ul>
  ${todos.map((todo) => (
    `<li key="${todo.id}">${todo.text}</li>`
  )).join('')}
</ul>`

We call the join method in the above code with the empty string. This will produce one large string that will get inserted into the DOM. If you prefer to make your HTML source pretty, you can pass the newline character to the join method. Don't forget to escape the newline character properly; it should look like join('\\n').

Conclusion

Hopefully that clears up some of the confusion when coming from React projects to writing web components — whether or not you are using the Enhance framework or not. If you are interested in learning more about Enhance:

Follow Axol, the Enhance Mascot on Mastodon…
Join the Enhance Discord and share what you've built, or ask for help.

Removing React is just weakness leaving your codebase

Simon MacDonald — Wed, 31 Jan 2024 19:44:25 +0000

Apologies to Chesty Puller for appropriating his quote, “Pain is weakness leaving the body.”

It’s 2024, and you are about to start a new project. Do you reach for React, a framework you know and love or do you look at one of the other hot new frameworks like Astro, Enhance, 11ty, SvelteKit or gasp, plain vanilla Web Components?

In this post, I will enumerate why I no longer use React and haven’t for the past two years after 7 years of thrashing about with the library.

Quick note: I started writing this post before taking off for the holidays. Well, there must have been something in the zeitgeist, as we’ve seen a spate of articles where developers are voicing their displeasure with React.

Increasingly miffed about the state of React releases by Tom MacWright
Kind of annoyed at React by Cassidy Williams
React, where are you going? By Matteo Frana
The Decline of React by Chris Ferdinandi
Concatenating text by Johan Halse

It’s not that React has been immune to criticism, as Zach Leatherman has detailed in his post A Historical Reference of React Criticism, but it sure seems like we’ve reached a tipping point.

The Shiny Object Syndrome

React has used the shiny object syndrome to its advantage.

Shiny object syndrome is the situation where people focus undue attention on an idea that is new and trendy, yet drop it in its entirety as soon as something new can take its place.

So, how is React like the shiny object syndrome? Obviously, there was a lot of hype around React when it was originally released by Meta nee Facebook, which had developers flocking to the library.

Whether on purpose or not, React took advantage of this situation by continuously delivering or promising to deliver changes to the library, with a brand new API being released every 12 to 18 months. Those new APIs and the breaking changes they introduce are the new shiny objects you can’t help but chase. You spend multiple cycles learning the new API and upgrading your application. It sure feels like you are doing something, but in reality, you are only treading water.

Just in the time that I had been coding React applications, the library went through some major changes.

2013: JSX
2014: React createElement API
2015: Class Components
2018: Functional Components
2018: Hooks
2023: React Server Components

By my reckoning, if you’ve maintained a React codebase for the past decade, you’ve re-written your application at least three times and possibly four.

Let’s take React out of the equation and imagine you had to justify to your boss that you needed to completely re-write your application every 2.5 years. You probably got approved to do the first rewrite, you might have got approval for the second rewrite but there is no way in hell you got approval for the third and fourth rewrites.

By choosing React, we’ve signed up for a lot of unplanned work. Think of the value we could have produced for our users and company if we weren’t subject to the whims of whatever the cool kids were doing over in React.

Stop signing up for breaking changes!

The Rule of Least Power

When building web applications, we should remember the rule of least power.

When designing computer systems, one is often faced with a choice between using a more or less powerful language for publishing information, for expressing constraints, or for solving some problem. This finding explores tradeoffs relating the choice of language to reusability of information. The "Rule of Least Power" suggests choosing the least powerful language suitable for a given purpose.

W3C - https://www.w3.org/2001/tag/doc/leastPower.html

When building on the web, we could take this to mean that we should start with a base of HTML for our content, add CSS for presentation where necessary, and finally sprinkle in JavaScript to add interactivity and other capabilities that HTML and CSS cannot handle. React flips this on its head by starting with JavaScript to generate the HTML content, adding JavaScript to apply the CSS presentation too, and finally adding yet more JavaScript to apply the interactivity.

This contravenes the rule of least power.

Presentation

Here’s a simple React heading component.

function MyHeading({ children }) {
  return (
      <h2>{children}</h2>
  );
}

It looks like you are writing HTML, but you are not. You’re writing JSX (JavaScript syntax extension). Fundamentally, JSX just provides syntactic sugar for the React.createElement(component, props, ...children) function. So the JSX <MyHeading>My Heading</MyHeading> code compiles to:

React.createElement(
  MyHeading,
  {},
  'My Heading'
)

While you may think you are writing HTML, you are actually adding a lot of unnecessary (and possibly unexpected) JavaScript to your application.

Styling

CSS in JS libraries are very popular in React applications as they allow you to ~~avoid learning CSS~~ take a component-based approach to styling. The original CSS in JS library was developed by Christopher Chedeau, a front-end engineer who worked on the React team at Meta.

Let’s use JSS for our example:

import React from 'react'
import {createUseStyles} from 'react-jss'

const useStyles = createUseStyles({
  myButton: {
    color: 'green',
    margin: {
      top: 5,
      right: 0,
      bottom: 0,
      left: '1rem'
    },
    '& span': {
      fontWeight: 'bold'
    }
  },
  myLabel: {
    fontStyle: 'italic'
  }
})

const Button = ({children}) => {
  const classes = useStyles()
  return (
    <button className={classes.myButton}>
      <span className={classes.myLabel}>{children}</span>
    </button>
  )
}

This is great because we’ve been able to co-locate our styles with our components, but it comes at a cost: performance.

A quick reminder of how browsers work: first, it downloads your HTML. Then, it downloads any CSS from the head tag and applies it to the DOM. Finally, it downloads, parses and executes your JavaScript code. Because you have added your CSS declarations in all of your components, your JavaScript bundle is larger than it would be for a non-CSS in JS solution. This will increase the time it takes to parse your code just because of the larger bundle size, as well as the execution time due to the additional function calls to serialize the CSS.

We are drowning in JavaScript.

Use less of it.

This is not new advice.

Who’s running React these days?

No really. Who is running React? React’s last official release (as of this writing) is 18.2.0, released on June 14th, 2022. That was 19 months ago. To me, that signals that ~~Facebook~~, er Meta, is no longer interested in pushing the library forward and instead, IMHO has ceded the leadership of React to the frameworks.

Is this a good thing? I’m not too sure. One problem with this arrangement is that Vercel is a venture-capitalist-backed startup, and they need to show a return on investment to their investors. As we’ve seen in the industry in the past year, VC funding is drying up. God forbid something happens to Vercel, but what happens to Next.js — and, to a greater extent, React — if Vercel disappears?

Additionally, there are worries about Vercel’s current stewardship of React. For instance, Next.js uses Canary versions of React because those are "considered stable for libraries." That seems quite odd to me. As well, Next.js overrides the global implementation of node fetch, which leads to problems — a decision that the Next.js team seems to be rethinking.

I’m not the only one worried about this, as the Remix team has forked React into their organization. No commits yet, but it makes you wonder.

Where do we go from here?

This post may feel pretty negative to you, and from my point of view, it was born of the frustration I’ve had dealing with React applications as a developer and an end user. Don’t even get me started on the GitHub rewrite, which doesn’t seem to be going too well.

Just so we are clear, you weren’t wrong to choose React for previous projects. It is/was a hugely popular library. Companies were hiring React developers, and you needed a job. No one here is saying you were wrong to use React to further your career.

However, here is my unsolicited advice:

If you are starting a new project today, evaluate the other options like Enhance, Astro, 11ty, SvelteKit, and vanilla Web Components.
If you are currently maintaining an existing React application, investigate how you can add web components to your project. Web components are library agnostic, so you can begin to future-proof your application. (Angular, React, Vue)
Inquire how you can use HTML and CSS to replace some of the things you do in JavaScript currently.

Conclusion

It may seem hyperbolic to say that React is a liability lurking in your codebase, but is it? You are staring down an eventual React 19.0 release, which will introduce a number of breaking changes, forcing you to rewrite your application yet again.

Why?

Is it React’s vaunted developer experience benefits? Or is it the better user experience? Nope and nope!

My suggestion is to start investigating how you can remove this weakness from your codebase. Look at ways to de-risk what will be yet another rewrite.

And then level up even further by learning web fundamentals.

The web is backward and forward compatible. Anything you learn about HTML, CSS and browser API’s will serve you well for the next 25 years, which is not something you can say about the current fashion in JavaScript libraries. By ejecting from the thrash of React and other heavy-handed frameworks and doubling down on web fundamentals, you’ll be future-proofing both your career and your codebases.

Shadow DOM: Not by Default

Simon MacDonald — Fri, 18 Aug 2023 19:53:32 +0000

Yesterday, I briefly interacted with Manuel Matuzović after reading his Mastodon post on his growing doubts over the shadow DOM in general.

After almost a year working with web components I'm starting to doubt the usefulness of style encapsulation and shadow DOM in general.

Styling and some accessibility stuff is so much easier without…

Manuel Matuzović, August 17th 2023

@matuzo That's how all of us enhance.dev folks feel. The shadow DOM is a tool that should be reached for only when needed. It shouldn't be the default when it comes to working with custom elements/web components.

Simon MacDonald, August 17th 2023

@macdonst interesting! That's the exact opposite of what e.g. the lit docs say. Do you have your or your team's thoughts on shadow don written down somewhere?

Manuel Matuzović, August 17th 2023

@matuzo let me find something or better yet this gives me the excuse to blog about thoughts that have been running through my head for a bit.

Simon MacDonald, August 17th 2023

This made me realize we haven’t done the best job of explaining why we don’t default to using the shadow DOM and how Enhance works. So let’s dig in!

Why not just use the shadow DOM from the start?

In many cases, you ain’t gonna need it (YAGNI). The light DOM has served the web well for many years, and we can get quite far with it. To enumerate some of the reasons why we don’t immediately reach for the shadow DOM, they would be:

HTML-first: To keep our page weight down, we defer adding JavaScript until it is absolutely required. For many of our custom elements, we can get by with only HTML and CSS.
Server-side Rendering: While we are excited about Declarative Shadow DOM it has yet to land in all evergreen browsers (come on FireFox). Until such time it becomes ubiquitous, we’ll stick with our approach.
Flash of Unstyled Custom Element (FOUCE): as described below, waiting for the customElements.define() method to be called before your web component is displayed can negatively affect users’ impression of your application.
Form participation: by default, elements in the shadow DOM inside a form do not inherit the default behaviors of form elements. For example, a submit button in the shadow DOM will not automatically submit your form when the Enter key is hit. There is a spec called Form Associated Custom Elements (FACE) that gives you the APIs to build web components that participate in forms. However, fixing a problem created by JavaScript by writing more JavaScript is like handing a drowning man a glass of water, IMHO.
Styling: I confess that I am CSS challenged, but the shadow DOM introduces a new way of styling components for the sake of style encapsulation. Plus, we have other (easier) ways of ensuring style encapsulation.
Accessibility: the shadow DOM introduces problems with accessibility. For more info, read this thoughtful post from Nolan Lawson.

What is Enhance?

Enhance is an HTML-first full-stack web framework that gives you everything you need to build standards-based multi-page web apps that perform and scale.

Right, but what does that mean?

It means that Enhance is a one-stop solution for building web applications. You write your application using web standards like HTML, CSS and JavaScript. Enhance allows you to server-side render (SSR) your custom elements while providing a path for them to be “enhanced” to full web components.

Okay, that sounds good, but how does it work?

Let’s show instead of tell by building a simple message component from the ground up using Enhance. Let’s create our Enhance single file component “app/elements/my-message.mjs”.

export default function MyMessage({ html, state }) {
  const { attrs } = state
  const { message = '' } = attrs

  return html`
    <h1>${message}</h1>
  `
}

This is a very simple custom element that will take the string from the attribute message and wrap it in a h1 tag. To use it in our HTML page, we’d just write:

<my-message message="Hello World"></my-message>

Which produces:

Hello World

When viewed in the browser.

Great, now we have the basis of our single file component by writing the HTML-first, but now I want to do some styling, so let’s add a style tag to our component.

export default function MyMessage({ html, state }) {
  const { attrs } = state
  const { message = '' } = attrs

  return html`
    <style>
      h1 { color: Crimson; }
    </style>
    <h1>${message}</h1>
  `
}

Refreshing our browser, we now see hello world in crimson.

Hello World

But wait, wouldn’t that style tag screw up the style of all the h1 tags on my page? Don’t we need to use the shadow DOM here to encapsulate our component styles away from the rest of the page?

Well, you could do that, and you wouldn’t be wrong, but one of the philosophies behind Enhance is to delay using the shadow DOM until you absolutely need it instead of immediately reaching for it.

Style Transforms

The way Enhance prevents your component styles from interfering with other elements on your page is by running a style transform on the server before sending your HTML to the client. In our above example, it will take the style tag:

<style>
  h1 { color: Crimson; }
</style>

And hoist it to the head of your document, where it will look like this:

<style>
  my-message h1 { color: Crimson; }
</style>

If you have more than one my-message element on your page, the style transform will also deduplicate the CSS so the directives only appear once.

This provides the added benefit of avoiding the dreaded Flash of Unstyled Custom Element (FOUCE) when dealing with web components. This way, you can avoid using the:

:not(:defined) {
  visibility: hidden;
}

trick to hide web components until they are defined by a call to customElements.define().

But this isn’t a web component?

True. I’d say what we have built so far is a server-side rendered custom element, and it doesn’t become a real web component until we enhance it (see what I did there) by calling customElements.define(). So let’s go ahead and round out our single file component by adding in some JavaScript.

export default function MyMessage({ html, state }) {
  const { attrs } = state
  const { message = '' } = attrs

  return html`
  <style>
    h1 { color: Crimson; }
  </style>
  <h1>${message}</h1>
  <script type="module">
    class MyMessage extends HTMLElement {
      constructor() {
        super()
        this.heading = this.querySelector('h1')
      }

      static get observedAttributes() {
        return [ 'message' ]
      }

      attributeChangedCallback(name, oldValue, newValue) {
        if (oldValue !== newValue) {
          if (name === 'message') {
            this.heading.textContent = newValue
          }
        }
      }
  }

  customElements.define('my-message', MyMessage)
  </script>
`
}

Ah, now we have a real web component. If you update the message attribute of the my-message tag, the component will re-render itself.

In our example, we still aren’t using the shadow DOM, and I don’t see any reason why we would need to at this point, but if you really wanted to, you could change the script tag to use the shadow DOM approach.

export default function MyMessage({ html, state }) {
  const { attrs } = state
  const { message = '' } = attrs

  return html`
    <h1>${message}</h1>
    <script type="module">
    const template = document.createElement('template')
    template.innerHTML = "<style>h1 { color: Crimson; }</style><h1></h1>"

    class MyMessage extends HTMLElement {
        constructor() {
          super();
          const shadow = this.attachShadow({ mode: 'open' });
          shadow.appendChild(template.content.cloneNode(true));
        }

        static get observedAttributes() {
          return [ 'message' ]
        }

        attributeChangedCallback(name, oldValue, newValue) {
          if (oldValue !== newValue) {
            if (name === 'message') {
              this.shadowRoot.querySelector('h1').innerText = newValue
            }
          }
        }
      }

      customElements.define('my-message', MyMessage)
    </script>
    `
}

This doesn't mean you are required to write vanilla JavaScript web components either. If you are familiar with using Fast or Lit to write web components you can include those libraries in you Enhance application. However, with the introduction of Enhance base classes for the light and shadow DOM you can get the same DX improvements where you write less boilerplate web component code while enabling the sharing of a render method between the SSR and CSR rendering.

Next Steps

If you disagree with this article, maybe try out Enhance in anger and let us know what you think.
Follow Axol, the Enhance Mascot on Mastodon…
Join the Enhance Discord and share what you’ve built, or ask for help.

Introducing Enhance Movies

Simon MacDonald — Wed, 26 Jul 2023 23:43:28 +0000

We are excited to present our non-trivial learning application, Enhance Movies, designed to highlight the exceptional web development experience you get from Enhance. Our movies app is built with Enhance and The Movie Database API. With a strong focus on simplicity, performance, progressive enhancement, and offline local development capabilities, this application is set to transform your understanding of what can be done by focusing on the web platform.

Easy-to-Understand HTML Markup

Our sample application boasts easy-to-understand HTML markup, making it accessible to developers of all levels. Whether you're a seasoned pro or just starting your web development journey, our application ensures that you can quickly grasp and extend its functionality effortlessly.

Check out the clean markup via the use of custom elements:

<movie-symbols></movie-symbols>
<movie-header></movie-header>
<movie-layout>
  <movie-feature slot="header"></movie-feature>
  <movie-sidebar slot="left-sidebar"></movie-sidebar>
  <div class="p0" slot="main">
    <movies-index-collection></movies-index-collection>
  </div>
  <movie-footer slot="footer"></movie-footer>
</movie-layout>
<script src='/_public/browser/movie-trailer-modal.mjs'></script>

Performance

Performance is the backbone of any successful web application. We understand the significance of speed and efficiency in delivering a seamless user experience. Our sample application has been meticulously crafted with performance in mind. Say goodbye to sluggish load times and lagging interactions – our application ensures snappy responses and lightning-fast performance across devices and networks.

Don’t believe us, check out our PageSpeed Insights results.

Progressively Enhanced

Building for the web means embracing the diversity of user devices and capabilities. Our application follows a progressive enhancement approach, guaranteeing a fantastic user experience regardless of the user's browser or device. Users with modern browsers will enjoy enhanced features, while those with older setups will still access the core functionality – ensuring inclusivity and wider reach for your projects.

All the functionality for this application is accomplished with HTML, CSS and just 8.6 kb of JavaScript (3.9 kb compressed). What is even more impressive is you can turn JavaScript off completely and the application still works. Go ahead give it a try!

Local Development

The world doesn't have consistent internet access everywhere, but that shouldn't limit you while developing. Our sample application is designed to work seamlessly even in offline scenarios. Developers can access cached content (I hope you like Transformers: Rise of the Beasts), perform tasks, and run searches, thanks to the power of offline functionality via API response mocking.

Experience it Yourself

We believe in the power of experience, and thus, we encourage you to try our sample application firsthand. Discover the seamless blend of easy-to-understand HTML markup, performance, progressive enhancement, and local development – all in one package.

🔗 Live Demo of Enhance Movies

With this example, we hope to demonstrate the incredible potential of web development using modern web standards — and to help you embrace the future of web development today!

Next Steps

Checkout the source code for the example app at enhance-movies.
Follow Axol, the Enhance Mascot on Mastodon..
Join the Enhance Discord and share what you’ve built, or ask for help.

Air Quality App with Enhance

Taylor Beseda — Wed, 12 Jul 2023 17:30:31 +0000

With wildfire season well upon us in North America, it’s a good idea to keep an eye on local air quality.
Let’s get some real time data from the US EPA’s AirNow program.
Even with a limited API request budget, we can get snappy results by caching and refreshing data on demand.
All with features already built into Enhance.

Try the AQI app now.

AirNow API

https://www.airnowapi.org/aq/observation/zipCode/current/?format=application/json&API_KEY=_SECRET_&zipCode=90210

That’s it, that’s the URL we’ll use to request the air quality index (AQI) for any given US zip code*.
We get back an array of one to three measurements if a weather station is found near the requested zip code.

{
  AQI: 58,
  Category: {
    Name: 'Moderate',
    Number: 2,
  },
  DateObserved: '2023-06-08 ',
  HourObserved: 10,
  LocalTimeZone: 'MST',
  ParameterName: 'O3',
  ReportingArea: 'Denver-Boulder',
  StateCode: 'CO',
}

We’ll need to keep in mind that this API limits us to 500 requests per hour, however the docs also let us know that most data points are updated once each hour.
So if our application caches its copy of that data for 15 min, we can query 125 unique zip codes each hour - probably a good start, at least until it goes viral 😉

*For simplicity, I’m sticking with US data, but international data is available.
I recommend checking out IQAir.

Databases in Enhance Apps

To cache AQI info we’ll need to stash data in a database.
And it needs to be fast!

Enhance is built on top of Architect and comes with all of Arc’s superpowers for free.
These features (database access, scheduled functions, event queues, and more) are all opt-in and don’t bloat your deployed project.

The data layer is powered by DynamoDB from AWS, so it’s incredibly quick to set and get data for a page request.
Like, <10ms fast.

The simplest way to start with database operations is to install @begin/data (this library can be used with any Arc/Enhance app, even if you deploy to your own AWS account).

Here’s a sample of usage:

import data from '@begin/data'

const table = 'pizza'

await data.set([ // save multiple pizzas at once
  {table, key: 'bbq-chkn', toppings: ['chicken', 'chz', 'bbq sauce']},
  {table, key: 'southwest', toppings: ['chilis', 'red onion', 'corn', 'chz']},
  {table, key: 'hawaiian', toppings: ['chz', 'ham', 'pineapple']},
])

const bestPizza = data.get({table, key: 'hawaiian'})

console.log(bestPizza.toppings.at(-1)) // 'pineapple'

Cache API Requests

I’ve created a simple form component that GETs the /us route with a zip query parameter.
My Enhance API function will then lookup the most recent AQI data for that zip code.
But a visitor could refresh that page several times over the course of an hour, burning through my allotted AirNow API limit.

So when the data is fetched the first time, I’ll cache the response with a time-to-live (TTL) value of 15 min - AirNow’s data rarely changes for a given location more than once in an hour.
Then, when that user refreshes or someone else requests the same zip code, I’ll check the database first and only query the API if a record doesn’t exist for that zip.

import data from '@begin/data'

const { AIRNOW_URL } = process.env
const table = 'aqi'

export async function get({ query: { zip } }) {
  if (!zip) return {} // just render the form

  const cacheKey = `zip:${zip}`

  let aqiData
  try {
    // first, check the cache
    const cached = await data.get({ table, key: cacheKey })

    if (cached?.aqiData) {
      aqiData = cached.aqiData // continue with data we have
    } else {
      // no cache, go get some data from AirNow
      const response = await fetch(AIRNOW_URL + `&zip=${zip}`)

      aqiData = await response.json()

      await data.set({ // cache the new data
        table,
        key: cacheKey,
        aqiData,
        ttl: Math.round(Date.now() / 1_000) + (60 * 15),
        // ↑ 15 minutes from now as seconds since epoch
      })
    }
  } catch (error) {
    return { status: 500 }
  }

  return { json: { aqiData } }
}

Granted this doesn’t have much error handling, but it serves as a great example of how simple my API layer is here.

Now we can present this data in our views powered by server-rendered custom elements and browser-native web components! I won’t get into the specifics of creating SVG meters (inspired by breathable.app), but here’s what I worked up:

Extended Example

In my full example I also grab a visitor’s likely zip code based on their IP address and serve that result from the index route.
Not only is the AQI data cached, but so is the zip code lookup since that service also has daily limits.

Interactive example here: https://invent-k6b.begin.app/

And the source code: https://github.com/enhance-dev/enhance-example-aqi

You can even see the range of meter values: https://invent-k6b.begin.app/test

Building a Design Portfolio with Enhance

Cole Peters — Tue, 20 Jun 2023 21:16:39 +0000

There’s a lot to be said for dogfooding, and lately I’ve been eating a ton of Enhance™ brand dog chow. Whether using it to build our ludicrously fun landing page or a quick demo of our fluid modular scales, I seem to appreciate Enhance the more I use it. (You might think it’s easy to heap this kind of praise on a product I’m partly responsible for nurturing, but like many creative folks, my standards tend to skyrocket when dealing with my own output.)

Recently, our team was discussing the idea of producing more example applications — you may have noticed Ryan’s recent authentication examples or Taylor’s test app for database providers. Meanwhile, I’ve been really excited to see what the web designers of the world will get up to once they get familiar with our framework — and with that in mind, I spent a week or so putting together an example of a design portfolio built with Enhance.

My goal with this example app was to keep the code clean and easy to follow, while also demonstrating just how straightforward it can be to create appealing, engaging interfaces with a minimal, standards based stack. That stack consists solely of:

Enhance, for authoring web pages and components
Enhance Styles (which is built into Enhance itself), to style our pages and components with parametric CSS utility classes, fluid modular scales, custom properties, and component scoped CSS rulesets

Despite this stack being focused on Enhance, it’s important to note that most of this project’s code is just HTML and CSS. Yet, when viewing it in the browser, this app feels very much like what you might expect from a more involved tech stack — except that it loads faster, is more resilient, and works without JavaScript in the browser (teehee).

In all seriousness, though, herein lies a fundamental truth: you really don’t need much beyond web standards these days to create beautiful, dynamic, engaging web content. I want to say that extra loud for all the designers and CSS focused engineers out there who I know have felt (quite understandably) shut out of a lot of JS centered web development over the past decade. It used to be that a web designer could carry out a lot of their work using just HTML and CSS. I feel like those days are coming back with a vengeance, especially with tools like Enhance helping folks take advantage of things like custom elements and cutting edge CSS techniques (along with a ton of under the hood optimizations to deployment and performance). The fact that the native web platform is just that good is also a win for folks more steeped in JS based web development, as it allows them to drop many additional frameworks that are no longer required for success.

In order to focus on these benefits and avoid introducing potentially unnecessary complexity, I introduced a few constraints to this example — primarily in the form of keeping all the content local to the project (instead of using a CMS, for example). I cut a few corners as well, such as omitting descriptive text for images (which I highly recommend you do in all real world projects) and using some duplicate images and placeholder text to pad out the example’s content.

With all that said, let’s take a walk through the example app and see what’s cooking.

You can view the portfolio example live at: https://snow-wfi.begin.app/

Welcome to the Axol Design Collective

The fictional Axol Design Collective — stylized as a.d.c — is an interdisciplinary design studio, which basically means they somehow manage to do architectural design, landscape design, typography, product design, and more. In reality, I just wanted an excuse to use a variety of rad design outputs as demo material for this website.

We’re introduced to a.d.c’s work on the homepage of this website, primarily through a series of impressive, high resolution photographs of ‘their’ work (in actuality, a bunch of images sourced from Unsplash). This introduces one of the first components I’ll provide an overview of — the Cover Image component.

The Cover Image component takes a series of images, renders them within a responsive container with a fixed aspect ratio, and then crossfades between each of those images on a loop — with each image sized to fill the container’s aspect ratio using the object-fit: cover CSS rule.

If you take a look at the code for this component, you’ll see there’s actually not much to it. It’s essentially comprised of a hardcoded list of image URLs, and a Single File Component which:

Takes our list of images and turns them into img tags with some utility classes for styling
Renders some (component scoped!) CSS rulesets to set the component’s aspect ratio, the images’ transition styles, etc.
Returns some HTML (on the server) to structure this component (including references to several Enhance Styles utility classes for the layout)
Includes a script to run in the browser to toggle each image’s opacity at a set interval, thus giving us our animation

With just these 64 lines of code, we get an engaging, customizable component to show off some beautiful photography on our homepage (or anywhere else we might want to use it).

Another win for this component: if the end user’s browser can’t load that included chunk of JavaScript (for any of a myriad of reasons that can and do happen), this component won’t break. Instead, that user will simply see the first image in the list, without the transition to other images. This is much better than the spinner (or worse, nothing at all) that you tend to get when many ‘modern’ JavaScript frameworks fail in the browser. This represents an approach called progressive enhancement — which Enhance is designed to optimize for — and which delivers a better baseline experience for all users (which can then be incrementally improved upon). We’ll see another example of this approach later in the walkthrough.

The Work page

Moving on to the Work page, we tackle a common UI design pattern — a grid of cards, in this case containing summaries of a.d.c’s case studies. This layout is composed primarily from two custom elements.

First, there’s the Case Studies component, which is a styled wrapper that applies a grid layout, with the number of columns in that layout determined by the space available to the Case Studies component itself (as opposed to the available size of the viewport). Because we’re using CSS container queries to set the number of columns, this component and its layout could be reused in a number of macro layouts, and it would still render an appropriate number of columns regardless of how much space has been made available for that component.

Second, there’s the Case Summary component, which handles rendering an individual entry in the Case Studies layout. To use the Case Summary component, we pass it a number of attributes:

an image URL and an accompanying value for the alt attribute
a title and description to display for the entry
a URL to link to when the component is clicked

With these attributes passed in, the component proceeds to render a couple of CSS rulesets for the image styling (all values of which are customizable via CSS custom properties) as well as the markup for its content. By default, this component renders the image in a 3:2 aspect ratio, at 75% opacity, and applies a transition to the scale and opacity values when the component is hovered or focused. This results in a gentle but pleasing interaction that adds depth to an otherwise static grouping of cards — all with no JS required.

Let’s dig into one of these case studies to see what’s under the hood.

Going atomic with custom elements

The first few sections of each case study page are laid out the same — a large title, a full width image, and an adaptive two column grid containing some background information about the project. This brings us to a few simpler components that are nonetheless worth a closer look.

First up: the Adaptive 2 Column Grid component. This basic component renders a single column view below a certain viewport width, and then switches to a 2 column grid above that viewport width. That width value is customizable by the user of this component, but defaults to 48em. Additionally, this component will swap the order of its two columns above the given viewport width — this was done in order to show each project’s metadata list first on mobile screens, and second on larger screens in order to provide an ideal layout for either variant.

Going even simpler, there’s the Text Container component. The only thing this component is responsible for is setting a maximum width for its contents, and applying a margin between successive paragraph elements. This gives us a nice readable line length on every child element of this component, without restricting various elements (like <p> elements) to this constraint via global element selectors.

We repeat this pattern again with the Data List and Unordered List components. These components are responsible solely for providing focused, repeatable styles to lists authored with <dl> and <ul> elements respectively.

Components like this may not look like much, but they excel at creating abstractions of layout and component styles that you can easily reuse across single or multiple projects. Just as utility classes inform a methodology for composing atomic styles in place with our content, these custom elements allow us to create highly focused ‘atomic’ components, which can themselves then be composed together. When using Enhance Single File Components to accomplish this, we gain a number of benefits:

Colocation: styles are written alongside and travel with the component itself.
Ease of updates: component styles (whether scoped rulesets or compositions of utility classes) can be changed once to update everywhere.
Appropriate abstraction: we avoid having to repeat utility class compositions in multiple places, and — conversely — the need to resort to global selectors which might require cumbersome opt outs.
Brevity: both the functionality and the required styles of the component remain compact and easy to reason about.
Containment: styles apply only to the given component and its child content.
Performance and resilience: unlike many other web component frameworks, Enhance Single File Components are rendered on the server, meaning there’s no waiting (or chances for errors) for these components to load via JavaScript.

To me, this strategy represents a beautiful evolution of the paradigm proposed by atomic CSS; you might even call components such as these ‘atomic elements’ or ‘utility elements’.

To get a sense of how this all plays out, let’s take a closer look at a case study page — for example, the page for Axolotl Commons. On lines 7–23 of this page’s code, you’ll see a few components in use: first, the aforementioned Adaptive 2 Column Grid, and inside it, a Project Data component. The Project Data component is itself another small abstraction: it applies a background color, and then wraps its children with the aforementioned Data List component. If you look back at lines 9–22 of our HTML page, you’ll see that we’re thus using the Project Data component to render an instance of the Data List component, and a nested Unordered List component inside of it.

This should give you a good idea of how seemingly simple custom elements can be composed together to form more sophisticated layouts, all with a rigorous approach to styling and paired with highly legible, declarative source code.

A very snappy image gallery

Moving further down the page for Axolotl Commons, we get to the juicy part of the case study, presented as a horizontally scrolling image gallery. This particular gallery has a few tricks up its sleeve, however — including the use of CSS Snap Points.

To create this image gallery, I dusted off a Collection Layout component I’d first stubbed out a number of months ago for this very purpose. This is another component that delivers a lot more than the brevity of its code might suggest, purely by relying on advances in the web platform itself. Specifically, it renders an overflowing flexbox layout of items with optional scroll snap properties. This allows us to render a gallery of items which, when scrolled, will stop at the closest ‘snapped’ element inside it. This UI pattern will be familiar to anyone who’s navigated through a streaming media service’s catalog.

To complete this component (have a look at the source code if you’d like to follow along), we apply some styles to ensure the images in the gallery will be rendered at an ideal size. In particular:

We cap each image’s inline size (the logical term for width) to 90% of the image gallery itself. This ensures a hint of the next image in the gallery is always visible as an affordance for users to scroll.
We also cap the images’ block size (the logical term for height) at 80% of the current viewport’s height. This ensures the image remains within the vertical bounds of the browser, and also helps to create space to keep the site’s navigation bar from colliding with the image.
Finally, we use the object-fit: contain property to ensure that each image’s intrinsic aspect ratio is preserved, thus avoiding images getting stretched when satisfying the previous two size restrictions.

This gives us a fully responsive horizontal image gallery with scroll snapping, which works with absolutely no JavaScript required.

We aren’t quite done yet, though — we still have another type of image gallery to explore.

A little light boxing

The second type of image gallery included in our portfolio example renders a grid of thumbnails, each of which can be clicked to display the full size image in a lightbox (that is, the image rendered in a modal overlay). This type of gallery can be seen on the case studies for Moji, Rome Concepts, and Curve & Counter.

To create this gallery, we start with the Image Grid component, another example of concise source code belying a depth of functionality. First, we use a couple utility classes to render a grid layout with fluid gaps. The real magic happens when we set our grid-template-columns property on the grid layout. It might be worth pulling this style apart in more detail to make things clear:

First, we use the repeat() function with the auto-fit value to create a layout composed of as many columns as will fit without overflowing our grid container.
Next, we use the minmax() function to specify the minimum and maximum permitted width of each column; this will be used to determine how many columns can fit in each row.
We define our minimum as either 20% of the component’s width, or 250px — whichever is larger — using the max() function. We do this in order to prefer a fluid value (20%), but not if that value ends up being smaller than 250px (which would make the images in the grid quite small).
Finally, we define our maximum value as 1fr, which equates to 100% of the available width (not the full width) of the component. This keeps the image grid usable if only a very small number of images are used, in which case each image would occupy an equal portion of the available space.

The result is a fully responsive grid of fluidly sized, reflowing images, created without a single media or container query.

Next, we have our Lightbox component. We use the dialog element to power much of this component, as it includes a ton of helpful accessibility measures such as focus trapping and built in screen reader support. Unfortunately, the dialog element requires client side JavaScript to operate, so we need to account for the instances where JavaScript may fail to load via another dose of progressive enhancement.

To do this, we first wrap our Lightbox content with a link to the full size image — this way, if JavaScript isn’t available, users clicking on the thumbnail will still be forwarded to the full size image. Then, we include a script on the client which, when loaded, takes over the click event for those links, and instead triggers the link’s corresponding dialog element to open, revealing the full size image as modal content instead. We also include a form with a button to close the dialog element once it’s been opened.

Finally, we use our Image Grid and Lightbox components together for the full effect — a responsive grid of image thumbnails that open full sized images in lightboxes (or as full page redirects if no JavaScript is available). Pretty neat, and built entirely with standard platform features!

Over to you!

This example app was a ton of fun to build, but it wasn’t just a self serving exercise. As mentioned earlier, I’m really excited to find out what other design minded folks are going to get up to with Enhance — and to encourage that, I invite all of you to use this project’s code however you’d like. The linked GitHub repo includes a readme with instructions on how to get started with running this app locally, as well as links to the Enhance docs so you can start exploring our framework in more detail. If you happen to make use of any code in this project, attribution is always appreciated, but is absolutely not required.

However, I do hope you’ll share whatever you make with me and the rest of the crew over on our Discord (or hit us up with any questions or input you may have)!

It’s such an exciting time to be working on the web, and the increasing pace and breadth of web standards is only making this all the more exciting. Combined with a little help from frameworks like Enhance to get potentially tricky aspects like server side rendering in place (and to provide a happy path to integrating databases and APIs), I think it’s safe to say the future is looking incredibly bright. I hope to see you there!

Authentication with Magic links

Ryan Bethel — Wed, 14 Jun 2023 13:26:29 +0000

Websites should be secure. They should also be easy to use. These requirements seem at odds with many development decisions. Magic links are a popular authentication method that uses email (or phone) links to log in directly to a site. They are a good compromise between security and ease of use for most applications. This fourth installment of the series shows how to use magic links with Enhance and discusses some of the tradeoffs.

TL;DR

All of the pieces are already in place to log in with magic links. The previous posts covered registering a new user and verifying email address or phone number by sending links or codes. All that remains is to:

Add a login form that asks for just the email or phone number to log in.
Send a unique link to that email or a code to that phone number using the same process as verification.
Once the link is clicked or the code is entered, the session is updated and the user is logged in.

Magic Link Login

One of the best features of this login is that it requires only a single input field.

After clicking on the link received by email, the server verifies the link. If it is valid, the session is updated to log the user in. They will then immediately see the following screen confirming they are authenticated.
That is it.

The code for this login handler is below. This endpoint serves the form for entering an email address with an ordinary GET request. A POST request with that email will trigger a link to be sent by email. That link will return here with a token as a query parameter which can be verified. If that token is valid, the associated account is added to the session, and the user is logged in.

// /app/api/login/magic-link.mjs
import sendLink from '../../auth-shared/send-email-link.mjs'
import db from '@begin/data'
import { getAccounts } from '../../models/accounts.mjs'

export async function get(req) {
  const token = req.query?.token
  const { problems, login, ...newSession } = req.session
  if (problems) {
    return {
      session: newSession,
      json: { problems, login }
    }
  }

  if (!token) return

  if (token){
    const verifySession = await db.get({ table: 'session', key: token })
    const {linkUsed}=verifySession
    const linkExpired = verifySession?.ttl < Date.now()
    if (!verifySession || linkUsed || linkExpired) { 
      return { location:'/login/link-expired' } 
    }

    await db.set({
      ...verifySession, 
      table: 'session', 
      key: token, 
      linkUsed: true  
    })

    let accounts, account
    try {
      accounts = await getAccounts()
      account = accounts.find(i => i.email === verifySession.email && 
        i.authConfig?.loginWith?.email)
    }
    catch (e) {
      console.log(e)
    }

    if (!account) { return {location:'/login/magic-link'} }

    const accountVerified = account?.verified?.email
    const { password: removePassword, ...sanitizedAccount } = account

    if (!accountVerified) {
      return {
        session: {
          redirectAfterAuth:verifySession?.redirectAfterAuth || '/', 
          unverified: { ...sanitizedAccount } 
        },
        location: '/verify'
      }
    }
    return {
      session: { authorized: { ...sanitizedAccount } },
      location: verifySession?.redirectAfterAuth || '/'
    }
  }

}

export async function post(req) {
  const session = req?.session
  const {email} = req.body
  const { redirectAfterAuth = '/' } = session

  if (!email){
    return {
      session: {...session, problems:{form:'No Email Address'}},
      location: '/login/magic-link'
    }
  } 

  if (email) {
    const accounts = await getAccounts()
    const account = accounts.find(a => a.email === email && 
      a.verified?.email && 
      a.authConfig?.loginWith?.email)
    if (account) { 
      await sendLink({ email, subject:'Enhance Auth Login Link',
        linkPath:'/login/magic-link', redirectAfterAuth })
    }
    return {
      location: '/login/wait-link'
    }
  } 
}

Magic code/SMS

As discussed in the previous post, SMS messages are not as secure as email addresses. For this reason, allowing users to log in with just a phone number is also less secure. There are situations where this might be a reasonable tradeoff. It may be fine, for example, as a login to a survey to ensure that each user only submits one response.
The form below is the log in by phone example.

In this case, a one-time code is sent to the phone number and a new form is presented in the browser for entering that code. After the one-time code is submitted, the user is logged in and receives the same confirmation message as in the magic link.

Email only streamlined registration

One advantage of the magic link is a more streamlined login experience. In some cases, you might want to streamline registration also. An email (or phone number) might be the only piece of information needed from the user.
There are two options for this. First is to remove everything from the registration form except for the email or phone number. Another option is to drop the registration altogether. If a new email is submitted for login, it can be registered as a new user then.

Try it out

The code for the full example can be found at github.com/enhance-dev/enhance-auth. Try out the deployed example using magic link login.

Next Step

The next post in this series will cover how to do social login. It is another popular option that can streamline logging in down to a single click.

Verify email and phone for new accounts

Ryan Bethel — Wed, 14 Jun 2023 13:15:50 +0000

Having a verified way to communicate with account owners is critical for most applications. It is the best way to recover account access if a password is lost or forgotten. In our previous authentication posts, we covered Why you should roll your own auth and Authentication for a username and password flow. This third installment of the series focuses on account verification with an email or phone number.

TL;DR

An email or phone number is given at registration.
Using SendGrid, an email is sent with a verification link.
Using Twilio, a one time code is sent as an SMS message.
The account is verified as soon as one of those links/codes is used.
At login, if the user forgets their password, they can click “forgot password”.
They will receive a password reset link to recover the account.

Now, let's deep-dive into each of these components.

Lego not Ikea

Think of this authentication series as more like Lego, less like Ikea. Ikea furniture has detailed instructions for only one outcome, Lego gives flexibility to choose the parts you want for different outcomes. Although we include both phone and email options, often, email is enough. SMS has some vulnerabilities that make it less secure than email. These are building blocks; use only what you need.

Twilio and SendGrid

Software projects require constant build versus buy decisions. This series started by making the case that you should build your own authentication rather than buy it from a third party. But here, we use SendGrid and Twilio for email and phone messages. Email deliverability is a significant challenge. The likelihood of your messages being seen by users is much higher with a reputable email service. And the only practical way to send SMS messages is to connect to the network through a third party.

Both these services have a limited free tier so you can try them more easily. Note that for Twilio this demo uses their Verify API. It is built for this purpose and it handles the logic of sending and verifying the one time codes.

Your mileage may vary. But in general, the cost and complexity of adding third party dependencies only grows with time, so it is still best to avoid them when possible.

Environment variables

Configuring the services requires five environment variables. For SendGrid, an API key is needed as well as the email address that will be used as sender for messages. Twilio has an API token and an account service ID. The SMS messages come from a Twilio verified number. The test phone number is where the SMS messages will be sent during local development. That means you can register accounts with fake phone numbers and the SMS code will all be sent to this phone number.

# /.env
SENDGRID_API_KEY=key
TRANSACTION_SEND_EMAIL=me@example.com
TWILIO_API_ACCOUNT_SID=key
TWILIO_API_TOKEN=key
SMS_TEST_PHONE=+15555551111

Local development without API keys

Local development is valuable for testing business logic and iterating quickly. This demo is written so that the code functions in local dev even with no API keys. Without them, the app will print the email validation link and SMS one time codes to the console. This makes it easier to add authentication to an app during the earliest stages of development. Then when the app is ready to be deployed, real API keys can be added.

Email verification

When a user registers with an email address, a unique verification link is sent. When the link is clicked a success message confirms that their account is verified. The database entry for that account is updated to reflect that the account has been verified.

The handler below is on the /verify route. After submitting registration, the unverified user info is added to the session and redirected here. This endpoint initiates the verification of email, phone, or both.

// /app/api/verify/index.mjs
import {sendCode} from '../../auth-shared/sms-code-verify.mjs'
import sendLink from '../../auth-shared/send-email-link.mjs'

export async function get(req){
  const session = req.session
  const { unverified, authorized, redirectAfterAuth = '/', ...restSession } = session
  let phone,email,phoneVerified,emailVerified
  if (unverified) {
    phone = unverified.phone
    email = unverified.email
    phoneVerified = unverified.verified?.phone
    emailVerified = unverified.verified?.email
    const verifyPhone = phone && !phoneVerified
    const verifyEmail = email && !emailVerified
    if (verifyEmail){
      // send verification link
      await sendLink({
        email,
        redirectAfterAuth,
        subject:'Enhance Auth Verify Email Link',
        linkPath:'/verify/email'
      })
      if (!verifyPhone){
        return {
          location: '/verify/waiting-email'
        }
      }
    }
    if (verifyPhone){
      // send SMS code
      const { smsVerify, unverified, authorized} = req.session

      const serviceSid = await sendCode({
        phone,
        friendlyName:'Enhance Auth Verify Phone'
      })

      const newSession = { ...req.session }
      newSession.smsVerify = {otp:{ serviceSid }}

      return {
        session: newSession,
        location: '/verify/phone'
      }
    }
  } else if (authorized) {
    phone = authorized.phone
    email = authorized.email
    phoneVerified = authorized.verified?.phone
    emailVerified = authorized.verified?.email
    return {
      json:{
        verifyPhone:phone && !phoneVerified,
        verifyEmail:email && !emailVerified
      }
    }
  }
}

The function below sends the verification link using the SendGrid API. It sets a reference to the token being sent with some meta data so that when the link is clicked the server can continue verifying the account. A key difference with the email link verification vs. the phone is that when the email verification link is clicked, it opens in a new browser window, and therefore starts with a new session.

// /app/auth-shared/send-email-link.mjs
import crypto from 'crypto'
import db from '@begin/data'
import sgMail from '@sendgrid/mail'

export default async function sendLink({ email, subject='', text, html, linkPath, redirectAfterAuth = '/', newRegistration = false }){
  const isLocal = process.env.ARC_ENV === 'testing'
  const requiredEnvs = process.env.TRANSACTION_SEND_EMAIL && process.env.SENDGRID_API_KEY
  const domain = process.env.DOMAIN_NAME || 'http://localhost:3333'
  const verifyToken = crypto.randomBytes(32).toString('base64')
  const link = `${domain}${linkPath}?token=${encodeURIComponent(verifyToken)}`

  const ttl = Date.now() + 60*60*1000
  await db.set({ table: 'session', key: verifyToken, verifyToken,
    email, redirectAfterAuth, newRegistration, linkUsed:false, ttl})


  // Local Development Testing Setup
  if (isLocal) {
    console.log(`${subject}: ${link}`)
  }

  if (requiredEnvs) {
    sgMail.setApiKey(process.env.SENDGRID_API_KEY)
    let toEmail = email
    if(isLocal) toEmail = process.env.TRANSACTION_SEND_EMAIL;
    const msg = {
      to: toEmail,
      from: `${process.env.TRANSACTION_SEND_EMAIL}`,
      subject,
    }

    if (text) {
      msg.text = text(link)
    } else if (html) {
      msg.html = html(link)
    } else {
      msg.text = `${subject}: ${link}`
    }

    try {
      await sgMail.send(msg)
    } catch (e) {
      console.error(e)
      console.error(e.response.body.errors)
    }
  } else {
    console.log('TRANSACTION_SEND_EMAIL and SENDGRID_API_KEY needed to send')
  }

  return verifyToken
}

Once email verification is initiated, the server redirects to the /verify/email route. The handler for that route is below. It checks the status of the verification and shows a success or waiting message.

// /app/verify/email.mjs
import db from '@begin/data'
import { getAccounts, upsertAccount } from '../../models/accounts.mjs'

/**
 * @type {import('@enhance/types').EnhanceApiFn}
 */
export async function get(req) {
  const token = req.query?.token
  const { authorized, unverified, ...newSession } = req.session

  if (token) {
    const verifySession = await db.get({ table: 'session', key: token })
    const { linkUsed } = verifySession
    const linkExpired = verifySession?.ttl < Date.now()

    if (!verifySession || linkUsed || linkExpired) return  { location: '/verify/expired' };

    await db.set({ ...verifySession, table: 'session', key: token, linkUsed: true })
    let accounts = await getAccounts()
    let account = accounts.find(acct => verifySession.email === acct.email)

    if (!account) return { location: '/login' };

    account.verified = account.verified ? {...account.verified , email:true} : {email:true}
    account = await upsertAccount({ ...account })
    return {
      session: {},
      location: '/verify/success-email'
    }

  } else if (unverified) {
    let accounts = await getAccounts()
    let account = accounts.find(acct => unverified.email === acct.email )
    const accountVerified = account.verified?.email

    if (!account) return {location: '/login'};
    if (accountVerified) {
      return {
        session: {},
        location: '/verify/success-email'
      }
    }

    const { redirectAfterAuth = '/' } = req.session

    await sendLink({ email: account.email, subject:'Enhance Auth Verify Email Link', linkPath:'/verify/email', redirectAfterAuth })

    return {
      session: {},
      location: '/verify/waiting-email'
    }

  } else if (authorized) {
    if (authorized.verified?.email===true){
      return {
        location: '/verify/success-email'
      }
    } else {
      return { location: '/verify/success-email' }
    }

  } else {
    return {
      location: '/login'
    }
  }
}

Phone verification

When an account is registered with a phone number, the unverified account info is added to the session and the browser is redirected to /verify. A one time code is sent to the phone number, and the user is then prompted to enter this code.

The function below uses the Twilio Verify API to send the one time code. Note that if you are in a local development environment and the environment variables are not present, the API is bypassed and a code is sent to the console.

// /app/auth-shared/sms-code-verify.mjs
import twilio from "twilio"
const accountSid = process.env.TWILIO_API_ACCOUNT_SID
const authToken = process.env.TWILIO_API_TOKEN
const isLocal = process.env.ARC_ENV === 'testing'
const requiredEnvs = (process.env.TWILIO_API_ACCOUNT_SID && process.env.TWILIO_API_TOKEN)

export async function sendCode({phone,friendlyName}){
  let service
  if (requiredEnvs){
    const toPhone = isLocal ? process.env.SMS_TEST_PHONE : '+1'+phone.replace('-','')
    const client = twilio(accountSid, authToken)
    service = await client.verify.v2.services.create({
      friendlyName,
    });
    await client.verify.v2.services(service.sid).verifications.create({
      to: toPhone,
      channel: 'sms',
    });

    if (!process.env.SMS_TEST_PHONE) console.log('Warning: SMS messages will be sent to phone numbers unless SMS_TEST_PHONE is set');
  } else {
    console.log('Missing required environment variables')
    if (isLocal){
      console.log('Use simulated One Time Password "123456" for testing')
      service = {sid:'simulated-testing'}
    }
  }
  return service.sid
}

export async function verifyCode({phone, serviceSid, smsCode }){
  let verification, status
  if (requiredEnvs){
    const toPhone = isLocal ? process.env.SMS_TEST_PHONE : '+1'+ phone.replace('-','')
    const client = twilio(accountSid, authToken)
    verification= await client.verify.v2
      .services(serviceSid)
      .verificationChecks.create({ to: toPhone, code: smsCode })
    status = verification.status
  } else {
    console.log('Missing required environment variables')
    if (isLocal){ status = smsCode === '123456' ? 'approved' : false }
  }
  return status
}

The following is the handler for /verify/phone. This handles the forms for entering the code and success messages once verified.

// /app/api/verify/phone.mjs
import { sendCode, verifyCode } from "../../auth-shared/sms-code-verify.mjs"
import { getAccount, upsertAccount } from "../../models/accounts.mjs"

export async function get(req) {
  const { redirectAfterAuth = '/' } = req.session
  const { smsVerify, unverified, authorized } = req.session
  const {otp } = smsVerify || {}
  const phoneVerified = authorized?.verified?.phone || unverified?.verified?.phone

  if (!authorized && !unverified) {
    return {
      location: '/login'
    }
  }
  if (phoneVerified) {
    return {
      location:'/verify/success-phone'
    }
  }
  return {
    json: { otpSent: !!(otp?.serviceSid) },
  }
}

export async function post(req) {
  const { otpCode, request } = req.body
  const { smsVerify, unverified, authorized} = req.session
  const { otp } = smsVerify || {}
  const phoneVerified = authorized?.verified?.phone || unverified?.verified?.phone
  const phone= authorized?.phone || unverified?.phone

  if (request && phone) {

    const serviceSid = await  sendCode({phone, friendlyName:'Enhance Auth Verify Phone'})
    const newSession = { ...req.session }
    newSession.smsVerify = {otp:{ serviceSid }}

    return {
      session: newSession,
      location: '/verify/phone'
    }
  }
  if (otpCode) {
    const { serviceSid } = otp

    const status = await verifyCode({phone, serviceSid, smsCode:otpCode})

    if (status === 'approved') {
      let { smsVerify, unverified, authorized, ...newSession } = req.session
      let key = authorized?.key || unverified?.key
      let account = await getAccount(key)
      let match = account?.phone === phone
      let verified = account?.verified
      if (!match) {
        return {
          session: {},
          location: '/login'
        }
      }

      if (verified) {
        account.verified.phone = true
      } else {
        account.verified = {phone:true}
      }

      if (match) {
        let result = await upsertAccount(account)
        let {password:removePassword, ...newAccount} = result

        const redirectAfterAuth = req.session.redirectAfterAuth || '/'
        return {
          session: { ...newSession, authorized:newAccount },
          location: redirectAfterAuth
        }
      }
    }
  }
  return {
    location: '/verify/phone'
  }
}

Forgot Password

With a verified account, users can recover if a password is lost or forgotten. On the login screen there is a “Forgot password” link that initiates this process. After entering their phone or email address, a link or one time code is generated.

Next steps

Now that we have a fully verified account we have the option to allow users to login directly with just their email or phone number. We will cover using these magic links in the next post. To try out this code here is an example deployed on Begin. You can register an account to try resetting your password. Note that in this deployed example accounts are automatically deleted from the database after a day. The code for the full example can be found on GitHub at https://github.com/enhance-dev/enhance-auth.

Tested: Database Providers on Lambda

Taylor Beseda — Tue, 06 Jun 2023 23:27:09 +0000

The last couple years have seen the rise of third party database providers, Database as a Service (DBaaS).
Instead of hosting your database on the same box as your primary application server, developers can use an external db host.
Often called "serverless" databases, these offerings offload the responsibility of maintaining a database appliance.

Providers also often offer useful dashboards, data browsing, branching, schema versioning, and more.

Selecting a Database

When adding a data layer to any application, choosing a database type, engine, and, now, provider is an important choice.

Database Paradigm + Speed

Probably the most important factor when choosing a database is deciding on "relational" tables like SQL or "document" storage, often called NoSQL.
But for this experiment, we'll set that aside and focus on the second most important consideration: access speed.

Specifically, we'll look at how fast the simplest queries are from a Lambda (deployed to AWS with the vanilla Node.js runtime) to various third party db vendors.

The Tests

I've created an Architect application (hosted on Begin) that's made up of several functions: one for testing each provider and one to provide a web view of embedded <iframes> with the results of each.

Each test implementation performs essentially the same query:

SELECT * FROM things

The code and more technical explanation is available on the actual test page:

Sampled Speeds

Provider	Driver	Approx. Query Time
Neon ¹	`postgres`	300ms
	`@neondatabase/serverless`	100ms
Supabase ²	`postgres`	450ms
	REST API via `fetch`	25 - 375ms
PlanetScale	`mysql2`	125ms
	`@planetscale/database`	25 - 150ms
MongoDB	`mongodb`	725ms
DynamoDB	`@architect/functions`	10ms

¹ This does not include the cold start.
The "wake" time can exceed 5s (5,000ms), but once active is 0.
Neon is in early access and is working on various (paid) ways to manage this penalty.

² Supabase's @supabase/supabase-js was not tested as it requires a build step on install (my CD environment, Lambda, doesn't have node-gyp).
I expect it would perform similarly to their REST API.

Regional Differences

The above sampling is for tests where the database provider is always in a different US region from the Lambdas that connect to them.

The only provider sharing a region with the Lambda is Dynamo since both resources will naturally be created in the same AWS region.

All providers get a significant speed boost when in the same region as your Lambda and using the "native" driver.

For example, when both Lambda and Supabase are in us-east-1, the same query with postgres takes ~50ms: 9x faster 🔥

(Limited tests were conducted in shared regions but are not demonstrated live.)

Considerations

These tests do not:

attempt to pool or keep-alive connections
snapshot results or track variance over time
test subsequent queries
use a large dataset or a variety of DB operations
thoroughly consider resource regions

Conclusions

Not surprisingly, AWS's own DynamoDB is the fastest way to query data from a Lambda-based application.
Its repeatable 10ms query latency is 2.5 times better than the closest competitor's best results.
We acknowledge that it may be intimidating to get started with a NoSQL database, and that's why we provide @begin/data as an abstraction layer on top of DynamoDB.
For folks who want to learn more about DynamoDB we recommend Alex DeBrie's The DynamoDB Book.

That said, all tested provider queries are less than half a second (except MongoDB - however, their paid tiers do reach that 500ms threshold)!

Ultimately any database is better than no database.
Don't be paralyzed or resort to throwing the kitchen sink at the problem. Pick one and get to building the initial implementation.

DEV Community: Begin

Island Architecture with Web Components

Benefits of Using Web Components in an Island Architecture

Creating an Enhance Island

Wrapping Up

Further Reading

Component Communication in Enhance

Child to Parent communication

Parent to Child communication

Shared State or Store

Final Thoughts

Introducing Enhance Image

Simplified authoring

Configuration options

Pushing performance further

Beta available today!

A React Developers Guide to Writing Enhance Components

Why is there so much confusion?

JSX is not…

JSX is…

Quoting Attributes

Naming Attributes

Complex Attributes

Rendering Markup from Arrays

Conclusion

Removing React is just weakness leaving your codebase

The Shiny Object Syndrome

The Rule of Least Power

Presentation

Styling

Who’s running React these days?

Where do we go from here?

Conclusion

Shadow DOM: Not by Default

Why not just use the shadow DOM from the start?

What is Enhance?

Right, but what does that mean?

Okay, that sounds good, but how does it work?

Hello World

Hello World

Style Transforms

But this isn’t a web component?

Next Steps

Introducing Enhance Movies

Easy-to-Understand HTML Markup

Performance

Progressively Enhanced

Local Development

Experience it Yourself

Next Steps

Air Quality App with Enhance

AirNow API

Databases in Enhance Apps

Cache API Requests

Extended Example

Building a Design Portfolio with Enhance

Welcome to the Axol Design Collective

The Work page

Going atomic with custom elements

A very snappy image gallery

A little light boxing

Over to you!

Authentication with Magic links

TL;DR

Magic Link Login

Magic code/SMS

Email only streamlined registration

Try it out

Next Step

Verify email and phone for new accounts

TL;DR

Lego not Ikea

Twilio and SendGrid

Environment variables

Local development without API keys

Email verification

Phone verification

Forgot Password

Next steps

Tested: Database Providers on Lambda