DEV Community: Simon MacDonald

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.

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.

Why you should roll your own auth

Simon MacDonald — Wed, 10 May 2023 18:28:14 +0000

Conventional wisdom states that rolling your own authentication system can be a significant undertaking that requires a lot of expertise in security and web development. In most cases, using a third-party authentication service is better than trying to build your own from scratch. However, there are some cases where rolling your own auth may be beneficial, such as:

Customization

If your authentication needs are unique or require specific customizations, rolling your own auth may be the better option. Third-party authentication services may not be able to meet your specific requirements.

Leaving your application to show a third-party dialog can be “jarring” for your users. Most third parties offer limited customization options or provide you with an API to make the authentication calls yourself. At this point the effort to build your own system may not be much different than customizing a third party solution.

Compliance

If your business operates in a highly regulated industry, you may need to comply with specific security and privacy regulations that third-party authentication services may not meet. In this case, rolling your own auth may be necessary to ensure compliance. Additionally, your application may have region specific regulations as to where the data must be hosted.

Control

By rolling your own authentication system, you have complete control over the entire authentication process, from user data storage to encryption. This can be beneficial for businesses that need complete control over their authentication systems.

Two important points about control is that owning your own auth solution:

Allows you to avoid slow API calls to third party services to retrieve user information. Slow is a relative term, but a sub 10 ms query to your cloud hosted database will beat an API call every day of the week.
Retains ownership of your user database.

Cost

Depending on your authentication needs and the volume of users, rolling your own auth may be more cost-effective than using a third-party authentication service. Third-party authentication services can be expensive, especially for large businesses with many users.

Overall, rolling your own authentication system is a viable option. Especially when you consider your own authentication requirements, compliance, control and cost issues. However, building your own auth requires specialized security and web development expertise, and the risks of building an insecure authentication system can be significant. Therefore, weighing the pros and cons carefully and seeking expert advice before deciding to roll your own auth is essential.

In other words,

Starting next week, we are embarking on a series of posts to teach you how to safely and securely implement your own authentication solution.

Username and password authentication
Confirming email addresses and phone numbers
Magic links and one-time passwords
OAuth

Next Steps

Join the Enhance Discord and share what you’ve built or ask for help.
Let us know what features you would like to see covered in our Authentication series.

Supporting Publish Own Site, Syndicate Elsewhere

Simon MacDonald — Mon, 01 May 2023 13:40:14 +0000

Our next step towards making it easier for everyone to participate in the open and indie web is the release of @enhance/arc-plugin-posse. This plugin checks your RSS feed for new content and syndicates it to whatever platforms you choose. The plugin is designed to work seamlessly with the Enhance Blog Template, but you can also deploy it as a standalone plugin for existing sites.

What is "Publish Own Site, Syndicate Elsewhere?"

Publishing on your own site and syndicating elsewhere (POSSE) is a content strategy involving creating content on your website first and then distributing it to other platforms. This approach allows you to take advantage of the traffic and visibility of different platforms while retaining control over your content and driving traffic back to your website.

What are the benefits of POSSE?

Control Over Your Content

You have complete control over your website when you publish content on it. You can choose the tone, the format, and the length of your content. You can also include links to other content on your website, which can help to drive traffic. When you syndicate your content elsewhere, you can retain this control by creating a direct ownership chain that can be traced back to you without any intervening 3rd party’s Terms of Services getting in the way.

Increased Visibility

Syndicating your content on other platforms can increase your visibility and reach a larger audience. Publishing content on high-traffic websites relevant to your niche exposes it to a new audience that may not have found it otherwise. Syndication can increase website traffic and attract new customers.

Cost-Effective

Publishing content on your own website is typically very cost-effective. All you need is a website and some basic content-creation tools. The hardest thing is creating and posting content on a regular basis. To start, consider using the Enhance Blog Template and deploying to Begin for free. Worried about the ole bait and switch on costs? Checkout our pricing guarantee. If you want a custom domain name, you can do that with Begin Domains.

Getting Started

To start syndicating your content to other sites, we need to add the plugin to an existing Enhance application. First, install the plugin from npm:

npm install @enhance/arc-plugin-posse

