Static Assets

Asset Hashing

One of the key features of Bubs is to asset hash all of your assets.

This means that instead of loading dist/screen.css, it will transparently replace the call to this file to be dist/screen-as32ksdf9.css. This is known as asset-hashing, or fingerprinting.

There are two benefits to this:

1. We solve issues where different users have different versions of the same file. Never again tell a user to "Do a hard refresh".
2. We can tel the user to cache this file forever, making the site more performant for repeat visitors.

As part of the gulp release task, assets are generated to timber/static/**. At the top level is a manifest.json file, which contains the mapping of the original filename to your hashed versions.

It looks like this:

  "css/screen.css": "css/screen-479e960066.css",
  "fonts/avenir/31E66B_0_0.eot": "fonts/avenir/31E66B_0_0-2540f57a07.eot",
  "fonts/avenir/31E66B_0_0.ttf": "fonts/avenir/31E66B_0_0-2b9fba3051.ttf",

How to refer to assets

Because of this changing nature of assets, we need to follow a few guidelines with how we call files. This will ensure that proper dev/static paths are used depending on your environment.

For files you want to check into git, they should go into wp-content/themes/timber/assets/**, where ** is something like img, fonts, scss, etc.

When referencing an image from SCSS or JS, you'll want to make it a relative call. So something like ../img/some-file.png.

If for some reason you need an absolute path, you can refer to things as /wp-content/themes/timber/static/**. In local mode, this will be re-written via htaccess to the assets folder. In production, this will get replaced with the correct file as specified in manifest.json

When calling from a timber file, we have a few twig helpers you can use.

1. You can use the rev function, and call a file like this: <link rel="stylesheet" href="{{ function("rev", "css/screen.css") }}">

2. Or you can call the file without revisioning, but with env locations like this: <img src="{{ img_dir }}/logo.png" alt="">. There are variables for assets_dir, img_dir, css_dir, js_dir.