Skip to content

michtio/craftcms-claude-skills / skills/craft-plugins

craft-plugins

Verified

Index and router for plugin-specific Craft CMS 5 guidance — configuration, Twig API, PHP API, migrations, deployment, and pitfalls for the plugins this pack documents. Load whenever a task names a plugin this pack documents, and for passwordless or magic-link auth with no plugin named; read references/<plugin>.md first.

references/blitz.md

View on GitHub
# Blitz

Full-page static caching by putyourlightson. Converts Craft pages into static HTML files, reducing TTFB from 600-900ms to ~25ms. Smart invalidation on content changes, CDN purging, cache warming, and dynamic content injection.

`putyourlightson/craft-blitz` — $99

## Documentation

- Overview: https://putyourlightson.com/plugins/blitz
- Configuration: https://putyourlightson.com/plugins/blitz#configuration
- Twig API: https://putyourlightson.com/plugins/blitz#template-tags
- Dynamic content: https://putyourlightson.com/plugins/blitz#dynamic-content
- Hints utility: https://putyourlightson.com/plugins/blitz#hints

When unsure about a Blitz feature, `WebFetch` the plugin page.

## Common Pitfalls

- Leaving Craft's native `{% cache %}` tags in Blitz-cached templates — full-page caching makes template caching redundant, and `{% cache %}` can interfere with Blitz invalidation. Remove `{% cache %}` from templates Blitz caches (see "Blitz vs `{% cache %}`" below).
- Caching pages with CSRF tokens — forms with CSRF tokens get frozen in the cache. Render the token dynamically with `craft.blitz.csrfInput()` (or use `craft.blitz.includeDynamic()` for the whole form partial).
- Including user-specific content in cached pages — anything that varies per user (cart counts, logged-in state, dashboards) must use `craft.blitz.includeDynamic()` / `craft.blitz.fetchUri()` or be loaded client-side.
- Caching pages behind authentication — `account/*`, admin areas, and any authenticated routes must be excluded via `excludedUriPatterns`.
- Upgrading across 5.13.0 without a cache clear — element, field and element-query dependency tracking became site-aware in 5.13.0, so clear or refresh the cache once the update completes. From then on, saving translated content refreshes only the affected site's pages and the pages depending on them (putyourlightson/craft-blitz#803). Also be on 5.12.16+, where POST requests to pages containing cached includes could be processed more than once (#849).

## What to Exclude From the Cache

The URI/query-string patterns a site builder cares about live in `config/blitz.php`. Exclude anything personalized or non-HTML:

```php
// config/blitz.php (excerpt — front-end-relevant keys only)
'excludedUriPatterns' => [
    ['siteId' => '', 'uriPattern' => 'account/.*'],   // authenticated routes
    ['siteId' => '', 'uriPattern' => 'api/.*'],        // JSON endpoints
    ['siteId' => '', 'uriPattern' => 'actions/.*'],    // controller actions
],
'excludedQueryStringParams' => [
    ['siteId' => '', 'queryStringParam' => 'gclid'],
    ['siteId' => '', 'queryStringParam' => 'fbclid'],
    ['siteId' => '', 'queryStringParam' => 'utm_.*'],
],
```

With `cacheNonHtmlResponses` enabled, XML sitemaps and JSON API responses get cached too — exclude them. All settings support per-site config via `siteId` (empty string `''` matches all sites). See Blitz's [configuration docs](https://putyourlightson.com/plugins/blitz#configuration) for the full set, and "Refresh Modes" below for `refreshMode`.

## Refresh Modes

`refreshMode` (in `config/blitz.php`) controls what happens to a cached page when its content changes. The default is `3`. The integer values map to Blitz's `SettingsModel` constants:

| Mode | Value | Behavior | Best for |
|------|-------|----------|----------|
| Expire + manual | `0` | Marks pages stale; regenerated manually (cron) or organically on next visit | Full control / lower traffic |
| Clear + manual | `1` | Deletes cached files; regenerated manually (cron) or organically | Simple setups |
| Expire + queue | `2` | Marks stale, regenerates in a queue job. Serves stale content until done | **High-traffic sites** |
| Clear + queue | `3` | Deletes files, regenerates in a queue job (default) | Most sites |

