Intelligent static file caching for creating lightning-fast sites with Craft CMS.
Clone or download
Latest commit 221b0ba Nov 14, 2018
Failed to load latest commit information.
docs/images Updated readme Jul 25, 2018
src 1.6.8 Nov 14, 2018 1.6.8 Nov 14, 2018 Initial commit Jun 26, 2018 Updated readme Nov 7, 2018 1.5.5 Nov 1, 2018
composer.json 1.6.8 Nov 14, 2018

Blitz Plugin for Craft CMS 3

The Blitz plugin provides intelligent static file caching for creating lightning-fast sites with Craft CMS.

It can highly improve a site's performance by reducing the time to first byte (TTFB). This reduces the load time of the site as well as the load on the server. Google recommends a server response time of 200ms or less.

Although the performance gains depend on the individual site and server setup, the following results are not uncommon (on a 5 Mbps cable connection with 28ms of latency):

  • 650ms (without caching enabled)
  • 400ms (with caching enabled, without server rewrite)
  • 120ms (with caching enabled and server rewrite)



This plugin requires a commercial license which can be purchased through the Craft Plugin Store. The license fee is $49 plus $19 per subsequent year for updates (optional).


Craft CMS 3.0.0 or later.


Blitz is available in the Craft Plugin Store and can also be installed manually using composer.

composer require putyourlightson/craft-blitz


When caching is enabled and a URI on the site is visited that matches an included URI pattern, Blitz will serve a static cached HTML file if it exists, otherwise it will cache the template output to a HTML file. Excluded URI patterns will override any matching included URI patterns.

Using a server rewrite (see below) will avoid unnecessary PHP processing and will increase performance even more.

Blitz is compatible with live preview. It will detect when it is being used and will not cache its output or display cached file content (provided the server rewrite, if used, checks for GET requests only).


Cache Invalidation

When an element is created, updated or deleted, any cached template files that used that element are deleted. A job is then automatically queued to refresh the cleared cache files. This applies to all element types, including global sets.

The "Blitz Cache" utility allows users to clear and warm the cache. Warming the cache will first clear the cache and then add a job to the queue to pre-cache files. Cached files and folders can be cleared manually using the utility or by simply deleting them on the server.


The terminal can also be used to warm or clear all cache with the following console commands:

./craft blitz/cache/warm

./craft blitz/cache/clear

Note that if the @web alias is used in a site URL then it is only available to web requests and will therefore not be included in cache warming with the console command.


Craft's template caching ({% cache %}) tag does not play well with the cache breaking feature in Blitz. Template caching also becomes redundant with static file caching, so it is best to remove all template caching from URIs that Blitz will cache.

URIs with query strings will only be cached if the "Query String Caching Enabled" setting is enabled. If it is disabled then no caching of URIs with query strings (anything following a ? in a URI) will take place. If it is enabled then all URIs with query strings will be cached. This will help with performance but may end up in a large amount of cached files.

When a URI is cached, the static cached file will be served up on all subsequent requests. Therefore you should ensure that only pages that do not contain any content that needs to dynamically changed per individual request are cached. The easiest way to do this is to add excluded URI patterns for such pages.

Pages that display the following should in general not be cached:

  • Logged-in user specific content such as username, orders, etc.
  • Forms that use CSRF protection
  • Shopping carts and checkout pages

Server Rewrite

For improved performance, adding a server rewrite will avoid the request from ever being processed by Craft once it has been cached.

In Apache this is achieved with mod_rewrite by adding the following to the root .htaccess file, just before the rewrites provided by Craft. Change cache/blitz to whatever the cache folder path is set to in the plugin settings.

# Blitz cache rewrite
RewriteCond %{DOCUMENT_ROOT}/cache/blitz/%{HTTP_HOST}/%{REQUEST_URI}/%{QUERY_STRING}/index.html -s
RewriteRule .* /cache/blitz/%{HTTP_HOST}/%{REQUEST_URI}/%{QUERY_STRING}/index.html [L]

# Send would-be 404 requests to Craft

In Nginx this is achieved by adding a location handler to the configuration file. Change cache/blitz to whatever the cache folder path is set to in the plugin settings.

# Blitz cache rewrite
location / {
  if ($request_method = GET) {
    try_files $uri /cache/blitz/$http_host/$uri/$args/index.html;

# Send would-be 404 requests to Craft

URI Patterns

URI patterns use PCRE regular expressions. Below are some common use cases. You can reference the full syntax here.

  • . Matches any character
  • .* Matches any character 0 or more times
  • .+ Matches any character 1 or more times
  • \d Matches any digit
  • \d{4} Matches any four digits
  • \w Matches any word character
  • \w+ Matches any word character 1 or more times
  • entries Matches anything containing "entries"
  • ^entries Matches anything beginning with "entries"
  • ^entries/entry$ Matches exact URI
  • ^entries/\w+$ Matches anything beginning with "entries/" followed by at least 1 word character


Cached HTML files are timestamped with a comment at the end of the file.

<!-- Cached by Blitz on 2018-06-27T10:05:00+02:00 -->

If the HTML file was served by the plugin rather than with a server rewrite then an additional comment is added.

<!-- Served by Blitz -->

Created by PutYourLightsOn.