Forem: Jordan Finneran

Shopify App: October 2025 Updates

Jordan Finneran — Mon, 06 Oct 2025 11:34:55 +0000

Intro

I've been a little quiet blogging recently, I've been busy working on Transfers and Replenishment Limits for my app.

But there has been a lot of updates in the Shopify app world released recently, so time to catch up on the latest changes!

App Bridge

Shopify App Bridge has changed a lot over recent years. For those not familiar it is a JavaScript library that helps you build apps that integrate with Shopify Admin and the Shopify APIs.

A little timeline of the changes:

2018: App Bridge was first released as a npm package. 🤯
2022: App Bridge 3 was released, the last major version on npm.
2024: App Bridge 4 was released; this was a move off npm to a unversioned CDN script tag.
2025: App Bridge and Polaris are now both moving to a unversioned CDN script tags, unifying the development experience further.

NPM

If you're on an older app bridge version or doing npm i @shopify/app-bridge then you will need to update your code to move off this and instead use the script tag.

Your app will need to include the following in the head of your HTML, and it should be the first script tag to load.

<head>
    <meta name="shopify-api-key" content="%SHOPIFY_API_KEY%" />
    <script src="https://cdn.shopify.com/shopifycloud/app-bridge.js"></script>
</head>

Now when your app loads Shopify will take care of loading the latest version of App Bridge for you and setting up a shopify global variable for you to use.
Shopify have got some helpful migration guides available too.

UI components

If you were using the script tag, you might have used the UI components that were available on the global shopify variable.
For example, ui-modal, ui-nav-menu, ui-save-bar and ui-title-bar or the React wrappers around these components.

These were separate to Polaris components and lead to a bit of a confusing experience, with these being added via the script tag and Polaris being added via npm.

Shopify has been doing work to unify the experience of using Polaris and App Bridge together. You can now use the new Shopify Web Components which are more consistent with Polaris components.
These are available via the same script tag as App Bridge, so you do not need to change anything there.

These new components are prefixed with s- and have a slight difference in usage, which you can read more here for the App Bridge components: App Bridge Web Components

Unversioned

Now this is a controversial move, but Shopify have decided to move to an unversioned script tag for both App Bridge and Polaris. This means they will update and serve the latest version of these libraries to you automatically.

This is a big change from the previous approach of using versioned npm packages.

Now the benefits of this are you always get the latest features and bug fixes without having to do anything; however, it does mean you have less control over when you get these updates.

However, seeing the long long tail of apps on older version of App Bridge, I'm looking at you the 500ish downloads of a 7-year-old version of the app bridge package in the last 6 months! I can see why managing it this way makes sense for Shopify, even if it feels a little riskier for app developers.

Polaris

Polaris which is Shopify design system has also moved to an unversioned script tag and seen a lot of changes in October 2025.

Previously Polaris was only available as React components via npm package. This was really helpful as React was very popular in the web and JavaScript world at the time.

However it meant you had to use React to use Polaris, which was not ideal for everyone especially if your app backend wasn't in JavaScript.

Now Polaris is available via a script tag, which loads in the new Shopify Web Components! These are framework agnostic, so you can use them in any web app regardless of the backend or frontend framework you are using.

I know web components can be a bit of a scary topic for some, especially given the historic of support in Javascript frameworks.
But it is now widely supported across all modern browsers and frameworks have got much better support for them.

Again, I can see why Shopify has made this change:

More consistent experience for merchants when using apps, remember when Shopify changed the primary button from green to black? Now all apps using Polaris will get this change automatically rather than a slow move over by apps.
Easier to use Polaris in any app regardless of the backend or frontend framework, as these are web standards you can use the tooling you want and optimise your app with your expertise without learning React.
Better caching and admin loading performance, as Shopify can do smarter caching of this across apps rather than each app loading the same or similar libraries.
Better performance for apps, as there will be less Javascript and bundle to run compared to React.
Consistent experience because these can be run anywhere it means Admin components, UI extensions across of all of Shopify can use the same components and reducing the maintenance burden for Shopify and you as app devs!

Migration

If you were using Polaris via npm, you will need to update your code to move off this and instead use the script tag and new web components.

Your app will need to include the following in the head of your HTML, and it should be after the App Bridge script tag.

<head>
  <meta name="shopify-api-key" content="%SHOPIFY_API_KEY%" />
  <script src="https://cdn.shopify.com/shopifycloud/app-bridge.js"></script>
  <script src="https://cdn.shopify.com/shopifycloud/polaris.js"></script>
</head>

I spoke to Shopify about doing this migration and they recommended using the Shopify Dev MCP (Model Context Protocol) server to help AI tools to better understand the documentation and help you migrate.
I will be giving this a try later this month and share how I get on!

This also is a good opportunity to review your app design and see if you can improve the user experience with the latest Polaris components and design patterns.

It also gives you the opportunity to review your app framework, for example if you were using React before you could consider moving to something like Preact or Astro for better performance, developer and merchant experience.

Here is a link to the updated Polaris and App Bridge documentation.

Remix

I'm just going to touch on this one quickly, the previous Shopify CLI created apps using Remix.

This has now been changed to React Router, however, don't fear this as it is a bad naming change rather than a huge underlying change.

Remix was built on top of React Router, and then they basically merged to have the same features. I won't go into the history of why, but you can read more here: Remix and React Router.

Just wanted to highlight this if you are creating a new app via the Shopify CLI and see this change.

UI Extensions

UI Extensions have also seen some updates recently too! Previously you could build in React or Vanilla JS.

React gave us a familiar way to build extensions but lead to large bundle sizes when Shopify needed to load these in the Checkout, POS, Admin etc.
Vanilla JS was a bit more bare bones and lead to a lot of boilerplate code to get things working.

Also, each team had a slightly different set of components and APIs to use, which made it a bit inconsistent to build with.

Because of the unifying of Polaris to web components, you can now use the unified Polaris web components in your UI extensions!

This should mean you don't have to repeat very similar but slightly different code across different extensions, which I cannot wait for. POS UI extensions were always more different than the others so very happy to see this be unified.

And because of this change Shopify have also moved to Preact as the main framework for building UI extensions.
Preact if you haven't heard of it is a smaller and faster alternative to React but is compatible with React.

I think this is a great choice as it gives a good developer experience, but also much better performance for merchants. This also means if you want to, you can use Preact Signals which is a great performance optimisation for state management over hooks.

I was already using Preact for the Admin side of my app, because of the performance and bundle size benefits. So, I'm very excited to be able to use it across the app and UI extensions.
Each of the UI extensions have their own guide to migrate:

Admin UI Extensions don't have migration guide yet, but it will be similar to the other extension types linked about. You can read about the new setup here: Admin UI Extensions

Lastly to note there is a new 64 KB file size limit for UI extensions, so just be aware of this when building your extensions, as you won't be able to exceed this limit.

Summary

In summary, there has been a lot of changes in the Shopify app world recently, I know it can feel a bit overwhelming and keeping up with everything can be a challenge.

Firstly, don't panic, your existing apps will continue to work as normal, and you can migrate at your own pace.

Secondly, take the time to read through the documentation and understand the changes and how they impact your app. I would plan out the migration across your apps and extensions and take the opportunity to review your app design and framework choices to improve the experience for both you and merchants.

Finally, if you do come across any issues or rough edges, make sure to report and share it in the Shopify Dev forum, as the Shopify teams have got really active there which has been great personally.

I'm planning on tackling this towards the end of the month and November, so I'll share how I get on and any tips and tricks I find along the way.

Pimsical is my business, where you can find more Shopify content, my Shopify apps or help to optimise your operations and streamline your business backend.

Shopify: Getting to grips with GraphQL

Jordan Finneran — Tue, 13 May 2025 09:08:22 +0000

Intro

The Shopify GraphQL documentation can be a lot to get to grips with, even if you adopt an approach I recommend.

So what can make it easier for us, especially keeping up to date with the new versions and changes...

Linting!

This linting is designed to work with eslint, which is very commonly used in the JavaScript world.

To use this you should have an eslint.config.js file.

Building ontop of the great work by @graphql-eslint/eslint-plugin, I've created a new eslint plugin to add some Shopify GraphQL specific best practices!

This means you can check your GraphQL for unknown fields, deprecations when migrating between versions and best practices around mutations and pagination for example.

With Shopify Codegen

The linters work best combined with knowledge about Shopify GraphQL Schema.

If you are already using Shopify GraphQL Codegen, this does a lot of the work for us and is our recommended approach.

In your .graphqlrc.ts or equivalent JS file, ensure that pluckConfig is exposed in the default extensions object.

This will allow the linters to pick up the GraphQL code from your codebase using the same prefix as the codegen tools, it also uses the schemas from here as well.

Here is an example .graphqlrc.ts file, of how to expose this pluckConfig.

However as long as the path projects.default.extensions.pluckConfig exists in your config it will be used, so you can config this how you want to.

import { shopifyApiProject, ApiType } from '@shopify/api-codegen-preset';

const apiVersion = '2025-04';
const config = shopifyApiProject({
  apiType: ApiType.Admin,
  apiVersion: apiVersion,
  documents: ['./**/*.{js,ts,jsx,tsx}'],
  outputDir: './shopify/types',
})

