Mike Fallows

Adding an SVG favicon with dark mode support

Wed, 25 Oct 2023 09:00:00 GMT

When I first set this site up I used this technique to add a favicon with the 🥶 (cold face) emoji. This was a great way to have a favicon present without having to stress about designing one, or resorting to my usual default of a black square 🥱. Good enough for now, I thought, I can worry more about it later.

Here's the code I used for that.

<link rel="shortcut icon" href="data:image/svg+xml,%3Csvg%20xmlns%3D%22http%3A%2F%2Fwww.w3.org%2F2000%2Fsvg%22%20viewBox%3D%220%200%20100%20100%22%3E%3Ctext%20y%3D%22.9em%22%20font-size%3D%2290%22%3E%F0%9F%A5%B6%3C%2Ftext%3E%3C%2Fsvg%3E" type="image/svg+xml">

That was fine until I noticed that a search result for my site in DuckDuckGo (my primary search engine at time of writing) didn't support emojis as a shortcut icon. I think partially because it (or Bing or whichever system it uses for it) tries to generate a small self-hosted image for the short cut icon. Drat. Time to do something about it.

I still didn't really want to have to design anything. I can tackle that later if I ever get around to seriously thinking about the visual identity of this site. For now I wanted a small improvement, a kaizen[^1] if you will. So I thought about whether it was possible to get raw SVG versions of emoji. In my search I came across OpenMoji which I'd seen mentioned before. It provides open source versions of emoji that are available as coloured or outlined SVG files. Perfect!

I decided to switch from 🥶 (cold face) to 👾 (space invader/alien monster) as I really liked the image by Antonia Wagner, and it worked well in outline. I decided to go for outline so that I didn't have to commit to a colour. I also wanted to implement dark mode support to the SVG and I though it would make doing that simpler.

Dark mode support

Adding dark mode support was pretty simple. First I replaced all hardcoded colour references to currentColor so I could control the colour more reliably through CSS. eg.

- <rect ... stroke="#000000" ... />
+ <rect ... stroke="currentColor" ... />

Then I added some CSS in the body of the SVG file by using a <style> tag inside a <defs> tag. That CSS simply applied a black stroke to all the visual elements in the SVG, and using an @media rule, switched that to white when a visitor is in dark mode.

<svg ... >
  <defs>
    <style>
      rect, path, line, polyline {
        stroke: black;
        color-scheme: light dark;
      }
      @media (prefers-color-scheme:dark) {
        rect, path, line, polyline {
          stroke: white;
        }
      }
    </style>
  </defs>
  ...
</svg>

That's it! And here's the cute little critter in all its dark-mode-detecting[^2] glory.

And here's the code in full.

<svg id="emoji" viewBox="0 0 72 72" xmlns="http://www.w3.org/2000/svg">
  <defs>
    <style>
      rect, path, line, polyline {
        stroke: black;
        color-scheme: light dark;
      }
      @media (prefers-color-scheme:dark) {
        rect, path, line, polyline {
          stroke: white;
        }
      }
    </style>
  </defs>
  <g id="line">
    <rect x="25.175" y="31" width="3.6" height="6" fill="none" stroke="currentColor" stroke-linecap="round" stroke-linejoin="round" stroke-width="2"/>
    <polyline fill="none" stroke="currentColor" stroke-linecap="round" stroke-linejoin="round" stroke-width="2" points="22,45 16,45 16,39"/>
    <polyline fill="none" stroke="currentColor" stroke-linecap="round" stroke-linejoin="round" stroke-width="2" points="22.583,25 22.583,20 26,20"/>
    <polyline fill="none" stroke="currentColor" stroke-linecap="round" stroke-linejoin="round" stroke-width="2" points="48.708,25 48.708,20 45.292,20"/>
    <polyline fill="none" stroke="currentColor" stroke-linecap="round" stroke-linejoin="round" stroke-width="2" points="13,35 10,35 10,20 16,20 16,35"/>
    <polyline fill="none" stroke="currentColor" stroke-linecap="round" stroke-linejoin="round" stroke-width="2" points="56,35 56,20 62,20 62,35 59,35"/>
    <polyline fill="none" stroke="currentColor" stroke-linecap="round" stroke-linejoin="round" stroke-width="2" points="26,20 26,14 32,14 32,20"/>
    <polyline fill="none" stroke="currentColor" stroke-linecap="round" stroke-linejoin="round" stroke-width="2" points="39,20 39,14 45,14 45,20"/>
    <polyline fill="none" stroke="currentColor" stroke-linecap="round" stroke-linejoin="round" stroke-width="2" points="16,35 19,35 19,38 13,38 13,35"/>
    <polyline fill="none" stroke="currentColor" stroke-linecap="round" stroke-linejoin="round" stroke-width="2" points="59,35 59,38 53,38 53,35 56,35"/>
    <rect x="16" y="51" width="6" height="6" fill="none" stroke="currentColor" stroke-linecap="round" stroke-linejoin="round" stroke-width="2"/>
    <rect x="50" y="51" width="6" height="6" fill="none" stroke="currentColor" stroke-linecap="round" stroke-linejoin="round" stroke-width="2"/>
    <polyline fill="none" stroke="currentColor" stroke-linecap="round" stroke-linejoin="round" stroke-width="2" points="28,45 28,51 22,51 22,45"/>
    <polyline fill="none" stroke="currentColor" stroke-linecap="round" stroke-linejoin="round" stroke-width="2" points="50,45 56,45 56,39"/>
    <polyline fill="none" stroke="currentColor" stroke-linecap="round" stroke-linejoin="round" stroke-width="2" points="44,45 44,51 50,51 50,45"/>
    <rect x="43.425" y="31" width="3.6" height="6" fill="none" stroke="currentColor" stroke-linecap="round" stroke-linejoin="round" stroke-width="2"/>
    <path fill="none" stroke="currentColor" stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M44,45L44,45z"/>
    <path fill="none" stroke="currentColor" stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M39,20L39,20z"/>
    <path fill="none" stroke="currentColor" stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M16,25L16,25z"/>
    <path fill="none" stroke="currentColor" stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M49,25L49,25z"/>
    <line x1="28" x2="44" y1="45" y2="45" fill="none" stroke="currentColor" stroke-linecap="round" stroke-linejoin="round" stroke-width="2"/>
    <line x1="32" x2="39" y1="20" y2="20" fill="none" stroke="currentColor" stroke-linecap="round" stroke-linejoin="round" stroke-width="2"/>
    <line x1="16" x2="22" y1="25" y2="25" fill="none" stroke="currentColor" stroke-linecap="round" stroke-linejoin="round" stroke-width="2"/>
    <line x1="49" x2="56" y1="25" y2="25" fill="none" stroke="currentColor" stroke-linecap="round" stroke-linejoin="round" stroke-width="2"/>
  </g>
</svg>

And here's the code I needed to add to the head. As I was switching to using an external SVG file I noticed that I needed to add the sizes="any" to get it to show up properly.

<link rel="shortcut icon" href="/public/alien.svg" type="image/svg+xml" sizes="any">

All in all, a neat little way to get a dark mode supporting favicon!

[^1]: To 'change for better'. A business concept that refers to small incremental improvements. Wiki article. [^2]: Note: this only responds to the system dark mode, not the personal setting for the site because the colour scheme depends on the browser's chrome not the site's design.

Optimising CSS minification in Liquid

Tue, 24 Oct 2023 23:00:00 GMT

2025-09-22 Update: David Warrington posted about using the recently released inline_asset_content filter to liquid (see docs) to minify assets. This filter will automatically minify CSS (and JavaScript) files when they are inlined so I'm updating to use that technique instead.

One of the mailing lists I subscribe to is I Only Speak Liquid, where they regularly publish emails from their stable of developers with some great insights into working on Shopify themes and more generally working as a freelancer/consultant in the Shopify ecosystem. If you're looking for good content on those subjects, I definitely recommend subscribing.

One tip mentioned in an email by Billy Noyes was a way to use Liquid to minify CSS. The technique was provided by a community member in this forum post. It's a great way to remove unnecessary characters (like whitespace and comments) from a CSS file without the need for an additional build tool, so it's a low effort way to increase a site's performance by reducing its page weight.

Original

