Optimize your wordpress theme assets and deploy to S3 (and CloudFront)

Karel - September 9, 2015

This article is part of a series about how to make A slightly less shitty WordPress developer workflow. Check out the other parts if you haven’t already. You can also find the project on Github.

In our previous post, we shared how to setup an asset pipeline for development. You’ve spent some time developing your theme locally, now is the time to deploy to production. The first thing we’ll focus on is optimizing our theme and deploying the assets to S3 (and incidentally to CloudFront). Here is what we will accomplish:

  1. Optimize theme assets
  2. Version theme assets
  3. Deploy theme assets to S3
  4. One command to rule them all

1. Optimize theme assets

We already did some optimization in the previous part, for instance by concatenating scripts together. This is great to reduce the number of HTTP requests but it is not enough. We want to compress our images with a loss-less algorithm, minify javascript and styles and gzip it all. It will make our site 2 to 3 times smaller and that much faster. Your visitors will thank you!

The gulpfile comes pack with optimization tasks: optimize-styles, optimize-scripts, optimize-images and gzip-assets. You won’t actually call these directly because gulp deploy-assets will do it for you among other things as we’ll see shortly.

2. Version theme assets

Your assets will change and when they do, you want to be able publish the update to all your users. If you do not version your assets, your users that have a cached version might not get the updated asset. And it sometimes causes broken websites.

To version our assets, we use fingerprinting. It consists of appending a file checksum to the filename. If you change a pixel in an image, the checksum will be different. For instance, your logo.svg will become logo-5417b3d364.svg.

Obviously, you don’t want to manually handle that, so we have a version-assets task that grabs all your assets and versions them. But that’s only half of the work. Your CSS or HTML might be referencing this logo.png so we need to perform a search & replace on your CSS and HTML to replace them with the versioned logo. But we got you covered with two more tasks: replace-versionned-assets-in-assets and replace-versisonned-assets-in-templates.

NOTE: It is extremely important that in your templates and style files you link to the dist/ folder and not the assets/ folder for all your assets. Locally, it will work the same if you link your fonts or images to the assets/ folder but when you will deploy, the search and replace will look for that dist/ folder and NOT the assets/ one in your code. It means that when you deploy, your code will reference the wrong asset and your site will break.

3. Deploy theme assets to S3

At this point we have optimized versioned assets. We are going to use fast storage and a CDN for people all around the globe to have a fast experience of your website. Go ahead and create yourself an Amazon account.

Then direction S3, create a bucket. Optionally (but recommend for security reasons), you can create a IAM user that has only access to your newly created bucket. These instructions are pretty good. No matters whether you decide to do it or not, we will need a bucket, and a set of accessKeyId and secretAccessKey that has access to it. Assuming we have a bucket the-theme-bucket, we can fill the gulp.json config file as follow:

  "theme": "the-theme",
  "productionAssetURL": "https://s3.amazonaws.com/the-theme-bucket",
  "aws": {
    "params": {
      "Bucket": "the-theme-bucket"
    "accessKeyId": "putyouracceskeyidhere",
    "secretAccessKey": "putyoursecretaccesskeyhere"

The productionAssetURL is the url we will use to substitute in our templates and css when deploying. The main reason we do not use this URL directly in our them is because it is painful to maintain assets on S3 while you develop. It is a lot more pleasant to have your assets locally and gulp dev picking up the changes.

A link to /wp-content/themes/the-theme/dist/images/logo.svg will be replaced by https://s3.amazonaws.com/the-theme-bucket/images/logo.svg.

But the file does not live there yet. That’s what the publish-to-s3 task does. It also sets a header so that the assets never expires (aka being cached forever). That’s one benefit that versioned assets gives us, we don’t need to worry about expiry date on our assets.

4. One command to rule them all

This article explained what is going on in the background but the only command you will really use is gulp deploy-assets. It will:

  1. Compile your assets
  2. Optimize your assets
  3. Version your assets
  4. Update your templates and css with the right path
  5. Gzip it all
  6. Publish it all to S3


This article focused on optimizing and deploying our theme assets. In the next article we will see how the entire flow comes together with a live server. In a future article, we will maybe describe how you can keep your uploads in S3 alongside your theme assets.