export default {
  schema: `https://shopify.dev/admin-graphql-direct-proxy/${apiVersion}`,
  documents: ['./**/*.{js,ts,jsx,tsx}'],
  projects: {
    default: {
      ...config,
      extensions: {
        ...config.extensions,
        pluckConfig: config.extensions?.codegen?.pluckConfig,
      },
    },
  },
};

Without Codegen

If you are not using the codegen tools, you can manually define the schema in your eslint.config.js under parserOptions or add an equivalent Graphql Config file which will automatically get picked up.

Here is an example where I'm passing the schema information in parserOptions.

import js from '@eslint/js';
import graphqlPlugin from '@graphql-eslint/eslint-plugin';

export default [
  {
    files: ['**/*.graphql'],
    languageOptions: {
      parser: graphqlPlugin.parser,
      parserOptions: {
        graphQLConfig: {
          schema: `https://shopify.dev/admin-graphql-direct-proxy/2025-04`,
          documents: [['./**/*.{js,ts,jsx,tsx,graphql}']],
        },
      },
    },
    plugins: {
      '@graphql-eslint': graphqlPlugin,
      'pimsical-shopify-graphql': shopifyGraphqlPlugin,
    },
    rules: {
      ...graphqlPlugin.configs['flat/operations-recommended'].rules,
      '@graphql-eslint/require-selections': 'off',
      ...shopifyGraphqlPlugin.configs['flat/recommended'].rules,
    },
  },
];

eslint config

Now we've got our codegen and schema information prepared we can configure the linting!

Installation

Get all the packages installed.

npm i -D eslint @eslint/js @graphql-eslint/eslint-plugin eslint-plugin-pimsical-shopify-graphql

Queries in code

If your GraphQL queries are located in your code in JavaScript or TypeScript files, the linter can parse them like so:

import graphqlPlugin from '@graphql-eslint/eslint-plugin'
import shopifyGraphqlPlugin from 'eslint-plugin-pimsical-shopify-graphql';

export default [
  // any other linting config you wanted to have
  {
    files: ['**/*.{ts,js}'],
    processor: graphqlPlugin.processor
  },
  {
    files: ['**/*.graphql'],
    languageOptions: {
      parser: graphqlPlugin.parser
    },
    plugins: {
      '@graphql-eslint': graphqlPlugin,
      'pimsical-shopify-graphql': shopifyGraphqlPlugin,
    },
    rules: {
      ...graphqlPlugin.configs['flat/operations-recommended'].rules,
      '@graphql-eslint/require-selections': 'off',
      ...shopifyGraphqlPlugin.configs['flat/recommended'].rules,
    },
  },
];

This will use the pluckConfig we defined earlier to extract the GraphQL queries out of the strings and into temporary .graphql files so they can be linted and checked, using the processor in the config, like magic!

This will then parse them with the graphqlPlugin parse to understand the format and begin linting them with both the plugins and the rules listed below.

You can always configure these rules of either plugin how you'd like it to work, but above is our recommended approach.

Queries in `.graphql` files

If your queries are already in .graphql files then you don't need the processor from above. So your config can look like:

import graphqlPlugin from '@graphql-eslint/eslint-plugin'
import shopifyGraphqlPlugin from 'eslint-plugin-pimsical-shopify-graphql';

export default [
  // any other linting config you wanted to have
  {
    files: ['**/*.graphql'],
    languageOptions: {
      parser: graphqlPlugin.parser
    },
    plugins: {
      '@graphql-eslint': graphqlPlugin,
      'pimsical-shopify-graphql': shopifyGraphqlPlugin,
    },
    rules: {
      ...graphqlPlugin.configs['flat/operations-recommended'].rules,
      '@graphql-eslint/require-selections': 'off',
      ...shopifyGraphqlPlugin.configs['flat/recommended'].rules,
    },
  },
];

Run

Now you can run your linting! Use whatever command you already have or npx eslint .

Any deprecated fields will be listed along with any other schema issues and best practices. Helping keep on top of Shopify GraphQL!

Conclusion

I hope that this can help keep on top of GraphQL changes, updates and best practices. Making it a little easier to work with GraphQL going forwards.

If you have any suggestions for best practices or if there is something tripping you up in GraphQL, I'd love to hear about them and you can raise an issue on Github as this project is open source!

Learn More

Shopify: Unlocking the power of Shopify's new Product Model & APIs

Jordan Finneran — Wed, 16 Apr 2025 09:01:13 +0000

Intro

There have been a lot of recent changes related to managing product information with Shopify's APIs, particularly in how app developers now interact with product data. These include changes to the product model, how products themselves work, and migrating from REST to GraphQL.

As an developer who has experience building with the new Product APIs model, I'd like to share my experiences, and unpack some real-world examples that will help with understanding the updates and migration.

Product Model

Let's go over the product model changes first, as that will help us understand why GraphQL operates the way it does.

Previously the product model was compact with Product, Images, Product Variants, and Inventory Items all co-located together. The images were tied to Products and Variants so could not be reused between products in any file/media gallery.

Inventory Item information such as SKU and Weight were all combined with Product Variants. And of course, Product Variants were always attached to Products meaning we could only ever have 200 variants.

This made it easy to work with from a developer perspective, as you got all data in one API call, but you can see how it wasn’t easily extensible or very future proof.

The new product model separates these key components of a product into something that looks like the image below:

What you'll notice is that this also matches the Shopify Admin layout of a product, with a separate page for product variants, and separate boxes for media and inventory within that. Remembering the Shopify Admin Product layout will be useful when we come to looking at the GraphQL Product APIs.

The changes to the model give us some great capabilities:

Up to 2048 variants.
Media can be shared between products without copying the file multiple times, which makes it easier for merchants to manage
Support for larger videos and 3D Models as well as images.
Separation of Product and Product Variant merchandising information from Inventory and Operational data.

You can learn more about how to use the latest GraphQL product APIs in the developer documentation, which describes the model and components and some of the reasons behind the changes, and hopefully you can see some of the opportunities this update unlocks for us as developers to do a lot more with products.

GraphQL

Let's dive into some GraphQL now. If you’re new to GraphQL I'd recommend checking out the Shopify developer documentation first, which also includes a detailed migration guide too.

Rate Limits

One important aspect to understand when migrating from REST to GraphQL is that the rate limits are quite different. You may well need to make more calls in GraphQL than REST, but the rate limits are calculated based on a points system.

Points are determined either by how much each query costs, or with mutations that will always cost 10 points, regardless of the changes being made. You have a lot more points in GraphQL to use, compared to REST limits, so don't worry too much if you need to make additional GraphQL requests compared to REST.

You can also use Bulk Operations in GraphQL to create or update multiple products and variants in one go or process larger volumes of data.

Creation

The first thing we'll want to do with any product is create it. How exactly you do this will depend on how you want to work.

You can first create just the top level product information using productCreate, and if you're starting from scratch I would recommend this simpler option. You can see an example of what this would look like below:

const query = `mutation createProduct($product: ProductCreateInput!) {
  productCreate(product: $product) {
    product {
      id
    }
    userErrors {
      field
      message
    }
  }
}`

const variables = {
  "product": {
    "title": "Winter hat",
    "productOptions": [
      {
        "name": "Color",
        "values": [
          { "name": "Grey" },
          { "name": "Black" }
        ]
      }
    ]
  }
}

Alternatively you could use productSet which allows you to create a more complete product with variants etc., which is easier if you are migrating from an existing app or REST integration. I’ll give an example of this below given the complexity involved here, where we create a product, variants and set weights and inventory information.

One important thing to note here is that productSet is an upsert endpoint, it will create or update a product so just be aware of this, particularly if you are only updating variant information.

The first thing to call out from the example is we have a synchronous input option here, if you are creating a large product with lots of files and variants, it is best to run this as not synchronous otherwise it may timeout. You can then query the productSetOperation to check when this has completed.

As always with GraphQL ensure you check the userErrors in your response to catch any issues with your input. You can of course run this as a bulk job if you want to create a lot of products in one go.

On the input here is an example creating a product with a variant, media item (file) and inventory information.

const query = `
mutation createProductAsynchronous($productSet: ProductSetInput!, $synchronous: Boolean!) {
  productSet(synchronous: $synchronous, input: $productSet) {
    product {
      id
    }
    productSetOperation {
      id
      status
      userErrors {
        code
        field
        message
      }
    }
    userErrors {
      code
      field
      message
    }
  }
}`

const variables = {
  "synchronous": false,
  "productSet": {
    "title": "Winter hat",
    "metafields": [
      {
        "description": "<your-description>",
        "key": "<your-key>",
        "namespace": "<your-namespace>",
        "type": "<your-type>",
        "value": "<your-value>"
      }
    ],
    "productOptions": [
      {
        "name": "Color",
        "position": 1,
        "values": [
          {
            "name": "Grey"
          },
          {
            "name": "Black"
          }
        ]
      }
    ],
    "variants": [
      {
        "optionValues": [
          {
            "optionName": "Color",
            "name": "Grey"
          }
        ],
        "price": 79.99,
        "inventoryItem": {
          "measurement": {
            "weight": {
              "value": 1.70,
              "unit": "GRAMS"
            }
          },
          "sku": "SKU-123",
          "tracked": true,
        }
      },
      {
        "optionValues": [
          {
            "optionName": "Color",
            "name": "Black"
          }
        ],
        "price": 69.99,
        "inventoryItem": {
          "measurement": {
            "weight": {
              "value": 1.70,
              "unit": "GRAMS"
            }
          },
          "sku": "SKU-456",
          "tracked": true,
        }
      }
    ]
  }
}

