michtio/craftcms-claude-skills / skills/craft-plugins
craft-plugins
VerifiedIndex 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.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 8.4 KB |
| references/amazon-ses.md | markdown | 2.9 KB |
| references/blitz.md | markdown | 10.5 KB |
| references/cache-igniter.md | markdown | 2.8 KB |
| references/ckeditor.md | markdown | 18.5 KB |
| references/colour-swatches.md | markdown | 7.0 KB |
| references/element-api.md | markdown | 7.0 KB |
| references/elements-panel.md | markdown | 2.4 KB |
| references/embedded-assets.md | markdown | 5.1 KB |
| references/feed-me.md | markdown | 8.8 KB |
| references/formie.md | markdown | 27.5 KB |
| references/hyper.md | markdown | 5.4 KB |
| references/image-optimize.md | markdown | 27.6 KB |
| references/imager-x.md | markdown | 15.1 KB |
| references/knock-knock.md | markdown | 2.5 KB |
| references/navigation.md | markdown | 6.8 KB |
| references/password-policy.md | markdown | 5.1 KB |
| references/retour.md | markdown | 4.1 KB |
| references/seomatic.md | markdown | 23.2 KB |
| references/sherlock.md | markdown | 3.2 KB |
| references/sprig.md | markdown | 9.7 KB |
| references/timeloop.md | markdown | 6.7 KB |
| references/typogrify.md | markdown | 2.9 KB |
| references/vite.md | markdown | 6.1 KB |
| references/warp.md | markdown | 12.4 KB |
references/element-api.md
View on GitHub# Element API
First-party JSON API plugin by Pixel & Tonic. Define endpoints in a config file that map URL patterns to element queries with Fractal transformers. Powers headless/hybrid setups, AJAX feeds, calendar integrations, and any external data consumer that needs Craft content as JSON. 10K+ installs.
`craftcms/element-api` — Free (MIT)
## Documentation
- GitHub/README: https://github.com/craftcms/element-api/blob/4.x/README.md
- Plugin Store: https://plugins.craftcms.com/element-api
When unsure about a config option, `WebFetch` the GitHub README — it's the canonical reference.
## Common Pitfalls
- Not defining a transformer — the default transformer returns direct attribute values but **no custom field values**. Almost every real endpoint needs a custom transformer.
- Returning too much data — transformers should explicitly select fields, not dump everything. Keep payloads lean.
- Missing `one` for single-element endpoints — without `'one' => true`, the endpoint returns a paginated collection even for detail routes. Set it for `api/entries/<slug>` style endpoints.
- Using `'p'` as a URL parameter name — Craft reserves `p` for path resolution. Use any other parameter name.
- Not scoping criteria tightly — an open `craft\elements\Entry::class` without section/type criteria exposes all entries across all sections. Always filter.
- Forgetting the endpoint is cached by default — responses cache automatically and invalidate when relevant elements change. If you're hitting stale data, check whether cache invalidation is working or add explicit cache config.
- Exposing draft/revision data — Element API respects Craft's default query behavior, but misconfigured criteria can leak drafts. Don't override status/draft params unless intentional.
- Returning a Link field value raw — on Craft 5.11+ a `LinkData` object serialises to a full array (`type`, `url`, `label`, `elementId`, … see the `craft-content-modeling` skill's `field-types.md`); on 5.3–5.10 it was sparse. Pick the fields explicitly (`'url' => $entry->cta?->getUrl()`, `'label' => $entry->cta?->getLabel()`) so the payload shape doesn't change with the Craft minor.
## Config File
All endpoints are defined in `config/element-api.php`:
```php
<?php
use craft\elements\Entry;
use craft\elements\Asset;
use craft\helpers\UrlHelper;
return [
'defaults' => [
'elementsPerPage' => 20,
'pageParam' => 'pg',
'resourceKey' => 'data',
],
'endpoints' => [
// Collection endpoint — returns paginated list
'api/news.json' => function() {
return [
'elementType' => Entry::class,
'criteria' => [
'section' => 'news',
'orderBy' => 'postDate DESC',
],
'transformer' => function(Entry $entry) {
return [
'id' => $entry->id,
'title' => $entry->title,
'url' => $entry->url,
'date' => $entry->postDate->format('c'),
'summary' => $entry->summary ?? null,
];
},
];
},
// Detail endpoint — single element
'api/news/<slug:{slug}>.json' => function(string $slug) {
return [
'elementType' => Entry::class,
'one' => true,
'criteria' => [
'section' => 'news',
'slug' => $slug,
],
'transformer' => function(Entry $entry) {
return [
'id' => $entry->id,
'title' => $entry->title,
'url' => $entry->url,
'date' => $entry->postDate->format('c'),
'body' => (string) $entry->body,
'image' => $entry->heroImage
->one()?->getUrl('newsDetail'),
];
},
];
},
],
];
```
## Endpoint Configuration
| Setting | Type | Default | Description |
|---------|------|---------|-------------|
| `elementType` | string | — | Element class (required). `Entry::class`, `Asset::class`, `Category::class`, etc. |
| `criteria` | array | `[]` | Element query params: `section`, `type`, `orderBy`, `limit`, `relatedTo`, etc. |
| `transformer` | callable/class | default | Maps element → response array. Closure or `TransformerAbstract` class. |
| `one` | bool | `false` | Return single element instead of collection. |
| `paginate` | bool | `true` | Enable pagination on collection endpoints. |
| `elementsPerPage` | int | 100 | Page size. |
| `pageParam` | string | `'page'` | Query param for pagination. |
| `resourceKey` | string | `'data'` | Key wrapping element data in response. |
| `cache` | bool/int | `true` | Cache duration in seconds, or `true` for auto-invalidation. |
| `meta` | array | `[]` | Custom metadata in response root. |
| `serializer` | object | `JsonApiSerializer` | Fractal serializer instance. |
| `callback` | string/null | `null` | JSONP callback parameter name. |
## Custom Transformer Class
For complex endpoints, use a dedicated transformer:
```php
<?php
namespace modules\transformers;
use craft\elements\Entry;
use League\Fractal\TransformerAbstract;
class NewsTransformer extends TransformerAbstract
{
public function transform(Entry $entry): array
{
return [
'id' => $entry->id,
'title' => $entry->title,
'slug' => $entry->slug,
'url' => $entry->url,
'date' => $entry->postDate->format('c'),
];
}
}
```
Reference in config: `'transformer' => new \modules\transformers\NewsTransformer()`.
## Dynamic URL Parameters
URL patterns support Craft's route tokens:
```php
// Slug token
'api/entries/<slug:{slug}>.json' => function(string $slug) { /* ... */ },
// Entry ID
'api/entries/<entryId:\d+>.json' => function(int $entryId) { /* ... */ },
// Section handle
'api/<section:{handle}>.json' => function(string $section) { /* ... */ },
```
## Events
The plugin fires `EVENT_BEFORE_SEND_DATA` before sending:
```php
use craft\elementapi\controllers\DefaultController;
use craft\elementapi\events\BeforeSendDataEvent;
use yii\base\Event;
Event::on(
DefaultController::class,
DefaultController::EVENT_BEFORE_SEND_DATA,
function(BeforeSendDataEvent $event) {
// Modify $event->data before it's sent
}
);
```
## Multi-Site
Endpoints serve the current site's content by default. To pin to a specific site:
```php
'criteria' => [
'site' => 'en',
'section' => 'news',
],
```
## Pair With
- **Timeloop** — expose recurring dates as JSON for external calendar apps
- **SEOMatic** — use Element API for meta endpoints, SEOMatic for rendered page SEO
- **Blitz** — cached pages + JSON API endpoints from the same Craft install
- **Scout / Typesense** — Element API for structured feeds, search plugins for full-text
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 |