Here is the initial implementation (rewritten slightly to make comparison easier, and added some comments to explain what's happening):

{% capture bloated %}
/* CSS ... */
{% endcapture %}

<!-- CSS {{ bloated.size }} chars -->
{%- liquid
  assign original = ''
  # remove line breaks,
  # multiple whitespace characters and
  # split on closing comment tags
  assign chunks = bloated | strip_newlines | split: ' ' | join: ' ' | split: '*/'
  # iterate over each chunk of CSS
  for chunk in chunks
    # remove comments and whitespace around syntax characters
    assign mini = chunk | split: '/*' | first | strip | replace: '; ', ';' | replace: '} ', '}' | replace: '{ ', '{' | replace: ' {', '{'
    assign original = original | append: mini
  endfor
  # calculate characters saved
  assign change = original.size | times: 1.0 | divided_by: bloated.size | times: 100.0 | round: 1
%}
<!-- original    -{{ bloated.size | minus: original.size }}   {{ 100 | minus: change }}%  -->

This alone was providing me with a 10% reduction across most of the CSS I tried it on. However, having looked at the code, I thought I could see an opportunity to improve on it very slightly, and wanted to see if there were any meaningful gains to be made. I noticed that the final semicolon in a ruleset was being preserved, but it can safely be removed. If you have only 100 rulesets that could still save up to 100 characters. That extra bit of code was replace: ';}', '}'.

Test

I wanted to find out how much of a difference this made on a real codebase, and also test that nothing would break as a result, so I set up the following test. I used a 5,000+ lines CSS file from one of my projects to test the results.

{% capture bloated %}
// 5000+ lines of CSS
{% endcapture %}

<!-- CSS {{ bloated.size }} chars -->
{%- liquid
  assign original = ''
  assign chunks = bloated | strip_newlines | split: ' ' | join: ' ' | split: '*/'
  for chunk in chunks
    assign mini = chunk | split: '/*' | first | strip | replace: '; ', ';' | replace: '} ', '}' | replace: '{ ', '{' | replace: ' {', '{'
    assign original = original | append: mini
  endfor
  assign change = original.size | times: 1.0 | divided_by: bloated.size | times: 100.0 | round: 1
%}
<!-- original    -{{ bloated.size | minus: original.size }}   {{ 100 | minus: change }}%  -->

{%- liquid
  assign optimised = ''
  assign chunks = bloated | strip_newlines | split: ' ' | join: ' ' | split: '*/'
  for chunk in chunks
    assign mini = chunk | split: '/*' | first | strip | replace: ': ', ':' | replace: '; ', ';' | replace: '} ', '}' | replace: '{ ', '{' | replace: ' {', '{' | replace: ';}', '}'
    assign optimised = optimised | append: mini
  endfor
  assign change = optimised.size | times: 1.0 | divided_by: bloated.size | times: 100.0 | round: 1
%}
<!-- optimised   -{{ bloated.size | minus: optimised.size }}   {{ 100 | minus: change }}%  -->

Results

Here are the results:

<!-- CSS 121066 chars -->
<!-- original    -12829   10.6%  -->
<!-- optimised   -16091   13.3%  -->

Nice! An extra 300+ characters removed equating to over 2.5% more of a reduction. The output CSS worked perfectly still. For very little effort or intervention, a 10%+ reduction is a great result, and will benefit almost any project.

Extracting to a snippet

Finally to wrap it up I created a snippet called minify-css.liquid so that I can easily add this feature to any large CSS files as well as to snippets and sections that may also contain large chunks of CSS that could benefit from minification.

{%- liquid
  assign chunks = input | strip_newlines | split: ' ' | join: ' ' | split: '*/'
  for chunk in chunks
    assign mini = chunk | split: '/*' | first | strip | replace: ': ', ':' | replace: '; ', ';' | replace: '} ', '}' | replace: '{ ', '{' | replace: ' {', '{' | replace: ';}', '}'
    echo mini
  endfor
%}

So it can even be used like this:

<style>
{%- capture bloated %}
// Unminified CSS
{%- endcapture %}

{%- render 'minify-css', input: bloated -%}
</style>

Now I can maintain beautiful, well documented, human-readable CSS code across an entire theme and still have it optimised for performance without any additional build tools.

Avoiding a DOMContentLoaded gotcha with readyState

Mon, 23 Oct 2023 15:00:00 GMT

I hit one of those strange issues where a script failed sometimes and only in Safari.

It was on a Shopify theme - in this case I was modifying some of the HTML in the header of a site via JavaScript, but didn't realise that in some cases the theme's JavaScript was also modifying some of the same parts of the DOM. I had also moved the code from being inline to an asychronously loaded script, and had dutifully wrapped it in a DOMContentLoaded event listener, patted myself on the back and got on with the day.

That was until, the inevitable it's not working email landed. It turned out that Safari, and possibly only certain versions of Safari, would call the DOMContentLoaded event in an unreliable way (compared to other browsers) and was therefore executing my script unpredictably. The end result was that the modifications I wanted to make to the DOM weren't taking place, and I think it was down to the DOMContentLoaded event being triggered before all scripts were loaded. A little hunting on Stack Overflow and I managed to find this trick (which I'm recording here as a note to self).

function init() {
  // code to run on load...
}

if (document.readyState === 'loading') {
  // document still loading...
  document.addEventListener('DOMContentLoaded', () => {
    init();
  });
} else {
  // already loaded, chocs away!
  init();
}

It essentially checks to see if the browser reports that it's still loading via document.readyState (docs) and if so, registers the DOMContentLoaded event listener. If not, then it can safely be assumed that the event has already been fired, in which case, we run the code immediately. For convenience you can wrap all the code you wanted to run in a function (in this example, init).

I'm not sure if this only relates to Safari (although it seems to be more commonly reported that way) and/or I've just been lucky enough that I've not run into it before, but it's handy to have in the toolbox to keep things more robust.

Prefill a Shopify discount with the Fetch API

Mon, 23 Oct 2023 10:00:00 GMT

Shopify has a method for prefilling discounts at checkout. It's designed to allow a merchant to share a link for marketing purposes so that visitors using the link will conveniently have the discount applied at checkout rather than having to remember the spelling of the code, or get frustrated with typos. The discount link takes the format <SITE URL>/discount/<DISCOUNT CODE>.

Visiting that link will store a discount code in a browser Cookie (to be read later at the checkout), and then redirects the visitor to the homepage[^1] so that the whole process feels seamless.

Why not use an Automatic Discount?

Shopify also supports Automatic Discounts that don't rely on having a specific code applied at checkout. Unfortunately, there are some limitations to Automatic Discounts, so certain discounts can only be achieved when requiring a code.

Just use `fetch`

There are also some cases where traffic may already be inbound to a specific page and there's no opportunity to use the /discount/ link directly. For that case (and the one above) I set up a simple section that a client can add to any page to make a 'visit' invisibly with a fetch request and have the discount prefilled. I chose not to directly manipulate or create the Cookie myself as that would involve a lot more code and as the format of the Cookie is not documented, it's also more likely to change without any notice and silently break. So this simple one-liner does the job and should be well supported.

Here's the code with section settings that allow it to be added to your OS2 templates.

{%- if section.settings.discount_code != blank -%}
<script>fetch('/discount/{{ section.settings.discount_code }}');</script>
{%- endif -%}

{% schema %}
{
  "name": "Prefill discount",
  "class": "shopify-section--prefill-discount",
  "tag": "section",
  "settings": [
    {
      "type": "text",
      "id": "discount_code",
      "label": "Discount code"
    }
  ],
  "presets": [
    {
      "name": "Prefill discount"
    }
  ]
}
{% endschema %}

Caveats

Shopify will only store and apply one prefilled discount at checkout, so keep in mind that if a visitor already has another discount stored in a Cookie, that will then be overridden if they visit a page with the section prefilling the discount. So be careful not to leave expired or unwanted versions of these sections live on the site as you may unintentionally overwrite another code!

[^1]: Actually, it's even better, you can add additional parameters to the link to redirect to another part of your site besides the homepage, as you can see in the docs.

Implement a low stock notice in a Shopify theme

Thu, 19 Oct 2023 23:00:00 GMT

I recently needed to implement a small feature on a Shopify theme to display a low stock notice.

Requirements

This was a quick task that simply needed to display a low stock notice when the selected variant was below a certain threshold, and reflect the change when another variant was selected. For example, given the following scenario:

low stock threshold is 5
product has two variants: Standard and Deluxe
Standard has 20 items in stock
Deluxe has 3 items in stock

The notice should only show when the Deluxe item is selected and it should include the number of units left in stock, i.e. "3 in stock".

Demo

Here's a demo (try selecting Deluxe):

Considerations

Because this theme had the option to display variants as a select dropdown, or as radio options that acted like buttons to select the variant, I decided to look for a way I could make this feature generic enough to work with both. I noticed both versions would dynamically update a hidden variant input to reflect the chosen variant's ID. This made it easy to observe changes to that ID and to know when to update the notice and identify the currently selected variant.

The code

As I wanted to enable this as a section (so that it could be used conditionally on different templates), I could use Liquid to store the variant stock quantities in a JavaScript variable[^1].

const inventory = [
  {%- for v in product.variants %}
    { id: '{{ v.id }}', quantity: {{ v.inventory_quantity | json }} },
  {%- endfor %}
];

Assuming that the HTML structure of the page is something that could be boiled down to a simplified structure like this:

<div class="product">
  <form>
    <input type="hidden" class="product-variant-id" value="123">
    <select name="id" class="options">
      <option value="123">Standard</option>
      <option value="456">Deluxe</option>
    </select>
  </form>
</div>

Then the script would look like this:

<script>
  window.addEventListener('DOMContentLoaded', () => {

    // Initial config
    const threshold = 5;
    const productSelector = '.product';
    const optionsSelector = '.options';
    const hiddenVariantIdInputSelector = '.product-variant-id';
    const initialVariantId = '{{ product.selected_or_first_available_variant.id }}';

    // Store stock quantities
    const inventory = [
      {%- for v in product.variants %}
        { id: '{{ v.id }}', quantity: {{ v.inventory_quantity | json }} },
      {%- endfor %}
    ];

    // Find the root product element
    const productEl = document.querySelector(productSelector);
    if (!productEl) return;

    // Find the options selector (we will append our low stock notice container to this)
    const optionsEl = productEl.querySelector(optionsSelector);
    if (!optionsEl) return;

    // Append the notice container
    optionsEl.insertAdjacentHTML('afterend', `<div class="stock-notice"></div>`);

    // Method to update the content of the notice container
    // if the stock is not above the threshold
    function updateMessage(variantId) {
      const stockNoticeEl = productEl.querySelector('.stock-notice');
      if (!stockNoticeEl) return;
      let message = '';
      const variant = inventory.find(i => i.id === variantId);
      if (variant && (variant.quantity > 0 && variant.quantity <= threshold)) {
        message = `${variant.quantity} in stock`;
      }
      stockNoticeEl.textContent = message;
    }

    // Update the message on first page load
    updateMessage(initialVariantId);

    // Find the input that is updated with the selected id
    const hiddenVariantIdInputEl = productEl.querySelector(hiddenVariantIdInputSelector);
    if (!hiddenVariantIdInputEl) return;

    // Watch the input for changes and update the message in response
    hiddenVariantIdInputEl.addEventListener('change', (e) => updateMessage(e.target.value));

  });
</script>

Other considerations

I ended up adding the inventory threshold as a section setting so that it could be populated through a value stored on the product as a metafield. I also added some styling to the message, and made the message customisable, ie. the message could take the format "Hurry, only {count} left in stock!", where {count} would be dynamically replaced by the remaining stock quantity.

This is the way

What I particularly liked about this implementation was that it didn't require editing a single existing theme file. It's an approach that I try to prioritise as much as possible as it has multiple benefits for working within a codebase.

In the past I might have been tempted to update the theme's JavaScript to insert this functionality where the code dynamically changes the selected variant. Or add it into the variant selector's Liquid file. Certainly that might have been a more direct approach. However, the maintenance burden is likely to be much greater whenever you want to upgrade the theme (especially if you do a lot of point upgrades) when having to diff/re-apply these types of changes every time. Worse when it's to a large file like the theme's main JavaScript file.

By isolating this feature to its own file, it makes it easier to delete it completely if the theme implements its own version of the feature, or identify how that feature works or needs to be changed, fixed or improved. Even if a new version of the theme handles quantity changes differently, the only thing that is likely to change is one of the selectors, or how to observe the selected variant (maybe through a MutationObserver or detecting changes to parameters in the uri) which is a much smaller change to make.

I've found life much easier customising themes with this approach.

[^1]: Note that I store the id as a string for comparison later (thanks to @ThomasAndrewMacLean). I've also used the json filter to help make sure that a value suitable for a JavaScript object should always be output (probably overkill as it's unlikely that Shopify will ever change this API, but I try to do this as a best practise).

Quick error reporting with Val Town

Mon, 21 Aug 2023 12:00:00 GMT

This post was updated on 24th October 2023 to reflect the changes in Val Town v3.

Recently I needed to quickly inspect a script running in the 'Additional Checkout Scripts' portion of the order thank you / status page for a Shopify client. These are copy-paste scripts and there's no easy way to manage them, and it's particularly difficult to test them properly without running real orders. The client was seeing some odd data in their reporting and suspected that there might be some occasional errors with one of the scripts, but it was hard to work out when or why this might be happening.

Welcome to Val Town

I'd recently heard about the features of val.town – a new project that enables you to quickly create javascript functions with a public API endpoint, and some neat features like a small amount of storage and an email notification system, even on their free plan.

I was honestly blown away by how quickly I could add some observability to a script this way. At the heart of it, Val Town lets you build some serverless functions via the web browser using an interface that will be familiar if you've used GitHub gists.

All I wanted to do was be able to log a minimal amount of data whenever the script runs and let Val Town notify me by email if an error was detected in the script so I can investigate it.

Creating a store

First, let's create a store:

export let store = [];

Yep, that's literally it. Val Town will let you add up to 100kb of data to that value (on its very reasonable free tier), at which point it will begin to truncate the data. This is plenty for my purposes as I'm only storing an order id and at most I'm only interested in a few dozen of the latest records.

Still, it might be useful to have a way to empty our store (let's say you potentially fill the store up with lots of dummy data while preparing to write a blog post 👀), so you can create an additional Val with the following snippet. Note that we're importing set from Val's standard library to update the value of one of our other Val's by reference. Also note that it's constructed as an IIFE to make sure that the function is invoked when you 'run' the Val.

Just beware that when you run this Val, the results may not appear instantly (ie. your store won't be cleared out straight away so wait a few moments to see the results).

import { set } from "https://esm.town/v/std/set";

export const clear = (async () => {
  await set("store", []);
})();

Creating an endpoint

Finally, the cool part: a Val that serves as our web endpoint to receive the data from our script. Here, we're accepting three arguments, subject, message and an optional error. The subject and message will be added to the store, and if an error is present it will also use the email function from the standard library to send me an email. Val will only send emails to the email address of the account. This is a totally acceptable limitation, but I guess if you needed to notify others you could set up a forwarding filter.

You should also note that I'm importing my store Val so that I can append to it and then use the set function to update the Val with the new contents.

import { email } from "https://esm.town/v/std/email";
import { set } from "https://esm.town/v/std/set";
import { store } from "https://esm.town/v/<user>/store";

export async function report(subject, message, error = false) {
  store.push({ subject, message });
  await set("store", store);
  if (error) {
    await email({
      subject: `Error: ${subject}`,
      html: `<pre>${message}</pre><hr><pre>${error}</pre>`,
    });
  }
}

Remember to click the lock icon on the Val to convert from a 'private' Val. Private Val's need an API key that you wouldn't want to leak publicly.

A note on security

By making the Val unlisted (or public) you can send unauthorised web requests. For the purpose of knocking up some temporary logging on a protected part of the internet (a checkout thank you page) you have some security through obscurity, but it's not enough for general purpose, so just keep this in mind. I'm certainly not storing or transferring any sensitive data (only an order id reference), and I'm aware that the endpoint could be abused to spam me at which point I'd have to take measures to defend against that if it were the case (like, change the Val's endpoint?). If you make the Val 'public' (as opposed to unlisted) you make it available to other Val users to reference inside their Vals.

Sending data to Val Town

With that in place, you will need to add some code to format your data and send the request to the API endpoint that Val Town provides. Here I'm storing the strings for the subject and message data I want to store (Shopify's Liquid syntax will replace the {{ shop.url }} and {{ order_id }} dynamically). I append any error that is thrown in the script that I want to test and finally, use the fetch method to send this data to Val Town. Anything you include in the args parameter will be passed as arguments to the Val.

let report = [
  `Order on {{ shop.url }}`,
  `order_id: {{ order_id }}`,
];

try {
  // main script to test
} catch (error) {
  report.push(error);
}

fetch("https://api.val.town/v1/run/<username>.report?args=" + JSON.stringify(report));

With this tool you can have a simple mechanism for reporting how and when a script runs and an email notification for errors. I can see plenty of ways this could be augmented to capture more information or to create additional Vals to inspect the store, like looking for duplicate order IDs being logged. As Val Town has a built-in 'Interval' system you could even periodically run Vals to clear your log, or aggregate the data and email yourself a summary.

Val Town is very cool.

Links #5

Wed, 16 Aug 2023 23:00:00 GMT

Worthy of note.

Wonky, an audio story by Michelle McGhee It's always great to find truly interactive content that takes full advantage of being on the web. As a huge fan of Dilla and someone that has next to no musical education, I found this a wonderful explanation of why his music hits differently.

CSS HD Gradients Killer tool to let you build out high definition gradients leveraging the oklch colour scheme. Anyone who remembers working on optimising GIFs and battling 'strobing' effects in certain gradient colour combinations, will appreciate that oklch provides much more natural (to the human eye) gradation points between colours.

Don't Compare Averages Great article by Martin Fowler detailing the flaw in the (often tempting) method of comparing sets of averages, and how misleading the results can be.

Alan Braxe in studio As someone who's musical awakening came at the height of French House this is a fascinating glimpse of how those tracks were made and how much the style was defined by the technology they were using. A reminder that cruder tools can be limiting, but are often more fun to play with! The impact of personal computers on DIY music soon ushered in almost unlimited abilities to create and source sounds, but so often the friction and imeadiacy inspires much greater creativity in some.

Midjouney takes on Sol LeWitt's Wall Drawings I remember being fascinated by the concept of LeWitt's wall drawing instructions and years ago having a conversation with a technician that installed a LeWitt at a gallery in Manchester. There's something really interesting in the boundaries established in the instructions that allow a little bit of personal interpretation so that the outcome isn't entirely predictable, but you can still see all the drawings as both the same and entirely unique. A great task for an AI prompt. Also, lol at it utterly refusing to draw wavy vertical lines.

Subscribe Wherever You Get Your Podcasts Great observation on how podcasts have delivered on the principle of an open web, and maybe how else that can be expanded to other aspects of the online experience.

Observing cart changes in a Shopify theme

Mon, 06 Mar 2023 00:00:00 GMT

Recently I needed to write some code to monitor and respond to changes made to a Shopify cart. The script would need to be added to several themes and be independent of the specific theme the site used or potential apps that were (or would be) installed.

This presented a challenge as cart interactions can take many forms and vary across themes. For example, as well as a dedicated cart page most sites have some sort of dynamic 'Ajax' cart. Many can also have apps integrated with the theme that enable products to be added to the cart in different ways.

I've often seen crude attempts to solve this by adding event listeners to the 'Add to cart' button on the product page. But this falls down once you consider things like 'Quick Buy' or 'Upsell' features, or take into account that simply clicking an 'Add to cart' button doesn't guarantee a product is actually added to the cart. Problems like network request errors, or items becoming sold out come into play and it quickly becomes complicated.

Detecting changes to the cart

To solve this I opted to record requests to both the cart page, and the /cart/* endpoints used to dynamically mutate the cart. This would mean that regardless of which part of the theme or an app was updating the cart, I would be able to detect and react to it.

Determining if a request is made to the cart page is easy enough as you can just inspect the location or type of the current page.

In Liquid you can access the type of page from the request object.

const page_type = {{ request.page_type | json }};

It's a bit more complicated to watch for dynamic requests, but you can do that with a PerformanceObserver that filters on resource-based performance activity, and within that modern fetch requests as well as the older xmlhttprequest type.

The observeCartChanges function below

loops over entries to the PerformanceObserver
checks if the entry is an Ajax request
checks if the endpoint of the request contains /cart/[^1]

Finally, it initiates the observer restricted to only resource entries.

function observeCartChanges() {
  const cartObserver = new PerformanceObserver((list) => {
    list.getEntries().forEach((entry) => {
      const isValidRequestType = ['xmlhttprequest', 'fetch'].includes(entry.initiatorType);
      const isCartChangeRequest = /\/cart\//.test(entry.name);
      if (isValidRequestType && isCartChangeRequest) {
        // handle cart request
      }
    });
  });
  cartObserver.observe({ entryTypes: ["resource"] });
}

Determine the changes to the cart

Now that we have a way to observe when the cart is changed we next need to determine how the cart has changed.

At first, I considered inspecting the endpoint that was requested, eg. cart/add.js and assume that the items in the payload had been added to the cart. However, just because the request has been made is no guarantee that it was successful. It could be an invalid request such as an out-of-stock item or use badly formed data.

I decided the better approach is to track the current state of the cart and, given a request to mutate the cart, get the latest version and figure out what changes have been made. I chose to use a fetch request to get the latest cart state and track it in local storage for reference.

Retrieving and storing cart state

Here's a quick example of fetching the current cart, as well as storing and then retrieving it from local storage:

const response = await fetch('/cart.js');
const cart = response.json();
localStorage.setItem('cart', JSON.stringify(cart));
const storedCart = JSON.parse(localStorage.getItem('cart'));

Identifying items that have been added or removed

Next, to work out whether items have been added or removed from the cart, I created a function that accepts the old cart items (eg. retrieved from local storage) and some new cart items (eg. retrieved from a fetch request) and returns a tuple of the added and removed items. To do this, I find the items present in the new cart that are not present in the old cart and stored these in the added array. Next, I do the inverse and check for items in the old cart that no longer exist in the new cart to determine what has been removed, and stored them in the removed array.

It starts getting a bit complicated to read here as I've used some quite generic terminology like l and r for left and right, and used li to represent the items on the left-hand side. I try to avoid this type of naming, but as this is just a simple algorithm for comparing arrays, the terseness is okay for me. Fortunately, because Shopify applies a unique key property to each line item in the cart, it's easy to check whether the current line exists in both carts. The onlyInLeft function takes the two carts and filters out any items in the left cart that exist in the right cart.

Here's an example of how that function could look:

function findCartChanges(oldCart, newCart) {
  const onlyInLeft = (l, r) => l.filter(li => !r.some(ri => li.key == ri.key));
  return {
    added: onlyInLeft(newCart.items, oldCart.items),
    removed: onlyInLeft(oldCart.items, newCart.items),
  };
}

Identifying items that have been updated

So far, so good. But this still doesn't take into account quantities of exiting line items being increased or decreased.

For example, if a customer already has Product X in their cart and then adds another Product X then I want to record that item in the added array with a quantity of 1 (to represent the quantity added to the previous state of the cart). I considered adding a third property to the returned object with a key of updated, but the distinction wasn't necessary for my use case. Quantity changes could be recorded in the relevant added and removed properties.

To do that, I assign the original calculations to a result variable. That allows me to iterate over the new cart's items and look for matching lines (by key) that exist in the old cart, but have a different quantity value. I can then calculate the difference between the two quantities – a negative value means the quantity was reduced and a positive value means increased. So I can make a copy of the line item, update its quantity to an absolute number of the calculated value (so that negative numbers become positive), and then push that item onto the correct property of the result object.

Here's how that looks:

function findCartChanges(oldCart, newCart) {
  const onlyInLeft = (l, r) => l.filter(li => !r.some(ri => li.key == ri.key));
  let result = {
    added: onlyInLeft(newCart.items, oldCart.items),
    removed: onlyInLeft(oldCart.items, newCart.items),
  };

  oldCart.items.forEach(oi => {
    const ni = newCart.items.find(i => i.key == oi.key && i.quantity != oi.quantity);
    if (!ni) return;
    let quantity = ni.quantity - oi.quantity;
    let item = { ...ni };
    item.quantity = Math.abs(quantity);
    quantity > 0
      ? result.added.push(item)
      : result.removed.push(item)
  });

  return result;
}

Wrapping up

Here's an example of wrapping it all up into a CartWatcher class with an init method to handle fetching current cart details in case there have been changes between requests and setting up the observer for dynamic requests. The emitCartChanges method fires a custom event with the details of the changes whenever the cart is updated. This allows me to build several features that can independently listen and respond to changes in the cart without having to repeat this code. If I needed more flexibility I could add the ability to configure things through the constructor such as the keys used in the events and local storage (if I was worried about collisions).

class CartWatcher {

  init() {
    this.emitCartChanges().then(() => {
      this.observeCartChanges();
    });
  }

  async fetchCart() {
    const response = await fetch('/cart.js');
    return response.json();
  }

  storeCart(cart) {
    localStorage.setItem('cart', JSON.stringify(cart));
  }

 storedCart() {
    return JSON.parse(localStorage.getItem('cart')) || { items: [] };
  }

 findCartChanges(oldCart, newCart) {
    const onlyInLeft = (l, r) => l.filter(li => !r.some(ri => li.key == ri.key));
    let result = {
      added: onlyInLeft(newCart.items, oldCart.items),
      removed: onlyInLeft(oldCart.items, newCart.items),
    };

    oldCart.items.forEach(oi => {
      const ni = newCart.items.find(i => i.key == oi.key && i.quantity != oi.quantity);
      if (!ni) return;
      let quantity = ni.quantity - oi.quantity;
      let item = { ...ni };
      item.quantity = Math.abs(quantity);
      quantity > 0
        ? result.added.push(item)
        : result.removed.push(item)
    });

    return result;
  }

  async emitCartChanges() {
    const newCart = await this.fetchCart();
    const oldCart = this.storedCart();
    const changes = this.findCartChanges(oldCart, newCart);

    const event = new CustomEvent("cart_changed", { detail: changes });
    window.dispatchEvent(event);

    this.storeCart(newCart);
  }

 observeCartChanges() {
    const cartObserver = new PerformanceObserver((list) => {
      list.getEntries().forEach((entry) => {
        const isValidRequestType = ['xmlhttprequest', 'fetch'].includes(entry.initiatorType);
        const isCartChangeRequest = /\/cart\//.test(entry.name);
        if (isValidRequestType && isCartChangeRequest) {
          this.emitCartChanges();
        }
      });
    });
    cartObserver.observe({ entryTypes: ["resource"] });
  }
}

Here's a quick example of newing up the class and adding a listener for the cart_changed event that will log out the changes to the cart whenever it is updated.

const myCartWatcher = new CartWatcher;
myCartWatcher.init();
window.addEventListener("cart_changed", e => console.log(e.detail));

You could of course use this to provide some feedback to the customer, log some data in analytics or provide an offer based on the change to the cart.

[^1]: According to the Cart API docs, regardless of the locale, the endpoints that mutate the cart all contain /cart/ eg. /{locale}/cart/add.js, /{locale}/cart/update.js, etc.

Add a custom domain to CloudFront with Cloudflare

Tue, 28 Feb 2023 00:00:00 GMT

After trying and failing to get this to work several times I thought I'd record the particular setup that worked for me. The main thing I've learned is that there are a lot of moving parts and layers of caching so sometimes it just takes some patience. Now I've finally succeeded, I intend to apply this to several sites mainly to decouple myself from the default AWS CloudFront domain.

With some of the sites I look after, static assets such as images are stored in an S3 bucket and I've set up CloudFront as a CDN, but I want my assets served from a nice domain name that I control, rather than the default one supplied by CloudFront.

Pick a domain for the CDN

Pick the domain you want to use. Ideally, you should use a subdomain of the site's primary domain. If there are some access issues with managing the DNS of the site's primary domain, then you may want to reserve another generic domain for this purpose. Using the same top-level domain might help you operate a stricter CORS setup if you need it. A prefix like cdn. is a sensible option. For this post, let's assume it's cdn.project.tld.

Set up a new SSL certificate in ACM

Assuming that you already have an S3 bucket set up and are using CloudFront, then the next step is to create a custom SSL certificate with AWS Certificate Manager (ACM). You can access this via the AWS console. There are a couple of things that I read were important to keep in mind when setting this up. Regardless of which region your bucket is located in, the SSL certificate should be located in the us-east-1 region.

In ACM choose to request a certificate. The Certificate type should be set to 'Public', and use the domain you picked earlier, eg. cdn.project.tld. Use the DNS validation method so the certificate can auto-renew, and pick the default/recommended 'Key algorithm' (I don't know if this matters).

Validate the CDN via Cloudflare

When you view the new certificate in ACM, it will provide you with a CNAME key-value pair. Log into Cloudflare and create this new DNS record. The CNAME record should not be proxied. Note that the name that you copy from AWS will include the top-level domain, so make sure that you correct that before creating the record on Cloudflare (it's quite long so the end can be obscured in the input field). I like to add a note here in Cloudflare for the record too, something like 'AWS CloudFront SSL Certificate'.

Once you've created the record, check back on ACM and see if the certificate has updated its status from 'Pending' to 'Issued'. It might take some time, but in my experience, it worked pretty much instantly.

Assign the SSL certificate

Now you can assign the SSL Certificate to your CloudFront distribution, so head over to CloudFront in AWS, and locate the relevant distribution. Edit the General Settings. This is where you can assign the alternate domain name you want to use instead of the default CloudFront-assigned URL. In this case, it's cdn.project.tld. Now select the SSL certificate you just created. Choose the recommended Security policy and add the additional supported HTTP versions (I don't see any harm). I keep the logging setting off, and IPv6 on. I also like to add a description eg. CDN for project.tld.

Create the DNS records for the custom domain

In Cloudflare, create the CNAME record for custom CDN domain (in this case cdn.project.tld) and set the target as the CloudFront distribution domain that was used previously. It looks something like abc123.cloudfront.net. Don't proxy this domain and let CloudFront handle all the caching[^1].

Test, test again and be patient

To test this, try accessing a CloudFront asset through the new domain e.g. where it might have been https://abc123.cloudfront.net/image.png, try https://cdn.project.tld/image.png. Again, this could take a few minutes to work, and sometimes it might stop working for a bit, and then work again, so I usually leave it overnight to propagate (48 hours if you really want to feel safe).

If it's still not working, double-check that you haven't set up the last step as a proxied domain. This seems to be the part that takes the longest to resolve if you've made a mistake, so you may need to check back in a few hours. Sometimes when I'm finding DNS records I like to try and flush the cache of the problem record in Google's public DNS. I honestly can't tell whether it makes a difference but sometimes it's just nice to experience the placebo effect from doing it 😉.

[^1]: I'm sure there's a way to set this up which uses CloudFlare to proxy requests to CloudFront or even directly to the S3 bucket. That might be useful particularly if you're serving things like your CSS or JS from S3 and want the benefits of Brotli compression that Cloudflare provides. Cloudflare also gives you a global cache on the free tier, whereas a global cache in CloudFront is more expensive than limiting it to North America and Europe. For my needs it's fine.

Detect subscription orders in the Shopify checkout

Fri, 17 Feb 2023 00:00:00 GMT

This week I needed to help a client distinguish which orders contained subscriptions so they can measure the results of their PPC[^1] advertising. As their business model is heavily geared towards subscriptions and subscriptions will typically indicate a much higher LTV[^2], measuring which adverts are more likely to generate subscription purchases is a key metric.

It was a bit harder than I expected, and that's down to the limited amount of data available on the 'Thank You' page of Shopify's checkout.

The result

Here's the final logic that I used in the additional scripts part of the checkout:

# track subscriptions
assign includes_subscription = false
for line_item in line_items
  if line_item.selling_plan_allocation.selling_plan.name contains 'Delivery every'
    assign includes_subscription = true
  endif
endfor

That will check if any of the line items on an order include a subscription purchase and give you a nice variable you can use to conditionally fire an event, or pass as a value to Google Tag Manager.

For example, to fire a Meta pixel 'Subscribe' event:

{%- if includes_subscription == true %}
  fbq('track', 'Subscribe');
{%- endif -%}

To include as a dataLayer variable.

dataLayer.push({
  event: 'purchase',
  ecommerce: {
    // ...
    'includes_subscription': {{ includes_subscription | default: false }},
    // ...
  }
});

Why the hacky inspection of selling_plan.name?

As I mentioned earlier, you're a bit limited with the data you can access on the initial 'Thank You' page that you're presented with immediately after placing an order. That's because the full order hasn't been created yet due to the potential delays in building up the order in a background task.

It's also very hard to test the Thank You page, as to my knowledge you can't simulate it, so you have to place a live order to test each code change. Initially, I ran my tests by visiting the status page of an order that had already been placed. The 'Order Status' page has access to the entire order object which, you can use to find out if selling_plan.recurring_deliveries is set to true. That appeared to be the most robust way to identify subscription orders. Unfortunately, the only field available on the 'Thank You' page is selling_plan.name.

As far as I could tell, at least in my client's case (English language only checkout), the selling plan name for a line item would always begin 'Delivery every' as in, 'Delivery every 1 week', 'Delivery every 2 weeks', etc. The other types of selling plan names would not.

Why not use Customer Events?

There certainly was the option of using a Checkout Completed Customer Event instead of the checkout additional scripts. And while I welcome the introduction of this feature, I've found it much harder to test as the delay between making changes and seeing those updates reflected in the shop have been unpredictable.

[^1]: Pay Per Click: display advertising through platforms like Google or Meta where you pay for the amount of traffic the advert drives to your website. [^2]: Life Time Value: the total amount spent by an individual customer over their lifetime.

Adding search to an Eleventy site

Wed, 08 Feb 2023 00:00:00 GMT

TL;DR I went with Pagefind and followed this solution by Robb Knight which I had running locally after about 10 mins. Sure, I lost an hour or so deploying it because I'd got my node versions out of sync, but that's to be expected.

Finding my search solution

Weirdly, I've found that I seem to read the posts on this site more than I write them. I say read, but I just mean referring to the stuff I've written because it has left my head. For a long time I've tried to keep some developer notes in my note-taking app de jour, but those often tend to be quick copy-paste bits of code with perfunctory captions, and the habit of properly writing up technical notes on this blog has been more useful than I imagined. As there are only a couple dozen posts it's pretty easy to navigate to the information I'm looking for from the homepage. Still, I'm a developer, so that extra effort seems like something I can waste an afternoon resolving.

It was also an academic exercise as I've only ever had to implement very simple search solutions that query a database (hello LIKE %%), or the platform I'm working on has already implemented it. I wasn't sure how you would handle this on a static site. I assumed it would mean some sort of serverless function or using a third-party integration. The fact that there's a solution that just crawls your site, looks for HTML attributes to decide what to add to the file-based index, and then queries that client-side is so simple in its genius. That's essentially what Pagefind does. It also ships with a little Svelte-based search UI component that you can drop-in and customise with a few CSS variables. It makes it very easy to integrate with low performance footprint.

Honourable mention

When I was casting about for solutions I found some older posts by Raymond Camden, one on adding Lunr to an Eleventy site and one on using Algolia. Ultimately, both those posts came with caveats, but they both seem like viable solutions. Lunr is not that different to PageFind, but it perhaps needs a bit more setup to install on Eleventy. Algolia has a great reputation, but I didn't see the need to use an external service given the modest size of this site.

One of the things I'm particularly enjoying about Eleventy is the ease of finding well written up solutions, and getting to tinker with them.

The search page is now live.

Links #4

Tue, 07 Feb 2023 00:00:00 GMT

Interesting bits from around the web.

Visit for a surprise. A great example of thinking deeply about the nuances involved in ensuring the web is accessible to as many people as possible without just ticking "accessibility" checkboxes. Context is key.

AARRR. A nice pirate-y acronym to help you remember "acquisition, activation, retention, referral, and revenue". I find this useful when looking at a client's site and other touch-points to try and find opportunities to leverage improvements. You can be certain that there's always one point that can benefit from more attention.

Before YouTube's algorithm there were "coolhunters". An article in The Atlantic about the way the YouTube homepage was curated by hand. I think there's a lot to be said for having a strongly opinionated editorial direction on the web, I try to encourage this with homepages and merchandising online shops. There are some potential downsides (you can't please everyone and you run the risk of gatekeeping) but human elements in a digital world stand out.

How YouTube killed IE6. I was reminded of this article in The Verge about the actions of a small group of engineers at YouTube in the early days that helped accelerate the demise of Internet Explorer 6, and I don't blame them one bit. Bonus, there's a picture of a client in the screen grab of YouTube's homepage. There's also a Twitter thread somewhere that I can't find for the life of me, but was an interesting tale of Pinterest's human curated homepage in the early days.

AI is not the problem. Obviously, it's the hot topic, and there's plenty of opinions around, but this one struck a chord. I recently listened to the 2021 Reith Lectures on the BBC which had some interesting discussion around the ethics of AI from a time before ChatGPT and Stable Diffusion become part of the discourse.

Hello World with Lit

Mon, 24 Oct 2022 00:00:00 GMT

The world of Web Components seems to be getting more attention recently so I've been exploring some of the frameworks emerging around it. Here are some notes on my initial experience with Lit (specifically version 2).

Aims

Build a small web component that can:

render some HTML
accept some data as a property
have a button that can mutate that data
style the component
expose some styling

That's pretty much 90% of what I've been doing with Web Components.

Getting set up

The first thing I did was head over to the docs. They provide some interactive tutorials in a REPL which look great but for whatever reason, was behaving slowly when I visited. I also wasn't sure if Lit required a build step so I decided I'd rather try to get something running locally (like the boomer I am).

This turned out to be the most confusing part for me because my preferred way of learning involves watching a screencast and hopefully copy-pasting or re-typing some code into my editor and viewing the results. The Lit introductory screencast I found on YouTube used TypeScript and I'm not all aboard the TypeScript train yet. I wanted a more apples-to-apples approach to the way I currently write my Web Components so I realised I was going to have to bumble through on my own a bit.

This is not to criticise Lit, I think it's marketing itself as an alternative to developers coming from the React ecosystem and that seems perfectly reasonable. I'm personally coming from a "sprinkles"[^1] background so there are some gaps I have to acknowledge.

Rendering a component

After some back and forth trying to make things much more complicated than I needed to, I ended up with a minimal HTML page that registered a Lit component:

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>Lit Test</title>
  <script type="module">
    import { html, LitElement } from 'https://cdn.jsdelivr.net/gh/lit/dist@2/core/lit-core.min.js'

    class HelloWorld extends LitElement {
      render() {
        return html`<p>Hello world</p>`;
      }
    }

    customElements.define('hello-world', HelloWorld)
  </script>
</head>
<body>
  <hello-world></hello-world>
</body>
</html>

Great, I have a page that renders a <p>Hello world</p> in the shadow DOM of the <hello-world> element. By the way, that Lit Core library comes in at just over 16kb at the time of writing – time to find out what affordances that payload gets me!

Of note here is that the render function and the html helper are taking care of a few things under the hood and allowing for the use of tagged template literals. For comparison, here's the boilerplate you would need to write the same functionality without Lit.

class HelloWorld extends HTMLElement {
  constructor() {
    super();
    this.attachShadow({ mode: "open" });
    let p = document.createElement('p');
    p.innerText = 'Hello world';
    this.shadowRoot.append(p);
  }
}

Passing properties

I found the Lit docs a bit confusing here, mainly because the script examples only included the JS portion without the HTML element and attribute I was looking for. It also opens with examples using decorators which require a build step (they are still only a proposal). I'm unfamiliar with the syntax and I wasn't sure whether this was a Lit requirement or something to do with TypeScript but it turns out you can achieve the same thing by defining a static properties object.

class HelloWorld extends LitElement {
  static properties = {
    name: { type: String }
  }
  render() {
    return html`<p>Hello ${this.name || 'world'}</p>`;
  }
}

Allows you to do:

<!-- output: Hello world -->
<hello-world></hello-world>
<!-- output: Hello you -->
<hello-world name="you"></hello-world>

Mutating the data

That's all good, but how about adding some behaviour to the component? This is where Lit's use of tagged template literals helps to make things so much easier. Using @click allows you to create an event listener and remove the need for a whole host of boilerplate to register elements, insert them into the DOM, attach events to them, as well as managing the component's state. I made a simple button to add exclamation marks to the name property with a couple of lines of code.

class HelloWorld extends LitElement {
  static properties = {
    name: { type: String }
  }
  constructor() {
    super();
    this.name = "world";
  }
  makeLouder() {
    this.name = this.name + '!'
  }
  render() {
    return html`
    <p>Hello ${this.name}</p>
    <button @click=${this.makeLouder}>Louder</button>
    `;
  }
}

Styling

Because Lit uses the Shadow DOM, it isolates your styling from the rest of the document by default. Making it easy to style your component without worrying about parent styles leaking in, or clashing with other styles. Lit offers a handy css function to help manage these styles. This may initially break some syntax highlighting in your editor, but there's a selection of VS Code extensions that add syntax support for Lit.

You can apply styling to the root component element using the :host selector. You can even set styles conditionally based on the state of the element. You can interpolate variables into the css function eg. the fontFamily variable set outside the component, and you can expose certain values by declaring CSS variables.

import { css, html, LitElement } from 'https://cdn.jsdelivr.net/gh/lit/dist@2/core/lit-core.min.js'

const fontFamily = css`sans-serif`;

class HelloWorld extends LitElement {
  static styles = css`
    :host {
      display: block;
      padding: 1rem;
      background: var(--background, #eee);
    }
    :host(.blue) {
      background: aliceblue;
    }
    p {
      font-family: ${fontFamily};
    }
  `;
  render() {
    return html`<p>Hello world</p>`;
  }
}

<!-- Background #eee -->
<hello-world></hello-world>
<!-- Background aliceblue -->
<hello-world class="blue"></hello-world>
<!-- Background goldenrod -->
<style>
hello-world {
  --background: goldenrod;
}
</style>
<hello-world></hello-world>

Thoughts

So far my use case for Web Components often means creating one-off, quite simple components that need to be portable (ie. dropped into Shopify themes), where it doesn't necessarily make sense to add Lit as a dependency. However, for future projects that might need to make use of multiple Web Components, the small penalty of including Lit will surely be worth it for the reduced boilerplate and, I believe easier to read, code.

[^1]: The JavaScript "sprinkles" approach is a largely undefined term that tends to refer to a backend-driven site or app that includes a small amount of JavaScript added to the front end for client-side activity (as opposed to a fully-fledged SPA). It usually implies using small bits of custom JS, or micro-frameworks like Stimulus, jQuery or Alpine.

Links #3

Mon, 05 Sep 2022 00:00:00 GMT

A recent reading list.

How to ask good questions. A great reminder of how to seek help successfully. The focus is on getting help on technical subjects in a team environment, but it could easily be extrapolated to any subject or situation with plenty of useful lessons about good communication in general.

The World's Most Satisfying Checkbox. A neat example of how small interactions can be elevated. When working on transactional sites, micro-interactions can be a great opportunity to explore identity can be expressed beyond colours, fonts and messaging. It's also a good reminder of how much attention these interactions automatically receive in the world of game design.

Prioritize What You Do. This is a fantastic list for retailers on where to prioritise efforts. It's easy to become distracted by novel techniques and forget to give precedence to the basic principles of selling online. Personalisation is the only thing I would caveat because, in my experience, it can create unneeded complexity and make customer experiences more opaque and harder to empathise with (although this largely depends on the nature of your products).

Conditional Border Radius In CSS. A neat trick to toggle border-radius in CSS based purely on a container element's width. Something to tide us over until Container Queries are supported.

Adding a `robots.txt` file to an Eleventy site

Thu, 01 Sep 2022 00:00:00 GMT

Having set up a fair few sites over the years, I periodically get a chunk of emails from Google's Search Console notifying me of indexing errors. Usually, these are pretty small potatoes caused by things like old products being unpublished and will resolve themselves on the next crawl.

I realised I hadn't yet set up a robots.txt file for this site when a couple of errors popped up in Search Console that I wouldn't have expected. The errors I had were for:

https://mikefallows.com/cdn-cgi/l/email-protection
https://mikefallows.com/admin/

I had already set up a sitemap.xml file but somehow overlooked creating a robots.txt file at the time. The /admin/ URL was easy for me to identify, that is for my Forestry integration which I use as a CMS. That page has a noindex meta tag in the head.

<meta name="robots" content="noindex" />

I was mistaken

I was under the impression that would be enough to signal to Search Console that it should be ignored, but it turns out that it's being included in my sitemap.xml so it's (quite rightly) marked as invalid.

The other URL that started /cdn-cgi/l/email-protection was more of a mystery. I hadn't added anything in a /cdn-cgi/ folder! The fact that it contained a reference to a CDN was a clue, so I wondered if it was related to Netlify, but I couldn't think of an obvious reason why it would have any reference to emails. After a bit of quick research, I realised this was related to Cloudflare which I'd recently set up for the site. As I had activated their proxy in front of the site, it explained the unknown folder and it appears to be a part of their bot protection.

So to fix these validation errors in Search Console I needed to:

add a robots.txt file that disallows /admin/ and /cdn-cgi/
exclude /admin/ from my sitemap.xml

Adding a `robots.txt` file

This is super-easy in Eleventy. I created a file: src/robots.txt; and added the following to my .eleventy.js config:

// Put robots.txt in root
eleventyConfig.addPassthroughCopy({ 'src/robots.txt': '/robots.txt' });

The addPassthroughCopy method will just copy the file "as is" into the generated _site folder. Great.

My robots.txt file looked like this:

User-agent: *
Allow: /
Disallow: /admin/
Disallow: /cdn-cgi/

Host: https://mikefallows.com/

Sitemap: https://mikefallows.com/sitemap.xml

The important parts were the two Disallow rules that tell bots that they shouldn't try to crawl or index those paths in their results.

You can also view whatever the current version is.

Excluding pages from `sitemap.xml`

My sitemap is generated by a single sitemap.xml.njk file:

---
permalink: /sitemap.xml
eleventyExcludeFromCollections: true
---
<?xml version="1.0" encoding="utf-8"?>
<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
{%- for page in collections.all %}
  {%- set adminUrl = r/^\/admin\//i.test(page.url) %}
  {%- set draft = page.data.draft %}
  {%- if not adminUrl and not draft  %}
    {%- set absoluteUrl %}{{ page.url | url | absoluteUrl(metadata.url) }}{% endset %}
    <url>
      <loc>{{ absoluteUrl }}</loc>
      <lastmod>{{ page.date | htmlDateString }}</lastmod>
      <changefreq>{{ page.data.changeFreq if page.data.changeFreq else "monthly" }}</changefreq>
    </url>
  {%- endif %}
{%- endfor %}
</urlset>

This generates an XML file for all pages, excluding any pages where the URL begins /admin/ or is marked as a draft. I usually default my posts to draft until I'm ready to publish them. Draft posts are excluded by checking if the frontmatter has draft value set to true.

The key bit was writing the Regex to test that a URL begins /admin/:

set adminUrl = r/^\/admin\//i.test(page.url)

Just to break that down:

r/ regular expressions in Nunjucks need to be prefixed with r
^ indicates we're only matching the start of the string
\/admin\/ literally matches /admin/
/i makes the test case insensitive (y'know, just in case)

What I find most enjoyable about having my own site is having the time to tinker and dig through these types of issues. When they're low pressure like this one, it's great to spend a little time polishing and learning in a way that I often miss in client work. For such a small task, I solidified my knowledge just a little bit more about Eleventy, Sitemaps, Regex, and Robots files and that's mostly due to taking the time to write it up.

Compiling `.kit` files with Grunt

Thu, 11 Aug 2022 00:00:00 GMT

This week I needed to hand over some files to another development team. I was originally commissioned to create some email templates way back in early 2013 for Campaign Monitor and, apart from some small tweaks and additions, the templates have hardly changed since. You can view an archived version of one of the earliest. But this is a better one. Design credit to my good friend Eóin MacManus.

The templates made some heavy use of <repeater> regions, a feature of Campaign Monitor's templates that I utilised to allow multiple sections with different colour backgrounds. Because this was email, it required a lot of inline CSS and a lot of code repetition to achieve the desired result. I was using CodeKit a lot at the time and the app had just introduced the .kit file feature. Kit files added variables and imports to HTML via CSS-style comments which reduced the amount of code I needed to write substantially.

This worked great for the best part of a decade as the sole developer on the project: I could easily make a small adjustment and compile the files quickly with my copy of CodeKit.

Now that I needed to pass the files on to another team, I wanted to do so without the requirement of a proprietary app to compile the templates. A quick search and I discovered there was an open source node-based compiler for .kit files and a Grunt plugin that leveraged it. I was aware of Grunt as an alternative task runner to something like CodeKit and it had a reputation for having a straightforward build pipeline so it seemed like a good solution.

First I installed Grunt and the CodeKit plugin:

npm i -D grunt grunt-codekit

Then I set up a simple Gruntfile.js config file that would compile my newsletter template to HTML:

module.exports = function(grunt) {

  grunt.initConfig({
    codekit: {
      'build/newsletter/newsletter.html': 'src/newsletter/newsletter.kit'
    },
  });

  grunt.loadNpmTasks('grunt-codekit');

  grunt.registerTask('default', ['codekit']);
};

Now all I needed to do was run grunt at the root of the project and my src/newsletter/newsletter.kit file would be converted to HTML at build/newsletter/newsletter.html. Easy as that!

When you add a new template to Campaign Monitor you need to upload the HTML template and also any images the template uses as a separate zip file. Now that I'd got this far I figured I could make that final step easier too. First I installed the grunt-zip plugin:

npm i -D grunt-zip

Then I added the zip task to my Gruntfile so that my images were zipped into my build folder ready to be uploaded.

module.exports = function(grunt) {

  grunt.initConfig({
    codekit: {
      'build/newsletter/newsletter.html' : 'src/newsletter/newsletter.kit'
    },
    zip: {
      'build/newsletter/img.zip': 'src/newsletter/img/*'
    }
  });

  grunt.loadNpmTasks('grunt-codekit');
  grunt.loadNpmTasks('grunt-zip');

  grunt.registerTask('default', ['codekit', 'zip']);

};

There are potentially a bunch more steps I could add like optimising the images and minifying the HTML but as Campaign Monitor already applies its own optimisations there's no need to overengineer this solution (as much as I'd love to).

Laravel Sail, Vite and SSL with a custom domain

Fri, 29 Jul 2022 00:00:00 GMT

The Shopify apps I build are typically powered by Laravel. Version 8 introduced Sail[^1] as an alternative to Valet and version 9 introduced Vite[^2] to replace Laravel Mix (Webpack). I ran into an issue developing my Shopify apps locally when I tried to switch to using these new features.

Using a custom domain

Giving each project its own development domain is a great feature of Valet. Sail assumes a default laravel.test domain but allows you to override that in the Docker config. If you wanted to use a domain such as myproject.test you can make a couple of changes to achieve that.

In your .env file set the APP_URL value and add a new Sail-specific APP_URL value:

APP_URL="http://myproject.test"
APP_SERVICE="myproject.test"

Then update the docker-compose.yml file to reflect the new domain, changing laravel.test to myproject.test.

version: '3'
services:
  myproject.test:
    build:
    # etc...

Securing the domain with Caddy

Because Shopify requires secure URLs for its Oauth integration, I followed this guide by Gilbert Pellegrom to enable HTTPS for Sail using Caddy. I won't repeat the steps here, but it involves adding a Caddy service to Docker, creating a custom Caddyfile and setting up an endpoint for Caddy. Gilbert's post kindly provides a gist with some example code you can drop in. The only changes you would need to make is replacing any references to laravel.test with myproject.test.

You will also want to update the APP_URL in your .env file to use https now:

APP_URL="https://myproject.test"

I also found I needed to add a line to the AppServiceProvider's boot method to force all links to use HTTPS. Without that, at least on my machine, routes or URLs generated with the url() helper would use the HTTP scheme instead.

public function boot()
{
    \Illuminate\Support\Facades\URL::forceScheme('https');
}

Now running sail up should give you a server you can access at https://myproject.test. However, you may find that the certificate is untrusted. If you don't want the warnings to keep appearing and you're on a Mac, you can add the certificate to your Keychain Access and mark it trusted. Details on how to do that are also included in Gilbert's guide.

Securing Vite's dev server

The last issue I bumped up against was that, by default, Vite will run its dev server on HTTP, which means that the browser wouldn't load the styles and scripts on my pages. It's possible to set Vite to load its server under HTTPS, but it won't have a certificate. You can use the @vitejs/plugin-basic-ssl plugin to generate untrusted certificates which will allow you to access the page, but you will need to first dismiss a warning. You can follow the steps in this Stack Overflow answer to set your Vite config's host settings to allow it to run on the Docker container. This is how I set it up at first, but dismissing the warning and seeing the red badge in the address bar bothered me.

I also tried to figure out a way to get the Vite server to use the Caddy certificates but I couldn't work it out. That is probably the best solution so if you figure it out – please let me know!

The alternative I went with was to use the vite-plugin-mkcert package. This allows you to generate a trusted certificate locally on-the-fly. The one compromise is that you have to run the Vite server outside the Docker container (ie use npm run dev rather than sail npm run dev). In my case, that is acceptable as I'm not using it to build the production assets and the Vite server is probably going to run faster outside of Docker too. What I decided to do was to use a dedicated subdomain of my project eg. vite.myproject.test for the Vite server so that I didn't have any conflicts with existing certificates or other projects.

My final vite.config.js file looked like this:

import laravel from 'laravel-vite-plugin'
import { defineConfig } from 'vite'
import mkcert from'vite-plugin-mkcert'

export default defineConfig({
    server: {
      https: true,
      host: 'vite.myproject.test',
    },
    plugins: [
        mkcert(),
        laravel({
          input: [
            'resources/css/app.css',
            'resources/js/app.js',
          ],
          refresh: true,
        }),
    ],
})

Now when I start work on a project I can run sail up -d && npm run dev and have my app running locally with trusted HTTPS along with all the speed and Hot Module Reloading goodness of Vite.

[^1]: "A light-weight command-line interface for interacting with Laravel's default Docker development environment". Recently I've preferred to use Docker over Laravel Valet as I'm regularly switching between projects with different PHP versions and database engines, as well as working locally on either Intel or Silicon hardware. [^2]: "A modern frontend build tool that provides an extremely fast development environment". I've never really been comfortable with Webpack configs. Mix was a much simpler wrapper, but with esbuild under the hood, Vite seems to be so much faster.

Bulk deleting Cloudflare DNS records

Mon, 25 Jul 2022 00:00:00 GMT

I've recently been trying to consolidate some of the services that I use, a sort of technical spring clean if you will. In summer.

As well as transferring domains that I own to a single provider, I wanted to have a single point of management that would also work for domains that I don't own, but happen to manage on behalf of clients. I've long been wanting to tinker with Cloudflare as it offers a chunk of nice features like DDoS protection, asset compression, HTTPS and email routing, all on a pretty generous free plan. So far I've found it easy to work with, and after migrating a dozen or so domains to it, I've had a pretty good opportunity to try it out.

When you set up a new 'site' in Cloudlflare, you give it a domain and it will try to detect all the A records and create those for you. It does also seem to detect a couple of other records, but in most cases I've had to manually add some records myself, usually to do with email and third-party verification (DMARC, SPF, etc.). You can also import records from a text file, but for my needs adding a couple of extra records helped me review any obsolete records that existed anyway.

The problem

The only real issue I ran into was that for a couple of domains, on importing them to Cloudflare, it detected and created dozens of A records for standard terms eg. 1, 2, 3 ... a, app, apps ... www1, www2, etc. Nearly 200 unused records in total on one domain. The Cloudflare UI doesn't currently offer any ways to remove DNS records in bulk, so the process of removing so many manually, and on several domains made me look for a solution.

A fix

Fortunately one of the other benefits of Cloudflare is that it offers a Rest API which allows you to delete DNS records programmatically. I was able to put together a script to delete the unused records on one of my domains pretty quickly. I already knew I was going to be repeating this task on other domains, and that there would be some different requirements for each, so of course, I ~~wasted some time~~ did the sensible thing and put together a little repo that could be configured. I haven't done much PHP recently so it was also an excuse to flex that muscle. It's still my favourite scripting language for putting something together quickly.

I honestly couldn't figure out why this happened on some domains and not others, there wasn't anything I could identify as the root cause. Maybe you're here because you've encountered the same problem? If so hopefully this script might help you out!

Handling dark mode in HTML emails

Sat, 16 Jul 2022 00:00:00 GMT

Recently I needed to customise an HTML email template written in Pug. This was my first time using Pug and I was pleasantly surprised to find it intuitive and with a few useful features to help organise some reusable components. Its terse syntax is also handy for email templates, as supporting current email clients (even in 2022!) means that you still need to work with deeply nested tables to achieve even the simplest of layouts.

Although CSS support in email is improving, there's still a range of mail clients that are hard to test, so resources like Can I email... are invaluable in helping identify which features are widely supported. For example, my first thought was to use SVG and then define the colours in CSS. Unfortunately, the support at this point is still lacking, so it does require creating multiple versions of images that you need inverting for your design.

I've noticed that some email clients (particularly on mobile), will do their best to apply a dark theme to emails, and sometimes the results can be less than satisfactory. In this case, the company's branding was monochrome, so it gave me an opportunity to easily adopt a dark mode alternative as the colour scheme was so simple.

Declaring dark mode support

The first thing to do is indicate that the email supports both light and dark mode. You can declare this in a <style> tag within the head of a document.

:root {
  color-scheme: light dark;
  supported-color-schemes: light dark;
}

It's then possible to use a media query to detect the mode that mode.

@media (prefers-color-scheme: dark) {
  /* styles for dark mode... */
}

Providing alternative colours

As a fallback for clients that may not support alternative colour schemes, I set my light styles first and then used the media query to override those styles for dark mode. Pug allows you to store values in a variable that can be interpolated into strings. Normally on a web page, I would use CSS Variables (Custom Properties) but support for that is still patchy for emails.

I created a set of variables for my "default" colours, and then a matching set of alternative "inverted" colours. This helped keep everything symmetrical and made it easier not to miss any elements that I needed to account for in dark mode.

Here's a basic example declaring some default colours for the element with a class of .document that I used for the root of my email, and then declaring the inverted colours for dark mode.

.document {
  background-color: #{defaultBgColor};
  color: #{defaultTextColor};
}

@media (prefers-color-scheme: dark) {
  .document {
    background-color: #{invertedBgColor} !important;
    color: #{invertedTextColor} !important;
  }
}

Handling alternate images

There are only some images that need to be handled for dark mode, and these were graphic elements that essentially match the text and background colours of the design.

The strategy I used to handle these was to wrap the light and dark versions of images in a span element with a class to identify which mode the image was supposed to appear in. I used the wrapping span to declare some width and height values which had the added bonus of keeping these graphic images sharp on high-density screens.

Using a Pug mixin you can create a function to return the HTML with both images - note the span with a class of .light-mode-images wraps logo.png and .dark-mode-images wraps logo-inverted.png.

mixin logo()

  span.light-mode-image(style='width:180px;height:64px;')
    img(src='#{assetUrl}/logo.png' alt='Acme' width='360' height='128')
  span.dark-mode-image(style='width:180px;height:64px;')
    img(src='#{assetUrl}/logo-inverted.png' alt='Acme' width='360' height='128')

Now we can use some generic CSS rules to handle the correct display of images by toggling between display: block and display: none.

span.light-mode-image {
  display: block;
}

span.dark-mode-image {
  display: none;
}

@media (prefers-color-scheme: dark) {
  span.light-mode-image {
    display: none !important;
  }

  span.dark-mode-image {
    display: block !important;
  }
}

Other considerations

For this relatively simple template, I only had to generate one other mixin function for a graphic element (an arrow) and handle some link colours. In this case, the template was defaulting to system fonts. If it was using a custom font then it might be worth adjusting weights as light-on-dark text can often appear heavier than dark-on-light.

Because the design was essentially black and white, it was easy to decide which colours needed swapping and what the alternative would be. Once you start getting into lighter colours the decision about the alternatives becomes a bit harder to decide, so testing and image generation can increase the workload, and accessibility concerns may require more attention.

In the end, I was pleased I managed to get an effective result with a relatively low number of lines of code. Better still, I got an appreciation of how much potential work would be involved in a more complicated design!

You can check out a finished email for Australia's best record shop.

Links #2

Thu, 12 May 2022 00:00:00 GMT

A list of articles which have recently grabbed my attention.

Optimising Largest Contentful Paint. The really interesting part of this for me is that pop-ups (aka Facehuggers) which typically prompt you for your email, if big enough, will be considered the LCP. A lot of these are delayed on purpose, but the speed test won't distinguish that so you are artificially signalling to Google that your page is slow.

Favicons in 2021. The plethora of shortcut icon formats that have been introduced, has tended to make me nope out of providing anything beyond a simple 64x png and cross my fingers. With wide support for SVG things seemed to have calmed down, so this seems like a manageable amount of work to do on new projects.

Putting Ideas into Words. I started this blog as an experiment to see if I could improve my writing, and help me to clarify some of my nebulous ideas and document things that I've learnt (so that maybe it will stick better). One of the best side effects is that writing about something forces me to test my assumptions before committing them to the world wide web.

Lou Ottens Interview. A very technical interview from 2013 with the inventor of the compact cassette who passed away in 2021. There's an interesting parallel to the web world in terms of developing standards and how they are often trumped by popularity. Lou on the Dolby B format: "I was afraid that it would cause a lot of confusion in the market. And I think I was right. But being right is not always good enough. Ray Dolby came to visit me and I gave my arguments, but he went on. Lesson: you cannot stop progress..."

Omnichord OM-27. Not an article, but a fun little experiment by Jake Albaugh that makes use of the Web Audio API. Make the music with your mouse, Biz.

Making a Shopify Theme App Extension for Google Site Verification

Wed, 23 Feb 2022 00:00:00 GMT

Given that I'm all in on Shopify's OS2 themes, I've been looking for a way to experiment with building the recently introduced "app extensions" for themes. These extensions provide a way to add functionality to Shopify themes without the need to change the underlying theme code itself.

Assuming you already have a Shopify Partner account and the Shopify CLI installed, then it's incredibly simple to get started with theme app extensions. As a small project to get familiar with them, I set myself the task of creating an app that allows you to insert a tag to verify a site with Google. Although I tend to recommend verifying via DNS records, sometimes it's more suitable to include a meta tag in the <head> of the site.

Theme app extension benefits

Normally adding a verification tag would mean editing all of the /layout files in a theme like theme.liquid and password.liquid . Once those files are edited it also means maintaining those changes any time you update the theme. Using a theme app extension reduces this burden.

Shopify hosts the code for the extensions on their servers so performance is great and, as a developer, you don't have to worry about standing up servers or deployments.

The verification tag

The tag in question is very simple and has the following format:

<meta name="google-site-verification" content="UNIQUE_ID">

I want to be able to have a theme block that allows adding the client's UNIQUE_ID as a setting in the theme's customisation UI, and once set rendering a valid tag in the <head> portion of the site.

Creating the app

Extensions must be associated with an app so you need to create an app first if you don't have one set up already. The easiest way is to use the CLI's app create command. You can pick which starter template to work with, eg. Node, PHP, etc. I went for Node, but it's not particularly important because I'm not worried about creating any UI for the app right now.

shopify app create node

Next, I supplied a name for the app. I just picked something generic: 'Theme Blocks'. It will also ask you which type of app you want to create, for simplicity I picked 'Custom' which means it can only be installed on one specific store.

That created an app and output a link to it in the Partner dashboard. It also provided a link to a page in the dashboard where I could install the app in my chosen store. I didn’t do that though (yet).

Creating the extension

There are two types of theme app extensions. Standard “App blocks” and “App embed blocks”. It’s the embed blocks that I’m interested in as they allow you to insert code into the <head> portion of the document. You can learn a bit more in Shopify's Getting Started Guide.

A theme app extension should be created within the app project itself. This isn't actually that explicit in the documentation so, at first, I wasn't sure if it should be treated as a separate project in its own repo. Don't make the same mistake. At the root of the project I ran:

shopify extension create

I was prompted to choose the app I wanted to associate the extension with and I, of course, picked the one I was currently working on. The next question was about which type of extension I wanted to create for which I selected “Theme App Extension”.

The project now contained a folder called theme-app-extension scaffolded with empty assets, blocks, locales and a snippets folder, along with a .env file and .shopify-cli.yml file.

Building a block

Okay, now for the block code itself. I created a blocks/google-verification.liquid file with the following contents:

{%- if block.settings.google_verification_id != blank %}
<meta name="google-site-verification" content="{{ block.settings.google_verification_id }}">
{%- endif %}

{% schema %}
{
  "name": "Theme Customisations",
  "target": "head",
  "settings": [
    {
      "type": "text",
      "id": "google_verification_id",
      "label": "Google verification ID"
    }
  ]
}
{% endschema %}

This should make sense if you're familiar with Shopify's theme sections. Essentially I'm defining some settings that can capture the information I need and dynamically insert that data where I need to.

Note the target is set to head and I’m rendering the tag only on the condition that a google_verification_id is provided.

Publishing the extension

Now I can cd into the theme-app-extension folder and run

shopify extension push

The following dialogue allowed me to register the extension and update the .env file, then run any validation before pushing it to Shopify. Once it’s pushed, it outputs a link to the app in my Partner dashboard where I can version and publish it. Here I can also enable a development store preview so I can test the changes.

I can now go to a theme in my development store, and in the theme customiser under Theme Settings > App Embeds I can see my new app block sitting there waiting to be enabled. Genuine thrill when stuff like this just works™.

To test it, I enabled the block, added a dummy verification ID, hit save and checked the output theme code. Sure enough, in the <head> tag, before the standard Shopify content_for_header output, I can see the verification tag output using the data I added.

Nice. I’ve managed to modify a theme without having to change any of the underlying theme templates themselves.

Updating the extension

Shopify lets you work in 'draft' mode, and has a workflow to publish versions of your extension in production so you can push as many changes as you want, and safely test updates in your development store.

Connecting the extension

To simulate collaborating on an extension I checked out the project repository on another machine and was able to populate the .env file by running:

shopify extension connect

Some notes

It’s worth mentioning that changing the filename of any of the extensions will lose any settings previously created in a theme. So will changing any of the ids in the schema settings in the same way that they would if you were using theme sections. I would want to give this some consideration if I was building a public app.

You can only have one theme extension per app, but I'm not sure if there's a limit to the number of blocks it can have. I might want to be conservative with the number of blocks I created in a public app, but the blocks themselves might be more complex as a result. For custom extensions, I might prefer to have more, simpler blocks to make it easy to add new blocks and make them more portable between clients too.

Overall, I'm super impressed with the experience of creating my first theme app extension, and I intend to use it a lot as a tool to add theme customisations in future.

Using PostCSS and Autoprefixer with esbuild

Tue, 15 Feb 2022 00:00:00 GMT

In a previous post, I described how to use esbuild as a bundler for Shopify themes.

In this post, I want to document an additional step to use a tool called Autoprefixer (a PostCSS plugin) which will automatically add browser vendor prefixes to your compiled CSS so that features are supported in older browsers.

Why add vendor prefixes?

Even in the days of modern "evergreen" browsers, users don't always upgrade in a timely fashion or are on older versions of operating systems which are limited to certain versions of browsers (👋 Safari). Vendor prefixes were initially a way for browsers to ship their own implementations of features which developers could opt into before standards had been agreed but I think it's largely abandoned as an approach now. I don't want to keep track of which vendor prefixes I should include where but when it comes to e-commerce, a broken-looking site can reduce credibility, and ultimately sales.

Wouldn't it be nice if there was a tool that keeps track of which vendor prefixes I should still be including, and like, y'know, add them for me at build time? Could it please compile my old Sass files too? Really fast? Oh goody.

Adding PostCSS and Autoprefixer

Fortunately, the esbuild-sass-plugin package by Gianluca Romeo I was already using makes integrating PostCSS super easy and documents a simple example that includes Autoprefixer.

First, install the necessary packages from the command line.

npm i -D postcss autoprefixer postcss-preset-env

Then we can update our esbuild.config.js to use these plugins.

import esbuild from 'esbuild';
import { sassPlugin } from 'esbuild-sass-plugin';
import postcss from 'postcss';
import autoprefixer from 'autoprefixer';
import postcssPresetEnv from 'postcss-preset-env';

esbuild.build({
  //...
  plugins: [
    sassPlugin({
      async transform(source, resolveDir) {
        const {css} = await postcss([autoprefixer, postcssPresetEnv({stage: 0})]).process(source, {from: undefined})
        return css
      }
    }),
    //...
  ],
  //...
});

I ended up adding {from: undefined} to the options of the process function, just to quieten a warning about the way the source maps are generated. It's true that with this config the source maps aren't really very useful, but I haven't taken the time to look into getting that set up correctly. For now, I'm just glad to have the benefit of having the vendor prefixes added as part of the build and a single entry point.

I could probably improve this, if I felt the need/pain, by defining a separate config for CSS eg. an esbuild.css.config.js with just the rules for the CSS compilation and with the option to run those independently or in parallel.

Defining supported browsers

The last part is specifying which browsers you want to support, to define which vendor prefixes are required. There is a couple of ways to handle this, but I prefer to add a browserslist property to my package.json as it's pretty universally supported, and fairly explicit.

The current default is to specify that usage is greater than 0.5% and at least the last two versions are supported which, will make sure that the most commonly used browser versions are included.

{
  //...
  "browserslist": "> 0.5%, last 2 versions, Firefox ESR, not dead"
}

You can learn more about Browserslist queries.

With that, my built CSS includes the necessary vendor prefixes. Plus I now also have a config that's easily portable between other Shopify themes (Gist) where I'm bundling Sass and using the Shopify CLI.

Links #1

Sun, 06 Feb 2022 00:00:00 GMT

I've never really been good at keeping bookmarks, so I'm going to try tracking interesting things I've found on the web in posts for future me. I'm hoping this also provides some lower-effort content that I can publish more easily, and get less hung up about writing "proper" posts. Not entirely uninspired by Bruce Lawson's Reading Lists.

NFTs weren't supposed to end like this. Anil Dash on the unfulfilled promise of technology benefitting artists foremost.

Okuda Hiroko: behind the Sleng Teng rhythm. Fascinating how culture was transferred via pre-internet age technology with unexpected consequences.

CEOs are hugely expensive – why not automate them? Indeed. Via the New Statesman.

Shell script suggestions for speedy setups. A great post on scripting your project setup to reduce the friction when jumping into a project.

Monkey Patching. Although Rene Merino's article uses Craft CMS for its example, it's a great piece on when and why Monkey Patching is a useful technique. It for sure comes in handy when customising Shopify themes.

One Look Dictionary. A useful writing tool.

How to read complex code. A talk, by Dr Felienne Hermans, which covers the challenges of encountering unfamiliar code. It provides some insight on ways to improve cognition of unfamiliar syntax. Plenty to consider when it's code you might encounter, or considering the reader of the code you write.

Responsive images in Shopify themes

Wed, 22 Dec 2021 00:00:00 GMT

Performance is a useful metric for most cases on the web. None more so than in e-commerce where performance can have a dramatic impact on conversion rates and therefore profits.

One of the benefits of using a platform like Shopify is that you can leverage their margins of scale to achieve high-volume global performance for a fraction of the cost you would need to spend to do it yourself. Although the operating costs of servers have been shrinking in previous years, the complexity and pace of change have increased. As someone that would just about describe themselves as a full-stack[^1] developer, I feel like I offer my clients more value with my front-end expertise than back-end.

Outside of video, images are likely to be the heaviest assets on a web page in terms of sheer file size. This can be particularly true on e-commerce sites, where high-quality images are a key factor in sales conversion. This post covers my current best practices for handling responsive images in Shopify themes when you have access to the image object.[^2]

tl;dr

Skip ahead to the new image_tag section, if you don't want to wade through my ruminations on the old ways.

Legacy solution

Before the picture element, srcset and loading="lazy" attributes had enough cross-browser support, detecting which images to load – and when – relied on using JavaScript. The technique I used allowed me to effectively query whether an image was within the browser's viewport, and based on the containing element, identify the most appropriate sized image to load in.

This was possible due to Shopify's CDN that allowed you to store a single large image, but also fetch different versions of the image by adjusting certain values in the filename. For example, a large (2000×2000px) image named arthur.jpg could be scaled down to 100×100px by requesting arthur_100x.jpg. In Liquid that could be achieved with the img_url filter like so:

{{ settings.banner | img_url: '100x' }}
// Outputs: //cdn.shopify.com/full/path/to/arthur_100x.jpg

Please note: I'm excluding the cache-busting part of the query strings in my examples for simplicity's sake.

This meant that even with significant design changes, there was no need to worry about replacing existing images (as long as the originals were already stored at a large enough size). Later Shopify introduced more features to the CDN like the ability to crop images or convert images to the progressive jpeg format (pjpg), which was then superceded by more modern formats like webp (update: and now avif).

Later Shopify made it possible to request image transformations by appending query parameters to the request rather than by mutating the filename itself. For example, the equivalent file of arthur_100x.jpg could be requested instead with arthur.jpg?width=100.

{{ settings.banner | image_url: width: 100 }}
// Outputs: //cdn.shopify.com/full/path/to/arthur.jpg?width=100

This also makes programmatically generating image URLs (for example in JavaScript) easier, because it doesn't rely on a regular expression to check whether the passed filename already includes an image transformation eg. arthur_480x.jpg that needs to be accounted for. But we're not covering that here.

Lazy loading

The concept of lazy loading is that you needn't load images that the visitor can't immediately see anyway – perhaps because they are outside of the browser's viewport (lower down the page), or in an unreached slide in a slideshow component.

Originally you needed to rely on the browser's resize and scroll events to detect when and which images might be required. These events could have their performance penalty, particularly on image-heavy pages and so meant leveraging things like debounce to minimise calculations. The tricks were frankly quite gnarly and I found no perfect solution, even after several years of refinements. This was exacerbated with the introduction of Apple's retina display on iPhones creating the additional matrix of serving higher resolution images at each size.

Some of these issues were mitigated with the introduction of the browser's IntersectionObserver API, which allowed you to more easily detect images entering (or more usefully: about to enter) the viewport with a much lower performance cost.

Two things have largely removed the need for JavaScript solutions. The first: cross-browser support for srcset, a feature which allows you to define a set of images and let the browser decide which is most appropriate, based on a much broader set of variables such as device, network speeds, and battery level; the second: a loading="lazy" attribute, which lets the browser use similar factors to optimise when the browser should start loading in an image with minimum interruption to the visitor's experience.

In a template, a responsive image might be constructed like this:

<img
    src="{{ settings.banner | img_url: '2000x' }}"
    srcset="{{ settings.banner | img_url: '320x' }} 320w,
      		{{ settings.banner | img_url: '640x' }} 640w,
      		{{ settings.banner | img_url: '1000x' }} 1000w"
    alt="Let's go swimming!"
    width="2000"
    height="2000"
    loading="lazy"
/>

There are surprisingly few places where you need to define image outputs in a theme, but I tried to avoid some duplication by creating a generic snippet for images and passing the image object into it.

The new `image_tag` filter

Even more recently, Shopify has introduced the image_tag filter which cleans up a lot of boilerplate and provides a consistent way to generate responsive images in theme code. Effectively you can generate the same thing with just the filter:

{{ settings.banner | image_url: width: 2000 | image_tag }}

Output:

<img
  src="//cdn.shopify.com/full/path/to/arthur.jpg?width=2000"
  alt=""
  srcset="//cdn.shopify.com/full/path/to/arthur.jpg?width=352 352w,
          //cdn.shopify.com/full/path/to/arthur.jpg?width=832 832w,
          //cdn.shopify.com/full/path/to/arthur.jpg?width=1200 1200w,
          //cdn.shopify.com/full/path/to/arthur.jpg?width=1920 1920w"
  sizes="(min-width: 1100px) 535px,
         (min-width: 750px) calc((100vw - 130px) / 2),
         calc((100vw - 50px) / 2)"
  width="2000"
  height="1600">

The generated image tag includes some good defaults for sizing the image based on the original image size. These can be overridden if you need to fine-tune the output.

You can also pass other attributes to the image_tag filter, such as alt tags, class contents or maybe even to add hooks like data attributes for scripts. You would pass an alt tag like this:

{{ settings.banner | image_url: width: 2000 | image_tag: alt: "It's a wild combination" }}

Good performance optimisations

You're already getting some good performance benefits from using srcset on large images, but what if you wanted to add that snazzy lazy loading feature? Easy:

{{ settings.banner | image_url: width: 2000 | image_tag: loading: "lazy" }}

There is a caveat to using the loading="lazy" attribute, in that it can potentially have a negative performance impact if it is used on images that are already within the browser viewport on load. Therefore it's advised that you only use it on images lower down on the page.

However, for key images, it may also be useful to prioritise the loading of those images to reduce "layout shift" and display key content to the visitor faster. You can do that by setting a preload attribute on the image_tag filter with a value of true. Behind the scenes, Shopify will send a Link header in the response to the browser with a rel attribute of preload that contains the relevant srcset and sizes values. That case would look something like this:

{{ settings.banner | image_url: width: 2000 | image_tag: preload: true }}

You want to be careful about how many preload hints you give to the browser, as too many may render the benefits moot. It's ideal for the first image on a product page, or a large banner image on the homepage, for example.

More details about the image_tag filter can be found in the docs.

It's one of the better feelings in development when you can revisit some code and easily remove workarounds, and it's an added bonus if you get some quick performance wins at the same time!

[^1]: The term "full-stack" seems to have quite a fluid definition depending on who you ask, and the term has certainly expanded over the years. Originally it might mean someone that knows how to use a MySQL database and write some jQuery. These days you might be expected to understand a frontend framework like Nextjs and write your own Docker config.

[^2]: In some cases, you may only have the URL of the image on Shopify's CDN (typically if you're adding images into the body of the rich text editor). In those cases, images can still be optimised, but the strategy is a bit more complicated and I hope to cover that in a later post.

Using tags to render related content in Shopify themes

Tue, 21 Dec 2021 00:00:00 GMT

With the recent launch of Shopify's OS2 themes, I wanted to reflect on a technique that has been extremely useful as a way to add richer layouts to themes. OS2 introduced a way to add Metafields natively and easily generate new templates via the theme editor, including fields that can also pull in data based on those Metafields.

This latest combination has opened up a native way to build rich templates without the need to edit code directly or resort to third-party apps. The ability to add features via third-party apps is one of the killer features of Shopify. That said, I've always had huge reservations about adding apps that change, or require changes to the theme code. As well as introducing a potential maintenance burden when updating or switching themes, it also seems to carry a high risk in terms of breaking the website in a very consumer-facing and hard-to-debug way. It's not unusual for store owners to contact me to resolve issues caused by the (un)installation of apps that may not even necessarily be the fault of the app developers.

Benefits of tags

The big benefit I see of using tags is how well they are already supported in Shopify's admin. They are already exposed in the admin when editing resources, it's possible to group resources by tag and either add or remove tags in bulk making it easy for a store owner to manipulate tags, or find and change resources with a given tag.

The only real downsides are the lack of tags on resources like collections or pages. But most use cases I've encountered have applied to products and articles anyway.

Using tags as a key-value store

By defining a structure for your tags, it's possible to use them as a type of key-value store. I tend to do this by defining a separator for namespace, key and value. eg. namespace:key:value.

Using that structure means that within liquid we can look for tags with the given namespace, or namespace and key, then extract the value. Let's say we want to be able to associate a related collection with a product. If our namespace was theme and our key was related-collection, and the value could be the handle of the collection we wanted to identify, then a tag might look like theme:related-collection:bestsellers.

If that tag was assigned to an article then in a template with access to the article object, we could access the collection like this:

{% liquid

assign needle = 'theme:related-collection:'

for tag in product.tags
	if tag contains needle
		assign handle = tag | remove: needle
        break
    endif
endfor

assign related_collection = collections[handle]

%}

You can then, for example, display the products from that collection below the article.

Why the namespace?

Although it's not necessary to use the namespace in the example above, the namespace has a couple of useful benefits. First, it protects you from potential collisions with tags created by apps or that a shop owner wants to apply. Second, you can use the presence of the namespace to quickly exclude those tags in the case that you want to use and expose tags for their "traditional" use, i.e. to filter for a related topic.

Here's a simple example of excluding tags by detecting the presence of the namespace:

<ul class="tags">
{%- for tag in product.tags %}
	{%- unless tag contains 'theme:' %}
		<li>{{ tag }}</li>
    {%- endunless %}
{%- endfor %}
</ul>

Use cases

Along with the ability to associate a group of products with an article, other use cases I've found have included storing rich content in a single blog post or page, and then associating that with several products. This could be videos, animation, or a gallery of images that can then be displayed on multiple product pages, without the need to duplicate the content or update it on each product.

The value doesn't need to be a handle either, it can be used to store meaningful strings like a colour, or a date that can be used in the layout. You could then use those to define the colour of elements on the page, or a countdown timer.

Hiding Shopify pages from search results

Mon, 20 Dec 2021 00:00:00 GMT

Url structure

Shopify has a defined URL structure, for example, all product URLs include /products/. If you're used to having complete control over your URL structure, this can feel quite restrictive at first. I tend to quite like working within constraints and the consistent and immutable nature of the URL structure can be a benefit.

Besides anything else, it reduces the surface area for potential bikeshedding[^1] opportunities.

Reasons for hiding content

Sometimes it's useful to create collections, or posts in Shopify that aren't meant to be customer-facing, at least on their own. In the past, I've used the collections feature to group "sibling" products or to conform to certain tax overrides. I've used blog posts as a source of shared content to augment product descriptions.

In these cases, the collection or post was never meant to be crawled. In addition, because the content is designed to be pulled through to different areas of the site, it can fall foul of duplicate content penalties from search engines.

Using `robots.txt`

Recently, Shopify has added the ability to customise a store's robots.txt file by adding a robots.txt.liquid template to your theme. A robots.txt file is designed to provide instructions to a search engine's web crawler on how to crawl your site. It's mostly used to indicate which URLs should not be indexed. Previously, you weren't able to do that as themes only shipped with a Shopify-generated robots.txt file that you weren't able to influence as a theme developer (or shop owner).

The only reliable way I was able to prevent URLs from being indexed was by using a robots meta tag with a content="noindex". This is a meta tag you can add to the head of the HTML document that tells web crawlers not to add the current page to the index. A full tag would be inserted between the head tags like so:

<head>
  <meta name="robots" content="noindex">
  //...
</head>

Using the `seo.hidden` metafield

There is an, apparently, undocumented feature that will add this meta tag to pages for you. To do so you need to add a Metafield to a resource with a namespace of seo, a key of hidden and a truthy value, eg. 1. At the time of writing Shopify has introduced a native way of adding Metafields to products via the admin, but it's not available for other resources such as collections, or articles (yet!).

Metafields can be added to other resources via Shopify's API or through an app. But there is another way to edit Metafields directly in Shopify's admin. You can create and modify Metafields by appending values to the query string generated by the bulk editor. For example, you could begin bulk editing some collections and add &edit=metafields.seo.hidden to the address in the URL bar, and it will expose a field you can populate with a 1 for collections you don't want to be indexed.

Using a custom Metafield

Before I discovered that Shopify had already defined a Metafield for this purpose, I had used a similar approach of assigning a custom Metafield and adding some logic to the theme code to determine whether the page should output a noindex meta tag. In fact, I also used a similar tag to output custom canonical URLs and other data to the head.

Alternative solutions

Quite often I resort to the presence of a tag to define some custom functionality because they are exposed readily in the admin and easy to change. The issue is that, unlike products and articles, resources like collections and pages can't be tagged.

Normally I try to expose as many options as possible via the theme editor using section settings, but sections need an id in the HTML and are by default wrapped in an HTML tag. There are ways to circumvent that, but it feels less robust overall as a solution because I find theme customisations are better for providing visual feedback rather than having hidden consequences.

Another solution which can work when you have a simple on/off state is to rely on a template, eg. applying a collection.noindex.liquid template to the relevant collections. This is relatively easy to implement and control in the admin. However, if you're already using multiple templates, then creating additional noindex templates for each one becomes somewhat problematic to maintain.

Trade-offs

As with most solutions to tricky problems with a platform like Shopify, there are trade-offs. Often it's a case of trying to predict which solution will be the least likely to fail, have the lowest maintenance burden and is within a client's technical abilities to manage. This tends to come down to experience, but I often look for options that will be the easiest to change in future, as with the introduction of the ability to customise the robots.txt file (like so many improvements) previously difficult to achieve features become much easier.

[^1]: A metaphor to illuminate Parkinson’s Law of Triviality. It describes the act of spending a majority of a project's time on trivial but easier-to-grasp details rather than more important and difficult to criticise tasks. The original example was focussing on the materials used to build the bike shed of a nuclear power plant.

Refactoring a Shopify upsell widget to a Custom Element

Tue, 26 Oct 2021 00:00:00 GMT

Clients often ask me for a good way to upsell a product at the point of purchase. A good example might be a florist wanting to sell a vase with a bouquet. The main product they're selling is the bouquet, but it's probable that the customer may also like to add a vase to their order at the same time.

One solution would be to add a "fake" variant to the product that acts as a combo of the bouquet + vase, but this quickly falls down with stock, reporting, etc as the upsell vase is its own product with inventory that should really exist separately. It's also then necessary to create all the extra "fake" variants on each product. What if there's a requirement for more than just the vase, or different styles of vase?

The simplest solution is to add a prompt in the description that directs customers to the upsell product(s), but this is not as convenient as being able to add the product without leaving the page.

There are apps that offer this functionality, but they're not always the most elegant which is an issue for design-led sites.

I recently tackled this issue for a client and my initial solution accepted a Shopify Collection and used vanilla javascript to display the products with +/- buttons to set the quantity added to the cart. This first solution worked great, but there was some complexity in tracking the state of each product's quantity and having to continually filter DOM elements to match a reference.

Here's a simplified example of the type of code I was using just to add a product to the cart:

<div class="custom-upsell-products">
  <div class="custom-upsell-products-item">
    <button data-decrease data-id="123">-</button>
    <input data-quantity data-id="123" value="0">
    <button data-increase data-id="123">+</button>
  </div>
  <!-- more products -->
</div>

const increaseButtons = document.querySelectorAll('.custom-upsell-products button[data-increase]');
const quantityInputs = document.querySelectorAll('.custom-upsell-products input[data-quantity]');

function enableLoading(el) {
  el.closest('.custom-upsell-products-item').classList.add('loading');
}

function disableLoading(el) {
  const quantity = Array.from(quantityInputs)
    .find(quantityInput => quantityInput.dataset.id == el.dataset.id)?.value || 0;
  handleChange(el.dataset.id, quantity);
  el.closest('.custom-upsell-products-item').classList.remove('loading');
}

function handleChange(id, quantity) {
  //  set button state, etc
}

function increaseCart(id) {
  // get current quantity
  // send post request to cart
}

increaseButtons.forEach(increaseButton => increaseButton.addEventListener('click', () => {
 enableLoading(increaseButton);
 increaseCart(increaseButton.dataset.id)
   .then(qty => {
     Array.from(quantityInputs)
       .filter(quantityInput => quantityInput.dataset.id === increaseButton.dataset.id)
       .forEach(quantityInput => quantityInput.value = qty);
    })
    .catch(err => console.error(err))
    .finally(() => disableLoading(increaseButton));
  })
);

You don't have to particularly understand in detail what's going on in the example above, but you'll notice that there's a lot of occasions where the code needs to iterate over the DOM elements to get a reference to the relevant product. It's possible that it could be done with a different DOM traversal strategy, or maybe there's a better way to store references (quite possible!) that I'm not aware of. In this instance, the code needed to account for an unknown number of upsell products, so it has to rely on a lot of assumptions about how the code is set up too. There's a trade-off between storing the id on a parent element (more complex traversing) or adding a reference to the id on all the interactive elements. It's much harder for me to feel confident about where the boundaries should be.

I often have to write code like this for Shopify themes, and I know it's a smell when I have to start querying elements for their state, passing around references (elements, ids) or trying to make unique-enough selectors to avoid leaking styles, etc. Traditionally, I would just suck it up and hope that I can still understand it if I ever have to come back to it to make changes.

Enter Custom HTML Elements

More often I'm encountering widgets that are implemented using Custom HTML Elements (sometimes referred to as Web Components) that encapsulate some code into a defined HTML element, usually with some bespoke interactivity. This sounded like it might be a solution for my upsell widget... (Spoiler: it was!)

Here's the same functionality implemented with a Custom HTML Element.

<custom-upsell-product data-id="123">
  <button data-decrease>-</button>
  <input data-quantity value="0">
  <button data-increase>+</button>
</custom-upsell-product>
<!-- more products -->

class CustomUpsellProduct extends HTMLElement {
  constructor() {
    super();

    this.id = this.getAttribute('data-id');
    this.quantityInput = this.querySelector('input[data-quantity]');
    this.increaseButton = this.querySelector('button[data-increase]');

    this.increaseButton.addEventListener('click', () => this.quantity++);
  }

  get quantity() {
    return this.quantityInput.value;
  }

  set quantity(value) {
    this.enableLoading();
    this.updateCart(value)
    .then(qty => this.quantityInput.value = qty)
    .catch(err => console.error(err))
    .finally(() => this.disableLoading());
  }

  handleChange() {
    // set button state, etc
  }

  updateCart(quantity) {
    // send post request to cart
  }

  enableLoading() {
    this.classList.add('loading');
  }

  disableLoading() {
    this.handleChange();
    this.classList.remove('loading');
  }
}

customElements.define('custom-upsell-product', CustomUpsellProduct);

There is so much complexity from the implementation that has now been removed. Each product has its own internal state eliminating the need to filter through elements, pass around ids, or traverse the DOM. In this case I've used accessors (get/set) to simplify the code further, and easily been able to use a more generic updateCart method but these are really just implementation details (although they were certainly easier to reach for in this version).

Just the fact that the line lengths are shorter and a huge amount of visual noise has been removed from both the Javascript and the HTML makes it much easier to reason about. I'm confident that returning to this code 12 months from now to add a feature would be much less onerous than the original implementation too.

I'm pretty pleased to discover how well Custom HTML Elements solve common problems I've experienced when adding features to Shopify themes, and I'm looking forward to being able to use them more in future and even refactor older code towards a simpler – and ultimately more portable – implementation.

Check out my starter gist of a full implementation that can be modified and integrated into any Shopify theme.

Adding VAT to 31,522 Shopify prices as quickly as possible

Wed, 20 Oct 2021 00:00:00 GMT

I built my first Shopify theme in 2012, and after years of custom-built PHP carts, and third-party self-hosted products, Shopify was a breath of fresh air. No servers to worry about, a pleasant templating language in Liquid, great support and an API that gave you advanced capabilities when you needed it.

Shopify and the VAT problem

I only had one major gripe: VAT support. Shopify took a very North American-centric approach to tax, that assumed that you expected to see pre-tax prices with the tax added at the checkout. European tax laws require prices to be displayed inclusive of tax, and that proved to be a big issue. Customers outside the EEC weren't required to pay tax on products (they would often be subject to import duties instead) so it was common - particularly with high ticket items - to offer the net price to customers outside the EEC. This was difficult with Shopify, as it had no way to allow you to deduct the domestic tax from a product's price at checkout.

The hack

The solution for years was to store all prices as their net value and customise themes to display a VAT calculated price. This is essentially a simple solution, but caused no amount of headaches when integrating Shopify with third parties or trying to build complex functionality, not to mention odd penny rounding issues.

It meant I became quite the expert on all the ways that this approach could break, and spent a huge amount of my professional time working around these limitations.

The eventual fix

Almost ten years later, in early 2021 the fix I had been waiting for finally arrived. Ironically this may be the one upside of Brexit for me as it seemed to coincide with Shopify making a host of changes to accommodate the UK leaving the EU. There was now a checkbox in the settings to deduct VAT at checkout. Hallelujah.

The easy way

Soon it became time to start taking advantage of this on client sites. For smaller stores with relatively fixed catalogue sizes, this was a pretty simple process of removing any price customisations in the theme and updating the prices and the setting. For a few dozen products a quick import of new prices updated in a spreadsheet was sufficient.

The hard way

However, some of my clients have been on Shopify for years and were consistently publishing new products weekly. In one client's case, I believe they were one of the first Shopify Plus shops in the UK and had a catalogue of 8,187 products, totalling 31,522 individual prices that needed updating! Such a fundamental change required closing the shop while prices were updated, and as a high-traffic site, minimising downtime was a priority.

Running that amount of data through a spreadsheet risked being slow and extremely error-prone. Some prices needed to be preserved because they're not subject to VAT like books and magazines. A slight mistake could overwrite the data on over 8,000 products.

I realised I could use my Shopify CSV Export app to optimise the process. I set up a development store and imported the existing catalogue to safely test against (it took over 12 hours for the initial import to complete!). This doubled to test any theme updates against too, so I could be confident that prices would be displayed properly after the switch - some of the code in that theme hadn't been touched for years.

I then set about writing a script that would create an optimised CSV of just the minimal data needed to modify prices. Then I allowed for it to split the export into a backup of the existing prices (so I could reset if anything went wrong) and the new modified prices that we would want to import.

Optimising imports

Importing the full 31,522 updated prices took over 80 minutes - but the bulk of those products aren't even published on the online store. The total number of prices for published products was 4,300 which took less than 10 minutes to import. Nice! We would only need to close the store for a few minutes to update the online prices, publish the theme and make any changes to settings and apps we needed to. We could import the rest of the prices for the physical store and historical products separately.

I updated the script so that it would create 4 files on export:

the original prices of published products
the original prices of unpublished products
the updated prices of published products
the updated prices of unpublished products

The exports were always much faster, taking only seconds to generate the full 31,522 prices, even when split into existing and new. This allowed me to take an up-to-the-minute snapshot of the prices as we closed the site, meaning there was no impact on business operations in preparation either.

In the end, even with manual acceptance testing and some last-minute decisions, the site was closed for less than 20 minutes. A few moments after re-opening it was a relief to see an order placed with correctly calculated tax and the rest of the prices completed updating about an hour later.

It pays to test

Taking the time to set up the development store and run the tests may have saved hours of problems, and possibly even some disastrous outcomes. It gave me the chance to test some hypotheses, measure real-word examples and safely experiment with solutions without impacting the day-to-day business. Changing prices, and updating the entire catalogue has such a high risk of going wrong that perhaps the biggest benefit of tests is providing the confidence to be able to safely make the switch when the time came.

Uploading Source Maps to Honeybadger with GitHub Actions

Wed, 08 Sep 2021 00:00:00 GMT

I've been a happy user of Honeybadger for well over a year now. For the small apps I've built it has often been enough to rely on users reporting bugs, as I usually have a direct line of contact with the user (AKA the client).

Error Tracking Shopify apps

As the apps I've been building have become more complex and the number of users increased, it seemed prudent to add an error reporting service to my stack. I'd heard good things about Honeybadger, and I liked that they promoted good company ethics and had seen a lot of support in the development communities that I subscribe to. Their free tier seemed like it would cover my requirements comfortably, and allow me to scale as necessary. I was pleasantly surprised at how quickly I had error reporting set up in my apps, along with automatically generating GitHub issues for errors that were detected.

This was particularly the case for the backend of the apps that I typically develop in PHP with Laravel. They have a Laravel-specific integration which is a cinch to install.

Some of my most heavily used apps are integrated with Shopify and utilise Shopify's React-based framework, Polaris. The JavaScript is minified for production so by default errors reported in JS can be obscured by the minification process. Often the nature of the error can reveal its origin, but that's not always the case.

Using Source Maps

Fortunately, it's possible to provide Source Maps to Honeybadger which can then interpret the errors and identify their location in the source files. Much easier to debug!

Honeybadger can try to detect your Source Maps automatically, but by its nature, can be unreliable. A better solution is to upload the latest source maps to Honeybadger on each deployment.

This can be done in any number of ways, including a Webpack plugin or cURL.

Using GitHub Actions

In the end, I decided to explore doing it via GitHub Actions. I have been keen to find an excuse to try them out since they launched but haven't really needed to, or had the impetus to dig into it.

There is already a GitHub Package provided that handles the hard part of uploading the files to Honeybadger via their API. All I had to do was configure it correctly.

I clumsily added the Action via GitHub's web interface, and after a couple of false starts (YAML is unforgiving), I had my first successful run and Source Maps uploaded. It took less than 20 mins in the end.

The final action looked like this:

on:
  push:
    branches:
      - main

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
    - name: Checkout repository
      uses: actions/checkout@v2

    - name: Install npm packages
      run: npm install --prefer-offline --no-audit

    - name: Build production assets
      run: npm run production

    - name: Upload source maps to Honeybadger
      uses: honeybadger-io/github-upload-sourcemap-action@master
      with:
        api_key: ${{ secrets.HONEYBADGER_API_KEY }}
        minified_url: ${{ secrets.PRODUCTION_URL }}/js/app.js
        minified_file: public/js/app.js
        source_map: public/js/app.js.map

I stored the API key for the project as a GitHub Secret to keep it secure, and I also stored the URL of the production site to make this action more portable. This works for me as I try to enforce building my apps in a consistent way.

Now each time the main branch is updated, the npm packages are installed, the production assets (including Source Maps) are generated and the latest Source Maps are uploaded to Honeybadger with a reference to the commit. So it's much easier for me to track down the source of any JS errors that users generate in production (and of course, fix them 😉).

Archiving a Perch CMS site by statically rendering it with Wget

Fri, 27 Aug 2021 00:00:00 GMT

I started working with the London Short Film Festival in 2007, creating the brochure and website for the 2008 festival that takes place in early January. If you've ever been involved in the organisation of festivals you'll know that, due to the sheer number of parties involved, no amount of preparation can entirely prevent information arriving at the last minute.

After getting that first brochure signed off and delivered to the printers just before Christmas, I quickly put together a website with Wordpress that was little more than a glorified page of the event listings.

12 years of Perch

The following year I used the relatively new Perch CMS that I found much more developer friendly than Wordpress and could still be hosted cheaply. The site would always get a lot of traffic in the short period of time up to and during the festival, but much less outside of it, so keeping annual hosting costs low in the days before autoscaling was a big bonus.

Year by year, I would update the site for a sustained period adding new features and evolving the design to match the look of the printed promotion. I took great care to preserve access to old events and film listings (typically 300+ each year) along with articles from festivals past. Consequently, the site went through several data migrations.

The site went from being a supplement to the listings brochure to becoming the primary source of truth, allowing me to generate listings content for the brochure from data initially added to the CMS. Using the CMS first made getting content approved by third parties much easier, and meant a lot of previously tedious aspects of the job could be automated.

The (generally) annual cadence of the work on the site meant there would always be some updates to apply to the CMS, versions of PHP or MySQL, current best practices and often dropping feature support for obsolete browsers.

In 2020 the festival took on a new director and due to the pandemic took place online and employed a new technical team, so with a little sadness and relief, I'm no longer spending my December days scrambling to put the site together. I still had (felt?) the responsibility to archive the existing content. Initially, that was just a case of swapping to an archive subdomain, but I knew that keeping the site on the LAMP stack would not make sense permanently.

Legacy LAMP sites

Anyone who's spent time as a general web developer in the 2000s has probably stood up a few PHP sites that are still ticking along on an old shared server running on some now obsolete version of PHP. They're probably running fine (and I'm sure a lot are still generating a good profit!) but as always there are potential security risks running on versions of software that no longer receive security fixes, and the chances of being able to fix something on a site rotting on some crusty version of PHP5 doesn't sound very appetising.

Even though the site was running on PHP 7.4 (the latest at the time) I didn't want the technical burden of having to maintain and pay for a server or applying security updates to the CMS software for a site that doesn't need to be dynamically rendered or even updated. By taking a static snapshot of the site and hosting the files (effectively for free) on a CDN, I could reduce the technical burden to essentially zero. It also meant it would require a lot less energy and overhead to run the site - it seemed like the responsible thing to do.

Of course, there's always the potential that the site will need to be updated in some way, so I decide a good solution would be for me to be able to run the site locally and then automate the process of snapshotting and deploying the site to something like Netlify.

Only running the site locally

I've always been able to run the site locally for development purposes, initially using things like MAMP but more recently using Laravel Valet (with a custom driver). I relied on taking copies of the production database to the staging server to get an up-to-date version of the production state that I can work on safely. The only change I made was to store a SQL dump in the repo so that I could always restore a working copy of the site from just the repo. I considered adding scripts to restore the database, run composer, set up a Docker file etc as well as one to dump changes to the database, but in the end, I just left some notes for myself in the README. There's a good chance I'll never need to use this repo again, but if I do that will be the time to solve that problem.

Generating the static site

Although it would probably make sense to have the static sites generated and hosted within the same repo, for simplicity I decided that all the static files could be generated in a separate repo. It's possibly something I would change, but for now, it feels much 'lighter' to separate out the repos.

I decided to use Wget to clone the locally running version of the site and store it in a folder that can then be set to serve the files, in this case, /public which conveniently allowed me to serve the files locally via Valet for testing purposes. It took me scouring a few tutorials and some trial and error to get the configuration of arguments that I wanted.

I ended up with something like this:

wget -mpckEnH -P ./public https://lsff.test

-m creates a mirror of the site
-p get all images, etc. needed to display an HTML page
-c resume getting a partially-downloaded file
-k make links in downloaded HTML or CSS point to local files
-E save HTML/CSS documents with proper extensions
-nH won't create host directories
-P define a directory to save files to

This worked a treat, and the only issue was that absolute urls would refer to the local domain https://lsff.test but the files would eventually be hosted at a different domain https://lsff.newbuild.studio so I realised I would need to do a find and replace on the url. There's probably some solution for this built into Wget, but I couldn't figure it out. A couple of trips to Stack Overflow (plus some more trial and error) later and I decided the best solution for me would be to use a combination of the find file finding command and the stream editor command, sed.

On Mac OS you need to create backup files when you run sed to preserve the integrity of the filesystem or something. Eventually, I got the following to work.

find ./public -name "*.html" -type f -exec sed -i '.bak' 's/lsff\.test/lsff\.newbuild\.studio/gI' {} \;

Great! I could now generate a fully working static reproduction of the site 🙌

The interesting outcome was that now the generated files were being stored in a repo, I could easily see how small changes to the original site were reflected in the static output and therefore which files were directly effected. Reviewing the files helped me spot a couple of small errors, pages that needed to be removed and other improvements that could be made quickly. It was satisfying being able to see the resulting changes in a git diff in a way that you don't when dynamically generating the content and only working with the templates.

I noticed a couple of oversights, like needing to empty the /public directory before running wget, so that pages I wanted to be removed didn't remain. Although I could add the .bak files I was generating to .gitignore it added a lot of noise to the file explorer so I decided to clean those up on each run too. In the end, I had a build.sh file I could run that looked like this:

rm -rf ./public
wget -mpckEnH -P ./public https://lsff.test
find ./public -name "*.html" -type f -exec sed -i '.bak' 's/lsff\.test/lsff\.newbuild\.studio/gI' {} \;
find ./public -name "*.bak" -type f -delete

Deploying to Netlify

All that remained was setting up a new site in Netlify linked to the repo on GitHub that served the ./public folder and pointing the domain. I can't see this archive of the London Short Film Festival ever generating enough traffic to escape the free tier and, if necessary, there's a few useful goodies like redirects and snippet injection I can take advantage of if I ever need to.

So that's it – with just a handful of commands – I can pull down both repos make a change in the dynamic one and generate and publish a new set of static files to the web. I now have a solid solution for archiving and hosting static versions of LAMP sites without losing the ability to still make changes via the CMS.

Installing Perch Runway via Composer

Mon, 16 Aug 2021 00:00:00 GMT

When I've needed to provide a CMS for brochure sites, my first port of call has been Perch CMS. I've been using it since 2010 (when it was still v1.2!) as a great solution to adapt static sites to be updated by a client (eg. adding a news section), or building out highly customised views. Perch uses PHP and MySQL so it was familiar and easy to set up locally and host on a budget.

The Problem

As some of the sites grew in their volume of content and feature complexity, I upgraded them to Perch's more advanced developer version, Perch Runway (released 2014). Runway has features like collections and dynamic routes, making it more akin to popular MVC frameworks like Laravel, and the types of dynamic regions you get in Craft. Unlike Laravel and Craft it didn't have the convenience of Composer to pull in useful packages and facilitate the types of deploy pipelines I had become accustomed to.

It's expected with Perch that to upgrade to new versions you would replace the core folder with new files downloaded from your account and then manually uploaded to the client's server. To use a deployment pipeline meant either committing all of Perch's core files to version control (yuk), or manually updating multiple sites and local development machines with each release, which even with a small number of projects quickly becomes onerous and error-prone.

The ideal

What I wanted to be able to do is pull in specific versions of Perch, or easily update to the latest version consistently across projects and machines. Because Perch doesn't provide this feature I decided to roll my own. To do this I realised I could host my own, private repository of Perch with versioned releases in one place. The issue was that because Perch's files need to be accessible in a publicly accessible directory, I would need to figure out how to set up Composer to install the files outside the /vendor folder.

Installers

Fortunately, there's a Composer tool designed just for this purpose. It's specifically designed to allow packages to be installed outside the /vendor directory (useful for things like Wordpress). Normally you would define within the package where the files would be installed, and although Perch is typically installed in a /perch directory, it doesn't have to be and for some projects I have it installed in /cms for example. That's okay because the Installers Extender allows the client composer.json file to define where the Perch core files should be installed to.

Setting up Perch as a package

In my case, I created a private repository on GitHub called perch-core - but it could be called anything - and committed the latest version of Perch's core files.

To set up the repository as an installer, I first needed to add a composer.json to the project which I did by running: composer init and following the instructions.

Next, I installed the two packages I needed:

composer require composer/installers oomphinc/composer-installers-extender

After committing the changes to composer.json, I pushed them to GitHub and was now ready to tag the repo with the current release of Perch (at the time v3.1.5). This would allow me to specify the version of Perch I required in my client projects.

Installation on a Perch project

Now I'm able to install Perch as well as any other composer dependencies in my project such as a helper file, or a package to support the use of .env files. It's important to make sure that the /vendor directory is not publicly accessible on the web server, so my Perch projects are typically set up with the following structure:

public/
├─ perch/
│  ├─ core/
├─ favicon.png
├─ .htaccess
vendor/
composer.json

To use my private perch-core repository and have the contents be installed to /public/perch/core I need to add the following to my composer.json file:

{
  ...
  "require": {
    "mikenewbuild/perch-core": "^3.1"
  },
  "repositories": [
    {
      "type": "vcs",
      "url": "git@github.com:mikenewbuild/perch-core.git"
    }
  ],
  "extra": {
    "installer-types": [
      "perch-core"
    ],
    "installer-paths": {
      "public/perch/core/": [
        "mikenewbuild/perch-core"
      ]
    }
  }
}

In the repositories section, I've defined the location of my private repo on GitHub, and in extra I define the package that should be "installed" and the directory where the package should be installed.

It's possible to define multiple packages and locations, which is useful for applying the same technique to eg. Perch Add Ons.

One last thing

Because I don't want to make the Perch core files public I also needed to set up a Personal Access Token in GitHub to grant access to the private repository. This can be done with either an SSH key or by adding an auth.json file to the root of the project with the generated token:

{
  "github-oauth": {
    "github.com": "github-token-here"
  }
}

Needless to say, this file should not be committed to the repo as it includes sensitive information.

Running composer install in my client project will now replace the /public/perch/core folder with the contents of my perch-core repository, and other packages in the vendor directory. The version will be stored in the composer.lock file so I can quickly replicate my project in any environment.

This small addition has made my development workflow much more robust and enables me to leverage Composer in my Perch projects. I can also track the changes to Perch core, and if necessary apply my own patches to enable support for newer versions of PHP before an official version of Perch is released.

Using Jest tests to replace jQuery in a Shopify theme

Mon, 26 Jul 2021 00:00:00 GMT

I started building custom Shopify themes in 2015 when it was still quite painful dealing with different browsers and lots of elements of Shopify relied on jQuery by default. In 2020, the browser landscape is much less problematic and so I decided to stop supporting IE and only target modern browsers instead. Although most sites still get a tiny percentage of traffic from older browsers, the number is dwindling and actual sales are non-existent so the cost of extra development is no longer justified.

This has given me the opportunity to do all my new feature development with modern JavaScript techniques using newer frameworks like Alpine.js. Still, there is a lot of previous code knocking around that relies on jQuery and a lot of it is fundamental to the way the theme works. I'm generally fine with leaving working code alone, but jQuery is quite a heavy dependency, so there are definite performance gains from removing it.

Also, it should go without saying, that the code I wrote in 2015 is much more naïve than the code I would write today. Although I'm sure I will have a similar attitude in the future to the code I write now :)

The difficulty is how to replace such a fundamental part of the codebase (relatively) painlessly without risking breaking something?

Benefits of tests

Something that I've come to rely on a lot in backend development is automated testing. Sadly I've struggled so far to develop a good testing workflow with JavaScript. So I wanted to use upgrading a legacy codebase as a good opportunity to work on that.

Ultimately I believe Shopify themes would benefit the most from end-to-end testing tools like Cypress, but due to the nature of theme development on Shopify, this seems quite daunting. What I want primarily is to be able to quickly set up and run tests to give me a quick feedback loop so I can confidently refactor code.

Fortunately, most of the code I would be updating is limited to DOM traversal, toggling a few classes and some very simple DOM insertion. More complex code (mainly around cart interaction) I would want to manually test anyway. I figured this simpler code might be a good candidate for a testing framework like Jest.

Install & set up

This was my first experience setting up Jest in a project and credit to the maintainers, it was much easier than I expected and thanks to the helpful error messages I had it set up to my specific requirements in minutes.

I installed Jest with the command:

$ npm i jest --save-dev

Now any files ending .test.js will be treated as a test when running jest from the root of the project.

You can also keep all your files in a dedicated test folder, which I would typically do when using things like Pest, but in this case, I want the files to be easily transferrable between projects so I opted to colocate my tests with my implementation code.

Running tests

The first snag I hit was using import statements in my tests. I wanted to use imports as I'm in the future now. At the time of writing, this is only supported as an experimental feature in Jest, but as I'm not planning to do anything crazy in my tests it has worked fine for me. It does mean adding a flag to the command, so it's easier to add to an npm script:

{
  scripts: {
    "test": "node --experimental-vm-modules node_modules/.bin/jest"
  },
  "type": "module"
}

Module imports are now automatically supported when I run npm test

Testing the DOM

Pretty much all of the work I'm doing with JS is to do with DOM manipulation, certainly the code I had written with jQuery. Jest has some features that make it easy to test the basic DOM manipulation which I was performing. I struggled a bit when it came to things like using setTimeout so I decided to dig into that another day and focus on the simple stuff and test anything more complicated manually.

There is one thing you need to do to allow your tests to use the DOM, and that is to include a doc block at the beginning of your tests.

/**
 * @jest-environment jsdom
 */
 test('...', () => {
   // test DOM stuff...
 })

Here's a full example of a test for a dynamic gallery component. It's a quick test that given the right HTML structure, clicking a thumbnail will update the main image with the relevant src attribute and apply an active class to the corresponding thumbnail.

/**
 * @jest-environment jsdom
 */

import dynamicGalleries from "./dynamicGallery"

test('it can dynamically update a main image by clicking thumbnails', () => {

  document.body.innerHTML = `
    <div class="gallery">
      <img src="1.jpg" class="main">

      <img src="thumb-1.jpg" class="thumb" data-gallery-img-src="1.jpg">
      <img src="thumb-2.jpg" class="thumb" data-gallery-img-src="2.jpg">
      <img src="thumb-3.jpg" class="thumb" data-gallery-img-src="3.jpg">
    </div>
  `;

  const main = document.querySelector('.main');
  const thumbs = document.querySelectorAll('.thumb');

  dynamicGalleries('.gallery', { main: '.main', thumb: '.thumb' });

  expect(thumbs[0].classList.contains('active')).toBe(true);

  thumbs[1].click();

  expect(thumbs[0].classList.contains('active')).toBe(false);
  expect(thumbs[1].classList.contains('active')).toBe(true);
  expect(main.src).toBe('http://localhost/2.jpg');
})

This allowed me to refactor away jQuery from the implementation of the dynamicGalleries() function using the instant feedback from a test and giving me the confidence that I haven't broken anything. All this without having to wait for files to bundle and sync with Shopify and a browser refresh. 🔥

Helpful utilities

As I mentioned earlier, I rarely do anything that complicated with jQuery anyway, but its killer feature has always been the elegance of accessing the power of the Sizzle selector engine with the $() function. Thanks to jQuery a lot of the power of that engine is now available in the browser's native APIs with querySelector, querySelectorAll, nextSibling, closest, etc.

However, these aren't quite as terse, and having my code littered with document.querySelectorAll('div').forEach() isn't as nice as $('div').each() . Inspired by a great series of posts on taking a JavaScript Framework Diet by Sebastien De Dyne, I've been able to replace a lot of my jQuery use with some simple utility functions.

These two functions alone do most of the heavy lifting, which meant in most cases I could replace $('div').each() with _$$('div').forEach() .

function _$(selector, scope = document) {
  return scope.querySelector(selector);
}

function _$$(selector, scope = document) {
  return Array.from(scope.querySelectorAll(selector));
}

Of course, with Jest, it's easy to test this functionality too!

test('_$ can select an element', () => {
  document.body.innerHTML = `
  <div>
    <div id="test" class="yo"></div>
    <div></div>
  </div>
  `;

  const el = _$('div#test');

  expect(el).toBeInstanceOf(HTMLElement);
  expect(el.classList.contains('yo')).toBe(true);
})

As I worked my way through the code I was able to find other opportunities to add utilities for frequently used jQuery features like toggling classes, or wrapping elements in another element. With the tests as backup, it greatly reduced the amount of time it took to replace jQuery, and in many cases allowed me to significantly improve the simplicity and readability of the code I was refactoring.

I often find that making code easier to test improves the code itself.

Next steps

With these tests in place, I can now take steps towards a CI/CD pipeline which will allow me to run tests automatically when merging new features or fixes. This will reduce both the chances of regressions being introduced, as well as the time spent testing manually.

For now, I'm just happy to be able to write tests easily and get super quick feedback.

Shopify theme development with esbuild

Wed, 21 Jul 2021 00:00:00 GMT

Shopify recently released a new CLI that makes it easier to develop themes locally.

The old way: Theme Kit + CodeKit

Previously I had developed a workflow using Bryan Jones' CodeKit app[^1] and Shopify's old Theme Kit tool.

Using Shopify's old Theme Kit tool, I could bundle and minify assets with CodeKit, have them synced to a development theme on Shopify and then CodeKit could refresh the page for me. This gave me the closest thing to an ideal local development setup. There were some[^2] niggles[^3] though.

Shopify CLI for themes

With the announcement of Shopify's Online Store 2.0 came a new CLI (Command Line Interface) tool to manage themes with faster syncing and a local dev server out of the box. Along with being a much faster native solution for a local dev server, it has removed the need for managing API keys and config files for multiple themes (a particular nuisance when working across multiple machines).

Another difference with the Shopify CLI for themes over Theme Kit is that there is no feature for preventing syncing certain files. For example, I would often avoid syncing the settings_data.json files and keep these out of version control to avoid overwriting client customisations. However, with the changes to the structure of the new themes, the sync speed and the deprecation of automatic SASS compilation by Shopify, it makes less sense to not track all theme files.

Bundling assets with esbuild

With less need for third-party tooling and increased browser support for modern CSS and JavaScript, it's easy to imagine building new themes without the need for bundlers at all (unless I adopt things like TypeScript).

However, there are multiple themes I maintain that will take a lot of time to safely convert to the new store structure. In the meantime, I need a fast and simple way to bundle .scss and .js files. I could of course continue to use CodeKit for this purpose, but it feels like overkill for such a simple task. I also want to make it easier to run build steps as part of a deployment pipeline or work with other developers on a theme, so free open-source command line tools have some additional benefits.

Fortunately, esbuild is perfect for the task. It's fast, and although it requires some config I only needed less than 20 lines of code to replace my CodeKit setup.

My esbuild setup needed to:

bundle .js imports for browsers (and support some older browsers)
bundle .scss files to a .css file
minify the output
watch and bundle files on change

For the simplest set up you can just run esbuild from the command line without the need for a node_modules folder, but to handle .scss files and support older browsers requires a build config.

Set up

Here's a typical setup when converting a theme from CodeKit. My file structure typically looks like this:

assets/
...
src/
├─ scripts/
│  ├─ modules/
│  ├─ theme.js
├─ styles/
│  ├─ modules/
│  ├─ theme.scss

The only thing I would need to change is to import styles at the top of src/scripts/theme.js

import '../scss/theme.scss';

Install

I can install esbuild and a plugin to compile .scss files as npm packages via the command:

$ npm i esbuild esbuild-sass-plugin --save-dev

As esbuild relies on module imports "type": "module" needs to be present in the package.json file.

Build config

The convention is to set up a build file as esbuild.config.js. The example below takes the theme.js file as the entry point and compiles the minified output to the assets directory in a format for browsers that support the es2018 syntax. This allows for some slightly older versions of browsers to be supported, but not legacy versions like IE11 which I no longer actively support.

import esbuild from 'esbuild'
import { sassPlugin } from 'esbuild-sass-plugin'

esbuild.build({
  entryPoints: {
    theme: 'src/scripts/theme.js',
  },
  bundle: true,
  outdir: 'assets',
  target: ['es2018'],
  plugins: [sassPlugin()],
  minify: true,
  watch: true,
}).then(() => {
  console.log('Watching files...')
}).catch((e) => console.error(e.message))

Running node esbuild.config.js will bundle the files to the assets folder and watch for any changes to imported files. I usually add that to a "start" script so a boilerplate package.json might look like this.

{
  "devDependencies": {
    "esbuild": "^0.12.15",
    "esbuild-sass-plugin": "^1.4.8"
  },
  "scripts": {
    "start": "node esbuild.config.js"
  },
  "type": "module"
}

Next steps

I now have a setup that allows me to organise my code in a way that suits me best. I can leverage the features of Sass and npm with instant browser updates, generate minified assets and see the results of my changes almost instantly in the browser.

I'm still looking at ways to improve my process and I plan to introduce things like type safety, automated testing and code linting. I feel positive that this is all a step in the right direction.

Update

I have added a post on how to update your config to automatically add vendor prefixes to the compiled CSS using PostCSS and the Autoprefixer plugin.

[^1]: CodeKit provides a GUI for bundling assets with great defaults without having to resort to using a complex Webpack config like Shopify's Slate Theme. It also allowed me to set up a local server that could proxy to a specific development theme on the store.

[^2]: One drawback was that the bundling and syncing weren't instant, so I would need to set a 2-3 second delay on the refresh to allow for the bundled files to be uploaded to Shopify. Kudos to CodeKit for including that functionality though.

[^3]: Another was that at some point CodeKit released a fix for a bug where some URLs weren't being encoded. Unfortunately, I realised I had been relying on that bug to make it easier for me to quickly launch a development server. This is not a knock on CodeKit. It must have saved me hundreds of hours over the years I've been using it and it's still my go-to for lots of projects. There just has never been a great out-of-the-box developer experience for managing themes on Shopify.

An interview by Sam Waller for Nativve

Thu, 15 Jul 2021 00:00:00 GMT

Building the information super-highway

The internet… it’s pretty big these days, isn’t it? The so-called information superhighway has gone from being a quiet country lane to a fully-fledged six-lane autobahn, and is showing no signs of slowing down.

But this rapid development didn’t just happen on its own—behind all those fancy websites there’s a slew of hard-working web designers, building the brave new world one line of code at a time. Mike Fallows is one of them.

We met up with him in the physical world to discuss the place they call cyberspace.

Read the full interview on nativve.com.

Photos and words by Sam Waller.

Quickly export Shopify data to a CSV

Mon, 12 Jul 2021 00:00:00 GMT

Shopify provides some simple tools to export your data from the admin. There are also plenty of apps available that enable you to manage complex data exports.

But sometimes I just want to export some data into a CSV file, either from a resource that Shopify doesn't expose in the admin or that includes a field like the resource ID, that's not present in the standard exports. It would be nice to be able to do it without the cost or hassle of installing an app.

I've found a couple of simple scripts that have been published that do something similar, but they were either unmaintained and needed updating or required you to hardcode values to configure the resources you wanted to export.

So I decided this would be a good excuse to try and learn some more Node.js basics and leverage a handy Node wrapper for the Shopify API.

My end goal was to have a script where I could just set up some API access credentials, plug some variables into a .env file and quickly kick out a CSV from the command line. Referencing some of the existing implementations, I surprised myself by putting something together that did that in less than an hour and fewer than 100 lines of code.

It made me realise how easy and accessible using Node is for running small tasks locally where previously I might have used a shell script or full-blown app.

You can check out and use my simple Shopify CSV Exports script on GitHub.

Making this website

Sun, 11 Jul 2021 00:00:00 GMT

I have planned to have a personal site for a long time and in this (my first!) post I'm going to cover how I selected the technology used to build this site and why.

The main roadblock to having my own site over the years has been a mixture of "analysis paralysis", the commitment to maintaining it (cobbler's shoes) and for a large part the fear of it being - well - a bit rubbish.

I'm not a great writer, nor prolific, but I do document a lot of thoughts in emails. Email can be a great resource to dig into, but I hope a personal site of writing will serve as a way to distil those thoughts that are more important to me. I also want somewhere I can experiment freely, without the commercial considerations of professional work.

Left to my own devices, I'm pretty sure I would have put it off indefinitely. But as is so often the way, a casual conversation with a friend turned out to be the motivation I needed.

Thinking about what would be the best solution for him, helped me better consider what I would want. I wanted something that would be:

Low friction to update

I don't have a habit of writing a blog, and I know enough about myself that any substantial barrier to publishing new content will result in failure. I want it to be as easy as copy-pasting an email I've written. I want to be able to write in Markdown, and I don't want an editor that's going to start injecting cruft into the document. I want to be able to write directly in my code editor if it suits me and other times be able to use a GUI if I want to and still have version control.

Low cost

These days a few static pages of a personal blog needn't come with running costs to host. I don't want the "gym subscription" effect that contributes to feeling guilty about not writing more often. I've had such a good experience with Netlify hosting simple landing pages, I was looking for something easy to host there, but not necessarily tied to that service.

Portable

This basically means the freedom to switch tools easily whenever I need, or want to, or even archive the whole thing if I change my mind. I don't want an all-in-one solution, but pieces that can easily be swapped out for building, editing, hosting, etc.

Easy to maintain

I don't want to commit to maintaining a server and the evolving languages or database versions that come with that choice. I want to be able to have purple patches where I can work on it a lot, but also have the freedom to just leave it alone for long stretches.

Fun to tinker with

Part of the appeal of having a personal site is having a place where I can just try things out (in public). I'm fortunate enough to have clients with a lot of confidence in me, so I get plenty of creative opportunities in my professional work. Yet there are still times I want to be able to quickly try out a new idea free from commercial constraints, but may also serve as a demonstration of an idea that I can share when necessary.

Picking a stack

In 2021 there are a lot of options to choose from: headless CMS providers like Contentful or Sanity; hosted platforms like Tumblr or Substack; self-hosting a Wordpress or Ghost site. But these fail on either having to maintain a server, being tied to a service, being restricted in how much you can customise them, potentially incurring too high a financial cost or just subjectively being unappealing.

It would also be true to say that my experience with Netlify was a huge influence. I've been so impressed with it that it is my first consideration when hosting any static sites.

So this steered me towards static site generators. I already had some experience building client sites with tools like Jigsaw (PHP), Gatsby (React) and Routify (Svelte). I had success with all of them, and consider them great tools. I also considered Hugo (Go) and Jekyll (Ruby), but in the end, I felt like they all required either too much code out of the box, were subject to change, or meant committing to a single language.

I had been aware of Eleventy being a relative newcomer and had read some glowing reviews but still wasn't sure I "got it". Then I watched the creator, Zach Leatherman, demo it and its simplicity frankly blew me away. It felt easy to grasp, very flexible and lightweight and I was excited to try it out. You could literally start your site from a single file with zero config. It also supported Liquid syntax which I use regularly on Shopify themes so the learning curve was much less steep.

I could see that it was simple to deploy to Netlify (and others) via Git, and had support for Netlify CMS (which I'd used) as well as ~~Forestry~~[^1] TinaCMS[^2] which I was interested to try out.

So Eleventy it is, with GitHub and Netlify.

[^1]: Update: I went with Forestry and I can recommend it. [^2]: Further update: Forestry is now TinaCMS and still recommending it.

Mike Fallows

Adding an SVG favicon with dark mode support

Dark mode support

Optimising CSS minification in Liquid

Original

Test

Results

Extracting to a snippet

Avoiding a DOMContentLoaded gotcha with readyState

Prefill a Shopify discount with the Fetch API

Why not use an Automatic Discount?

Just use fetch

Caveats

Implement a low stock notice in a Shopify theme

Requirements

Demo

Considerations

The code

Other considerations

This is the way

Quick error reporting with Val Town

Welcome to Val Town

Creating a store

Creating an endpoint

A note on security

Sending data to Val Town

Links #5

Observing cart changes in a Shopify theme

Detecting changes to the cart

Determine the changes to the cart

Retrieving and storing cart state

Identifying items that have been added or removed

Identifying items that have been updated

Wrapping up

Add a custom domain to CloudFront with Cloudflare

Pick a domain for the CDN

Set up a new SSL certificate in ACM

Validate the CDN via Cloudflare

Assign the SSL certificate

Create the DNS records for the custom domain

Test, test again and be patient

Detect subscription orders in the Shopify checkout

The result

Why the hacky inspection of selling_plan.name?

Why not use Customer Events?

Adding search to an Eleventy site

Finding my search solution

Honourable mention

Links #4

Hello World with Lit

Aims

Getting set up

Rendering a component

Passing properties

Mutating the data

Styling

Thoughts

Links #3

Adding a `robots.txt` file to an Eleventy site

I was mistaken

Adding a robots.txt file

Excluding pages from sitemap.xml

Compiling `.kit` files with Grunt

Laravel Sail, Vite and SSL with a custom domain

Using a custom domain

Securing the domain with Caddy

Securing Vite's dev server

Bulk deleting Cloudflare DNS records

The problem

A fix

Handling dark mode in HTML emails

Declaring dark mode support

Providing alternative colours

Handling alternate images

Other considerations

Links #2

Making a Shopify Theme App Extension for Google Site Verification

Theme app extension benefits

The verification tag

Creating the app

Just use `fetch`

Adding a `robots.txt` file

Excluding pages from `sitemap.xml`

The new `image_tag` filter

Using `robots.txt`

Using the `seo.hidden` metafield