Variants

If you’ve used productCreate and want to then create some variants and media, you can then use the productVariantsBulkCreate which will allow you to create the variants and media items on a product.

Personally I would recommend using productCreate and this method, instead of productSet, to manage the product and variants as it keeps everything a little easier to understand. The input data is less complex, there is less risk as these are not upsert endpoints and you have to store less identifiers than needed with productSet. I believe it also sets you up nicely for updates as they follow a similar format.

const query = `mutation productVariantsCreate($productId: ID!, $variants: [ProductVariantsBulkInput!]!, $media: [CreateMediaInput!]) {
  productVariantsBulkCreate(productId: $productId, variants: $variants, media: $media) {
    productVariants {
      id
      title
      selectedOptions {
        name
        value
      }
    }
    userErrors {
      field
      message
    }
  }
}`

const variables = {
  "productId": "gid://shopify/Product/20995642",
  "variants": [
    {
      "price": 15.99,
      "compareAtPrice": 19.99,
      "optionValues": [
        {
          "name": "Golden",
          "optionId": "gid://shopify/ProductOption/328272167"
        }
      ]
    }
  ],
  "media": [
    {
      "mediaContentType": "IMAGE",
      "originalSource": "someExternalURL.jpg"
    },
    {
      "mediaContentType": "VIDEO",
      "originalSource": "stagedMediaResourceURL"
    }
  ]
}

Updates

Once you have a product, you’re going to want to update it or the variants. I'll cover updating media in the next section.

Again, you can use productSet here, as it will update the product. Make sure if you are doing this you provide IDs for all the existing variants, files etc. otherwise you will end up with duplicates of variants or other product content.

Alternatively you can use the specific methods, again this is what I would recommend, we’ve got productUpdate, productVariantsBulkUpdate which can allow you to really easily update certain properties on the product.

An example of updating a product and adding media.

const query = `mutation updateProductData($input: ProductInput!, $media: [CreateMediaInput!]) {
  productUpdate(input: $input, media: $media) {
    product {
      id
    }
    userErrors {
      field
      message
    }
  }
}`

const variables = {
  "input": {
    "id": "gid://shopify/Product/912855135",
    "descriptionHtml": "Updated description"
  },
  "media": [
    {
      "mediaContentType": "IMAGE",
      "originalSource": "someExternalURL.jpg"
    },
    {
      "mediaContentType": "VIDEO",
      "originalSource": "stagedMediaResourceURL"
    }
  ]
}

There are also some more specific named methods, if you are looking to change a product's options or published status for example.

An example of an existing product with colour options, now adding size options and automatically creating the new variants. If the product didn’t have the size options when initially created.

const query = `mutation createAdditionalOptions($productId: ID!, $options: [OptionCreateInput!]!, $variantStrategy: ProductOptionCreateVariantStrategy) {
  productOptionsCreate(productId: $productId, options: $options, variantStrategy: $variantStrategy) {
    userErrors {
      field
      message
      code
    }
  }
}`

const variables = {
  "productId": "gid://shopify/Product/20995642",
  "variantStrategy": "CREATE",
  "options": [
    {
      "name": "Size",
      "values": [
        { "name": "Small" },
        { "name": "Medium" },
        { "name": "Large" }
      ]
    }
  ]
}

Managing Media

The developer documentation comprehensively describes how to manage media for a product, so I won't repeat what is outlined there, but there are a couple of things I think are important to highlight:

Previously, REST calls only supported one image at a time. With the GraphQL methods, you can upload multiple images and other media in the same productUpdate call.
You can also stage your media so multiple images, videos and 3D models can be added at the same time, making it more efficient for adding multiple media items at once.
You can also use bulk imports with productUpdate, if you want to update multiple products and media.
If you're adding multiple media/images at once in a single GraphQL mutation, this will still only cost 10 points towards rate limits.
You can still include an external link to an image, when adding it to a product or variant. However, this normally means you have to host it somewhere first. Now you can use stagedUploadsCreate so you don’t need to do that anymore, and you can upload multiple images/videos or 3D items in one go!

Inventory Item

Up until now we've been dealing with the product or product variant information, which is mostly around merchandising the product and preparing it for sale. This is where the inventory item comes into play, it represents the actual physical item that will be sold.

Here is where the Stock Keeping Unit (SKU), weight or other logistical information all exist and is connected to the various inventory levels at each location. You can set some of these properties when creating a variant as we discussed previously. However it does also have its own methods as well, for example updating an inventory item.

An example of updating the information.

const query = `mutation inventoryItemUpdate($id: ID!, $input: InventoryItemInput!) {
  inventoryItemUpdate(id: $id, input: $input) {
    inventoryItem {
      id
    }
    userErrors {
      field
      message
    }
  }
}`

const variables = {
  "id": "gid://shopify/InventoryItem/43729076",
  "input": {
    "cost": 145.89,
    "tracked": false,
    "countryCodeOfOrigin": "US",
    "provinceCodeOfOrigin": "OR",
    "harmonizedSystemCode": "621710",
    "sku": "SKU-123",
    "measurement": {
      "weight": {
        "value": 1.70,
        "unit": "GRAMS"
      }
    }
  }
}

InventoryItem also has its own webhooks, so if you only need these pieces of information, for example for a warehouse, you can subscribe to the inventory webhook instead of relying on the product webhooks, which should be a bit more efficient.

Webhooks

If you're not using webhooks yet, they're a useful tool to get information out of Shopify asynchronously without rate limits. There are some useful docs here on them if you’d like further background https://shopify.dev/docs/apps/build/webhooks

Product Webhooks will now ONLY include the first 100 variants, all additional variants will be listed in the “variant_ids” property, this will also be backdated onto all product webhook versions. This will inform you which variants have been updated, you can then use the ID to more easily get the product variant information from Shopify API.

Also, there is the opportunity here to move beyond just product webhooks as there are also webhooks for the inventory item updates, inventory level updates, variants in and out of stock. So, make sure you check the documentation if there is an alternative that works for you!

Example Use Case

Let's unpack a full real world scenario. For example, let's imagine you have a products' SKU, and you want to update its inventory information and publication status, which is a common process.

This is how I would approach the problem and determine which GraphQL calls I may need:

It’s a SKU so it's Inventory Item which is related to a product variant (we know that from where the input is located in the Shopify Admin), so find we can that query and see if I can search by SKU, which we can https://shopify.dev/docs/api/admin-graphql/2025-01/queries/productVariants or https://shopify.dev/docs/api/admin-graphql/2025-01/queries/inventoryItems
From either query we can return a list of product variants on the nodes, so we need to look at that to see how we can get to the inventory and publication https://shopify.dev/docs/api/admin-graphql/2025-01/objects/ProductVariant
We can see on the variant it has Inventory Item which it says is for managing inventory, so we’ll probably need that ID later https://shopify.dev/docs/api/admin-graphql/2025-01/objects/ProductVariant#field-inventoryitem
But there’s nothing on there about the publication, so that must be on the product also that is where publications are on the Shopify Admin, there’s a load of fields on there about publication so grab the product ID which we'll probably need later as well https://shopify.dev/docs/api/admin-graphql/2025-01/objects/ProductVariant#field-product
From there we know we are now looking to make inventory changes, which will be a mutation and related to an inventory item. In the inventory section of the GraphQL docs mutations there is inventoryItemUpdate but that does have any quantities on, so let’s go with the one that has quantities in the name, which looks right and needs the ID we grabbed earlier https://shopify.dev/docs/api/admin-graphql/2025-01/mutations/inventoryAdjustQuantities
We saw before that the publication is on the product, so look through the product mutations for anything referencing it. There’s product publish, which sounds right and needs the product id from before, it is however deprecated but does direct you to the correct method of publishablePublish (my personal favourite mutation name) https://shopify.dev/docs/api/admin-graphql/2025-01/mutations/publishablePublish
We need to do multiple calls here which is fine, or if you want to you can combine mutations if you are doing them regularly. An example of how you can do this below, make sure each mutation has a unique alias. For example I'm calling mine detaching and appending.

const query = `mutation productVariantManageMedia(
  $productId: ID!,
  $detach: [ProductVariantDetachMediaInput!]!,
  $append: [ProductVariantAppendMediaInput!]!) {

  detaching: productVariantDetachMedia(productId: $productId, variantMedia: $variantMedia) {
    userErrors {
      code
      field
      message
    }
  }

  appending: productVariantAppendMedia(productId: $productId, variantMedia: $variantMedia) {
    userErrors {
      code
      field
      message
    }
  }
}`

If you're using NodeJS you're in luck because Shopify libraries are great.
This is a super lightweight GraphQL client for it @shopify/admin-api-client
If you're moving between REST IDs and GraphQL IDs then you can always get the legacyResourceId from the Admin API.
Lastly use the Shopify CLI and @shopify/api-codegen-preset to generate types from your GraphQL queries which makes working with the data much much easier.