Then add the plugin to your application by editing your .arc file and adding a line under the @plugins pragma:

@plugins
enhance/arc-plugin-posse

To configure your plugin you’ll add a few more lines to your .arc file:

@posse
feed "https://url.to/rss"
since “2023-04-27”

The feed option tells the plugin what RSS feed to inspect for new content while the since property lets the plugin know the date to start syndicating content on.

Syndication Targets

The plugin supports syndicating content to dev.to, Mastodon and Twitter (while it lasts 😉). Additional syndication targets are planned, but please let us know what you’d like to see next by raising an issue.

The plugin will only attempt to syndicate to a target if the necessary environment variables are set for each syndication target. For more information see the documentation on @enhance/arc-plugin-posse.

Mastodon Example

Twitter Example

Next Steps

Join the Enhance Discord and share what you’ve built or ask for help.
Let us know what features you would like to see next. What syndication targets are important to you?

Webmention Support in Enhance Blog Template

Simon MacDonald — Wed, 19 Apr 2023 14:48:56 +0000

We want to make it easier for folks to participate in the open and indie web. Our first step towards this goal was the publication of our Enhance Blog Template which enables you to publish your site and own your content. Our next step is adding support for incoming and outgoing webmentions to the blog template.

What is a Webmention?

A webmention is a simple way to notify any URL when you mention it on your site. When you link to another site, you send it a webmention (if it accepts them). Conversely, when a site links to your content, you can provide them with an endpoint where they can send you a mention.

Let’s walk through an example of two sites supporting webmentions talking to each other.

I have a website where I write short reviews about books I read. I really do at bookrecs.org.
My friend Cole has his website where he also writes a review about a book we’ve both read. In his review, he includes a permalink back to my original review.
When Cole publishes his article, his site automatically notifies me that his post has linked to my original post.
My site verifies that Cole’s post contains a link to my book review and stores information about Cole’s post so I can decide whether or not to include it as a mention in my review.

That’s two independent websites talking directly to one another without needing a centralized service.

Sometimes the web is just magic.

How it works

Adds microformat support for h-card and h-entry.
/webmention route to accept incoming mentions.
/admin routes to approve incoming mentions.
Scheduled function to send outgoing mentions

Microformats

microformats are HTML for marking up people, organizations, events, locations, blog posts, products, reviews, resumes, recipes etc. Sites use microformats to publish a standard API that is consumed and used by search engines, browsers, and other websites

When you send a webmention to a remote server, it will verify that your site links to the remote server. One way to make it easier for the mentioned site to display our webmention is to follow the h-card and h-entry microformats. The blog template will automatically wrap your blog post in an h-entry and include an h-card on every page.

h-card

You’ll first need to provide the data for your h-card. Open up the file app/api/h-card.json, then add whatever information you feel comfortable sharing online. At a minimum, we suggest adding your name, photo and URL.

For example:

{
    "name":"Sally Ride",
    "photo": "https://upload.wikimedia.org/wikipedia/commons/thumb/0/0c/Sally_Ride_%281984%29.jpg/1024px-Sally_Ride_%281984%29.jpg",
    "url": "https://en.wikipedia.org/wiki/Sally_Ride"
}

If you don’t have a photo hosted on the web we suggest you use your GitHub avatar which follows the format: https://github.com/username.png

See this example of all the properties you can add to your h-card.json file.

h–entry

When the blog template generates the HTML for your blog post, it applies the CSS classes required for it to be considered a valid h-entry.

<article class="h-entry">
  <h1 class="p-name">h-card Test</h1>
  <p class="dt-published">April 6, 2023</p>
  <section slot="e-content">
    <p>Testing having a blog post that has a h-card and h-entry.</p>
  </section>
  <section class="p-summary hidden">Testing h-card and h-entry.</section>
</article>

A quick explainer on microformat class names:

p-name - entry name/title

e-content - full content of the entry

dt-published - when the entry was published

p-summary - short entry summary

For more information see h-entry core properties.

`/webmention` Route

The blog template will automatically add a link tag with a rel of webmention in the head of your application that points to your webmention route. This is one of the ways remote services can discover your webmention route.

