DEV Community: Mike Fallows

Optimising CSS minification in Liquid

Mike Fallows — Tue, 24 Oct 2023 23:00:00 +0000

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.

Prefill a Shopify discount with the Fetch API

Mike Fallows — Mon, 23 Oct 2023 10:00:00 +0000

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¹ 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!

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

Mike Fallows — Thu, 19 Oct 2023 23:00:00 +0000

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".

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.

const inventory = [
  {%- for v in product.variants %}
    { id: '{{ v.id }}', quantity: '{{ v.inventory_quantity }}' },
  {%- 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="quantity">
      <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 quantitySelector = '.quantity';
    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 | json }}, quantity: {{ v.inventory_quantity | json }} },
      {%- endfor %}
    ];

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

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

    // Append the notice container
    quantityEl.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>

Customisation

You could add the inventory threshold as a section setting. That would also allow you to populate the threshold through a value stored on the product as a metafield 🙌

Quick error reporting with Val Town

Mike Fallows — Mon, 21 Aug 2023 12:00:00 +0000

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:

let store = [];

Yep, that's literally it. Val Town will let you add up to 100kb of data to that value (on it's 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 the @me shorthand for referencing your own Vals and also that it's constructed as an IIFE to make sure that the function is invoked when you 'run' the Val. A cool feature of Val Town is that you can easily reference other people's Val's with the @ syntax, but I think that it will be going away at some point in favour of standard import statements which is even cooler.

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).

const clear = (async () => {
  @me.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 console.email global 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.

function report(subject, message, error = false) {
  @me.store.push({ subject, message });

  if (error) {
    console.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 and 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.

Observing cart changes in a Shopify theme

Mike Fallows — Mon, 06 Mar 2023 00:00:00 +0000

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/¹

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.

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. ↩

Detect subscription orders in the Shopify checkout

Mike Fallows — Fri, 17 Feb 2023 00:00:00 +0000

This week I needed to help a client distinguish which orders contained subscriptions so they can measure the results of their PPC advertising. As their business model is heavily geared towards subscriptions and subscriptions will typically indicate a much higher LTV, 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.

Adding search to an Eleventy site

Mike Fallows — Wed, 08 Feb 2023 00:00:00 +0000

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.

Hello World with Lit

Mike Fallows — Mon, 24 Oct 2022 00:00:00 +0000

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"¹ 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 a 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.

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. ↩

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

Mike Fallows — Thu, 01 Sep 2022 00:00:00 +0000

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.

Laravel Sail, Vite and SSL with a custom domain

Mike Fallows — Fri, 29 Jul 2022 00:00:00 +0000

The Shopify apps I build are typically powered by Laravel. Version 8 introduced Sail¹ as an alternative to Valet and version 9 introduced Vite² 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.

"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. ↩
"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

Mike Fallows — Mon, 25 Jul 2022 00:00:00 +0000

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!

Making a Shopify Theme App Extension for Google Site Verification

Mike Fallows — Wed, 23 Feb 2022 00:00:00 +0000

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.