DEV Community: Steven Woodson

Web Components in Astro

Steven Woodson — Wed, 29 Nov 2023 12:00:00 +0000

I’ve recently been jumping into learning more about Astro, using a personal project that needs to be replatformed as an excuse to give it a try. The first thing I wanted to dive into and learn more about was how components are handled, and especially how well it plays with browser native Web Components.

I burned a lot of time here just trying to understand how a web component could be copied into an Astro project. So instead of waiting to blog about the whole process, I wanted to share my learnings about components separately first.

First Attempt – AstroHeart

My first attempt was to get the AstroHeart example in the Web components with custom elements section of the Scripts and Event Handling documentation to work.

I got it working when the whole code block was placed in a layout or a page, but not when it was a referenced component from the /components/ directory. I think we can all agree that adding web components to a page or layout would be categorized as a “Bad Idea”.

After much fiddling I came to the conclusion that an Astro component that then instantiates a native web component is the best I could manage. It feels weird, but it works.

Here’s the full minimal example of AstroHeart working as a web component wrapped with an Astro component on Stackblitz.

Second Web Component Attempt – Sidebar

Now that I know it’s possible, I wanted to ramp things up with an actually usable -and slightly more complicated – example. The first web component I needed to port over for my project happened to be the excellent Sidebar from the Every Layout project.

A couple new issues emerged in this process of adding it, here’s how I got passed them both.

Passing Props

Welp, the Every Layout Sidebar has five separate attributes that can be added to the <sidebar-l> custom element and I quickly realized I need to manage that prop handshake between Astro and the native web component.

First, I went with the most obvious solution of gathering all props and manually passing them in, something like the following:

---
const { side, sideWidth, contentMin, space, noStretch } = Astro.props;
---

<sidebar-l
  side={side}
  sideWidth={sideWidth}
  contentMin={contentMin}
  space={space}
  noStretch={noStretch}
>
  <slot />
</sidebar-l>

But that so verbose and error prone, there’s gotta be a better way right? Turns out, there is! Replace that code above with this and you’re all set.

<sidebar-l {...Astro.props}>
  <slot />
</sidebar-l>

Still a little weird but much better, right? Now if names change or more props are added I don’t have to keep going back to update this.

Scoped vs Global Styles

When styles are added to the Astro component using <style> tags, they’re automatically scoped. In some cases, as is the case for this Sidebar component with several modification options, this can be less desirable.

I found this out first hand when I was attempting to adjust the spacing between the sidebar and the main content area using <Sidebar space="var(--space-m)">. I came to realize that the default styles were of a higher specificity than the modified styles applied via that space attribute.

In cases like this, drop a is:global into the opening style tag like this, <style is:global> and it’ll be treated as a global style where the cascade for modifications will work.

I suppose you could also move the component styles to where the rest of your global styles are located, but you lose that encapsulation of everything being in one place.

Live example

I’ve worked up another Stackblitz for this Sidebar component example too.

Third Attempt – Auto-import Multiple Components

I still felt a bit odd with wrapping web components inside Astro components, even though I was able to overcome any blockers that emerged. I think it’s because having to manually Astro-ify every component I wanted to use feels like it goes against the portability of native web components.

So, I tried again.

With a bit more encouragement from Daniel Saunders, who reminded me that all it really takes is an import of the web component somewhere in the page, I set my sights on trying that.

As a quick proof of concept, I grabbed another of the free Every Layout components – the Stack – and built up a minimally viable page with the following. The references to web-components is because I wanted another separate directory under src to keep Astro components separate from web components.

<stack-l space="3rem">
  <h2>H2 headline</h2>
  <stack-l space="1.5rem">
    <p>
      Lorem ipsum dolor sit amet, consectetur adipisicing elit. Quasi aperiam,
      cupiditate qui totam incidunt ipsum dolores.
    </p>
    <p>
      Lorem ipsum dolor sit amet, consectetur adipisicing elit. Quasi aperiam,
      cupiditate qui totam incidunt ipsum dolores.
    </p>
  </stack-l>
  <h2>H2 headline</h2>

</stack-l>
<script>
  import '../web-components/Stack/Stack.js';
  import '../web-components/Stack/Stack.css';
</script>

Sure enough, that worked just fine!

Automating imports

But, adding a script tag with imports of the (potentially double digit) JS and CSS web component files I’d need to use on every page doesn’t sound like fun to me. Instead, I set my sights on auto-importing based on a glob pattern.

Enter Astro.glob() as that sounds like just what I need. I realized that what I was doing wasn’t going to work though, because I was attempting the import in the front matter which meant this was trying to import on the server side where HTMLElement isn’t defined.

Remembering that it needs to be in a script tag within the content of the page rather than in the front matter got me away from that error, but it still didn’t work.

I read up on what Astro.glob() is doing, it’s a wrapper for Vite’s Glob Import (import.meta.glob). That’s set up by default to lazy load which meant that it wasn’t going to end up on the page because I wasn’t using it on the server side. From the docs:

Matched files are by default lazy-loaded via dynamic import and will be split into separate chunks during build. If you’d rather import all the modules directly (e.g. relying on side-effects in these modules to be applied first), you can pass { eager: true } as the second argument

Once I did just that, I got it working!

Auto-importing at the Layout Level

One more change now that I had something functional, instead of doing this import on the page I moved it to the bottom of my global layout file.

Now, I have access to all web components on all pages that use this layout. Here’s the final code for importing everything, placed in my layout:

<script>
  const webComponentsCSS = await import.meta.glob(
    '../web-components/**/*.css',
    { eager: true }
  );
  const webComponentsJS = await import.meta.glob(
    '../web-components/**/*.js',
    { eager: true }
  );
</script>

I added a second web component to my setup to make sure it was importing both, and sure enough it did! Rather than pasting all that code here, scroll down to the Live example link below to see it all isolated in another Stackblitz.

Performance Implications

Because I’m still learning about all this, and the project I have in mind to use it is very small, I’ve not delved too deep into the implications of importing all web components in this way. I did run a production build to see how everything came together, it appears that all components are compiled into one hoisted.js file.

There’s likely some consideration needed for very large applications, because I’d bet the compiled source wouldn’t be ideal for projects of any real complexity. The first thing I’d try is bundling web components into sub directories and using this glob import pattern in smaller chunks.

Live example

Once again, I made this a minimally reproducible Stackblitz of two native web components being used on a page after being auto imported in the parent layout.

Conclusion

That’s where I’m at as of November 2023, I’m pretty happy with the auto-importing method noted in that third attempt above. But I am still very interested in hearing about other ways to do this, and especially about how it affects page performance. If you’ve got other methods to make this work, I’d love to see some examples!

I’ve already updated this post with the third example after some more fiddling, if I figure out or hear of any further updates I’ll be sure to keep this post updated.

I’m going to continue forward with porting a whole site to Astro, so expect to see another post soon about the rest of the process!

Eleventy Style Guide Generator – Step by Step guide adding to an existing site

Steven Woodson — Fri, 25 Aug 2023 21:03:30 +0000

I shared the Eleventy Style Guide Generator (source is on GitHub and here’s the demo site it generates) a few weeks ago. Because it’s a full Eleventy repo and not a plugin (can’t be until Virtual Templates are supported), I received a few questions about its requirements including:

Are design tokens required?
Is the use of WebC required?
Can I use a CSS preprocessor like SCSS?
How do I add this to an existing Eleventy site?

This post attempts to answer these questions, I’ll also be updating the repo with more of these details as well.

Are design tokens required?

No, you don’t need design tokens to use this generator.

If you decide not to use design tokens you can also remove some of the additional dependencies and files including:

the Tailwind dependency & configuration file at `tailwind.config.js. All it’s doing is converting the JSON sourced design tokens into usable CSS custom properties.
the two CSS utilities at src/_utilities/css-utils. Similarly, they’re only being used by the Tailwind configuration to generate the custom properties.
the tokens static design system page at src/design-system/Atoms/tokens.njk. It’s only there to itemize the individual design tokens.

Is the use of WebC required?

Not technically, but it’s highly encouraged.

WebC brings first-class components to Eleventy, this being a way to itemize components in a style guide it stands to reason that the two are well suited as a pair.

If you choose not to use WebC, or need to ease into supporting it in your existing project, here’s a few considerations.

Naming Collisions

The generator is assuming that each component under src/_includes/components has a .webc component and an .njk example defined. If your components are also going to be in Nunjucks you’ll need another qualifier added to example files so you can programmatically tell them apart.

Something like .stories.njk (like Storybook) would work fine. Then you’d update src/design-system/components-pages.njk to include that extra qualifier, for example like this

{%- macro c(path, name, params) -%} {% include "components/" + path + "/" + name + ".stories.njk" ignore missing %} {%- endmacro -%}

Layouts

There are also two WebC layouts that are being used to generate the style guide files at src/_includes/layouts/ds-static.webc and src/_includes/layouts/ds-wrapper.webc.

You could enable WebC just for new pages and templates like these, but it should be fairly straightforward to convert into another template language if you don’t want to enable WebC at all.

Existing components

There are a handful of components defined in the repo and they’re all WebC based components, so you won’t (easily) be able to make use of them.

You could convert them to another template language but that effort may not be worthwhile depending on your needs.

Can I use a CSS preprocessor like SCSS?

Sure, you can still use a preprocessor like LESS, SCSS, or Stylus if that fits better in your workflow.

I had decided on using only CSS to reduce the number of dependencies required, that’s all.

How do I add this to an existing Eleventy site?

I jotting down what I’ve needed to do to add this to my own site, and listed it all here.

This including everything that I had noted above as optional, so I’ve split it up into sections so you can skip the bits you don’t want.

File path references directly relate to the paths in the 11ty-design-system repo starting with src

Essentials Setup

First, you need to determine where you want the style guide to live, in the repo I’ve set this as /design-system but you can place it anywhere that makes sense for your project.

Copy the following pages to this new folder

src/design-system/components-pages.njk – generates the style guide page for each component, with tabs for Demo, HTML, and Context. Loads the demo as an iframe of…
src/design-system/components-full-pages.njk – this is the isolated component in a blank page. Iframed into the component page above.
- This is relying on a “base” layout too, if yours is in a different location you’ll need to update layout: layouts/base.webc as well.
src/design-system/index.md – The style guide homepage, feel free to replace the content here (and even change the template language).
src/design-system/Atoms – This folder contains files that itemize the design system tokens and most major native HTML elements

Copy the following to your layouts directory

src/_includes/layouts/ds-wrapper.webc – The layout of the design system pages, including the sidebar menu.
- This is relying on a “base” layout too, if yours is in a different location you’ll need to update layout: layouts/base.webc as well.
src/_includes/layouts/ds-static.webc – The layout for any static content pages you add in addition to the auto-generated ones.

Copy the following into your `.eleventy.js` config

/* Shortcodes */ config.addPairedShortcode('brace', function (content, type = 'curly') { const [opening, closing] = { curly: ['{{', '}}'], silent: ['{%-', '-%}'] }[type]; return${opening}${content}${closing}`;
});

config.addPairedShortcode('prettify', (content) => {
return prettify(content);
});

/* Filters */
config.addFilter('console', function (value) {
return JSON.stringify(value, null, 2);
});

/* Custom Collections /
// Filter source file names using a glob
config.addCollection('dsAtoms', function (collectionApi) {
return collectionApi.getFilteredByGlob(' */design-system/Atoms/** /*');
});
`

Descriptions in the same order as the code above:

Brace & Prettify shortcodes, for help displaying content in the Code and Context tab panels
console filter for stringifying the JSON configuration in the Context tab
dsAtoms custom collection so we can also add the static pages under the Atoms directory to the style guide menu

Copy the foundational CSS & JS

src/assets/css/design-system.css – helps with setting up design system specific styles like color swatches. Everything is prefixed with ds- to avoid CSS collisions.
src/assets/js/vendor/seven-minute-tabs.js – Powers the Demo, HTML, and Context tab structure for the component style guide pages

Copy the following data files

src/_data/components.js – generates all the components as a collection, be sure to update the folder paths here too if they’re different in your setup.
src/_data/global.js – defines the random function used in some templates to cache bust the CSS.
- If you have a cache busting filter in place you can skip this one and update references to global.random() with that instead.

With these steps I had a functional style guide being generated. You can see my progress at https://stevenwoodson.com/design-system/.

Screenshot of the Design Tokens design system page after following the steps in this section to get it added to my site.

Adding Design Tokens

Here’s what you need to copy to get design tokens set up:

tailwind.config.js – This is what powers the generation of all the CSS custom properties
postcss.config.js – PostCSS triggers the tailwind configuration, it also minifies the CSS
Build step for the above in your package.json, "css": "npx postcss src/assets/css/*.css --base src --dir dist", for example
src/_data/designTokens – This is where all the design token JSON files are stored, they’re in the data directory to make it easier to parse that data with Eleventy’s automated data cascade
src/_utilities/css-utils – Utility classes that the tailwind config needs in order to generate the custom properties and the clamp values that many of them need

The act of utilizing the design tokens is likely another post entirely, but the TL;DR of it is that you’re going to need to comb through your CSS and replace color, spacing, and other tokenized values with those coming from this generator.

Adding WebC Support & Components

Adding WebC support

You’re going to need Eleventy 2.0.0 or newer to be able to utilize WebC. I was on an older 1.x version and was surprised at how easy the upgrade process was. Hoping you have similar luck if you need to upgrade as well.
Follow the install steps from the official WebC docs, currently it’s not bundled with core so you’ll need to perform an NPM install and add the plugin to your config.

WebC Component Structure

All components are to be stored under src/_includes/components. One component per folder is the ideal and you can nest folders down to three levels currently.

Here’s the structure of a typical component folder, using the Sidebar component as an example:

sidebar-l.webc WebC component file – This is where the component itself is defined, in this case the WebC component is a wrapper for a pre-defined true web component so it only loads the CSS and JS.
sidebar.config.js Configuration file – Defines the component name and any additional context needed to demonstrate what the component can do.
Sidebar.css Web Component – it’s not required to store component styles here rather than with the rest of the site styles but can be a nice way to keep everything together in one place.
Sidebar.js Web Component JavaScript – This is where the Web Component is initialized using standard HTMLElement and customElements syntax.
sidebar.njk style guide example – The Nunjucks template file is where we demonstrate the component with example content.

Check out the Card component for an example of a simpler HTML-only component. This one contains a .webc component, a config, and a Nunjucks template for rendering the examples.

Send me your feedback!

Did you add this Eleventy Style Guide Generator to your site? I’d love to hear about it! If you’re willing to share your process adding it as well, that could inform future updates and documentation to make it easier for the next person. So please do reach out!

Pulling WordPress Post Categories & Tags Into Eleventy

Steven Woodson — Tue, 15 Aug 2023 12:55:00 +0000

TL;DR

This is another part in a series of posts about WordPress content being pulled into Eleventy, including:

Composable Architecture Powered by WordPress (where it all started)
Pulling WordPress Content into Eleventy
Adding a Table of Contents to dynamic content in 11ty

This post is specifically expanding on the progress from the Pulling WordPress Content into Eleventy post to add categories and tags to my blog posts. I’m also going to add per category-filtered pages, and a per tags-filtered pages for good measure.

Here’s what it’s going to look like when it’s all done, or you can click around my blog to see it for yourself.

Category Link List

Posts filtered by Category

Categories and Tags listed at the top of a post

Why?

As I’ve been focusing more on blogging lately, I’ve amassed enough posts that I started realizing that it’s getting progressively harder to find a blog post the older it gets.

Really the only way to do so currently is to go to the main blog page and scroll or run a page search. Not ideal. I could add a site search but I’ve been dragging my heels on that too, so I’m opting for something a little easier for now.

Time to utilize the built in functionality of Categories and Tags from WordPress!

Adding Categories and Tags to Posts

First things first, we need to make sure to add some categories and tags to blog posts. I hadn’t up until now because I wasn’t using them, so I spent some time coming up with a list of categories and tags I’d like to use and then using “Quick Edit” to apply them to posts quickly. Check out this Categories and tags article for more details.

Once we have that data set up in WordPress, we need to make sure we’re gathering it in Eleventy when performing a build. We need to have a list of categories and tags attributed to the post in order to link to them in the blog post template.

These are collectively what WordPress refers to as terms. The details (slug, title, etc.) of terms are not surfaced in the default REST API response, instead we’re only going to see references to their IDs in the main data object like this:

"categories": [7],
"tags": [34],

We’ll also see RESTful links inside _links (which would return these details separately) like the following:

"wp:term": [
  {
    "taxonomy": "category",
    "embeddable": true,
    "href": "https://mysite.com/wp-json/wp/v2/categories?post=1"
  },
  {
    "taxonomy": "post_tag",
    "embeddable": true,
    "href": "https://mysite.com/wp-json/wp/v2/tags?post=1"
  }
],

Getting terms in the REST API response

Instead of performing multiple queries to get the category and tag data, we can add them to the embed section of the same query we’re already using.

As noted in the previous post about pulling content from WordPress, I’m splitting out the posts method getAllPosts from the post details method requestPosts.

To add the terms details, we add &_embed=wp:term to the API request in requestPosts. So in our previous code _embed: "wp:featuredmedia", turns into _embed: "wp:featuredmedia,wp:term",.

Next, we need to make sense of that data and add it to the blogpost data object we’re using to generate the blog pages.

Organizing the term data

WordPress doesn’t discern between a “category” and a “tag” in the embedded JSON, all terms are stored together with an associated taxonomy. Categories are in the category taxonomy, and tags are in the post_tag taxonomy.

For the same example as above where there’s one category whose ID is 7 and one tag with an ID of 34, here’s a slightly trimmed version of what that raw data ends up looking like:

"wp:term": [
  [
    {
      "id": 7,
      "link": "https://mysite.com/category/webdev/",
      "name": "Web Dev",
      "slug": "webdev",
      "taxonomy": "category",

    }
  ],
  [
    {
      "id": 34,
      "link": "https://mysite.com/tag/eleventy/",
      "name": "eleventy",
      "slug": "eleventy",
      "taxonomy": "post_tag",
    }
  ]
]

So, we’re going to need to separate categories and tags ourselves to be able to use them in those separate contexts. Here’s how I’m doing it.

Before

metaDescription: metaDescription,
slug: post.slug,
title: post.title.rendered,

After

metaDescription: metaDescription,
slug: post.slug,
title: post.title.rendered,
terms: post._embedded["wp:term"] ? post._embedded["wp:term"] : null,
categories: post.categories,
tags: post.tags,
categoriesDetail:
  post._embedded["wp:term"]?.length > 0
    ? post._embedded["wp:term"].filter(
        (term) => term[0]?.taxonomy == "category"
      )[0]
    : null,
tagsDetail:
  post._embedded["wp:term"]?.length > 0
    ? post._embedded["wp:term"].filter(
        (term) => term[0]?.taxonomy == "post_tag"
      )[0]
    : null,

It’s a little gnarly looking, but we don’t want our code to break if there aren’t any categories or tags defined so the checks are all squished in there too. If tags are found, I’m then filtering out categories and tags separately in the returned post data.

You’ll notice I’m also passing along the array of categories and tags IDs in categories and tags too, this is for more easily filtering blog posts by these terms in the individual category and tag pages.

Blog Post Updates

Now that I have post categories and tags, time to add them to the blog post pages!

New Pages

These additions are all looking great, but if you’re following along you may notice that the links I’ve added to the blog post template are all going to 404 pages. Of course, that’s because they don’t exist yet so let’s get on that.

Gathering Categories and Tags Data

I’ve not figured out a way to compile all the categories and tags into their own collections by using the data we’ve already gathered in blog posts. Instead, I had to run separate REST API calls for them. If you know of a better way to do this please do let me know!

In setting up these two new REST API calls, I noticed quite a bit of duplication between them, so I opted to do some cleanup and isolate the API calls and data manipulation needed for them all. I called it /utils/wp-json.js. Here’s the code for that:

const { AssetCache } = require("@11ty/eleventy-fetch");
const axios = require("axios");
const jsdom = require("jsdom");

// Config
const ITEMS_PER_REQUEST = 10;

/**
 * WordPress API call by page
 *
 * @param {Int} page - Page number to fetch, defaults to 1
 * @return {Object} - Total, Pages, and full API data
 */
