craftcms-ops

Files (18)

• SKILL.md
• craft-facts.json · assets/
• entry-type-field-layout.md · assets/
• blitz.md · references/
• ckeditor.md · references/
• codeception.md · references/
• craft-vite.md · references/
• ddev.md · references/
• element-queries.md · references/
• formie.md · references/
• graphql.md · references/
• performance.md · references/
• plugin-development.md · references/
• seomatic.md · references/
• twig-security.md · references/
• upgrades.md · references/
• check-craft-facts.py · scripts/
• run.sh · tests/

SKILL.md (first lines)

# Craft CMS Operations

> Versions verified 2026-10-05 against Packagist and the official docs. Craft 5.x is
> current (5.11); Craft 4 and 3 are past security support; Craft 6 is in alpha.
> `scripts/check-craft-facts.py --live` re-checks the plugin majors on a schedule.

The recurring agency shape: Craft 5 (or a 4/3 site awaiting upgrade) on DDEV, with
SEOmatic, Blitz, Formie, and CKEditor, a Vite (or legacy Laravel Mix) front end, and
modules tested with Codeception and ECS. This file is the procedure and the router;
each topic lives in one reference.

## Step 1 - Orient before touching anything

| Check | Where | Tells you |
|-------|-------|-----------|
| Craft + plugin versions | `composer.json`, `ddev composer show craftcms/cms` | Which line of the [version matrix](#version-matrix) applies - Craft 4 and 5 APIs differ |
| Local environment | `.ddev/config.yaml` | PHP/DB versions; run everything as `ddev craft`, `ddev composer`, `ddev npm` |
| Schema | `config/project/*.yaml` | Source of truth for sections, fields, entry types, plugin settings |
| Config | `config/general.php`, `config/<plugin>.php`, `.env` | Environment-specific behaviour (`devMode`, `allowAdminChanges`, caching) |
| Front-end build | `package.json` + `config/vite.php`, or `webpack.mix.js` | craft-vite or Laravel Mix |
| Templates | `templates/_layouts`, `_partials`, `_partials/entry/<type>.twig` | Layout inheritance and element partials |
| PHP | `modules/`, `tests/`, `codeception.yml`, `ecs.php` | Where logic and tests live |
| Page cache | `config/blitz.php`, Blitz utility | Whether what you see is cached HTML - check before debugging "my change isn't showing" |

## Step 2 - Route the task

| Task | Read |
|------|------|
| Listing pages, relations, Matrix/nested entries, pagination, multi-site | [element-queries.md](references/element-queries.md) |
| Printing anything user-influenced, forms that POST, JS data, rich text output | [twig-security.md](references/twig-security.md) |
| Meta tags, JSON-LD, sitemaps, robots.txt, hreflang | [seomatic.md](references/seomatic.md) |
| Static caching, "changes don't show", cache warming, dynamic bits on cached pages | [blitz.md](references/blitz.md) |
| Building, theming, or debugging forms; spam; form emails not sending | [formie.md](references/formie.md) |
| Rich-text fields, nested entries inside rich text, Redactor conversion | [ckeditor.md](references/ckeditor.md) |
| Craft on DDEV: the `craftcms` type, `ddev craft`, Craft's `upload_dirs` (generic DDEV: `ddev-ops`) | [ddev.md](references/ddev.md) |
| Tests for modules/plugins, fixtures, ECS/PHPStan | [codeception.md](references/codeception.md) |
| Front-end assets, Vite dev server, critical CSS | [craft-vite.md](references/craft-vite.md) |
| Moving off Laravel Mix/Webpack, or Vue 2 to Vue 3 | `frontend-upgrade-ops` (the full migration playbook) |
| Upgrading Craft 3 → 4 → 5, plugin version lines, Craft 6 status | [upgrades.md](references/upgrades.md) |
| Slow pages, images, queue setup, production config | [performance.md](references/performance.md) |
| Core Web Vitals failing (LCP, INP, CLS), PageSpeed or Search Console flags | `web-perf-ops` (field data first; its `references/craft.md` maps the Craft levers) |
| Headless front ends, GraphQL schemas and tokens | [graphql.md](references/graphql.md) |
| Modules, plugins, events, migrations, queue jobs | [plugin-development.md](references/plugin-development.md) |
| Modeling a new flexible page type | [assets/entry-type-field-layout.md](assets/entry-type-field-layout.md) |

## Step 3 - Hold the non-negotiables

1. **Eager-load before you loop.** `.with([...])` up front; `.eagerly()` inside shared
   partials (Craft 5 only). One query per card is the most common Craft perf bug.
2. **Escape by context.** Never `|raw` user-influenced values; `|e('js')` inside JS
   strings; `{{ csrfInput() }}` in every POST form - `csrfInput({ async: true })` on
   cached pages.
3. **Schema only through Project Config.** Change it in the CP locally, commit
   `config/project/`, run `php craft up` on deploy. Production runs
   `allowAdminChanges => false`; never hand-edit the YAML.
4. **Data changes are content migrations** (`php craft migrate/create`), tested on a
   copy of production - not CP clicking on live.
5. **Production runs a queue worker.** Blitz regeneration, Formie emails and
   integrations, transform pre-generation, and resaves are all queue jobs.
6. **Fix queries, then cache.** Blitz for public pages; on Blitz-cached pages drop
   `{% cache %}` (or set `enableTemplateCaching` false).
7. **Logic lives in module services**, not Twig - services are testable.
8. **Stay on the latest Craft 5 patch.** Craft ships regular Twig/RCE security fixes.

## Version matrix

| Package | Craft 3 | Craft 4 | Craft 5 (current) |
|---------|---------|---------|-------------------|
| `craftcms/cms` | 3.9 (EOL) | 4.18 (EOL Apr 2026) | Craft 5.x (5.11); Craft 6 in alpha |
| `nystudio107/craft-seomatic` | 3.x | 4.x | SEOmatic 5 |
| `putyourlightson/craft-blitz` | 3.x | 4.x | Blitz 5 (5.13 needs Craft 5.6+) |
| `verbb/formie` | 1.x | 2.x | Formie 3 (Formie 4 in beta) |
| Rich text | Redactor | Redactor or `craftcms/ckeditor` 3.x | CKEditor plugin 5.x (needs Craft 5.10+; 4.x below that) |
| `nystudio107/craft-vite` | 1.x | 4.x | craft-vite 5 |
| `nystudio107/craft-imageoptimize` | 1.x | 4.x | ImageOptimize 5 |
| `spacecatninja/imager-x` | 3.x | 4.x | Imager-X 6 (5.x still maintained) |
| `codeception/codeception` | match core's `require-dev` | match core's `require-dev` | Codeception 5 |

Requirements for Craft 5: PHP 8.2+, MySQL 8.0.17+ / MariaDB 10.4.6+ / PostgreSQL 13+.
Details and plugin upgrade notes: [upgrades.md](references/upgrades.md).

## Everyday commands

| Command (prefix `ddev` locally) | Does |
|---------------------------------|------|
| `craft up` | Pending migrations + Project Config - run on every deploy |
| `craft project-config/apply` / `project-config/rebuild` | Apply YAML to the DB / rebuild YAML from the DB |
| `craft clear-caches/all` | Data, template, and asset caches |
| `craft queue/run` / `queue/info` / `queue/retry all` | Work and inspect the queue |
| `craft blitz/cache/refresh` | Refresh Blitz after template deploys (Blitz tracks content, not templates) |
| `craft migrate/create <name>` | New content migration |
| `craft make <type>` | Scaffold modules/plugins/components (`craftcms/generator`) |
| `craft entrify/categories <group>` | Convert categories (or `tags`, `global-set`) to entries |

## Craft 5 content model

| Concept | What it is | Craft 5 change |
|---------|-----------|----------------|
| **Section** | Single, Channel, or Structure; holds entry types + URI formats | - |
| **Entry type** | The unit of content shape | **Global and reusable** across sections and Matrix fields |
| **Field** | Reusable input | **Global**, with multi-instance use in one layout |
| **Matrix field** | Repeatable nested content | Stores **nested entries**, not blocks |
| **CKEditor field** | Rich text | Can hold **nested entries** inline |
| **Element partials** | `_partials/entry/<typeHandle>.twig` | `.render()` renders nested entries through them |
| **Project Config** | `config/project/` YAML | Source of truth - commit it |

Pick the section type by shape: **Single** for one-off pages (home, contact),
**Channel** for streams (news, events), **Structure** for hierarchies (pages, docs).
Prefer flat entry types plus a Matrix "page builder" field over many near-identical
sections. Starter shape: [entry-type-field-layout.md](assets/entry-type-field-layout.md).

## Gotchas

| Symptom | Cause | Fix |
|---------|-------|-----|
| Listing page runs hundreds of queries | Relation fetched per item | `.with()` / `.eagerly()` |
| Change visible in CP, not on site | Blitz/CDN serving cached HTML | [blitz.md](references/blitz.md#debugging-my-change-isnt-showing) |
| Form submissions save, emails never send | Queue not running in production | Queue daemon ([performance.md](references/performance.md#queue)) |
| Assets unstyled in production only | Vite 5+ manifest is in `dist/.vite/` | Set `manifestPath` ([craft-vite.md](references/craft-vite.md)) |

From 0xDarkMatter/claude-mods, MIT.

More from 0xDarkMatter/claude-mods