Documentation

Shopify Integration

Known Issues with Shopify Integration

We’re investigating and correcting an issue that causes stale images to be served by imgix when used with Shopify. This problem only happens when product images are updated. We are actively pursuing a fix for this issue.

imgix is easy to integrate with your Shopify store, and can help drastically improve conversion rates.1 To get started, you’ll need to sign up for imgix and set up a Source.

Once you’ve created your imgix account, it’s time to set up the Source you’ll use to serve your Shopify images. Head over to the Sources section of the dashboard, and click the Add a Source button. On the Source creation page, fill out the form with the following information:

  • Subdomain: Anything you like. In this tutorial, the example will use the subdomain imgix-shopify.
  • Source Type: Web Folder
  • Base URL: https://cdn.shopify.com

After everything is filled out, click Create Source to queue your new Source. On the next page, you should see the Status indicator change from Queued to Deployed after a few seconds. At this point, imgix is fully configured and ready to integrate with Shopify!

Shopify Theme Modification

To actually start serving your content with imgix, you’ll need to make two changes to your Shopify theme. Special thanks to Jason Bowman at Freakdesign for creating the initial version of these files. You can access Shopify’s theme file editor by going to Online store > Themes > Customize theme > Theme options > Edit HTML/CSS.

settings_schema.json

The first change lets you configure your imgix installation from inside Shopify’s theme settings. Copy the code below to the bottom of your theme’s Config/settings_schema.json file, inside the outermost pair of square brackets ([ ]). Make sure to add a comma (,) to the file following the } preceeding where you paste in this code.

{
  "name": "imgix",
  "settings": [
    {
      "type": "paragraph",
      "content": "Check out imgix's [Shopify integration guide](https://docs.imgix.com/guides/shopify-integration) to learn more about these options."
    },
    {
      "type": "checkbox",
      "id": "enableImgix",
      "label": "Enable imgix"
    },
    {
      "type": "text",
      "id": "imgixUrl",
      "label": "imgix subdomain",
      "info":"The subdomain you set within imgix. Example: `https://mysite-shopify.imgix.net`."
    },
    {
      "type": "text",
      "id": "imgixShopifyUrl",
      "label": "Shopify CDN domain",
      "default":"//cdn.shopify.com",
      "info":"Don't change this unless you have a proxy in place. Not sure? Leave it as is."
    }
  ]
}

imgix.liquid

The second file adds a new Liquid tag that helps you generate imgix URLs. This time, create a new file in the Snippets directory of your theme named imgix.liquid. Copy the code below into that file, and save it:

{% capture IMGIX %}
  {% comment %}
    <!--
    Convert a Shopify CDN path into an imgix path, with parameters.

    * Check out imgix's Shopify integration guide to learn more: https://docs.imgix.com/guides/shopify-integration
    * Refer to the imgix documentation to learn about all the available parameters: https://docs.imgix.com/apis/url
    -->
  {% endcomment %}
  {% if settings.enableImgix %}
    {% for i in (1..1) %}
      {% comment %}
        <!-- Check to make sure the src exists, and that imgix url theme settings is not blank. If blank, stop! -->
      {% endcomment %}
      {% unless src or settings.imgixUrl != blank %}
        {{ src }}
        {% break %}
      {% endunless %}

      {% comment %}
        <!-- Check to make sure the src has the Shopify CDN url in it. If it doesn't this does not need to run any further -->
      {% endcomment %}
      {% assign cdnUrl = settings.imgixShopifyUrl | strip %}
      {% unless src contains cdnUrl %}
        {{ src }}
        {% break %}
      {% endunless %}

      {% assign imgixUrl = settings.imgixUrl | strip %}

      {% comment %}
        <!-- Create a list of all the imgix filters we want to use -->
      {% endcomment %}
      {% assign filters = 'bri,con,cs,exp,gam,high,hue,invert,sat,shad,sharp,usm,usmrad,vib,auto,bg,blend,bm,ba,balph,bp,bw,bh,bf,bc,bs,bx,by,border,pad,faceindex,facepad,faces,ch,chromasub,colorquant,dl,dpi,fm,lossless,q,mask,nr,nrs,colors,palette,prefix,dpr,flip,or,rot,crop,fit,h,rect,w,blur,htn,mono,px,sepia,txt,txtalign,txtclip,txtclr,txtfit,txtfont,txtline,txtlineclr,txtpad,txtshad,txtsize,txtwidth,trim,trimcolor,trimmd,trimsd,trimtol,mark,markalign,markalpha,markbase,markfit,markh,markpad,markscale,markw,markx,marky' | split:',' %}

      {% comment %}
        <!-- Build up the list of filters to add to the url -->
      {% endcomment %}
      {% assign imgWithQuerystring = "?" %}

      {% if src contains '?' %}
        {% assign imgWithQuerystring = '&' %}
      {% endif %}

      {% for _filter in filters %}
        {% if [_filter] %}
          {% assign imgWithQuerystring = imgWithQuerystring | append:_filter | append:'=' | append:[_filter] | append:'&' %}
        {% endif %}
      {% endfor %}

      {% assign newSrc = src | strip | replace:cdnUrl,imgixUrl | append:imgWithQuerystring %}
    {% endfor %}

    {{ newSrc | default:src }}
  {% else %}
    {{ src }}
  {% endif %}
{% endcapture %}{{ IMGIX | strip | replace:'  ' | strip_newlines }}

Enabling the imgix Integration

Now that you’ve set up your Shopify theme to work with imgix, you can enable imgix in your theme settings. Head to the Online store > Themes > Customize theme. Once there, you’ll see an imgix option in the right-hand sidebar. Click on this to configure your imgix setup. It should look something like the following:

  • Enable imgix: Make sure this is checked.
  • imgix subdomain: Whatever you set your Source subdomain to in step 1. In this example: https://imgix-shopify.imgix.net.
  • Shopify CDN domain: You’ll most likely not want to change this from the default value of //cdn.shopify.com.

After you’ve set everything up, click Save changes, and you can move on!

Migrating Your Theme Images to imgix

At this point, you’re ready to change your existing theme’s images to use imgix. The exact process will vary depending on your theme, but the basic idea won’t change. Just find places in your theme where existing images are being output, and replace them with the imgix Liquid tag you just created. Here’s an example:

Before:

{{ product.featured_image | img_url:'grande' }}

After:

{% assign feat_img_url = product.featured_image | img_url:'master' %}
{% include 'imgix' src:feat_img_url w:600 auto:'format' flip:'v' %}

It’s a good idea to always use the master variant of Shopify’s images, and let imgix handle the resizing. That way, you’ll always get the best quality image possible. Jason Bowman has created a great demo page showcasing more potential uses of this tag.

Here’s another example of using imgix to easily build a responsive image using srcset and sizes:

{% assign feat_img_url = product.featured_image | img_url:'master' %}

<img
  src="{% include 'imgix' src:feat_img_url w:960 auto:'format' %}"
  srcset="
    {% include 'imgix' src:feat_img_url w:320 auto:'format' %} 320w,
    {% include 'imgix' src:feat_img_url w:640 auto:'format' %} 640w,
    {% include 'imgix' src:feat_img_url w:960 auto:'format' %} 960w,
    {% include 'imgix' src:feat_img_url w:1280 auto:'format' %} 1280w,
    {% include 'imgix' src:feat_img_url w:1600 auto:'format' %} 1600w
  "
  sizes="(min-width: 375px) 50vw, 100vw"
  alt="My awesome product"
>

This example will result in an image sized to fill the whole viewport’s width when below 375 pixels, and 50% of the viewport’s width when at or above 375 pixels. Eric Portis’ post on srcset and sizes is a great place to learn more about these responsive image tools.