Expire modes (`0`/`2`) keep serving stale pages until regeneration finishes — no cold-start stampede. Clear modes (`1`/`3`) drop the file immediately, so the next visitor hits PHP until it regenerates. The "manual" modes (`0`/`1`) rely on you refreshing via cron (see "Console Commands").

## Blitz vs `{% cache %}`

Full-page caching makes Craft's native `{% cache %}` tag redundant, and the two don't always cooperate on invalidation. In templates Blitz caches, remove `{% cache %}` tags (or disable template caching). Keep `{% cache %}` only for fragments on pages Blitz does *not* cache.

## Twig API

### Dynamic Content

For user-specific or real-time content within cached pages. `craft.blitz.includeDynamic()` returns a script that renders the template via an AJAX request on every page view, even when the parent page is served from cache:

```twig
{# Render a template dynamically (never cached) #}
{{ craft.blitz.includeDynamic('_includes/cart-count', {
    userId: currentUser.id ?? null,
}) }}

{# Fetch a URI's contents via AJAX after page render #}
{{ craft.blitz.fetchUri('/includes/user-menu') }}
```

### Cached Includes

`craft.blitz.includeCached()` caches a template separately and shares it across pages (server-side / edge-side include):

```twig
{{ craft.blitz.includeCached('_includes/global-nav') }}

{# With parameters #}
{{ craft.blitz.includeCached('_includes/sidebar', { section: 'news' }) }}
```

### Per-Page Cache Options

`craft.blitz.options()` controls caching for the current page. Pass an object, or chain the methods (`cachingEnabled`, `cacheDuration`, `expiryDate`, `tags`, `addTags` (5.12.10+), `trackElements`, `trackElementQueries`, `paginate`):

```twig
{# Object notation — disable caching for this page #}
{% do craft.blitz.options({ cachingEnabled: false }) %}

{# Expire this page at a specific date #}
{% do craft.blitz.options({ expiryDate: now|date_modify('+1 hour') }) %}

{# Chained — custom tags for targeted invalidation #}
{% do craft.blitz.options.tags(['homepage', 'featured']) %}

{# Chained — combine duration and tags #}
{% do craft.blitz.options.cacheDuration('P1D').tags(['home', 'listing']) %}

{# Chained — append tags from a partial without clobbering the layout's (5.12.10+) #}
{% do craft.blitz.options.addTags('sidebar') %}
```

`tags()` replaces the page's tags; `addTags()` merges into whatever is already set (array or comma-separated string), so a partial can tag itself without knowing what the layout set.

### CSRF in Cached Forms

A cached page would freeze a stale CSRF token. Render the token dynamically so forms keep working — these helpers fetch a fresh value at request time:

```twig
<form method="post">
    {{ craft.blitz.csrfInput() }}   {# full hidden input #}
    {# or, when you need the parts: #}
    {# craft.blitz.csrfParam() / craft.blitz.csrfToken() #}
    ...
</form>
```

## Server / Infrastructure Config (brief)

Beyond templates, Blitz has a pluggable driver system configured in `config/blitz.php` — not something a site builder normally touches:

- **Storage** — where HTML is written (file system vs Yii cache / Redis).
- **Generator** — how the cache is (re)generated (HTTP crawler, queue concurrency).
- **Purger** — clears an upstream CDN / reverse proxy on refresh (Cloudflare, CloudFront, KeyCDN, via add-on packages such as `putyourlightson/craft-blitz-cloudflare`).
- **Deployer** — pushes cached pages to a static host (e.g. the Git deployer).
- **Web-server rewrite** — an Nginx/Apache rule that serves cached files directly, bypassing PHP. The single biggest performance win, but a deploy/infra concern.
- **`batchInsertSize`** (5.12.14+, default `50`) — how many tracking records Blitz inserts per statement when it records a page's element and query dependencies. Added for the save-time deadlocks in putyourlightson/craft-blitz#903; lower it when large pages deadlock or trip packet limits on clustered databases.

Configure these per Blitz's official [configuration docs](https://putyourlightson.com/plugins/blitz#configuration). General Craft caching strategy lives in the `craftcms` skill's `caching.md`. Blitz is a plugin and runs on any host; on platforms that already ship full-page/edge caching (e.g. Craft Cloud, Servd) running Blitz on top is often redundant — check your host's built-in caching model before adding it.

