Skip to content

michtio/craftcms-claude-skills / skills/craft-cloud

craft-cloud

Unverified

Craft 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.

references/assets-and-transforms.md

View on GitHub
# Assets and Image Transforms on Cloud

Cloud replaces local asset filesystems and Craft's native image transformer with platform-managed equivalents. User assets live in a Cloud-managed S3 bucket; transforms run at the edge via Cloudflare and serve modern formats automatically.

## Documentation

- Assets reference: https://craftcms.com/docs/cloud/assets
- Cloud filesystem source: https://github.com/craftcms/cloud/blob/3.x/src/fs/AssetsFs.php
- Image transformer source: https://github.com/craftcms/cloud/tree/3.x/src/imagetransforms

## Common Pitfalls

- Leaving the **Subpath** blank on the Cloud filesystem. Even with a single filesystem, the docs are explicit: "Filesystems' base paths cannot overlap!" Use the Subpath option to reserve root space — e.g. `assets/` — so future filesystems (or future environments) can coexist.
- Running `aws s3 sync` without the `assets/` segment in the destination URL. "Files uploaded outside of [the `assets/` subpath] will be undiscoverable by Craft." Wrong destination, lost migration.
- Continuing to use ImageOptimize / Imager-X to generate srcset on Cloud. Cloud transforms images at the edge — these plugins duplicate the work and can produce stale references. See `limitations.md` (Plugin compatibility).
- Expecting `transform.mode = 'stretch'` to actually stretch. On Cloud the workers treat `stretch` like CSS `object-fit: cover` — proportional fill rather than independent W/H scaling. If you need pixel-exact stretching, generate the transform off-platform.
- Uploading an animated GIF over 50MP across all frames. Cloud rejects it.

## The Cloud filesystem type

The extension registers a `craft\cloud\fs\AssetsFs` filesystem type. Configure it as a normal Craft filesystem (Settings → Filesystems → New filesystem → type = Cloud), then point one or more asset volumes at it.

### Required settings

- **Subpath** (required) — automatically appended to both Base Path and URL. Use a value like `assets/` for the primary user-uploaded files. The third segment in the resulting S3 URL must be a subpath; files uploaded outside it are invisible to Craft.
- **Local Filesystem** section (recommended) — when migrating an existing site, copy the original Base Path and Base URL here. This lets local dev keep reading files from the same on-disk location while production reads from Cloud.

Internal filesystem types (you don't configure these — the extension manages them):

| FS class | Backs |
|---|---|
| `BuildArtifactsFs` | Build artifacts uploaded between phases |
| `BuildsFs` | Build metadata |
| `CpResourcesFs` | CP asset bundles published to the CDN at build time |
| `StorageFs` | Craft's `storage/` path |
| `TmpFs` | Temp paths returned by `Craft::$app->getPath()->getTempPath()` |

See `extension.md` (Filesystem types) for the full table.

## Image transforms at the edge

Every image transform call — `asset.getUrl({width: 800})`, named transforms, ad-hoc transforms, transforms from Twig or PHP — runs through Cloud's edge workers. Existing templates work without changes.

### Auto-negotiated formats

When no explicit format is specified, Cloud serves WEBP or AVIF based on the client's `Accept` header. Same URL, different bytes per client. Fall back to the original format for clients that don't support either.

### Limits

| Limit | Value |
|---|---|
| Maximum source file size | 70MB |
| Maximum source megapixels | 100MP |
| Maximum source megapixels (animated, total across frames) | 50MP |
| Maximum longest-edge output | 12,000px |
| Maximum longest-edge output for AVIF | 1,600px |

Sources exceeding these limits won't transform — Craft will fall back to the original. For images that need to ship at >12,000px on the long edge, deliver the original file directly (skip the transform).

### Stretch mode

`stretch` doesn't independently scale width and height — Cloud treats it like CSS `object-fit: cover`. The image fills the target box proportionally; the longer dimension is clipped. If you need true stretch semantics (rare for content images), do the resizing off-platform and upload pre-sized assets.

## Migrating assets from a self-hosted site

The supported tool is the AWS S3 CLI's `sync` command. Cloud's bucket address comes from the project and environment UUIDs (visible in Console). All environments in a project **share one bucket**, separated only by these per-environment UUID top-level directories — so getting the environment UUID right is what keeps a staging sync from landing in production's asset tree.

```sh
# Push local files into the Cloud bucket
aws s3 sync ./web/craft-cloud-assets/ s3://{project-uuid}/{environment-uuid}/assets/

# Pull Cloud files back to local (e.g. to refresh a dev environment)
aws s3 sync s3://{project-uuid}/{environment-uuid}/assets/ ./web/craft-cloud-assets/ --delete
```

The third URL segment (`assets/`) is mandatory and must match the Subpath you configured on the filesystem. Run periodically during the migration window to catch new uploads on the legacy site.

For the broader migration sequence (DB + assets + DNS cutover), see `migration.md`.

## What you don't need to do

- Generate srcsets in templates manually for Cloud's benefit — the existing transform calls produce all the URLs you need.
- Configure a CDN — Cloud's edge layer is the CDN.
- Set up a transform queue worker — transforms are synchronous edge operations, not Craft queue jobs.
- Install Cloudflare separately — Cloud is built on Cloudflare; you don't manage it.

Last verified against https://craftcms.com/docs/cloud/assets and `craftcms/cloud-extension-yii2@main` on 2026-05-28.
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