async function requestPage(apiBase, page = 1) {
  try {
    // https://developer.wordpress.org/rest-api/using-the-rest-api/pagination/
    const url = apiBase;
    const params = {
      params: {
        page: page,
        per_page: ITEMS_PER_REQUEST,
        _embed: "wp:featuredmedia,wp:term",
        order: "desc",
      },
    };
    const response = await axios.get(url, params);

    return {
      total: parseInt(response.headers["x-wp-total"], 10),
      pages: parseInt(response.headers["x-wp-totalpages"], 10),
      data: response.data,
    };
  } catch (err) {
    console.error("API not responding, no data returned", err);
    return {
      total: 0,
      pages: 0,
      data: [],
    };
  }
}

/**
 * Get all data from a WordPress API endpoint
 * Use cached values if available, pull from API if not.
 *
 * @return {Array} - array of data objects
 */
async function getAllContent(API_BASE, ASSET_CACHENAME) {
  const cache = new AssetCache(ASSET_CACHENAME);
  let requests = [];
  let apiData = [];

  if (cache.isCacheValid("2h")) {
    console.log("Using cached " + ASSET_CACHENAME);
    return cache.getCachedValue();
  }

  // make first request and marge results with array
  const request = await requestPage(API_BASE);
  console.log(
    "Using API " +
      ASSET_CACHENAME +
      ", retrieving " +
      request.pages +
      " pages, " +
      request.total +
      " total records."
  );
  apiData.push(...request.data);

  if (request.pages > 1) {
    // create additional requests
    for (let page = 2; page <= request.pages; page++) {
      const request = requestPage(API_BASE, page);
      requests.push(request);
    }

    // resolve all additional requests in parallel
    const allResponses = await Promise.all(requests);
    allResponses.map((response) => {
      apiData.push(...response.data);
    });
  }

  // return data
  await cache.save(apiData, "json");
  return apiData;
}

/**
 * Clean up and convert the API response for our needs
 */
async function processContent(content) {
  return Promise.all(
    content.map(async (post) => {
      // remove HTML-Tags from the excerpt for meta description
      let metaDescription = post.excerpt.rendered.replace(/(<([^>]+)>)/gi, "");
      metaDescription = metaDescription.replace("\n", "");

      // Code highlighting with Eleventy Syntax Highlighting
      // https://www.11ty.dev/docs/plugins/syntaxhighlight/
      const formattedContent = highlightCode(prepared.content);

      // Return only the data that is needed for the actual output
      return await {
        content: post.content.rendered,
        formattedContent: formattedContent,
        custom_fields: post.custom_fields ? post.custom_fields : null,
        date: post.date,
        dateRFC3339: new Date(post.date).toISOString(),
        modifiedDate: post.modified,
        modifiedDateRFC3339: new Date(post.modified).toISOString(),
        excerpt: post.excerpt.rendered,
        formattedDate: new Date(post.date).toLocaleDateString("en-US", {
          year: "numeric",
          month: "long",
          day: "numeric",
        }),
        formattedModifiedDate: new Date(post.modified).toLocaleDateString(
          "en-US",
          {
            year: "numeric",
            month: "long",
            day: "numeric",
          }
        ),
        heroImageFull:
          post._embedded["wp:featuredmedia"] &&
          post._embedded["wp:featuredmedia"].length > 0
            ? post._embedded["wp:featuredmedia"][0].media_details.sizes.full
                .source_url
            : null,
        heroImageThumb:
          post._embedded["wp:featuredmedia"] &&
          post._embedded["wp:featuredmedia"].length > 0
            ? post._embedded["wp:featuredmedia"][0].media_details.sizes
                .medium_large
              ? post._embedded["wp:featuredmedia"][0].media_details.sizes
                  .medium_large.source_url
              : post._embedded["wp:featuredmedia"][0].media_details.sizes.full
                  .source_url
            : null,
        metaDescription: metaDescription,
        slug: post.slug,
        title: post.title.rendered,
        terms: post._embedded["wp:term"] ? post._embedded["wp:term"] : null,
        categories: post.categories,
        tags: post.tags,
        categoriesDetail:
          post._embedded["wp:term"]?.length > 0
            ? post._embedded["wp:term"].filter(
                (term) => term[0]?.taxonomy == "category"
              )[0]
            : null,
        tagsDetail:
          post._embedded["wp:term"]?.length > 0
            ? post._embedded["wp:term"].filter(
                (term) => term[0]?.taxonomy == "post_tag"
              )[0]
            : null,
      };
    })
  );
}

function sortNameAlpha(content) {
  return content.sort((a, b) => {
    if (a.name < b.name) return -1;
    else if (a.name > b.name) return 1;
    else return 0;
  });
}

module.exports = {
  requestPage: requestPage,
  getAllContent: getAllContent,
  processContent: processContent,
  sortNameAlpha: sortNameAlpha,
};

With this new set of utilities, the actual data JS files are super small. Here are the blogposts.js, blogcategories.js. and blogtags.js files.

blogposts.js

const { getAllContent, processContent } = require("../utils/wp-json");

const API_BASE =
  "https://mysite.com/wp-json/wp/v2/posts";
const ASSET_CACHENAME = "blogposts";

// export for 11ty
module.exports = async () => {
  const blogposts = await getAllContent(API_BASE, ASSET_CACHENAME);
  const processedPosts = await processContent(blogposts);
  return processedPosts;
};

blogcategories.js

const { getAllContent, sortNameAlpha } = require("../utils/wp-json");

const API_BASE =
  "https://mysite.com/wp-json/wp/v2/categories";
const ASSET_CACHENAME = "blogcategories";

// export for 11ty
module.exports = async () => {
  const blogcategories = await getAllContent(API_BASE, ASSET_CACHENAME);
  return sortNameAlpha(blogcategories);
};