Integrations that auto-refresh the cache when other plugins change content (e.g. `SeomaticIntegration`, `FeedMeIntegration`) are enabled via the `integrations` config key.

## Console Commands

Run via DDEV locally (`ddev craft …`) or `php craft …` on a server — the backbone of cron-driven cache maintenance:

```bash
php craft blitz/cache/refresh           # Clear, flush, purge, generate + deploy everything
php craft blitz/cache/refresh-expired   # Refresh only expired pages
php craft blitz/cache/refresh-urls      # Refresh pages matching given URLs
php craft blitz/cache/refresh-tagged    # Refresh pages with given tags (e.g. home,listing)
php craft blitz/cache/generate          # Queue a full cache generation
php craft blitz/cache/clear             # Delete all cached pages
php craft blitz/cache/flush             # Delete all cache database records
php craft blitz/cache/purge             # Purge the reverse proxy / CDN
php craft blitz/cache/deploy            # Queue a remote deploy of cached files
```

All commands accept `--queue=1` to force queuing instead of immediate execution.

### Server cron + queue setup

For the "manual" refresh modes (`0`/`1`) and for keeping the cache warm, schedule refreshes with cron:

```cron
# Refresh expired pages hourly, 5 past the hour
5 * * * * php /path/to/craft blitz/cache/refresh-expired

# Refresh specific tagged pages daily at 6am
0 6 * * * php /path/to/craft blitz/cache/refresh-tagged home,listing
```

The "queue" refresh modes (`2`/`3`) and `generate`/`deploy` push Craft queue jobs. On a content-heavy site, run the Craft queue with a **daemonised queue runner** (a systemd service or supervisor process running `php craft queue/listen`) instead of the default web-triggered runner — this avoids PHP timeouts and memory exhaustion during large refreshes. See Blitz's [configuration docs](https://putyourlightson.com/plugins/blitz#configuration).

## Performance Hints

Enable the Hints utility (`'hintsEnabled' => true`) to surface template performance issues. CP → Utilities → Blitz Hints shows eager-loading opportunities, N+1 queries, and other optimization suggestions for your templates.

## Pair With

- **SEOMatic** — enable the `SeomaticIntegration` so the cache auto-refreshes on SEO changes.
- **Feed Me** — enable the `FeedMeIntegration` so imports auto-refresh the cache.
- **Cache Igniter** (`putyourlightson/craft-cache-igniter`) — warms CDN edge caches from multiple regions after a refresh (infra / global-site concern).
writing-skillsobra/superpowersUse when creating new skills, editing existing skills, or verifying skills work before deploymentStars: 322kUpdated Claude CodeCodexVerifiedInstall
xlsxanthropics/skillsUse this skill any time a spreadsheet file is the primary input or output. This means any task where the user wants to: open, read, edit, or fix an existing .xlsx, .xlsm, .xltx, .csv, or .tsv file (e.g., adding columns, computing formulas, formatting, charting, cleaning messy data); create a new spreadsheet from scratch or from other data sources; or convert between tabular file formats. Trigger especially when the user references a spreadsheet file by name or path — even casually (like "the xlsx in my downloads") — and wants something done to it or produced from it. Also trigger for cleaning or restructuring messy tabular data files (malformed rows, misplaced headers, junk data) into proper spreadsheets. The deliverable must be a spreadsheet file. Do NOT trigger when the primary deliverable is a Word document, HTML report, standalone Python script, database pipeline, or Google Sheets API integration, even if tabular data is involved.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
shipping-and-launchaddyosmani/agent-skillsPrepares production launches. Use when preparing to deploy to production, or when asking what needs to be in place before shipping. Use when you need a pre-launch checklist, when setting up monitoring, when planning a staged rollout, or when you need a rollback strategy.Stars: 119kUpdated Claude CodeCodexVerifiedInstall
childhoodthedotmack/claude-memBabysit a shipped release after merge, publication, or deployment. Verify published packages, production behavior, installed plugins, and late CI or user reports until the observation window is clean; use babysit for PR readiness before release.Stars: 118kUpdated Claude CodeCodexVerifiedInstall