michtio/craftcms-claude-skills / skills/craft-cloud
craft-cloud
UnverifiedCraft Cloud — Pixel & Tonic's serverless hosting platform for Craft CMS. Covers craft-cloud.yaml configuration, the Build → Migrate → Release deploy pipeline, the craftcms/cloud extension package, edge image transforms via Cloudflare, edge static caching with cache.rules + ESI, Cloud-managed S3 filesystem, MySQL 8 / Postgres 15 databases (no MariaDB, no tablePrefix), Console-based command runner and scheduled cron (once-per-hour minimum), auto-handled queue jobs, custom domains and SSL, preview environments per branch, Cloud limitations (ephemeral filesystem, no SSH, no .htaccess, no built-in mail), plugin development requirements for Cloud compatibility, and self-hosted → Cloud migration.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 18.8 KB |
| references/assets-and-transforms.md | markdown | 5.5 KB |
| references/caching-and-edge.md | markdown | 23.4 KB |
| references/commands-and-cron.md | markdown | 7.0 KB |
| references/config-file.md | markdown | 6.9 KB |
| references/database.md | markdown | 6.0 KB |
| references/deploy-pipeline.md | markdown | 16.6 KB |
| references/domains.md | markdown | 5.4 KB |
| references/extension.md | markdown | 15.6 KB |
| references/headless.md | markdown | 8.0 KB |
| references/limitations.md | markdown | 17.3 KB |
| references/local-dev.md | markdown | 6.8 KB |
| references/migration.md | markdown | 8.6 KB |
| references/plugin-development.md | markdown | 14.5 KB |
references/config-file.md
View on GitHub# `craft-cloud.yaml` — The Cloud Configuration File
The single platform-level config file Cloud reads. Lives at the repo root. Drives the build container, runtime web server, edge static cache, and URL rewrites.
## Documentation
- Configuration reference: https://craftcms.com/docs/cloud/config
- Static caching rules: https://craftcms.com/docs/cloud/static-caching
- Redirects and rewrites: https://craftcms.com/docs/cloud/redirects
## Common Pitfalls
- Putting it anywhere other than the repo root. Cloud looks for `craft-cloud.yaml` at the repo root only.
- Omitting `php-version`. It's the one required key — builds fail without it.
- Setting `node-version` without `npm-script` when your `package.json` doesn't have a `build` script. The default `npm-script` is `build`; if your build script is named differently (e.g. `production`), set `npm-script: production` explicitly.
- Leaving `webroot` set to the wrong directory after restructuring. Default is `web`. Common drift case: project moved to `public/` but `webroot` not updated.
- Trying to add post-deploy hooks or shell commands in `craft-cloud.yaml`. Not supported — there are no `build-hooks` / `post-deploy` / `commands` keys. Use the Console scheduled commands for recurring tasks; for one-off post-deploy work, run it manually in Console after the deploy completes.
- Treating `redirects:` / `rewrites:` as a `.htaccess` replacement for arbitrary rules. They're limited to simple from/to mappings — complex conditional rewrites aren't supported.
## Minimal viable config
```yaml
php-version: "8.3"
```
That's it. Everything else is optional with sensible defaults.
## All keys
| Key | Type | Default | Purpose |
|---|---|---|---|
| `php-version` | string (required) | — | PHP version for build + runtime. Quoted to keep `"8.3"` from being parsed as a number. |
| `node-version` | string | (no Node) | Node version. **Setting this triggers `npm clean-install` + `npm run <npm-script>` during build.** Omit if your project doesn't need a build step. |
| `node-path` | string | repo root | Directory to `cd` into before running `npm` commands. Set this when `package.json` lives in a subdirectory (e.g. `frontend/`). |
| `npm-script` | string | `build` | The npm script name to run. Override when your script is named `production`, `dist`, etc. |
| `artifact-path` | string | Inherits the value of `webroot` | Path to upload as the deploy artifact after the build phase. **Caution:** pointing it anywhere other than the webroot means webroot files are no longer published or accessible — the docs' guidance is to only ever change `webroot` and let this stay synchronized. See `deploy-pipeline.md` (Artifact URLs). |
| `app-path` | string | repo root | Where Craft's PHP application lives if not at the repo root. |
| `webroot` | string | `web` | The public document root, relative to `app-path`. Update if you've renamed `web/` to `public/`. |
| `cache` › `rules` | list | (no rules) | Edge static caching rules — a `rules` list nested under a top-level `cache:` key (not a flat `cache.rules:`). See [Static Cache Rules](#static-cache-rules) below. |
| `redirects` | list | (none) | URL redirects — see [Redirects](#redirects) below. |
| `rewrites` | list | (none) | URL rewrites — see [Rewrites](#rewrites) below. |
## Worked example
A typical Craft site with a Vite build, custom webroot, and edge caching for the marketing pages:
```yaml
php-version: "8.3"
node-version: "20"
npm-script: build
webroot: web
cache:
rules:
- pattern: "/account/*"
query-string:
mode: include
keys: all
- pattern: "/blog/*"
query-string:
mode: exclude
keys:
- utm_source
- utm_medium
- utm_campaign
- pattern: "/*?"
query-string:
mode: exclude
keys: all
redirects:
- from: "/old-blog/(.*)"
to: "/blog/$1"
status: 301
rewrites:
- from: "/legacy-api/(.*)"
to: "/api/v1/$1"
```
## Static cache rules
Cache rules live under a **nested `cache:` → `rules:`** key (not a flat `cache.rules:` key), and control how the edge layer keys cached responses. Each rule needs a `pattern` plus at least one of `query-string` or `cookies` (the cookie-vary key is `cookies:`, **not** `session:`). A wrong key name or the flat shape is ignored silently — you get default caching with no error.
**Important — duration is not a cache-rule key.** How long to cache is set in the response itself, via the `{% expires %}` Twig tag or `$this->response->getHeaders()->set('Cache-Control', ...)` in a controller. Cache rules control *what to cache* and *how to vary the key*, not *for how long*.
**Order matters — first match wins.** List rules from most specific to least specific.
```yaml
cache:
rules:
- pattern: "/search"
query-string:
mode: include
keys:
- q
- category
- pattern: "/blog/*"
query-string:
mode: exclude
keys:
- utm_source
- utm_medium
cookies:
- AD_SOURCE
- pattern: "/*?"
query-string:
mode: exclude
keys: all
```
For the full cache-rules surface (every `mode` value, cookie-vary semantics including serving fresh HTML to logged-in users, opt-out mechanisms, ESI), see `caching-and-edge.md`.
## Redirects
Server-level HTTP redirects, evaluated before the request reaches PHP.
```yaml
redirects:
- from: "/old-page"
to: "/new-page"
status: 301
- from: "/blog/(.*)"
to: "/articles/$1"
status: 302
```
- `from` — path pattern. Supports regex capture groups.
- `to` — destination. Use `$1`, `$2`, etc. for captures.
- `status` — `301` for permanent, `302` for temporary. Choose based on whether the change is final.
## Rewrites
Internal URL rewrites — the user sees the original URL, the server serves a different one. Use sparingly; redirects are usually clearer for content moves.
```yaml
rewrites:
- from: "/api/legacy/(.*)"
to: "/api/v1/$1"
```
Same `from` / `to` semantics as redirects, but no status code (the URL doesn't change in the browser).
## What `craft-cloud.yaml` does NOT configure
- Environment variables — those live in the Craft Console UI per environment, not in this file. See `deploy-pipeline.md` (Build-time vs runtime variables).
- Database connection — auto-wired by the Cloud extension. Don't set `CRAFT_DB_*` vars; don't touch `config/db.php`.
- Mail — Cloud has no built-in mail service. Configure your own SMTP transport in `config/app.php` or via env vars. See `limitations.md` (Mail).
- Custom domains — added via the Craft Console UI, not this file. See `domains.md`.
- Scheduled commands — managed in Craft Console under Commands → Scheduled Commands. See `commands-and-cron.md`.
- Queue runner — auto-handled by Cloud. No queue daemon to configure.
- Asset filesystem details — configured as a normal Craft filesystem using the Cloud extension's `AssetsFs` type. See `assets-and-transforms.md`.
Last verified against https://craftcms.com/docs/cloud/config on 2026-05-28.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| writing-skillsobra/superpowersUse when creating new skills, editing existing skills, or verifying skills work before deployment | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| 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: 198k | Updated | Claude CodeCodex | Verified | Install |
| 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: 119k | Updated | Claude CodeCodex | Verified | Install |
| 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: 118k | Updated | Claude CodeCodex | Verified | Install |