blogtags.js

const { getAllContent, sortNameAlpha } = require("../utils/wp-json");

const API_BASE =
  "https://mysite.com/wp-json/wp/v2/tags";
const ASSET_CACHENAME = "blogtags";

// export for 11ty
module.exports = async () => {
  const blogtags = await getAllContent(API_BASE, ASSET_CACHENAME);
  return sortNameAlpha(blogtags);
};

Creating a Blog Post Term Filter

Great, we have data now! The next step is to set up a filter so we can show category and tag pages with just the posts that contain them. Because both are ID based, I opted to create one filter that’d work for either. Here’s the code

  // Get the elements of a collection that contains the provided ID for the provided taxonomy
  eleventyConfig.addFilter("blogTermFilter", (items, taxonomy, termID) => {
    return items.filter((post) => {
      return post[taxonomy].includes(termID);
    });
  });

Now I can pass the taxonomy (categories or tags) and its ID to get a filtered list of posts with that category or tag.

Creating the Category and Tag Pages

We’re getting really close now!

The final step is to create the tags and categories filtered pages. For me, they both have basically the same structure so I’m just going to share the categories one here.

---
layout: layouts/base.njk
pagination:
  data: blogcategories
  size: 1
  alias: blogcategory
permalink: blog/category/{{ blogcategory.slug }}/
---
{% set blogslist = blogposts | blogTermFilter("categories", blogcategory.id) %}

<section class="l-container h-feed hfeed">
  <header class="feature-list__header">
    <h1 class="p-name">Blog Posts categorized under "{{ blogcategory.name }}"</h1>
    <a href="{{ metadata.feed.path }}">RSS Feed</a>
  </header>
  <p>
    <a href="{{ '/blog/' | url }}" class="btn btn--secondary btn--small">back to all blog posts</a>
  </p>

  <div class="grid-3-wide feature-list">
    {% for post in blogslist %}
      <div class="card z-depth-1 h-entry hentry">
        <div class="img-16-9-aspect">
          {%- if post.heroImageThumb %}
            <img src="{{ post.heroImageThumb }}" alt="" loading="lazy">
          {% else %}
            <img src="/assets/images/posts/post-hero-placeholder.png" alt="" loading="lazy">
          {% endif %}
        </div>

        <div class="card__content">
          <{{itemheader}} class="headline4 p-name entry-title">
            <a href="/blog/{{post.slug}}" class="u-url" rel="bookmark">
              {% if post.title %}{{ post.title | safe }}
              {% endif %}
            </a>
          </{{itemheader}}>
          <div class="l-post__meta">
            <p>
              <strong>
                <span aria-hidden="true" class="fe fe-calendar"></span>
                <time class="postlist-date" datetime="{{ post.date }}">{{ post.formattedDate }}</time>
              </strong>
            </p>
          </div>
          <div class="p-summary entry-summary">
            {%- if post.excerpt %}{{ post.excerpt | safe }}
            {% endif %}
          </div>
        </div>
      </div>
    {% endfor %}
  </div>
</section>

You can copy this file and replace the references to categories over to tags instead for the Tags version. For example {% set blogslist = blogposts | blogTermFilter("tags",blogtag.id) %}

Potential Further Enhancements

This ended up being a bit more to figure out than I anticipated going into it, and I’m pretty happy with where it is now.

I do, however, have some ideas for future further enhancements:

In addition to Previous and Next posts at the bottom of a blog post page, it’d be really great to have a “Related posts” section. That’s a fairly common feature of blogs and would help with discoverability.
Advanced filtering from within the main Blog page would be nice, rather than just separate pages per category and tag. This would open up further options like filtering by category and tag together.

I may make time for these soon, let me know if you’d be interested in reading more about that!

Eleventy Style Guide Generator with WebC Component Support

Steven Woodson — Fri, 04 Aug 2023 10:20:17 +0000

TL;DR

I created an Eleventy style guide generator, features include:

Automatically itemized JSON-formatted design tokens like colors, fonts, and fluid scale and sizing.
Automatically itemized components and their variations based on a simple configuration file format
Eleventy WebC Component support and examples
Supports standalone documentation pages , perfect for displaying foundational HTML elements and explaining design system details in a more curated way.

Source is on GitHub and here’s the demo site it generates.

Impetus

I recently had the opportunity to create a new fairly simple Eleventy site and found myself wanting to also document some of the visual language and components therein.

I didn’t want to go overboard and install something like Storybook for this because – while I love Storybook – it can be a lot and this site definitely didn’t need all that.

So, in true developer fashion, rather than manually create a few static style guide pages and move on, I decided to make a design system generator!

I love the simplicity and speed of 11ty , and I love the organization of a good self documenting design system , so I combined the excellent work of several really smart people to pull these two together in a way that acts as a pretty nice starting point for a fluid, responsive, and blazing fast 11ty powered website.

Read on if you’re interested in the pieces that make up the whole, including the inspiration behind them.

Design Tokens

What better place to start than the at the smallest building blocks of a design system, right?

Need a quick intro to design tokens and how they relate to design systems? Check out this “What Are Design Tokens?” Smashing Magazine podcast episode with Jina Anne.

Design tokens are vital to the overall look and feel and are (ideally) used everywhere to promote consistency with spacing, fonts, colors, etc.

All tokens are stored in the /src/_data/designTokens/ directory, I did this purposefully because having the JSON in the Eleventy Data folder gives me these values to manipulate and use for free. Making the visual itemizing noted below really simple.

Token Definition

Here’s the structure I used for the token files themselves, they all came with a title, description, and an array of items. I also optionally added a meta object to store additional info, for example the sizes and spacing ones link to the Utopia calculator where it was generated.

{
  "title": "Name for these Tokens",
  "description": "Longform description of what these tokens define.",
  "meta": {},
  "items": []
}

I used the excellent tools James and Trys created called Utopia for the sizes and spacing tokens. Here’s the breakdown:

The Type Calculator defines the sizes.json tokens
The Space Calculator defines the spacing.json tokens

I also added a colors.json and fonts.json token JSON file to itemize those for consistency as well.

I now have a solid foundation for fluid typography and spacing, and consistent fonts and colors, so the applications I build will look wonderful regardless of the available space and will be consistent from page to page with minimal effort.

Converting to CSS Variables

Now that I have my tokens beautifully organized, I also needed a way to convert them into usable CSS variables.

There are some great well established tools out there that do this, such as Theo and Style Dictionary but for this I turned to the sage advice of Andy Bell via buildexcellentwebsit.es and used Tailwind to run through the token JSON files and generate the CSS variables I can use in my styling.

I went this route because it seemed to fit how I like to organize things, already had concepts inherent to Utopia (including clamp), and was already working in an Eleventy site.

These are defined in the /_utilities/css-utils folder and used in the tailwind.config.js configuration.

Here’s a truncated example of what it generates:

:root {
    --color-bg: #fff;
    --color-bg-alt: #fffaeb;
    ...
    --space-2xs: clamp(0.5rem,0.46rem + 0.19vw,0.625rem);
    --space-xs: clamp(0.75rem,0.69rem + 0.29vw,0.9375rem);
    ...
    --space-xs-s: clamp(0.75rem,0.59rem + 0.78vw,1.25rem);
    --space-s-m: clamp(1rem,0.53rem + 2.33vw,2.5rem);
    ...
    --size-step-n2: clamp(0.6875rem,0.65rem + 0.19vw,0.8125rem);
    ...
    --font-base: Segoe UI,Roboto,Helvetica Neue,Arial,sans-serif;
    --font-serif: Georgia,sans-serif;
    --font-code: Lucida Console,Monaco,monospace;
}

Visually Itemizing the Tokens

Being so vitally important to a successful product, I wanted a seamless and automated way to itemize these tokens for easy visual reference.

I’m still shocked at how easy this part ended up being once I decided to store the design tokens in the Eleventy data directory.

Because that data was automatically surfaced to page templates, all I needed to do here was to create an 11ty Nunjucks-based page that loops through the design token values and applies the tokens to some placeholder elements. You can see how this comes together at /src/design-system/Atoms/tokens.njk and a screenshot of it in action below.

Some overlapping screenshots of the tokens style guide page to illustrate how it itemizes the tokens visually

Style Guide Generator

With design tokens defined, accessible via CSS, and visually itemized in a page. I thought “wouldn’t it be great to have individual components automatically itemized in a similar way?”.

Foundation

After some searching for existing solutions I found this Eleventy Design System gem by Trys Mudford. It’s truly a wonderful foundation for exactly what I was hoping to achieve with this project.

While integrating that into what I was building, I noticed a few things that I wanted to expand upon to make it more versatile. Here’s the highlights of what I added:

Moved to a subfolder so it can be in the same codebase as the rest of the site
Ability to define components in subfolders of the _includes/components directory
WebC components support and examples

WebC Support

It just so happened that I was reading more about WebC while iterating on this idea. WebC is a new 11ty file extension that brings first-class components to Eleventy. An obvious addition to a style guide generator that itemizes components!

I will caution that WebC is still fairly new, there’s some things that work great with other file extensions that just don’t yet for WebC. I’ve itemized some of these as TODO items in the readme.

To see some WebC component examples, check out the Sidebar and Stack composition components courtesy of Every Layout, and the Card component utilizing some style inspiration from SmolCSS.

Other Conventions

Standalone Documentation Pages

Rather than having to create a “component” for foundational HTML elements and long form documentation within the style guide, I’ve built it so that you can define standard pages in the style guide as you would any other page.

It will automatically merge these static pages with the generated ones for components too!

For some examples of static pages, check out the src/design-system/Atoms folder. That’s where I’ve added block, form, inline, and preformatted HTML tags to quickly be able to preview how changes to the design tokens and styles affect these critical native tags.

Styling Methodology

I’ve quickly become a big fan of CubeCSS and have tried to adhere to those guidelines as best I can here. If you haven’t read about it yet I highly recommend you check that site out and give it a try.

Admittedly, in some cases it gets a little weird but I have my reasons! For example, I have web component styles sitting in the same folder as the web component itself (Sidebar for example) and I have others (Card for example) that have styles in the assets folder (card.css in this case) instead.

I did this because I wanted to adhere to the HTML-only Components rule where it renders native HTML and ignores the host component tag. Adding and referencing the styles in the component definition would have turned the Card example into a true web component instead.

Live Site Example

I’ve actually been sitting on this for a little while, before releasing something for general use I wanted to make sure to put it through a real site build process first. Happy to share the first such site has just been pushed live for the best (and most patient) client a guy could ask for – my dad!

His site at dannywoodson.org and the style guide for it is here.

Pretty neat to be able to compare the demo site with this live site and see the similarities, but also the differences!

Plans for the Future

I think there’s a lot of potential here, a couple of the bigger things I’d love to do with this are:

Continue to add foundational web components that can be reused across any kind of tech stack. Im considering adding some more baseline WebC components to this project as well, especially those found in Tugboat.
I’d ideally like this to be an Eleventy plugin that can be installed on an Eleventy site, rather than a full Eleventy site in itself. As far as I can tell there’s not a way to do so until Virtual Templates are made available.

Have any ideas? Are you going to give it a try?

I’d love to hear from you, reach out on the socials or start up an issue on GitHub.

Resources

Design Systems, Fluid Typography, Styling Methodologies oh my!

Fluid type, space, and grid calculations via Utopia
CSS methodology based on Cube CSS
Eleventy Design System by Trys Mudford & the companion explanatory blog post.
Some of the base components and styles are based on SmolCSS and Every Layout

Getting Started with WebC

Eleventy WebC Components main documentation
Crash Course in Eleventy’s new WebC Plugin video
Interactive Progressively-enhanced Web Components with WebC video
Introduction to WebC & Understanding WebC Features and Concepts from 11ty Rocks
11ty & WebC by W. Evan Sheehan

The Ideal Client and Project – Freelance Introspection

Steven Woodson — Sat, 08 Jul 2023 14:19:25 +0000

I’ve realized there’s a surprising amount of introspection required when you decide to go freelance. One is to figure out “the ideal” client and project.

When working at a company we don’t get the luxury of considering these ideals, you’re assigned a project and that’s that.

Getting Started

Now that I’m actively looking for opportunities, it’s important to have those ideals in mind so I can try to target those companies and projects that would be the best fit for me.

I’m gonna be honest, I still don’t have a great answer to this yet. Since I committed to sharing more of my process of going freelance, I’m posting my process now and hope to have an update soon with a clearer answer.

Here’s some questions I’m mulling over so far, I feel like the answers of these will help me get there:

What are some recent projects that made me feel the most proud when it was completed?
What kind of project teams did I tend to gel with the best?
What technologies were in use that made me the most fulfilled as a developer?
What kinds of clients inspired me to give my all every day?

Taking it Social

An earlier draft of this went out on LinkedIn, Twitter, and Mastodon. I got a couple of very interesting replies that I’m going to add to my own process, sharing them below so you can give them a go as well.

Alistair Shepherd

Unrelated, but I gotta highlight the creativity of Alistair’s website, especially the header. If you’re interested in the process that led to that amazing result check out his talk from the 2022 State of the Browser conference.

Many thanks to Alistair for sharing this gem via Mastodon.

It really makes sense to focus on the people and industries that resonate and provide more satisfaction. Something I’ll be keeping in mind in the work ahead.

Jon Gibbins

This advice from Jon really highlights his commitment to making the digital world better for all people and for our planet with As It Should Be.

I’ve certainly found the focus that comes from such introspection to be beneficial to also focussing my marketing efforts and value proposition.

One exercise I did a few years back was to put a line down the middle of a piece of paper, then write the things / values that matter most to me personally on one side, and the things I think matter most in my work or even the main kinds of projects / clients I’ve worked on / with. Then draw lines from one side to another to connect items that are linked to find common ground. These are areas of focus. Anything else should show where your work is not meeting your personal values.

You can do something similar with Ikigai exercises.

Jon Gibbins via LinkedIn comment

I really like this mentality of starting with my own values and letting that guide the process of finding common ground for clients and projects.

I had recently shared my personal and professional mission statement that I’ve been iterating on for over 5 years, I’m going to try this suggestion with that as my starting point.

How About You?

Have you done an exercise like this before? If you have some ideas to help me bring this more into focus I’d love to hear it!

By the way, I’m still looking for freelance web dev opportunities so if you have something coming up I’d love to hear more about how I can help bring it to life!

Steve Woodson – Independent Web Development Consultant

Steven Woodson — Sat, 01 Jul 2023 11:14:57 +0000

TL;DR

I’m terrible at burying the lede (as it’s the title of this post) so I’m starting with the TL;DR. I’m venturing out on my own offering freelance web development consulting!

Check out:

Services for my core values, how I’m different, and what web development services I can offer.
Testimonials for some kind words folks have recently shared about me, my work, and my leadership.
Project Inquiry to get in contact about an upcoming project I can help you bring to life!

The rest of this post shares some reflections on the past week, and goes into more detail about how I got to the point where I’m ready to go independent, and what else I have planned for the near future.

Reflecting on the Last Week

One week ago today I shared that I was laid off. I didn’t realize at the time how much this would resonate with people and am deeply humbled by the response.

Hundreds of reactions, dozens of comments, and just as many direct messages and emails. I’ve even got a few meetings scheduled with folks just to chat about our experiences and talk about what gets us excited about the future.

The offer made last week about being open to chat still stands. If you were recently affected by workforce reductions, are struggling to find the next adventure, or just want to chat about the difficulties we’ve all been facing these past few years.

Feel free to DM me on a social platform or send me an email. We can even book a half hour chat if you prefer to talk face to face. Let’s make some lemonade from these lemons!

The Dream

A few years into my web development career, somewhere around 2005, I started to dream about venturing out on my own. I would even go so far as to take on the odd freelance job when the opportunity would arise.

But I was a long way from taking a chance on full time freelance web development consulting.

I knew there was so much I could accomplish but also that the work itself is only one (albeit very important) part. I recognized that there’s marketing, sales, and business management that goes into it as well. Frankly, I was terrified of all three.

The most visceral reaction, however, was the scarcity mindset. The fear that I’d get everything set up, put myself out there, and nothing happened. I wouldn’t make any digital marketing connections, wouldn’t find clients that saw my potential as a web application developer, wouldn’t land any web dev projects.

It was enough to deter me from even giving it a try. So, for over 15 years this dream sat there in the back of my mind.

Why Now?

It’s amazing how much time one has to sit and think when not engrossed in day to day work. I spent a lot of that time this past week thinking about

what I’ve yet to accomplish
what I want my days to look like
and what is going to get me excited to get up out of bed every morning

I knew right away, there’s still that one big goal that checks all three of these boxes. Maybe losing my job is the universe telling me to just go for it already?

I had shared that thought privately with several colleagues, friends, and family and every single one had something positive to say. Here are some of them that really resonated with me:

“What you water will grow”
“Sometimes many of us need that kick in the ass.”
“This is definitely a sign from the universe for the push you needed […] everything happens for a reason!”
“That would be so great! One door closes, another opens”
“That’s great to hear on independent consulting. I’m big on universal signals, too!”

I’ve grown a lot in the last handful of years, not only as a developer but as a more confident leader, empathetic collaborator, and accessibility focused technologist. I’ve worked hard building a personal brand and now I feel ready to share all that experience directly with client teams as an independent consultant.