This endpoint supports POSTing application/x-www-form-urlencoded content type and verifies that the incoming data has a source and target properties. If it does, the incoming webmention is accepted and stored in our database for approval in our admin interface.

Admin Interface

Admin password

The /admin route is secured with a password. To configure the password on your blog, you will need to create an environment variable.

begin env create --env staging --name SECRET_PASSWORD --value yoursecretpassword

After you are logged in, the admin interface is where you can approve or reject webmentions.

Once approved, a webmention will appear below the post it mentions.

Outgoing Webmentions

By default, the blog template is set up to check for new posts on your site once per day. If it does detect a new post, it will inspect it for external links. Any external links found are checked to see if they accept webmentions. If the mentioned site does, a webmention is sent.

For high-traffic sites, you can increase this polling interval. In your app’s .arc file find the @scheduled section:

@scheduled
check-rss
  rate 1 day
  src jobs/scheduled/check-rss

Modify the rate property so the check is made more frequently. For example, this will check your site every hour:

@scheduled
check-rss
  rate 1 hour
  src jobs/scheduled/check-rss

The function supports any valid rate expression.

Next Steps

Join the Enhance Discord and share what you’ve built or ask for help.
Let us know what features you would like to see next. Maybe POSSE?

Making the leap to AWS with Architect

Simon MacDonald — Fri, 14 Apr 2023 15:01:40 +0000

A guest post by Ameya Charnalia on his journey to migrate from Heroku to AWS via Architect.

After Heroku axed its free-tier in 2022, I was approached by Simon MacDonald—head of developer experience at Begin and my JavaScript mentor—to migrate my Twitter bot, Billbot, to Amazon Web Services (AWS).

While I was at it, he also recommended moving to Mastodon since there was talk Twitter would be restricting access to its free API service in the coming weeks.

Access to the API remains free for write-only cases at the time of publishing.

This innocuous suggestion from Simon made me slightly nervous.

See, Heroku made it very easy for frontend developers like me to deploy our backend projects. Create a procfile, push your code up, make sure your environment variables are set up properly and, before you know it, you’re off to the races.

But I was only delaying the inevitable.

As my projects became more mature and scaled up, I became more involved in writing server-side code. Being a primarily self-taught developer, I knew I had to become familiar with industry-standard cloud solutions such as AWS, but I was spooked by the deployment process. I was warned the process could be cumbersome and the learning curve steep.

Did I say I was a tad nervous?

My bot, for example, runs every morning at 7 a.m. and tweets—or toots, depending on your social media platform—government bills scheduled for debate in the Canadian parliament for that day. How would I migrate my Node.js code from Heroku to AWS while learning about AWS cloud formations, lambdas and databases? I was worried my application would break and leave its users in the dark, scrambling to find out about the day’s bills. (OK, I admit I’m being a tad dramatic—the bot’s 200-odd followers could go to the House of Commons or Senate website to see the day’s projected business. But. I did want to ensure my application’s reliability)

That’s where Architect comes in.

Made by Begin, Architect is a simple, open-source framework for building and delivering powerful Functional Web Apps (FWAs) on AWS.

Off the hop, we decided we’d be using AWS lambda functions triggered through a daily cron job. To achieve this, we made use of Architect’s events-based helper functions. The Architect team has two Node.js runtime helpers: those for general purpose operations such as events and those designed solely for delivering dynamic data via HTTP endpoints.

We wrote two lambda events functions—one each for Mastodon and Twitter—and one scheduler function that dealt with most of the application’s business logic, which included making calls to parliament’s API, filtering the bills and returning all the necessary data to the handler function. When triggered by the schedule’s handler function, the Architect publish function checks which event subscriptions are associated with each event function and makes the calls to the Twitter and Mastodon APIs, respectively.

All of this makes sure that Billbot’s tweets and toots are on time, every day.

In the root of the application sits the app.arc file. Here you can declare the application namespace, its lambda functions, and any AWS regions and plugins it may use. Once I set up my AWS credentials via the AWS command line interface, I was ready to deploy.

@app
billbot

@scheduled
checkbills cron(0 11 ? * * *)

@events
postbill
tweetbill