Conclusion

I hope that this has helped add some context with real world examples and approaches to tackling the recent changes to product models and API’s. Once you’ve migrated to GraphQL, you're set up for the future, as this is Shopify’s primary API format now.

Which means upgrading and keeping track of any changes should be simpler for you and your apps in the future. Hopefully you can also see the opportunities that the product changes unlock for us to develop even more powerful product apps.

Shopify App: Where to store my app data?

Jordan Finneran — Wed, 12 Mar 2025 18:56:59 +0000

Intro

Building Shopify apps used to have only one option for storing your data, your own database. But Shopify platform has come a long way since then now we have got metafields and metaobjects, allowing us to store data in many ways across Shopify platform. Not only can we store data but also have control over the ownership and permissions models too!
But where is the best place to store your applications data? This blog post will explore the options available to you, and the best practices for storing your app data.

Questions

Theres some key questions about what your app is going to store and be used for, that can help you decide the best option of where to store your data.

You only need a rough idea of the answers to these questions.

1) What's the context of the data? i.e. does it align to a Shopify model would it make sense to store it on order/product etc or not
2) What's the volume of data like? i.e. are you storing a couple of key data points and config or thousands of records
3) Do you need to aggregate the information? i.e. compute totals across orders for example
4) Are there webhooks for the Shopify model? i.e. can you easily get a copy of data out of Shopify
5) Where will you need to access the data? i.e. only inside your app, on the storefront, on headless sites etc.
6) What's the access of that data look like? i.e. will there be constant or sporadic access of the data

Database

You will likely want a database to store some data regardless of the other information you'll want to store. As at the very minimum you will want to keep the store information, billing status, offline access token and contact info for your use and ease of access. This allows for a quick overview of the stores using the app, the billing plans in use, and provides the ability to contact them if necessary.

Always ensure you have secured this information, particularly the offline access token. You will want to encrypt the data at rest and in transit and ensure you are following best practices for securing your database.

Now we have covered the basics of what you will want to store in a database. Let us look at your answers to the questions above and where a database fits.

If you have a large volume of data to store, hundreds, thousands or more of items, you will likely hit limits on using metafields or metaobjects in Shopify so probably not best approach. A database using SQL or NoSQL would work best here as then the limits are all in your control.

If you need to aggregate the data regularly whether it be for dashboard, reports, or core app functionality, then a SQL based database is likely the right option. It will be much more efficient to do these aggregations than NoSQL. At the time of writing, you cannot aggregate across metafields or metaobjects in Shopify.

If you need to allow access to the data in your app from all over Shopify, whether it be your app, in liquid, headless etc. Then using your own database here would add complications for both you and the merchant in exposing the data, so a database might not be the right option here.

What is the access of the data you would store in a database? With constant requests, will you hit Shopify rate limits trying to access the metafields?
If it is going to be hit with substantial number of requests consistently then NoSQL database likely makes sense, just for scale.

Lastly how confident are you in what the data will look like, and will it need to change a lot over time? If not, then NoSQL might give you more flexibility as it does not need a specific schema and easier to change.
But SQL you will have to migrate the tables, and this could be annoying if you have to do that frequently.

Metafields

So, let us look at some of the options Shopify give us if we want to look beyond storing the data ourselves.

If the context of the data aligns to a Shopify model. Then you have some options, can you use the Shopify thing itself which saves you having to think of the format of the data and its lifecycle, like using draft orders or products etc and customising them.
But consider if other apps or the merchant might be using these for something else, will there be any impact and can you differentiate your versions of these, so it is clear to other apps and merchants what is create by your app or not.
Or does it make sense to extend the model using metafields, for example adding additional fields to a product or order. This is a great way to add additional information a Shopify model, in a structured way, instead of adding information to notes or tags.

Metafields with a definition can be viewed by the merchant in Shopify Admin, so you can easily add more information and context to Orders or Products for example. They can also be easily accessed from Liquid, Storefront, or other APIs inside of Shopify, making them ideal to access information across different areas.

Shopify have introduced some ownership and permissions for metafields now, so you can better control who can access that data and edit it. Giving you much better control over the data use inside of Shopify.

Metaobjects

If the data you want to store does not fit to the Shopify model, i.e. it is not directly related to an existing Shopify model, like products or orders. Then a metaobject might make sense, as here you can shape the data you want to store and allow customers to manage and edit that information as well.

These can also be easily viewed by the merchant in Shopify Admin under Content, so you can easily add more information. They can also be easily accessed from Liquid, Storefront, or other APIs inside of Shopify, making them ideal to access information across different areas.

Shopify have introduced some ownership and permissions for metaobjects now, so you can better control who can access that data and edit it. Giving you much better control over the data use inside of Shopify.

Not only that but the metaobjects can be translated as well, so you can support a more localised experience for the merchants if you are using the data on the shop front.

One size does not fit all

It may be the case that just one option does not fit all of what you need and that is also fine!

You could use a database for keeping the store information, and some data you need to aggregate.
If you can get data out of Shopify, leveraging webhooks for example. This could work really well, leveraging metafields, metaobjects in Shopify for your primary data storage and then keeping a copy of the data, you'd like to aggregate in a SQL Database. Meaning you get the best of both worlds!
Of course, you can also always use metaobjects and metafields together, to add even more context and information than using just one of these independently.

If you'd like to read more about metafields and metaobjects, here is a link to the Shopify documentation.

Summary

In summary, you can use Shopify Platform to easily store data for your application. You have got plenty of options to choose from, whether you use just one or multiple in combination make sure you pick the option that works best for you and your customers and merchants.

Pimsical is my business, where you can find more Shopify content, my Shopify apps or help to optimise your operations and streamline your business backend.

Shopify App Translations

Jordan Finneran — Sun, 29 Dec 2024 17:30:19 +0000

Intro

I've seen a lot of questions about the best way to integrate your Shopify app content with Shopify's Translate & Adapt app and allowing merchants to translate your apps content.
For example, if you are extending Shopify Checkout and would like merchants to be able to customise the translated content.

I've worked on this for a number of Shopify apps, so thought I'd share an approach.

Content

I believe the best way to allow custom translations of your apps content is to store the content in Shopify Metaobjects.
Metaobjects are pieces of content, which can easily be used across the Shopify Platform, either in Liquid or Storefront API. You can enable them to be translatable as well, which is what we will use later!

Ensure when you create the definitions they are not using app reserved prefix, e.g. beginning with $app, as otherwise Translate & Adapt app won't be able to access it.

Depending on how much content you want to translate you've got a couple of options here on designing your metaobject definition(s).

You may already have metaobjects or metafields with config for your app, I believe it's best to separate the content and config.

Specific Definitions

You could create one or many metaobject definitions, where each piece of content is a single_line_text_field.

The advantages of this are that if you have different content for different sections of your app, its easily understandable from the merchant's point of view.

For example, if you have content for the checkout, and their website. You could create two separate metaobject definitions, when this is displayed in Translate & Adapt app, it will be clear to the merchant, from the definition name and description, what the content will be used for.

However, there are some limits here. Firstly, you will be using the metaobject definition limits, which are fairly limited at the time of writing. Its best to be conscious that the merchant will be using other apps, which also could use definitions, so best to not be greedy with the number of definitions you create.

Also, there is a limit of 40 field definitions per metaobject definition, so if you have a limited amount of content the merchants can translate or can consolidate it down to 40 then this will work for you. Otherwise, you may want to create multiple metaobject definitions or consider the Extensible approach below.

Here is an example of what that looks like in Admin GraphQL API 2024-10.

mutation CreateMetaobjectDefinition($definition: MetaobjectDefinitionCreateInput!) {
  metaobjectDefinitionCreate(definition: $definition) {
    metaobjectDefinition {
      name
      type
      fieldDefinitions {
        name
        key
      }
    }
    userErrors {
      field
      message
      code
    }
  }
}

Variables:

{
  "definition": {
    "name": "My App Checkout Translations",
    "description": "Translations for the checkout section of my app.",
    "type": "my-app-checkout-translations",
    "fieldDefinitions": [
      {
        "key": "title",
        "name": "Title",
        "description": "The title of the checkout section",
        "required": true,
        "type": "single_line_text_field"
      },
      {
        "key": "subtitle",
        "name": "Subtitle",
        "description": "The subtitle of the checkout section",
        "required": true,
        "type": "single_line_text_field"
      }
    ],
    "capabilities": {
      "translatable": {
        "enabled": true
      }
    }
  }
}

Extensible

If you have a lot of content the merchant can translate and don't want to register specific definitions. What you can do is register a single metaobject definition.
Where you would create a metaobject definition, with a key and value. You may also want to register a description field, just to help the merchant understand where the content will be used.

One thing to note here, is that you'll need to be careful as the key can be translated by the merchant, just something to watch out for when retrieving the data.

mutation CreateMetaobjectDefinition($definition: MetaobjectDefinitionCreateInput!) {
  metaobjectDefinitionCreate(definition: $definition) {
    metaobjectDefinition {
      name
      type
      fieldDefinitions {
        name
        key
      }
    }
    userErrors {
      field
      message
      code
    }
  }
}

Variables:

{
  "definition": {
    "name": "My App Translations",
    "description": "Translations for my app.",
    "type": "my-app-translations",
    "fieldDefinitions": [
      {
        "key": "key",
        "name": "Key",
        "required": true,
        "type": "single_line_text_field"
      },
      {
        "key": "value",
        "name": "Value",
        "required": true,
        "type": "single_line_text_field"
      },
    ],
    "capabilities": {
      "translatable": {
        "enabled": true
      }
    }
  }
}

Translations

Now we have our metaobject definitions, it's time to add content and translate it.
Fortunately, Shopify provides this out of the box!

Firstly, create your metaobject, based on the definition you created earlier.

mutation CreateMetaobject($metaobject: MetaobjectCreateInput!) {
  metaobjectCreate(metaobject: $metaobject) {
    userErrors {
      field
      message
      code
    }
  }
}

Variables:

{
  "metaobject": {
    "type": "my-app-checkout-translations",
    "fields": [
            {
                "key": "title",
                "value": "My App Checkout"
            },
            {
                "key": "subtitle",
                "value": "Something to do with your order at checkout."
            },
        ]
  }
}

Next you need to get the translatable content for your metaobject, this will give you the digest and key that you can use when registering translations.

query {
  translatableResource(resourceId: "gid://shopify/Metaobject/1234567") {
    resourceId
    translatableContent {
      key
      value
      digest
      locale
    }
  }
}

Then you can register your translations using the translationsRegister mutation. You can also remove translations via a similar mutation.

mutation CreateTranslation($id: ID!, $translations: [TranslationInput!]!) {
  translationsRegister(resourceId: $id, translations: $translations) {
    userErrors {
      message
      field
    }
    translations {
      locale
      key
      value
    }
  }
}

Variables:

{
  "id": "gid://shopify/Metaobject/1234567",
  "translations": [
    {
      "key": "title",
      "value": "Paiement de mon application",
      "locale": "fr",
      "translatableContentDigest": "dcf8d211f6633dac78dbd15c219a81b8931e4141204d18fba8c477afd19b75f9"
    },
    {
      "key": "subtitle",
      "value": "Quelque chose à faire avec votre commande à la caisse.",
      "locale": "fr",
      "translatableContentDigest": "a18b34037fda5b1afd720d4b85b86a8a75b5e389452f84f5b6d2b8e210869fd7"
    }
  ]
}

Here you specify the language and the translated content. This allows you to provide translations if you want to. If you also want to allow merchants to translate content in your own app and interface, you can use this to store the translations in Shopify.

Gotcha

There is a gotcha with this approach. You cannot register translations in the stores default language.

This means you do have to do some management here, its best explained with an example.

If your default app content is in English, you can create your metaobject definitions.
You create the metaobject with the fields you defined, if the merchants default language is English, the content here can be English.
You can then register translations of this content in other languages, or the merchant can via Translate & Adapt app.

However, if the merchants default language is Japanese, then you would need to create the metaobject content in either Japanese, if you have that available or ensure the merchant knows they will need to change the default content to Japanese. Which they can do inside of Shopify Metaobjects section.
As you won't be able to register translations in Japanese.

It’s just a gotcha when registering translations. I’m hoping the Shopify team will remove this limitation so content can be registered in any language as it would make management of this much easier.

Displaying Content

Once you've set this all up. Merchants will be able to translate your content in Translate & Adapt app, and/or you can programmatically register them using Shopify APIs.

You can then access these translations. In Liquid the translated content will automatically be displayed based on the user's language.

If you are using the Storefront API, you can use the @inContext directive. You set the language you'd like the content in and Shopify will automatically look it up for you, or return the default content if not available in that specific language.

You can also always get the translations from the Admin GraphQL API, using the translatableResource and the translations list returned.

Translate & Adapt

You can then deep link into the Shopify Translate & Adapt app using the Metaobject ID. For example, if your app is embedded in Shopify you can use this style of link:

shopify://admin/apps/translate-and-adapt/localize/metaobject?shopLocale=fr&id=1234567

Changing the shopLocale, market and id query parameters to the relevant ones for your metaobjects.

Summary

In summary, you can use Shopify Platform to easily allow merchants to translate and manage your apps content, wherever you might be displaying it.

This is a less known but very powerful way to extend the Shopify Platform and your apps, without having to build out your own translation engine!

Pimsical is my business, where you can find more Shopify content, my Shopify apps or help to optimise your operations and streamline your business backend.

Stop Fetch-ing in error

Jordan Finneran — Thu, 23 Feb 2023 09:02:14 +0000

Intro
The Problem
The Solution
Summary

Intro

Before we jump in.
If you are thinking I use axios or requestjs etc so this doesn't apply to me.
Put the npm package down and step away from the install!

Fetch is now supported in all major browsers and even in NodeJS now!

Which is awesome! We now have a single way of making requests across the browser and backend!
So much time and npm downloads saved!

Also if you need to support really old browsers, there is an official polyfill you can load on your website to provide you with the same fetch experience.

Now let’s jump in!

The Problem

Fetch is awesome a really great way of making requests from your code.

However I've seen in many tutorials and code the following code, which will cause issues:

    fetch('http://example.com/movies.json')
    .then((response) => response.json())
    .then((data) => console.log(data));

Even in the Mozilla docs

Why is this a problem?

If the endpoint you are fetching, returns a not okay status code then fetch will not throw an error.
You have to check yourself if the status code if okay or not before trying to get the response body with response.json().
Otherwise you could end up with some generic error and no context around what caused it.

But, you might be saying to yourself well my endpoint always returns JSON, even in an error scenario.
This may be the case, but if anything out of your control errors for example an API Gateway then you are very likely to get a non JSON response and again cause yourself a headache debugging.

The Solution

The solution to this is really straightforward, simply check if the response if ok, before attempting to get the response body.

You can see in this example, I'm checking response.ok which indicates if your response status was in the 2XX range.

But you can also check for specific statuses as well. Here I'm checking for a 204 - No Content status code as I won't have any JSON to return in this instance.

Otherwise I reject the promise, returning the full response in the error.

I've also wrapped it in a try catch for safety in order to catch any CORS, timeout errors etc.

    const request = new Request('http://example.com/movies.json');
    try {
      const response = await fetch(request);
      if (response.ok && response.status !== 204) {
        return response.json();
      }
      if (response.ok && response.status === 204) {
        return Promise.resolve();
      }
      return Promise.reject(response);
    } catch (e) {
      return Promise.reject(e);
    }

Summary

In summary, fetch is awesome!

However there is a bit more to it in order to handle errors and bad responses from any endpoint you might be hitting, so double check your fetch code to make sure you are handling errors gracefully. It will definitely help when it comes to debugging any problems.

Happy Building!

5 things to consider when Designing Event Driven Systems

Jordan Finneran — Fri, 16 Jul 2021 18:20:09 +0000

Intro
Idempotent Nature
Data structure and storage
APIs
Versioning
Reconciliation
Summary

Intro

Event driven systems are becoming ever more popular and integral part of our modern lives.

Event driven systems consume and take action based on events, these systems also emit and define the events.

This allows for you to loosely couple your services in the system allowing each service to be developed faster, independently and reduce complexity as each service is only responsible for a single thing, normally a domain or entity.
For example Twitter could have domain for users, lists, bookmarks etc.

Each of these services is responsible for a single domain even though lists are made up of users for example, they remain independent and follow the principle of single responsibility.

In this example you could have teams independently developing the list and user services, which means those services could be developed faster and focus on features for each rather than having them rely on each other.

The bookmark service could for example take action on a tweet-bookmarked event and store the reference to the tweet that a user bookmarked so that user can view a list of them later. It could also define and emit it's own events too!

These events are published to a queue or bus, which can be subscribed or listened too by multiple subscribers and services. Often referred to as pub/sub pattern.

Event driven systems are great as the events logically make sense, in the systems we interact with everyday, when you start to model them.

However they come with plenty of things to think about. How to model your events, and what events to emit and how to separate your services. These are fundamental to the design of your event driven system.

On top of this there are a few key things that you need to consider when designing event driven systems.

Idempotent Nature

Idempotent means that multiple events being received have the same result every time.

Event driven systems need to be designed and programmed in an idempotent nature as there is no guarantee events will only be received once. Imagine for instance that your system receives webhooks from a third party that notifies you of events, this is a very common pattern for event driven systems.

With webhooks there is no guarantee that you will only get one webhook received, it can happen for a number of reasons I won't go into now.
Likewise you will often want events to be replayed incase of a system failure.

If this happens your system needs to be able to handle it and ensure the same result occurs no matter how many times the event is received. It would be no good if you ended up creating two orders instead of a single one due to receiving an order event twice.

This means that your storage solutions and business logic needs factor this in when being built. For example using UPSERT rather than INSERT into a database so that events are updated if they already exist rather than inserted twice. Ensuring the business logic has the same output every time an event is put through it, regardless of the datetime or number of times an event has been seen.

There's so much more to think about and detail when considering idempotency in systems, but hopefully this gives you a starting point to consider it.

Data structure and storage

We touched on it in the previous section but data is at the heart of any event driven system, so it crucial to consider it when designing your systems.

One of the first things to consider is the structure of your events, as we talked about previously your events shouldn't be stateful. For example they shouldn't have properties that depend on other events occurring and store state.