Making it a Reality

I’ve spent a considerable amount of time working through details and getting everything set up. In addition to the site updates noted at the beginning of this post I’ve also secured

a registered LLC, in partnership with my wife
business insurance, including cyber coverage
operations details including communications workfows, project management, and contract templates

I’m sure there’s countless more things that I need to do, but I’ve got the fundamental aspects ready and am officially open for business!

What’s Next?

Thought Leadership

Expect to see more “thought leadership” from me, even though I am not altogether fond of that term it does serve as a useful shortcut to what I mean. I have a dozen or so blog posts in draft ranging from technology leadership, productivity, and specific solutions to some of the day to day struggles of web developers.

I’m still learning when it comes to marketing, but one thing that always resonated with me is the simple fact that sharing what I’ve learned and helping others builds awareness and connections. That awareness and those connections can often lead to surprising and unexpected things.

Be Inclusive

I’m also working on more roadmap items for my SaaS accessibility auditing app Be Inclusive too. I’ve often lamented not having as much time as I would have liked to keep breathing more life into that app, make it faster, more compelling, and easier to use for the people that work so hard every day to push accessibility forward.

Got ideas?

What else would you like to see more of from me? If you’ve got some thoughts and ideas I’m certainly interested in hearing more about it.

I have some time now, and I’m so excited to be able to start spending more of it contributing to the web development, application development, and digital accessibility communities that have helped me learn and grow so much these past 20 years.

If you have a project coming up that could use an experienced web developer to help bring it to life, get in touch! I’d love to hear more about what you have planned, and how I can help.

Onward and upward! 🎉

I Was Laid Off, Now What?

Steven Woodson — Wed, 28 Jun 2023 12:33:37 +0000

If you’ve been following the news lately, it’s been a rather tough time in technology this year. Not a week goes by without news of several major companies letting go of significant percentages of their workforce, so much so that many organizations are keeping track of 2023 tech layoffs.

Well, as of last week I’m now one of the tens of thousands affected by these ongoing tech workforce reductions.

Facing The Feelings

Grief, Stress, Guilt

A few months ago, because of how pervasive layoffs have been industry-wide lately – including multiple rounds at my previous employer – I had done some reading on how to best support those affected. This article about Job Loss Grief and this one about Unemployment Stress struck a chord with me and I appreciate their advice even more as I read them again now. I highly recommend them, for folks recently laid off as well as for those interested in helping them.

Some of the most common advice in these and many other articles was to write about your feelings, share your story, and talk about it. That was the impetus for this post.

My Immediate Reactions

My first thoughts mid-call as I realized what was happening were “what about my coachees? what about my project team?” These people are going to be affected by this as well, now needing to carry on with less help and likely more anxiety about their own futures.

I’ve come to realize how much of a daily routine and sense of self gets tied up in a job after nearly 8 years. The more difficult realization is how quickly it can all disappear. Get the call and minutes later you’re locked out. I understand the precaution of it, and I know it’s never easy for those on the other side too, but there’s an abrupt coldness to it that still stings.

As strange as it may sound, I also felt a bit of guilt. Thinking of the tasks I postponed til later. That client project ticket I was actively working on. I should have committed that code, I should have written out some notes about my thought process, I should have been more diligent about taking notes about future plans.

Reflections

I had jotted down some reflections as they came to mind, here’s some of them.

Several times I’ve found myself in the Slack app on my phone, my autopilot taking me there to check out the latest messages only to be reminded that it’s gone.

I was blown away by the dozen or so folks who reached out to me immediately in these first days, that kind of support is not something I expected nor take for granted. I appreciate each and every one of them.

I have grown so much as a developer, a mentor, and a person in these past 8 years. I had the privilege of being a career coach to 10 wonderful people, worked on dozens of client projects, and had a small part in bringing accessibility to the forefront company-wide.

I’m going to miss so so much.

The little things. The everyday chatter with colleagues, shared pet pictures and music recommendations, opinions about industry news and latest goings on in web development.

The big things. The years-long collective accessibility documentation I had helped to curate in the company wiki. The client project I had spent the past year and a half guiding towards less technical debt, better accessibility, improved performance, and more efficient process. The team I was fortunate enough to work with, help guide, and learn from every day.

Self Care

In the same articles I had mentioned in the section above, another key point they all share is that you need to be intentional about taking care of yourself. Try to eat well and get good exercise and rest, seek good company, and practice mindfulness. It’s critical to do these things to balance against the grief, stress, and guilt.

Here’s some of my self care items these first few days.

I watched some guilty pleasure shows I don’t often make the time for, especially in those moments where any deep work or thought doesn’t come so easily. I gave myself permission to slow down and just enjoy something a little mindless.

Went on an hour and a half walk with my wife, including through a forest preserve. Time outdoors and in nature is never wasted.

A couple close friends took time out and set up an outing for all of us. It was a great time, I didn’t realize until later how much that lifted me up. I absolutely needed it and am so grateful.

Being the organization and productivity nerd that I am, I got some strange sense of enjoyment cleaning up my note taking apps, updating a bunch of my contacts with photos, and ironically enough in capturing the thoughts that led to this blog post.

I finally reorganized the living room entertainment center, wire management and all.

Today, I’m about to get to some yard work while listening to an audiobook.

Wrapping up

It was cathartic to jot down these thoughts and then compile them to share openly. I do feel like it’s helping me process things and start to look optimistically at the future.

Open Invitation to Chat

I’m sharing all this here in the hopes that it helps others going through this too to know you’re not alone, and whatever you’re feeling is a normal part of the process. Maybe it helps you make sense of your own experiences too.

Open invitation to you as well to chat via email, social media DMs, whatever you like. Let’s talk about it, share some reflections and process things together, then we can move on to talk about what has us excited for the future.

Speaking of, I’m some combination of excited and nervous about what I’m planning next. Working on some details and will be sharing more about that very soon. Stay tuned!

SVG Plaid Swatch Generator

Steven Woodson — Mon, 24 Apr 2023 14:00:00 +0000

Sometimes you’ve gotta make time to build something fun, today I whipped up a Plaid Swatch Generator!

Background

I built up my personal branding centered around the use of various plaid color combinations. I wanted all my projects to have unique color palettes but a distinctive style that was immediately apparent. For example, below are four of the logos I’ve created.

Some examples of my personal/professional branding

Early on, I was able to figure out how to get this to render as an SVG so I had more options for manipulating and so the plaid was always as performant and crisp as possible. I built a quick CodePen of it and moved on.

Impetus

I had a laundry list of things to do today, but I didn’t have much motivation so I was looking around CodePen (as you do) and came across the plaid Pen I had noted above. It sparked a thought “hey this could pretty easily become a cool plaid generator, I’d just need to figure out how to change the colors dynamically.”

Build

The dynamic color updates ended up being the main chunk of work here. Once I got color input elements added to the page and wired up with a bit of JavaScript, changing the fill of the related SVG rectangles was pretty straightforward.

I figured out how to get the colors to reflect in the example as you pan through the color wheel too, making choosing colors pretty intuitive as long as your browser supports more modern color picker options.

Easy Sharing

Check out some of the ones I generated as I was testing!

Since the main chunk of work wasn’t too bad, I set my sights on making this as easy as possible to grab and share. So I’ve added:

a download button, so you can get an SVG of your creation straight away
a URL auto-update to match your choices, making it easy to bookmark or share too

Feedback?

I have some other ideas for this, but wanted to make sure I kept it to an afternoon of hacking away. I do want to revisit it and refine with more, so give the Plaid Swatch Generator a try and let me know what you’d like to see added!

How I Hacked My Brain to Let Myself Relax in the Evenings

Steven Woodson — Tue, 28 Mar 2023 17:00:00 +0000

Do you ever find yourself constantly on the go, always trying to be productive? I’ve struggled with this for most of my adult life, spending evenings checking off tasks on my to-do list, a blur of writing code and responding to emails. But after a while, I realized that this wasn’t sustainable. I was regularly anxious, tired, and felt like I couldn’t just relax and recharge. I also didn’t like the feeling that family and friends were getting the leftover time not otherwise spent in this productivity cycle.

The Impetus

I’ve been reading a whole lot of self help and productivity books the past few years. Largely as a shot of motivation to keep up the few “tricks” that have started to help me control that anxiety while still pursuing goals, but also out of a desire to find new or different tricks to try.

One concept that came up often in these books is around being intentional with your time, be it making time for what you consider important, removing what you don’t consider to be essential, or building resilience to distractions.

They all come down to taking charge of your time.

“You only waste time if you’re not intentional about how you spend it.”

Jake Knapp & John Zeratsky, Make Time: How to Focus on What Matters Every Day

How I took charge of my time