@aws
profile default
region us-east-2
architecture arm64
runtime nodejs18.x

That was pretty much it.

Architect’s documentation is well-crafted and guides you in deploying your application, regardless of your comfort level with AWS. The developer experience was intuitive, and Architect stripped away much of the AWS complexity, allowing me to get right to learning about, and deploying with, lambda functions.

What’s more, is that it will to save me nearly $16 a month in Heroku bills.

If you want to learn more about Architect check out our documentation or join us on our Discord to ask a question.

Adding Comments to the Enhance Blog Template

Simon MacDonald — Thu, 30 Mar 2023 18:30:11 +0000

Recently, we released the Enhance Blog Template, and one thing I felt was missing was the ability to have random people on the internet disagree with me. That’s right. We’re adding a comment section.

Prerequisites

Install the Begin CLI as we will be using it to generate some code.

Getting Started

In order to super-charge our development, I will use the Begin CLI to scaffold our comments API routes and database access layer. From your terminal run:

begin generate scaffold Comment name:string email:email \
comment:string date:string slug:string

The scaffold command creates the following database backed API routes for you:

app/api/comments.mjs
- GET  /comments            # list all comments
- POST /comments            # create new comments
app/api/comments/$id.mjs
- GET  /comments/$id        # read one comment
- POST /comments/$id        # update a comment
app/api/comments/$id/delete.mjs
- POST /comments/$id/delete # delete a comment

We won’t use all of those API routes in this example, but you should be aware of how easy it is to get started building a CRUD app with the scaffold command.

New UI Components

While the scaffold command created a bunch of UI components for us they don’t match the design of the blog template so we are going to create some new components. The components created by scaffold are intended to get you up and running quickly but we expect you will end up removing them from your project and/or replacing them with your own implementations. When you do please share your designs on the Enhance Discord.

Create these four new files in your project.

// app/elements/field-set.mjs
export default function FieldSet ({ html, state }) {
 const { attrs } = state
 const { legend } = attrs

 return html`
   <style>
     fieldset {
       border: 3px solid hsl(0deg 0% 35% / 15%);
     }

     @media (prefers-color-scheme: dark) {
       fieldset {
         border-color: hsla(0deg 0% 85% / 30%);
       }
     }
   </style>

   <fieldset class='mt0 mb0 p0 font-body'>
     <legend class='font-heading p-2 text3'>${legend}</legend>
     <slot></slot>
   </fieldset>
 `
}

// app/elements/submit-button.mjs
export default function SubmitButton ({ html }) {
 return html`
   <style>
     button {
       background-color: var(--color-dark);
       color: var(--color-light);
       -webkit-font-smoothing: antialiased;
       -moz-osx-font-smoothing: grayscale;
     }

     @media (prefers-color-scheme: dark) {
       button {
         background-color: var(--color-light);
         color: var(--color-dark);
       -webkit-font-smoothing: unset;
       -moz-osx-font-smoothing: unset;
       }
     }
   </style>
   <button type='submit' class='pt-3 pb-3 pl0 pr0 font-semibold'>
     Submit
   </button>
 `
}

// app/elements/text-area.mjs
export default function TextArea ({ html, state }) {
 const { attrs } = state
 const { id, label, name, type } = attrs

 return html`
   <style>
     textarea {
       background-color: transparent;
       box-shadow: 0 0 0 1px hsl(0deg 0% 30% / 50%);
       resize: vertical;
       min-height: 6rem;
     }

     textarea:focus {
       outline: none;
       box-shadow: 0 0 0 2px var(--color-dark);
     }

     @media (prefers-color-scheme: dark) {
       textarea {
         box-shadow: 0 0 0 1px hsla(0deg 0% 80% / 60%);
       }
       textarea:focus {
         box-shadow: 0 0 0 2px var(--color-light);
       }
     }
   </style>
   <label>
     <span class='block text-1 mb-3 font-semibold'>
       ${label}
     </span>
     <textarea id='${id}' name='${name}' type='${type}' class='mb0 p-2 w-full leading3'></textarea>
   </label>
 `
}