One of the first thing to consider is how are you planning on structuring your events, a common pattern is to have an event wrapper that contains metadata about an event around the data of the event itself. Below is an example from AWS

{
  "version": "0",
  "id": "6a7e8feb-b491-4cf7-a9f1-bf3703467718",
  "detail-type": "EC2 Instance State-change Notification",
  "source": "aws.ec2",
  "account": "111122223333",
  "time": "2017-12-22T18:43:48Z",
  "region": "us-west-1",
  "resources": [
    "arn:aws:ec2:us-west-1:123456789012:instance/i-1234567890abcdef0"
  ],
  "detail": {
    "instance-id": " i-1234567890abcdef0",
    "state": "terminated"
  }
}

Where detail contains the body of the event, the other top level properties cover off the metadata around the event. You can also see it contains a version property which we'll talk about later.

The next thing to consider is how will you be storing your events and data?

Are you going to use an event sourcing pattern and store all your events and build up views of the data either as the events are stored or at read time. Or will your database be your view of the world and be the state of your system. Remembering of course this must handle receiving events possibly multiple times and out of order.

As there will be possible significant number of events to be stored you will need to consider the storage solution carefully as well.

APIs

You event driven system will likely include APIs to both access and affect the data held within it.

The first thing to remember is you are working with a system with eventual consistency, so any time sensitive events need to be carefully considered. No matter how fast you make your system there will be occurrences where an event isn't processes 'in time'.

If you have a user interface (UI) displaying these events or data resulting from these events you could use an optimistic UI, for example if an tweet is bookmarked the UI could add the tweet to the bookmarked list on the device (client) side before waiting to get the list from the backend as it may not be processed in time.

You could also consider how you are handling events, for example you could use an API which synchronously updates the bookmarked database and then emits an event to other systems with a tweet-bookmarked event for example. This ensures that your data store is up to date and ready for UIs to display the information when they call to get it but you still have other event driven options.

When designing your API for an event driven system you also need to consider what methods you use and how you design your API, for example POST methods don't behave in an idempotent nature as they create something new each time. Whereas PUT methods do as its specific to an ID. This is a really straightforward article covering off idempotent HTTP methods.

Depending how you are ensuring idempotency in your system e.g. constructing an ID consistently you might be able to still use a POST method and dedupe on the constructed ID, this doesn't truly follow HTTP specification but may be more pragmatic for your use case.

Versioning

Alongside considering your Data structure and APIs, we need to consider how to version them. Now I'm not really going to talk about versioning your API's here as there are plenty of articles about this but I am going talk to versioning your events.

You will need to change and version your events inevitably, however when you do there is more to think about in an event driven system.

The first thing to consider is how will your systems determine what version of event they are receiving. You can make all your events backwards compatible however this can be really tricky in the future.

You can also include a version field on your event. E.g. how the Eventbridge team at AWS does. You can then use this version in your downstream systems to correctly handle that version of your event.

When you need to update an event, you should consider the changes you need to make to your event, once happy with the new version of your event schema. You need to ensure you work backwards, up stream, towards the producer of the events.

Making changes to all these downstream services so they can handle both versions of your events will make the change over much smoother as each can then be deployed independently and remove any possible downtime as events could still be in transit with the old version when releasing the services.

Once that has been completed you can swap over to your new event version in the producer of the event.

You then need to decide if and how you are going to deprecate the previous event version.

This needs real thought if you are intend to store and replay events through a system.

Reconciliation

We spoke earlier about receiving webhooks from a third party, a common pattern in event driven systems. We also spoke about if they are delivered more than once, but what happens if they are delivered at all?

We need to consider fault tolerance in your event driven system and reconciliation plays a large part here.

If we are dealing with third parties outside of our control we need to reconcile the state they are in as we may have not either received or delivered events. Ideally you should ensure your system is fault tolerant enough to always deliver to third parties and retry or handle any failures but this might be hard initially, so a good fallback is reconciliation.

Normally reconciliation jobs are run on a time schedule e.g. a common usage is every night at midnight to get all the items from a third party and check your system to ensure we have received them all, if not push the correct events through the system. I would try to reconcile each domain or entity of your system independently, although depending on the third party, you may have to be flexible with this.

You could similarly do the same with a system you are delivering to and check everything is as expected.

Although with all event driven systems you have levels of eventual consistency, where you cannot guarantee at what point in time the system is up to date, reconciliation gives you a tighter timeframe on when you can be confident that your system is correct.

Summary

Event driven systems can be really powerful, scalable and solve many business problems. However all the benefits don't come without responsibility and plenty of considerations when designing them.

I'd love to hear any other tips or things you'd had to consider when designing or building event driven systems!

Happy event-ing!

Clouding Communications with acronyms

Jordan Finneran — Mon, 05 Jul 2021 20:31:09 +0000

Intro
Acronyms Seriously Suck
Cross Teams
New Starters
Context
Summary

Intro

Let me start by saying communication is hard. Clear, concise communication even more so.

Acronyms harm all communication. Acronyms are everywhere, all throughout our lives. But why.

Has anyone ever seen an acronym and thought yes, that has clarified things. Very rarely, if ever.

I hope I can convince you of one thing by the end of this blog, to stop using acronyms.

I'm going to start with an email from Elon Musk, sent to Space X employees in 2010. Regardless of your feelings about him, I hope you can see the points in his argument, that acronyms seriously suck!

Acronyms Seriously Suck - Elon Musk

There is a creeping tendency to use made up acronyms at SpaceX. Excessive use of made up acronyms is a significant impediment to communication and keeping communication good as we grow is incredibly important. Individually, a few acronyms here and there may not seem so bad, but if a thousand people are making these up, over time the result will be a huge glossary that we have to issue to new employees. No one can actually remember all these acronyms and people don't want to seem dumb in a meeting, so they just sit there in ignorance. This is particularly tough on new employees.

That needs to stop immediately or I will take drastic action - I have given enough warning over the years. Unless an acronym is approved by me, it should not enter the SpaceX glossary. If there is an existing acronym that cannot reasonably be justified, it should be eliminated, as I have requested in the past.

For example, there should be not "HTS" [horizontal test stand] or "VTS" [vertical test stand] designations for test stands. Those are particularly dumb, as they contain unnecessary words. A "stand" at our test site is obviously a test stand. VTS-3 is four syllables compared with "Tripod", which is two, so the bloody acronym version actually takes longer to say than the name!

The key test for an acronym is to ask whether it helps or hurts communication. An acronym that most engineers outside of SpaceX already know, such as GUI, is fine to use. It is also ok to make up a few acronyms/contractions every now and again, assuming I have approved them, e.g. MVac and M9 instead of Merlin 1C-Vacuum or Merlin 1C-Sea Level, but those need to be kept to a minimum.

He has really hit the nail on the head for me. I'd argue to go further not even have an approved list but it's the right direction!

Cross Teams

Next on my hit list of why you shouldn't use acronyms is it massively hinders cross team communications. This can be between frontend and backend teams. It can be between engineering teams and marketing teams. Throughout the whole company acronyms cloud communication.

Let me give an example, some people use PR in the marketing sector to refer to Page Rank, however in the engineering teams PR means something completely different, it means Pull Request. You can see how already those two teams could misunderstand a conversation just from the use of this one acronyms, never-mind when you start to include other teams and more and more acronyms.

I once was in a meeting with members from all different teams, and someone from the engineering department was explaining their role and what they do. Scattered throughout where fairly standard (from a engineering viewpoint) cloud acronyms e.g. EC2 (Amazon Elastic Compute Cloud), CDN (Content Delivery Network) and so on. At the time I was sat next to someone from the Human Resources department who whispered to me asking me to explain what each one meant as they didn't understand, others in the room had glazed over.

These fairly common acronyms in the engineering world were harming communications, confusing some people, switching others off from the content being delivered. It's so easy for us to slip into using these acronyms if we deal with them day to day. But we need to remember the audience we are communicating with. If we reduce our use of acronyms we will be less likely to fall into the trap of clouding cross team communications.

New Starters

Now never-mind clouding cross team communications, acronyms can harm communications inside your own team!

I can recall at least two situations where I was new to a team and in the morning stand up discussions, and I was completely lost, not because of the technical information but the use of many unfamiliar acronyms. I had no idea what they were talking about, until I had to pause the stand up and ask for them to explain what the acronym meant, which actually took longer than using the actual words contained in the acronym themselves.

This happens all the time, I'm certain, you've probably experienced this yourself.

Often it can be even worse if someone doesn't ask for clarity on the meaning of acronyms and leaves the conversation no clearer on what is going on and feeling out of their depth. This happened to me plenty of times early on in my career, where I'd frantically search for the meanings of acronyms after meetings to make sense of what had just happened in the meeting.

It can be really off putting for new starters to your team. It can also mean new starters are spending more time trying to decipher acronyms than getting stuck in with the team.

Context

Context is everything when communicating. It's very easy when communicating to forget the people you are communicating with likely won't have the same context and head space as you.

This is even easier to forget about the other persons context when writing using asynchronous communication e.g. email, written documentation, blogs, direct messages and so on. It's also less likely that the reader has your context and head space when consuming content from asynchronous communication sources. Making both ends of communication harder.