First, I had to come to terms with the fact that I have a strong need to feel productive. I’ve come to realize I can only really relax when I feel a sense of accomplishment, and know that I have a plan for continuing that into the future. So, instead of fighting against this part of myself, I decided to work with it.

“Remember that if you don’t prioritize your life someone else will.”

Greg Mckeown, Essentialism: The Disciplined Pursuit of Less

I started by time-boxing my productive time in the early morning before work. I found that I was most focused and least distracted in the morning, so I dedicate a couple of hours each morning to tackling my most important goal for that day.

“something magic happens when you start the day with one high-priority goal.”

Jake Knapp & John Zeratsky, Make Time: How to Focus on What Matters Every Day

Next, I started setting a daily “theme” for myself. This meant that each day, I would focus on one particular goal. For example, Monday might be dedicated to building a feature on Be Inclusive, Tuesday focuses on a blog post (like I am today), Wednesday towards reading a backlog of blog posts I’ve let pile up, etc. This helped me to avoid spending too much time on one particular area and ensured that I was making progress on all fronts.

I come up with these daily goals during my weekly planning every Sunday, so I’ve got the whole week mapped out in advance. This gave me peace of mind in the evening knowing I had time set aside and a plan for it the next day.

Permission to Relax

The end result? I can now relax in the evenings without feeling guilty or anxious about all the things I need to do. And, because I made it a habit to go to bed at the same time every night and wake up at the same time every morning, I’ve noticed that I’m sleeping better and have more energy throughout the day.

“The people we love most should not be content getting whatever time is left over. Everyone benefits when we hold time on our schedule to live up to our values and do our share.”

Nir Eyal, Indistractable

If you’re someone who always needs to be productive, I encourage you to give this approach a try. It might take some time to get used to, but trust me, it’s worth it.

Email Newsletters – My Emotional Response Spectrum and Organization Strategy

Steven Woodson — Fri, 17 Mar 2023 14:43:08 +0000

How’s that for a title? Basically, this is all about how I personally categorize newsletters, how that categorization has influenced how they’re organized, and how much attention they get as a result.

I don’t think it’s a controversial statement to say that email newsletters fall on a spectrum of emotional response between “awww yeah!” to “please, no.” I’m sure I’m not the first to frame it this way, though I’ve yet to see anyone else act on that emotional response in how they organize and read through these incoming messages.

Emotional Response Spectrum

Awww yeah!

These are the newsletters that help me stay in touch with the world, my industries of interest, and people I admire. The emotional response for me is one of excited anticipation, I know I’m going to spend a good deal of time on these and will generally enjoy them.

The vast majority of these tend to be of a link roundup variety. People go through quite a bit of trouble sifting through the endless stream of information and share the gold, and I really appreciate that. Some others are deeper dives into current events or a particular topic that I find interesting.

Some of my current favorites:

Alright, thanks.

These are the newsletters that are only occasionally relevant to me, have a certain quality that I appreciate, or otherwise are “okay” enough to open and scan in batches.

Nearly all of these are the daily-ish emails from brands, I regret to admit that most haven’t been unsubscribed because of the occasional emailed coupon. Some select few (like those noted below) I mostly keep around because I enjoy their messaging or find the information useful enough to scan when I can.

Some Examples:

Who Gives a Crap – Great brand that puts a lot of effort into making their mailers enjoyable
USPS Informed Delivery

Please, no.

Basically any mass-email sent to me without my asking for it.

Some examples:

Any newsletters I get auto-added to when I create an account, bonus 👎 points for those that don’t even make it a checkbox option in the sign up form.
Unsolicited messages for products or services past the first three. I give many a pass on a few cold emails when done tactfully, can’t fault someone trying to grow their business.
Extra rage bonus points to any I can’t easily unsubscribe from. One big example was the Ozy Media company, which I continued to get spammed daily until they finally shut down.

Email Organization Strategy

I get an unbelievable amount of emails every day, most I don’t need to spend mental cycles on anywhere remotely near daily. I am – for better or worse – an inbox zero kind of guy, so I’ve honed this strategy over the years to balance the need for a tidy inbox with the need to not be sifting through emails for hours every day.

My Newsletter Rules

I have a few strongly held rules to help maintain a reasonable number of emails coming through:

If I’ve not opened any messages from a particular sender in the last week or last 5 emails , whichever comes first, then I unsubscribe. This one is occasionally hard because I _want_ to like it, but actions speak louder than intentions. Time to go.
If you send more than 2 emails a day , I’m looking for ways to adjust my preferences. If I can’t adjust email frequency I’m out. I can barely count on one hand the reasons I’d be okay with this frequency of messaging.
If you send the same email multiple times, I seriously consider unsubscribing. I’m really sorry, I know email marketing is hard, but it’s not like Twitter where we’re trying to stay fresh in the ongoing stream of posts. Multiples of the same email still need to be handled separately and my patience for that is long gone.

Automated Categorization

Now that I’ve level set on the messages I’m willing to keep, I need to keep that list of messages organized. I use Gmail, though I’m sure this would work with any email organization system worth using. I set up rules for individual sender email addresses to go into one of a few newsletter specific labels:

BAC’N – Anything that doesn’t fit in the below two categories. I call it bac’n because, like spam, bacon is best enjoyed only occasionally.
Daily News – All the world events, financial, and other general daily news I try to consume to stay informed
Industry – All the web development, accessibility, design system, technology, etc. news that keeps me up to date on what’s trending around me professionally.

My newsletter inboxes

These emails are set to skip the inbox and go directly to the selected folder. This way I don’t get notifications of new messages, and I’m able to ignore them until I’m ready. Which brings me to…

Managing my Attention

Great, now I’ve got stacks of organized emails by category. Now, what do I do with them?

BAC’N emails are scanned as quickly as I can manage, I tend to do this about once a week. I take note of sales and any links to articles I may want to read in more detail.
Daily News I try (and often fail) to keep up with every morning. If I miss a few I read the latest and then scan the older ones for any info I may have missed. Given that they tend to be daily news, it’s often updates on ongoing stories so this has worked out pretty well.
Industry emails tend to take me the longest to get through because there are a lot of collections of links to long form articles. I try to chip away at these as I have some time but honestly this is the hardest one to manage because I wanna read _it all_ but it takes a lot of time.

Overthinking it?

Sometimes I do think “this is a lot of consideration for email newsletters”. But I’ve come to the conclusion that the occasional time I put into curating saves me a whole lot more in the long run. Besides, if you don’t control where your attention goes someone else will.

CloudFront Function for basic auth, redirect, and serving from S3

Steven Woodson — Wed, 15 Mar 2023 14:08:28 +0000

I recently had the opportunity to rethink how some CDN customizations were happening within an Amazon AWS managed project. Previously, we had used a couple Lambda@Edge functions to perform some light modifications during the Viewer request and Origin request cache behaviors. We had largely inherited the setup so hitting the reset button with some needed changes seemed a good idea.

Initial CloudFront Function Research

Enter CloudFront Functions, I had actually not heard of them previously but apparently they’ve been around since 2021. After getting up to speed reading up on the use case it seemed an ideal evolution from Lambda@Edge. The parts I was most excited about was reading the following:

offers submillisecond startup times, scales immediately to handle millions of requests per second, and is highly secure

Our use case needed the following:

A huge thank you to Joshua Lyman for writing up Add HTTP Basic Authentication to CloudFront Distributions, it ended up being a great head start to basic authentication I needed (item #1 on the list).

Basic Authentication for all lower environments , because we don’t want public access to content that’s still a work in progress
More control over redirects , because we’re using a JavaScript framework we weren’t able to control the response status as well as we would have liked (301 instead of 302 for example)
Add index.html to request URLs that don’t include a file name , also because we’re using a statically generated site based on a JavaScript framework.

Gotchas

I was initially surprised – coming from the Lambda functions mentality – that I wasn’t able to use a couple of the JavaScript niceties like the Nullish coalescing operator (??), Optional chaining operator (?.), and Conditional (ternary) operator. Found out that that’s because CloudFront functions only support ES 5.1.

I was also pleasantly surprised to see a high focus on optimization and utilization, you even get a handy “Compute Utilization” score every time you test so you can keep tabs on ensuring it’s comfortably within the max allowed time.

While much of these weren’t an issue for me, I also found out that:

Dynamic code evaluation (eval for example) and Timers are not supported.
The maximum memory assigned to CloudFront Functions is 2MB
CloudFront Functions only respond to Viewer triggers whereas Lambda@Edge can work with both Viewer and Origin triggers. In my case I was able to merge the code we were using in both situations without any issue, but your mileage may vary.
CloudFront Functions only support JavaScript (ES 5.1 as noted above), Lambda@Edge supports Node.js and Python too.
CloudFront Functions do not have access to the network or filesystem.
CloudFront Functions can only manipulate HTTP headers.

Benefits

Overall cheaper, and there’s a free tier available too.
Building & testing are so much faster because you can do so directly within CloudFront, no more saving, creating a version, attributing that to the CloudFront cache behavior and deploying to test!
Speed and scalability are amazing, you can support 10,000,000 requests per _second_ or more compared to up to 10,000 requests per second per Region for Lambda@Edge.

If you’re interested in more notes to help you choose which way to go, this Choosing between CloudFront Functions and Lambda@Edge section was really helpful for me.

The Code

Let’s get to work!

Final source

var authRedirect = {
  statusCode: 401,
  statusDescription: "Unauthorized",
  headers: {
    "www-authenticate": {
      value: 'Basic realm="Enter credentials to access this secure site"',
    },
  },
};

/**
 * Basic Authentication
 *
 * On all lower environment (dev & qa) we need basic authentication so general
 * public cannot access these sites. Bypass on prod and if authentication is
 * already secured.
 *
 * @param authorization - Incoming request authorization value
 * @param host - Incoming request host value
 * @returns boolean - Whether this request is authenticated
 */
function authCheck(authorization, host) {
  var productionHosts = ["mywebsite.com", "www.mywebsite.com", "blog.mywebsite.com"];

  // The Base64-encoded Auth string `secretuser:secretpass` that should be present.
  var expected = "Basic c2VjcmV0dXNlcjpzZWNyZXRwYXNz";

  // If this is a production website, we do not want to force any authentication
  if (productionHosts.indexOf(host) > -1) {
    return true;
  }

  // If an Authorization header is supplied and it's an exact match
  if (authorization && authorization.value === expected) {
    return true;
  }

  //Not production, auth header is either missing or failed to match
  return false;
}

/**
 * Redirect Check
 *
 * @param host - Incoming request host value
 * @param requestURI - Incoming request URI
 * @returns object|false - Returns an object containing the redirect details or false if no redirect necessary
 */
function redirectCheck(host, requestURI) {
  redirectPaths = {
    // '[FROM]': {'Location': '[TO]', 'status': [301|302]}},
    "/old-page-1": { Location: "/new-page-1/", status: 301 },
    "/old-page-2": { Location: "/new-page-2/", status: 301 },
    "/old-page-3": { Location: "/new-page-3/", status: 302 },
  };

  if (Object.keys(redirectPaths).indexOf(requestURI) >= 0) {
    var redirectTo = redirectPaths[requestURI];
    return redirectTo;
  }

  return false;
}

/**
 * Redirect Response
 *
 * @param redirectTo - object containing the redirect location and status details
 * @returns object - response object with redirect details
 */
function redirectResponse(redirectTo) {
  return {
    statusCode: redirectTo.status,
    statusDescription: "Moved",
    headers: {
      location: { value: redirectTo.Location },
    },
  };
}

/**
 * URL Rewrite
 *
 * Appends the /index.html to requests that don’t include a file name or extension
 * in the URL. Useful for single page applications or statically generated websites
 * that are hosted in an Amazon S3 bucket.
 *
 * @see https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/example-function-add-index.html
 * @param uri - Incoming request URI
 * @returns
 */
function uriRewrite(uri) {
  // Check whether the URI is missing a file name.
  if (uri.endsWith("/")) {
    return (uri += "index.html");
  }
  // Check whether the URI is missing a file extension.
  else if (!uri.includes(".")) {
    return (uri += "/index.html");
  } else {
    return uri;
  }
}

/**
 * Primary Handler
 *
 * Checks for authentication, then redirect, then URL rewriting
 *
 * @param event
 * @returns
 */
function handler(event) {
  var authorization = event.request.headers.authorization;
  var host =
    event.request.headers.host && event.request.headers.host.value
      ? event.request.headers.host.value.toLowerCase()
      : "";
  var requestURI = event.request.uri.replace(/\/$/, "");

  if (authCheck(authorization, host) === false) {
    return authRedirect;
  }

  var redirect = redirectCheck(host, requestURI);
  if (redirect !== false) {
    return redirectResponse(redirect);
  }

  event.request.uri = uriRewrite(requestURI);

  return event.request;
}

Conserving Sentry Transactions by Ignoring Laravel Routes

Steven Woodson — Tue, 28 Feb 2023 22:37:27 +0000

Yet another case of trying to find an answer to a very particular problem, coming up empty, solving it myself, and posting about it for future generations.

Update 2023-04-01

Thanks to Michi Hoffmann, this is now even easier to manage with a built in ignore_transactions configuration option now available as of release 3.17.0 of sentry-php!

Now, instead of using the before_send_transaction config I swapped to using ignore_transactions and my code changed to the following:

'ignore_transactions' => ['/_debugbar', '/monitoring', '/pleaseignoreme'],

Below is the original post for posterity, but with the addition above that solution is no longer necessary.

The Problem

I have a couple Laravel PHP routes that are triggered quite often, both are very specific to other site monitoring (is the site down?) and session management (am I still logged in?). These being utility routes that don’t serve a user-facing purpose, I don’t need any additional logging details about them from Sentry.

Can I prevent the transaction from being sent to Sentry before it even leaves my server? I tried searching terms like “sentry laravel ignore route” and “sentry control transactions from PHP” to no avail so I got to work.

The Solution

In my searches, I did find this helpful documentation for before_send_transaction specifically for Laravel. It’s an optional addition to the /config/sentry.php configuration. In it, you can define any logic you want to return null in preferred situations. This null return will lead to the event being discarded. Bingo!

Here’s the code I worked up.

'before_send_transaction' => function (
    \Sentry\Event $transaction
): ?\Sentry\Event {
    $ignore = ['_debugbar', 'monitoring', 'pleaseignoreme'];
    $request = $transaction->getRequest();
    $check = array_filter($ignore, function ($url) use ($request) {
        if (stripos($request['url'], $url) !== false) {
            return true;
        }
    });

    if (count($check) > 0) {
        return null;
    }

    return $transaction;
},

Here’s what it’s doing:

$ignore is the array of URL key terms I want to ignore, this is all you need to edit. Add any URL segments that you’d prefer not to be logged by Sentry and you good to go
$request is the request details coming from the packaged $transaction generated by Sentry. In it is the full URL that we use to test against
$check was my method of iterating through the ignore list and checking for a match. This filters the $ignore array down to just matches.
We then see if the count of $check is greater than zero, if so then one of the routes matched and we want to return null to ignore this transaction. Otherwise, return as normal.

That’s it!

Pretty simple, but it took a bit of digging through documentation to find before_send_transaction and through the Sentry package to see what $transaction contained so I’m hoping to spare the next dev that bit of trouble.

Onward and upward! 🚀

DEV Community: Steven Woodson

Web Components in Astro

First Attempt – AstroHeart

Second Web Component Attempt – Sidebar

Passing Props

Scoped vs Global Styles

Live example

Third Attempt – Auto-import Multiple Components

So, I tried again.

Automating imports

Auto-importing at the Layout Level

Performance Implications

Live example

Conclusion

Eleventy Style Guide Generator – Step by Step guide adding to an existing site

Are design tokens required?

Is the use of WebC required?

Naming Collisions

Layouts

Existing components

Can I use a CSS preprocessor like SCSS?

How do I add this to an existing Eleventy site?

Essentials Setup

Copy the following pages to this new folder

Copy the following to your layouts directory

Copy the following into your .eleventy.js config

Copy the foundational CSS & JS

Copy the following data files

Adding Design Tokens

Adding WebC Support & Components

Adding WebC support

WebC Component Structure

Send me your feedback!

Pulling WordPress Post Categories & Tags Into Eleventy

TL;DR

Why?

Adding Categories and Tags to Posts

Getting terms in the REST API response

Organizing the term data

Blog Post Updates

Categories

Tags

New Pages

Gathering Categories and Tags Data

Creating a Blog Post Term Filter

Creating the Category and Tag Pages

Potential Further Enhancements

Eleventy Style Guide Generator with WebC Component Support

TL;DR

Impetus

Design Tokens

Token Definition

Converting to CSS Variables

Visually Itemizing the Tokens

Style Guide Generator

Foundation

WebC Support

Other Conventions

Standalone Documentation Pages

Styling Methodology

Live Site Example

Plans for the Future

Resources

Design Systems, Fluid Typography, Styling Methodologies oh my!

Getting Started with WebC

The Ideal Client and Project – Freelance Introspection

Getting Started

Taking it Social

Alistair Shepherd

Jon Gibbins

How About You?

Steve Woodson – Independent Web Development Consultant

TL;DR

Reflecting on the Last Week

The Dream

Why Now?

Making it a Reality

What’s Next?

Thought Leadership

Be Inclusive

Copy the following into your `.eleventy.js` config