Instructions for AI coding agents (Claude Code, Cursor, Codex, Copilot, …) working in this repository.
CLAUDE.md imports this file, so it is the single source of truth for every agent.
A pnpm + Turborepo monorepo for one Strapi v5 plugin:
| Path | What it is |
|---|---|
plugins/<plugin>/ |
The plugin itself (admin/ + server/). There is exactly one folder under plugins/; its name changes when pnpm rename-plugin runs, so never hard-code it. |
apps/playground/ |
A full Strapi v5 app with the plugin installed. It is the fixture app for integration and E2E tests. |
packages/dev-utils/ |
Test harness and CLIs: setupStrapi/stopStrapi, createPlaywrightConfig, with-db, dev-strapi, rename-plugin. |
.claude/brain/ |
What agents and maintainers have learned about this repo. See The brain. |
pnpm install
pnpm build # build every package and the plugin
pnpm dev # playground + plugin watch (SQLite); dev:postgres / dev:mysql need Docker
pnpm lint # Biome lint + format
pnpm lint:ts # TypeScript check, admin + server
pnpm test:integration # Vitest + Supertest against a real Strapi (SQLite)
pnpm test:e2e # Playwright against the playground (SQLite)
pnpm changeset # describe a change to the published plugin- Strapi v5 only. Server code uses the Document Service API (
strapi.documents(uid)) and the v5 factories; neverentityServiceor v4 patterns. - Admin UI uses
@strapi/design-systemv2 and@strapi/icons: no raw HTML controls, no other icon set. Text goes throughreact-intlwith keys fromgetTranslation(); strings live inadmin/src/translations/en.json. - Use
PLUGIN_IDfromadmin/src/pluginId.tsrather than writing the plugin's name in new code (see.claude/brain/practices/rename-plugin-rewrites-a-fixed-file-list.md). - Biome formats and lints everything. A pre-commit hook runs Biome and the TypeScript check on staged files; do not bypass it.
- Changesets: a change that affects the published plugin needs a changeset (
pnpm changeset). Changes toapps/playground,packages/dev-utilsor repo tooling do not.
These are maintained outside this repo and referenced, not copied. Use the one that fits the task.
| Task | Use |
|---|---|
| Server or admin plugin code | strapi-plugin-dev skill (strapi-skills) |
| Admin screens: settings pages, tables, forms, modals | strapi-ui-design skill, plus the Strapi Design System for the visual language (strapi-design-system skill in Claude Code) |
| Planning, writing, fixing or reviewing tests | strapi-plugin-testing skill |
| Review before a PR | strapi-reviewer and strapi-ui-reviewer agents; /strapi-skills:verify, /strapi-skills:ui-audit |
| Adding a content type, admin screen or CM panel | /strapi-skills:add-content-type, /strapi-skills:ui-component, /strapi-skills:add-cm-panel |
| A fact worth keeping, or a term that misled | brain-remember skill (.claude/skills/brain-remember/SKILL.md) |
| Something went wrong and should not happen again | brain-retro skill (.claude/skills/brain-retro/SKILL.md) |
Do not run /strapi-skills:scaffold-plugin: the plugin is already scaffolded. To rename it,
use pnpm rename-plugin.
Getting the skills: Claude Code offers to install them when the folder is trusted (see
CLAUDE.md). Other agents can install them with npx skills add ayhid/strapi-skills or read the
SKILL.md files on GitHub. Agents without the skills should still follow the conventions above.
The skills describe a generic plugin layout. Here:
- Fixture app:
apps/playground. Its config and content types are what integration tests run against. - Harness:
setupStrapi()/stopStrapi()from@pluginpal/dev-utils, which boot the playground with an isolated database. Seeplugins/<plugin>/server/test/example.test.ts. - Integration tests:
server/test/**/*.test.ts, the only patternvitest.config.tsincludes. Pure unit tests need their own include pattern (and ideally their own Vitest project) so they run without booting Strapi. - E2E tests:
admin/test/*.spec.ts, Playwright viacreatePlaywrightConfig(), logged in byadmin/test/setup/auth.setup.ts. - Admin data fetching: the plugin's peer dependencies list
react-queryv3, whilestrapi-plugin-devrecommends@tanstack/react-queryv5 with its ownQueryClient. Pick one on purpose when adding data fetching, and record the choice in the brain. - fullstack-standards (the rule checker strapi-skills pairs with) is not enabled here. It is
opt-in because it blocks edits that break its layering rules; see its
README to turn it on, pointing its roots at
plugins/<plugin>/admin/srcandplugins/<plugin>.
.claude/brain/ holds what has been learned about working on this repo, committed so every agent and
contributor starts from it:
.claude/brain/GLOSSARY.md: terms that mean something specific here. Use its words..claude/brain/practices/: checked facts, one per file, indexed in.claude/brain/practices/INDEX.md. Before re-deriving how something in this repo works, read the index. For avolatileentry, run itsrecheckfirst..claude/brain/RETRO-LOG.md: what went wrong and the change that fixed it.
Add to it through the brain-remember and brain-retro skills (other agents: follow
.claude/brain/README.md). Never put secrets, tokens, hostnames or personal data in it.