Especially important to consider context, when some of the most common and pervasive forms of modern communications are asynchronous in nature.

It is so easy to slip into the use of acronyms when writing in particular, and for me. likely to be the biggest source of confusion. (It's much easier to ask someone what they mean by an acronym when speaking directly for example).
I've done it on several occasions when writing this blog and had to go back and correct myself. But if we remind ourselves of our readers and the readers context, we can make a conscious effort to remove acronyms and help clear up communications.

I've often read blogs, and attended presentations where I've had to search out the meaning of acronyms while trying to understand the meaning of the content I'm consuming. Making the processes of understanding and digesting the content doubly hard.

This is before you even consider the accessibility of the content. Try having a screen reader, read out text containing acronyms. It is so hard to maintain your train of thought and digest the content, for me at least.

Summary

Acronyms negatively impact communications throughout our lives, and yet they persist. Next time you use or hear an acronym being used, please consider how it's now clouding the communication and how you can help bring clarity to your communications.

In summary, I hope I've managed to convince you to stop using acronyms. If we all make a conscious effort to stop or at least reduce the usage of acronyms, we can make communications clearer, more concise and banish the confusion.

Considering the advantages of Cloud Native Architecture

Jordan Finneran — Tue, 15 Jun 2021 08:47:12 +0000

Intro
Focus
Management
Cost
Responsibilities
Vendor Lock In Myth?
Summary

Intro

I was going to write this about the Risks of Cloud Agnostic Architecture. However I think it best to stick with the positive and highlight the advantages of a Cloud Native Architecture instead.

The first thing you might be asking is...What is Cloud Native Architecture?

Cloud Native Architecture is designing your system, service or application, whatever it might be, to make use of the unique capabilities of the cloud and of your chosen Cloud Provider.

I consider this 'using the right tool for the job', you could use a hammer to get a screw into a plank of wood, but the right tool, the more specific tool, a screwdriver, would do a better job.

Focus

Let's take a database, a common requirement for almost any architecture.
There are an array of options depending on your chosen Cloud Provider, to name just a handful. AWS (Amazon Web Services) has Dynamodb, Aurora, RDS (Relational Database Service). Azure has Cosmos DB (which if you haven't heard of definitely check it out, it's a favorite of mine), SQL. Google Cloud has Spanner and Big Table and the list goes on and on and on.

Each has its own specific use case, or scenario it functions slightly better at than the others but they are all still a database.
You could also spin up your own database, on cloud servers or your own servers and manage that yourself. Which is how almost everyone worked with databases before the cloud and cloud providers became popular.

But a database, is still a database, in terms of infrastructure. I'm not referring to the data structures and modelling inside of a database here, just about the infrastructure.

Yours and your teams time, their focus is limited, you only have a finite amount of it. Only so much you can spend your focus and time on.
Would your business prefer that time to be spent on delivering value, delivering differentiators from your competition or spending more time on a building and managing database infrastructure.

Which is a problem with plenty of existing solutions, only a handful of which I mentioned before.

Management

Continuing on from Focus and our database example. Not only are there existing solutions to a database, but they are also managed for you.
Managed by teams who have the experience of running databases (or any other managed service) for many other businesses, at every kind of scale. That is one of the major benefits of the cloud, the providers will often have seen the scenario before with a different customer or because they have been running the database or service for a period of time before your use of it.

Not only do they have the benefit of experience, but it is also their focus, their teams focus, to make that database as good as it can be for the variety of businesses using it.
That is their focus, what is yours?

I recently got a little carried away with a load test, on a cloud native serverless system.
Which I had only previously tested with a few hundred events. I ended up putting 12,000 events through.

However I didn't need to worry as the system was using managed services, which tend to be charged on usage, they scaled up, absorbed and processed that load without breaking a sweat.
Because they were managed and will have definitely seen larger spikes of events than that, I didn't need to worry about the system coping or managing the scale myself.

Cost

Now this can be a double edged sword, Cloud Native Architecture tends to be priced based on usage which does have pros and cons.

There are plenty of stories where Cloud Budgets and limits haven't been put in place and people have ended up being billed large amounts due to something running wild.

However for every one of those stories, there are plenty of unheard ones about the benefits of usage based pricing.

For example, if you had air conditioning that you rarely used, but you kept it on and running at maximum all the time anyway, on the occasion you needed it, that would be inefficient and more expensive that it needs to be.
This is how I like to think of usage based pricing.

Why pay for a server or cluster, every hour of every day, when business as usual only needs a fraction of the computing power available? Would it not be better to only pay for what you use, when you use it.

I will caveat this section with making sure your architecture is efficient with its usage of cloud native services and designed well, will help massively with cost.

Also if you are worrying about your AWS bill I would recommend chatting to the duckbill group.

Responsibilities

As a business or as a member of a business, you have plenty of responsibilities and things to think about. The competition, your staff, the environment, the wider world and so on.

So why add one more thing for you to be responsible for? Responsible for if your system is scaling, if its managing and coping, if it needs your attention.

Now I'm not saying don't monitor your Cloud Native systems, definitely do.

What I am saying is that you probably have much less to be responsible for when using managed services, like we said before they are managed for you, with all the benefits that come with that.

The thing you do need to be responsible for yourself is designing your system up front and spending time on your Cloud Native Architecture to ensure you are using the best tool for the job and the unique advantages that your Cloud Provider gives you.

Vender Lock In Myth

You will often hear a disadvantage of Cloud Native Architecture, is that it means you are reliant on that Cloud Provider, you are locked in to that vendor.

Now it is true that because you are using Cloud Native systems you are tied to that vendor and it will be harder to migrate to another Cloud Provider, or in a disaster move over to another Cloud Provider.

However, I have yet to hear of anyone move Cloud Providers unless a large cost benefit has been agreed in advance. Furthermore, no matter how agnostic your architecture is, all the surrounding permissions models, and permissions themselves will all be different per Cloud Provider and need changing, as will any Infrastructure as Code for example Terraform. This all has to be Cloud Provider specific or Cloud Native by design.

If there is a disaster with your Cloud Provider (and that is a really big IF), how quickly could your data be migrated to a new Cloud Provider, how quickly any state? And what are the statistical chances of your Cloud Provider going down or having significant issues?

Summary

In summary, I believe utilising Cloud Native Architectures, which are often Serverless but thats another blog entirely, provide real benefits to your business and team.
It allows you to focus, to spend your limited time, energy and money on what you are best at, at differentiating your business and delivery value quickly for your customers.

Use the unique tools that each Cloud Provider gives you to your advantage, minimise the time you are spending on problems that don't make your business special, use the right tool for the job and leverage the clouds benefits.

Happy Building!

CSP - Content Security Policy

Jordan Finneran — Fri, 11 Jun 2021 21:10:25 +0000

Intro
Directives
Values
Summary

Intro

Lastly but by no means least, carrying on from my previous blog about website security week, we're going to talk about CSP or Content Security Policy.

CSP is Content Security Policy this is one of the most powerful tools in your arsenal to secure your website.

These are two ways to to set your content security policy, either as a header Content-Security-Policy or via a meta tag in your HTML for example:

<meta http-equiv="Content-Security-Policy" content="default-src 'none'; img-src https://google.com; child-src 'none';">

Directives

The content policy is made up of directives (the thing to restrict) and the value(s) on how it can be restricted. We won't cover all all the possible directives in this blog but you can find a list of all the directives here.

They syntax is as follows:

Content-Security-Policy: directive value; directive value value;

There are some key directives you should set.

default-src

As the name suggests this is the fallback if there aren't more specific directives used. I'd recommend setting it to 'none'

Content-Security-Policy: default-src 'none';

connect-src

This affects what you can 'connect' to via fetch and make HTTP requests to.

Content-Security-Policy: default-src 'none'; connect-src https://some.api.com;

img-src

This affects where you can load images from.

Content-Security-Policy: default-src 'none'; img-src https://some.img.host https://another.img.place;

form-action

This affects where you can send form submissions to via the HTML form attributes.

Content-Security-Policy: default-src 'none'; form-action https://some.api.host;

These are just a handful of the directives you should set on your content security policy. The more specific your content security policy directives the stronger your policy.

Values

You can specify many different types of values for each directive and its important to understand the affect of each one.

'none'

This won't allow loading of any resources.

Content-Security-Policy: default-src 'none';

'self'

Only allow resources from the current domain.

Content-Security-Policy: default-src 'self';

Hosts

Allow loading from any number of hosts, it can also have an optional protocol e.g. http:// or https://, an optional port e.g. some.website:8080, and/or an optional path e.g. https://some.website/path/to/file.

Content-Security-Policy: img-src https://some.img.host some.other.images.com img.org:8080 img.co.uk/path/to/img.jpg;

Schema

You can set just a schema e.g. https:, http:, data: but I generally wouldn't recommend this except perhaps for inline images which are data:xxxx.

Content-Security-Policy: img-src data:;

Nonce

This works in conjunction with the script HTML tag nonce attribute, the server must generate a unique value.

Content-Security-Policy: script-src nonce-DhcnhD3khTMePgXwdayK9BsMqXjhguVV;

SHA

This is a SHA hash of a resource for example, if you apply a content security policy the browser will generate these for you to use if you cannot use any of the other values.

Content-Security-Policy: script-src sha256-jzgBGA4UWFFm;

You can use any of these values in combination with one another to lockdown your content security policy as much as possible.

Here is an example:

Content-Security-Policy: default-src 'none'; script-src 'self' https://static.cloudflareinsights.com; img-src 'self'; style-src 'self'; connect-src 'self' https://cloudflareinsights.com https://api.challenge.new; font-src 'self'; base-uri 'none'; form-action 'none'; frame-ancestors 'none'; manifest-src 'self';

Summary

In summary, setting a content security policy is one of the most powerful tools in your arsenal to secure your website. It can take some time to set up a strict content security policy but that time is payed back tenfold in the benefits it provides.

Set that content security policy now!

Happy Building!

Clarifying CORS - Cross-origin Resource Sharing

Jordan Finneran — Tue, 01 Jun 2021 17:56:55 +0000

Intro
Access-Control Headers
Rate Limiting
Summary

Intro

Continuing on from my previous blog about website security week, we're going to talk about a CORS on the web.

CORS is Cross-origin Resource Sharing this is often used when your website is hosted separately from your API. e.g. your website is at website.com and calls your API at api.com.
This is a common architectural pattern as it allows each API and website to move independently and faster, however it can introduce some security issues.

Access-Control Headers

To allow CORS requests your API will need to response with certain headers, which allow certain behaviors from your website/frontend.

Access-Control-Allow-Origin

This header can be set with either the origin which will be calling the API, it can only be a single origin.
Otherwise it can be a * however this doesn't allow credentials to be passed, which we will talk about later.

If at all possible prefer setting a specific origin to a *.

Example Usage:

Access-Control-Allow-Origin: https://mozilla.org

Access-Control-Allow-Methods

This header can be set with a list of HTTP Methods that are allowed to be used to contact your API.

Generally speaking OPTIONS will want to be part of this list as any frontend will make a OPTIONS request, often referred to as a preflight request, before it makes the actual request. OPTIONS requests won't be made for GET requests.

It can also be * however, you should be specific if you can.

Example Usage:

Access-Control-Allow-Methods: POST, GET, OPTIONS

Access-Control-Max-Age

This header can be set to a time period that the frontend will cache the preflight OPTIONS request. It is a value in seconds for example 86400 seconds is 24 hours.

Let's say you've set Max-Age to the above, this means that the first request you make from the frontend to the API will make an OPTIONS request and then the actual request. It will subsequently won't have to make another OPTIONS request to that API for 24 hours.

Example Usage:

Access-Control-Max-Age: 86400

Access-Control-Allow-Headers

This header can be set with a list of Headers that are allowed to be passed onto your API.

Example Usage:

Access-Control-Allow-Headers: X-PINGOTHER, Content-Type

Access-Control-Allow-Credentials

This header specifies if to include credentials in the request. Credentials count as cookies, authorization headers or TLS client certificates.

Example Usage:

Access-Control-Allow-Credentials: true

Rate Limiting

You should note that Access-Control-Allow-Origin header only prevents browsers from making requests to the API. It does not prevent calls to your API from other machines, command line, Postman etc.
You should ensure that you have put other security measures in place to prevent misuse of your API, including Authentication and Rate Limiting.

Rate Limiting involves restricting too many calls being made to your API. It can be done in a number of ways depending on how your API is developed. I would look for libraries to help manage this for you.

Summary

In summary, separating your API and website can produce real development benefits however it can introduce security problems and having to deal with CORS.
Hopefully this helps clarify CORS and how you can secure it.

Set those headers now!

Happy Building!

Why your website needs validation

Jordan Finneran — Sun, 30 May 2021 21:19:39 +0000

Intro
Forms
Custom Validation
Summary

Intro

Continuing on from my previous blog about website security week, we're going to talk about a validation.

If accept user input, you are going to need to validate the input. Non validated user inputs can lead to security vulnerabilities for example SQL injection attacks, where user input escapes your database and starts modifying it. It can also lead to exceptions from your code if a user inputs text rather than a number for example.

Please Please Please ensure you do the same validation server side as you do on the frontend (client) side.

Forms

You user inputs should be contained in HTML forms which comes with lots of powerful validation tools built in.
This also means you can start to add validation without adding any extra javascript, increasing performance.

First thing to check on your inputs is, are you using the correct type:

button
checkbox
color
date
datetime-local
email
file
hidden
image
month
number
password
radio
range
reset
search
submit
tel
text
time
url
week

This will provide lots of out of the box validation goodness from the outset. More information on the types.

Next up for file inputs ensure you've set the accept attribute which allows you to check the type of the file for example accept="image/png, image/jpeg".
You should also set the multiple attribute to whether you are allowing many files or a single.

Next up for number inputs set the step attribute to ensure only increments of the amount you want are allowed to be entered.
Also set the min and max values as required to limit the numbers that can be inputted.
For non numeric values there are minlength and maxlength which limit the number of characters that can be inputted.

Finally we have pattern attribute, this can be used to match a specific Regular Expression to validate the input. If you are using one of the existing types above, for example email, you don't then need to have your own email regular expression.

Example usage:

<form name="venue">
    <label>What is the max number of decimal things?
        <input name="capacity" type="number" placeholder="e.g. 32" min="0" max="100" step="0.1" />
    </label>

    <label>Any images of your venue you wish to upload?
        <input name="images" type="file" accept="image/png, image/jpeg" multiple/>
    </label>

    <label>How do we contact you?
        <input name="contact" type="email" placeholder="e.g. bob@bob.com" />
    </label>

    <label>Enter UUID to test pattern usage?
        <input name="pattern" type="text" pattern="[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}" />
    </label>
</form>

Custom Validation

If you want to extend the validation of a form, I would recommend adding an event listener on the form for submit event, and then prevent the default action using event.preventDefault().
You can then run any validation on the form using javascript and set setCustomValidity on the inputs which then uses the in built goodness of forms and inputs to display the error message.

Example Usage:

HTML

<form name="venue" onsubmit="submit">
    <p class="passwordRules">Passwords must have at least one uppercase and lowercase letter, one number, and at least 8 or more characters.</p>

    <label>Password
        <input 
        name="password" 
        type="password" 
        required 
        placeholder="XXXXXXXX"
        pattern="(?=.*[0-9])(?=.*[a-z])(?=.*[A-Z]).{8,}"
        title="Must contain at least one uppercase and lowercase letter, one number, and at least 8 or more characters"/>
    </label>

    <label class="secondPass">Confirm Password
        <input
        name="confirmPassword" 
        type="password" 
        required 
        placeholder="XXXXXXXX"
        pattern="(?=.*[0-9])(?=.*[a-z])(?=.*[A-Z]).{8,}"
        title="Must contain at least one uppercase and lowercase letter, one number, and at least 8 or more characters"/>
    </label>
</form>

Javascript

  /**


Handle form submission
@param {Event} event the form submission event, preventing the normal form behavior
*/
async submit(event) {
event.preventDefault();
// custom validation of the passwords
this.validatePassword();
// grab the form and trigger validation
const form = this.querySelector('form');
const valid = form.reportValidity();
if (valid) {
    // do something with the form
} else {
  // form isn't valid
}
}


/**


Checks to see if passwords match
*/
validatePassword() {
const pass = this.querySelector('input[name="password"]');
const confirmPass = this.querySelector('input[name="confirmPassword"]');
if (pass.value !== confirmPass.value) {
  confirmPass.setCustomValidity("Passwords don't match");
} else {
  confirmPass.setCustomValidity('');
}
}

Summary

In summary, HTML gives us really powerful validation tools to check the user input and validate with minimal Javascript, which we can also extend with a little bit of Javascript too.
We must also ensure that any validation we have completed on the frontend is also done on the server side to prevent users circumventing your frontend and directly interacting with your API.

Validating your user input prevents a whole heap of issues and vulnerabilities for your applications and business.

Happy Validating!

Forem: Jordan Finneran

Shopify App: October 2025 Updates

Intro

App Bridge

NPM

UI components

Unversioned

Polaris

Migration

Remix

UI Extensions

Summary

Shopify: Getting to grips with GraphQL

Intro

With Shopify Codegen

Without Codegen

eslint config

Installation

Queries in code

Queries in .graphql files

Run

Conclusion

Learn More

Shopify: Unlocking the power of Shopify's new Product Model & APIs

Intro

Product Model

GraphQL

Rate Limits

Creation

Variants

Updates

Managing Media

Inventory Item

Webhooks

Example Use Case

Conclusion

Shopify App: Where to store my app data?

Intro

Questions

Database

Metafields

Metaobjects

One size does not fit all

Summary

Shopify App Translations

Intro

Content

Specific Definitions

Extensible

Translations

Gotcha

Displaying Content

Translate & Adapt

Summary

Stop Fetch-ing in error

Contents

Intro

The Problem

The Solution

Summary

5 things to consider when Designing Event Driven Systems

Contents

Intro

Idempotent Nature

Data structure and storage

APIs

Versioning

Reconciliation

Summary

Clouding Communications with acronyms

Contents

Intro

Acronyms Seriously Suck - Elon Musk

Cross Teams

New Starters

Context

Summary

Considering the advantages of Cloud Native Architecture

Contents

Intro

Queries in `.graphql` files