// app/elements/text-input.mjs
export default function TextInput ({ html, state }) {
 const { attrs } = state
 const { id, label, name, type } = attrs

 return html`
   <style>
     input {
       background-color: transparent;
       box-shadow: 0 0 0 1px hsl(0deg 0% 30% / 50%);
     }

     input:focus {
       outline: none;
       box-shadow: 0 0 0 2px var(--color-dark);
     }

     @media (prefers-color-scheme: dark) {
       input {
         box-shadow: 0 0 0 1px hsla(0deg 0% 80% / 60%);
       }
       input:focus {
         box-shadow: 0 0 0 2px var(--color-light);
       }
     }
   </style>
   <label>
     <span class='block text-1 mb-3 font-semibold'>
       ${label}
     </span>
     <input id='${id}' name='${name}' type='${type}' class='mb0 p-2 w-full' />
   </label>
 `
}

Great, now we’ve got some components that look good in our blog template in light or dark mode.

Creating a Comment

Now that we have some API routes to store our comments in a database, let’s update our post page to create comments. Open up app/pages/posts/$$.mjs as we are going to add a few lines.

First, we’ll need to pull more data from the store in order to populate the comment section.

 const { comment = {}, post, problems = {}, slug = '' } = store

Wait, hold up, why are we pulling the comment data from the store if this is a new comment? Well, it’s simple. If the user submits a new comment and there is a problem either on the server or with validation, we’ll need to repopulate the comment form to avoid them having to re-type everything. We’re not monsters.

Remember always validate your inputs on the client and on the server.

As well we’ll add a section underneath our blog post that will provide a form for the user to comment on our post.

<enhance-form
    action="/comments/${comment.key}"
    method="POST">
    <div class="${problems.form ? 'block' : 'hidden'}">
    <p>Found some problems!</p>
    <ul>${problems.form}</ul>
    </div>
    <field-set legend="Comment">
    <text-input label="Name" type="text" id="name" name="name"
     value="${comment?.name}"></text-input>
    <text-input label="Email" type="email" id="email" name="email"
     value="${comment?.email}"></text-input>
    <text-area label="Comment" type="text" id="comment" name="comment"
     value="${comment?.comment}"></text-area>
    <input type="hidden" id="slug" name="slug" value="${slug}" />
    <submit-button style="float: right"></submit-button>
    </field-set>
</enhance-form>

Full source code:

// app/pages/posts/$$.mjs
export default function ({ html, state }) {
 const { store } = state
 const { comment = {}, post, problems = {}, slug = '' } = store
 const { frontmatter } = post
 const { published = '', title = '', rating = '' } = frontmatter

 return html`
     <site-layout>
       <article class="font-body leading4 m-auto p0 p5-lg">
         <h1 class="font-heading font-bold mb0 mb4-lg text3 text5-lg tracking-1 leading1 text-center">${title}</h1>
         <p class='text-center mb0 mb4-lg'>${published}</p>
         <section slot="doc">${post.html}</section>
         <p class='mb0 mb4-lg'>${rating} out of 5 stars</p>
       </article>
       <enhance-form
         action="/comments/${comment.key}"
         method="POST">
         <div class="${problems.form ? 'block' : 'hidden'}">
           <p>Found some problems!</p>
           <ul>${problems.form}</ul>
         </div>
         <field-set legend="Comment">
           <text-input label="Name" type="text" id="name" name="name" value="${comment?.name}" errors="${problems?.name?.errors}"></text-input>
           <text-input label="Email" type="email" id="email" name="email" value="${comment?.email}" errors="${problems?.email?.errors}"></text-input>
           <text-area label="Comment" type="text" id="comment" name="comment" value="${comment?.comment}" errors="${problems?.comment?.errors}"></text-area>
           <input type="hidden" id="slug" name="slug" value="${slug}" />
           <submit-button style="float: right"></submit-button>
         </field-set>
       </enhance-form>
     </site-layout>
 `
}

What’s a slug?

Keen readers may have noticed a hidden field in our comment form called slug. In web parlance, a slug is the last part of the URL address that serves as a unique identifier of the page. We need to save the post URL as part of the comment for later when we want to display comments under our post.

In order for app/pages/posts/$$.mjs to have access to the slug we will need to populate it in our store by adding it to the return statement in app/api/posts/$$.mjs. Luckily, the request object passed to our GET handler makes it easy to provide a slug via req.path.

 return {
   json: {
     post,
     slug: req.path
   }
 }

Redirecting `POST /comments`

When scaffold runs it creates a POST /comments API route for you in app/api/comments.mjs. When the POST route runs to completion it will redirect the user back to the /comments UI route but we want to go back to the blog post we were reading instead. This will require a few minor changes to the POST route.

On the line under the post function declaration let’s grab the value of the slug the user submitted.

export async function post (req) {
 const slug = req.body.slug

Then anywhere you see location: ‘/comments’ replace it with location: slug.

Great, now our comment form’s hidden slug input value is properly populated and our API is re-directing you back to the page you were reading. Go ahead and submit a new comment on one of your blog posts, and it will be stored in the database.

Reading Comments from the Database

The next challenge is reading all of the comments from the database. Once again, scaffold comes to the rescue: It has already written the database access layer for you. In app/models/comments.mjs you will find all the methods you need in order to create, read, update, delete or list comments stored in the database. In our case, we’ll only need to list the comments.

Open up app/api/posts/$$.mjs and import the getComments function to get a list of all the comments in the database.

import { getComments } from '../../models/comments.mjs'

Then before the return in that file, we’ll query the database for all the comments and filter them based on the current page that is being viewed.

 const comments = (await getComments())
   .filter(comment => comment.slug === req.path)

And finally, update the return statement at the end of the file to include our comments array.

return {
  json: {
    comments,
    post,
    slug: req.path
  }
}

Full source code:

// app/api/posts/$$.mjs
import { readFileSync } from 'fs'
import { URL } from 'url'
import { Arcdown } from 'arcdown'
import HljsLineWrapper from '../../lib/hljs-line-wrapper.mjs'
import { default as defaultClassMapping } from '../../lib/markdown-class-mappings.mjs'
import { getComments } from '../../models/comments.mjs'

/** @type {import('@enhance/types').EnhanceApiFn} */
export async function get(req) {
 // reinvoked each req so no weird regexp caching
 const arcdown = new Arcdown({
   pluginOverrides: {
     markdownItToc: {
       containerClass: 'toc mb2 ml-2',
       listType: 'ul',
     },
     markdownItClass: defaultClassMapping,
   },
   hljs: {
     sublanguages: { javascript: ['xml', 'css'] },
     plugins: [new HljsLineWrapper({ className: 'code-line' })],
   },
 })

 const { path: activePath } = req
 let docPath = activePath.replace(/^\/?blog\//, '') || 'index'
 if (docPath.endsWith('/')) {
   docPath += 'index' // trailing slash == index.md file
 }

 const docURL = new URL(`../../blog/${docPath}.md`, import.meta.url)

 let docMarkdown
 try {
   docMarkdown = readFileSync(docURL.pathname, 'utf-8')
 } catch (_err) {
   console.log(_err)
   return { statusCode: 404 }
 }
 const post = await arcdown.render(docMarkdown)

 const comments = (await getComments()).filter(comment => comment.slug === req.path)

 return {
   json: {
     comments,
     post,
     slug: req.path
   },
 }
}

Pulling it all together

Now that the store is populated with all the values we need to display comments we can update our app/pages/posts/$$.mjs file one more time.

First, we’ll need to add the comments to the data we pull from the store.

 const { comments = [], comment = {}, post, problems = {}, slug = '' } = store

Then under the enhance-from tag we’ll add a new section which lists all the comments the blog post has received so far.

<h2 class="font-heading mt4 pl0 pr0 pl5-lg pr5-lg text1 text3-lg tracking-1 leading1">
  ${comments.length} ${comments.length === 1 ? 'comment' : 'comments'}:
</h2>
<dl class="font-body leading4 m-auto p0 p5-lg">
    ${comments.map(comment =>
      `<dt class="mb-6">
        <span class='font-semibold'>${comment.name}</span>
        <span class='text-1'>on ${comment.date}</span>
       </dt>
    <dd class="mb4">${comment.comment}</dd>`).join('')}
</dl>

Full source code:

// app/pages/posts/$$.mjs
export default function ({ html, state }) {
 const { store } = state
 const { comments = [], comment = {}, post, problems = {}, slug = '' } = store
 const { frontmatter } = post
 const { published = '', title = '', rating = '' } = frontmatter

 return html`
     <site-layout>
       <article class="font-body leading4 m-auto p0 p5-lg">
         <h1 class="font-heading font-bold mb0 mb4-lg text3 text5-lg tracking-1 leading1 text-center">${title}</h1>
         <p class='text-center mb0 mb4-lg'>${published}</p>
         <section slot="doc">${post.html}</section>
         <p class='mb0 mb4-lg'>${rating} out of 5 stars</p>
       </article>
       <enhance-form
         action="/comments/${comment.key}"
         method="POST">
         <div class="${problems.form ? 'block' : 'hidden'}">
           <p>Found some problems!</p>
           <ul>${problems.form}</ul>
         </div>
         <field-set legend="Comment">
           <text-input label="Name" type="text" id="name" name="name" value="${comment?.name}" errors="${problems?.name?.errors}"></text-input>
           <text-input label="Email" type="email" id="email" name="email" value="${comment?.email}" errors="${problems?.email?.errors}"></text-input>
           <text-area label="Comment" type="text" id="comment" name="comment" value="${comment?.comment}" errors="${problems?.comment?.errors}"></text-area>
           <input type="hidden" id="slug" name="slug" value="${slug}" />
           <input type="hidden" id="key" name="key" value="${comment?.key}" />
           <submit-button style="float: right"></submit-button>
         </field-set>
       </enhance-form>
       <h2 class="font-heading mt4 pl0 pr0 pl5-lg pr5-lg text1 text3-lg tracking-1 leading1">${comments.length} ${comments.length === 1 ? 'comment' : 'comments'}:</h2>
       <dl class="font-body leading4 m-auto p0 p5-lg">
         ${comments.map(comment => `<dt class="mb-6"><span class='font-semibold'>${comment.name}</span> <span class='text-1'>on ${comment.date}</span></dt>
           <dd class="mb4">${comment.comment}</dd>`).join('')}
       </dl>
     </site-layout>
 `
}

Demo

Wrapping Up

Adding commenting functionality to the blog template is not too difficult. However, it does avoid topics like authenticating the submitter and approving comments but this post was getting pretty long so we’ll defer those topics to another post.

If you want to learn more about the scaffold command, I suggest reading our earlier blog post on the topic. Have you tried out deploying a blog template yet? Let us know what you think on Discord or Mastodon.

Introducing the Enhance Blog Template

Simon MacDonald — Fri, 17 Mar 2023 21:57:30 +0000

One thing we’ve heard from users is that they want more options for getting started using Enhance. Today we are excited to announce our first Enhance application template - Blog. Give the new blog template a test drive then jump onto the Enhance Discord to tell us how it went, and let us know what other templates you’d like to see in the future.

Features

Author posts in markdown
Syntax highlighting of code blocks
Light and dark themes based on the operating system setting
Automatic RSS feed generation
CI/CD via GitHub Actions

Project Structure

app
├── api ............... data routes
│   ├── posts
│   │   └── $$.mjs .... load data for individual blog post
│   └── index.mjs ..... list of blog posts
├── blog
│   └── posts ......... post files in markdown format
│       └── *.md
├── elements .......... single file components
│   └── *.mjs
├── lib
│   ├── hljs-line-wrapper.mjs
│   └── markdown-class-mappings.mjs
├── pages ............. file-based routing
│   ├── posts
│   │   └── $$.mjs .... individual blog post
│   └── index.mjs ..... list of blog posts
└── head.mjs .......... head tag, used on all pages

Prerequisites

Install the Begin CLI to simplify the deployment of your new blog.

Local Development

Clone the blog template repository.

git clone git@github.com:enhance-dev/enhance-blog-template.git

Install dependencies

cd enhance-blog-template
npm install

Start the development server.

npm start

Open a browser tab to http://localhost:3333 and start editing your blog. The local development server will hot-reload your site as you make changes.

Blog Posts

You’ll probably want to clear out all the files in app/blog/posts since you didn’t write them. Any file with the extension .md will automatically be added to your blog. The filename should follow the format YYYY-MM-DD-title.md (e.g. 2023-03-07-new-post.md).

In order for the file to be correctly processed it needs to include some frontmatter. You are not limited to these three properties. Add additional properties and make use of them in your blog.

---
title: The title
description: A description of your post
published: The date published in the format "Month Day, Year" (e.g. March 7, 2023)
---

The rest of your post can be any valid markdown, including fenced code blocks. For more info on adding languages to the syntax highlighting, check out the documentation for Arcdown.

Customization

Styling

Styles for this template are applied in the following places:

styleguide.json: Dark and light colors are defined here, as are the font stacks to be used on headings and body text. System font stacks are used by default; you can find some great alternatives at Modern Font Stacks.
public/css/global.css: This stylesheet applies some basic styles at the global level.
public/css/a11y-dark.min.css: This stylesheet applies syntax highlighting to code blocks. Feel free to swap this out with another highlight.js theme of your choosing (and update the link to the stylesheet in head.mjs).
app/lib/markdown-class-mappings.mjs: This file exports an object of HTML element names matched to arrays of classes from Enhance’s utility class system. When your markdown files are converted to HTML, these classes will be attached to the respective HTML elements.
<style> blocks in the Single File Components (SFCs), which live in the app/elements directory. Styles written in these style blocks will be scoped to the custom elements they’re defined in.

This template supports dark mode out of the box — try switching between light and dark mode in your operating system settings to see this in action!

Site Title

There are a few places in the template where you will want to update your site’s title:

In app/head.mjs you can set the <title/> tag.
In app/elements/site-header.mjs you can set the blog title and subtitle that shows up on every page.
Finally, in src/plugins/create-rss-feed.js you can update the title and description that is included in your RSS feed.

Deploying Your Blog

Try out your blog by deploying it to the Begin free tier.

begin login

Create your application and staging environment by following the interactive prompts:

begin create
This project doesn't appear to be associated with a Begin app
? Would you like to create a Begin app based on this project? (Y/n) · true
? What would you like to name your app? · blog-template
? What would you like to name your first environment? · staging
Archiving and uploading project to Begin...
Project uploaded, you can now exit this process and check its status
with: begin deploy --status
Beginning deployment of 'staging'
Packaging build for deployment
Publishing build to Begin
Build completed!
Deployed 'staging' to: https://blog-template.begin.app

Try our your new blog by visiting the URL begin create provides for you.

Optional Step: If you plan on using the default GitHub Action for CI/CD you should create a production environment.

begin create --env production
App environment 'production' created at https://blog-template-prod.begin.app

Configuring CI/CD

This repo comes with a GitHub action that will deploy your site to the staging environment when there is a commit to the main branch and production when you tag a release.

For this to work you must create a repo secret named BEGIN_TOKEN. Once you successfully login to Begin using the CLI command begin login you can retrieve the value for BEGIN_TOKEN in the file ~/.begin/config.json. Use the value of access_token in this file as the value for BEGIN_TOKEN.

Next Steps

Join the Enhance Discord and share what you’ve built or ask for help.
Let us know what templates you’d like to see next!

DEV Community: Simon MacDonald

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

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

Why you should roll your own auth

Customization

Compliance

Control

Cost

Next Steps

Supporting Publish Own Site, Syndicate Elsewhere

What is "Publish Own Site, Syndicate Elsewhere?"

What are the benefits of POSSE?

Getting Started

Syndication Targets

Mastodon Example

Twitter Example

Further Reading

Next Steps

Webmention Support in Enhance Blog Template

What is a Webmention?

How it works

Microformats

h-card

h–entry

/webmention Route

Admin Interface

Admin password

Outgoing Webmentions

Further Reading

Next Steps

Making the leap to AWS with Architect

Adding Comments to the Enhance Blog Template

Prerequisites

Getting Started

New UI Components

Creating a Comment

What’s a slug?

Redirecting POST /comments

`/webmention` Route

Redirecting `POST /comments`