strapi

Imported from modem-dev/ossrules (public/files/strapi/AGENTS.md). Install upstream with npx skills add modem-dev/ossrules --skill strapi. Copyright stays with the author.

Strapi Monorepo — Agent Guide

Strapi is an open-source headless CMS. Yarn workspaces + Nx monorepo. Node ≥22 ≤26, Yarn 4. Target branch: develop (not main). All PRs go to develop.

Repository Structure

packages/core/       # Framework: strapi, admin, database, content-manager, types, utils…
packages/plugins/    # Official plugins: users-permissions, i18n, graphql, documentation…
packages/providers/  # Email + upload provider implementations
packages/utils/      # Shared tooling: logger, eslint-config, tsconfig, vitest-config
packages/cli/        # CLI tools: create-strapi-app, cloud-cli
examples/            # Dev sandboxes only — not published, not for production fixes
docs/                # Contributor documentation (also at contributor.strapi.io)
tests/               # Integration, E2E, and CLI test infrastructure

The following are the most important packages (not exhaustive — run yarn workspaces list for the full set):

Skills directories

.ai/skills/ is the canonical source for committed repo skills. Each subdirectory containing a SKILL.md is a skill.

The AI-tooling well-known locations are symlink targets maintained by yarn ai:sync: .agents/skills/, .claude/skills/, .cursor/skills/.

Run yarn ai:sync after adding or removing a skill in .ai/skills/ to keep all three target dirs up to date. Links are local-only (gitignored target dirs) — only .ai/skills/ content is committed.

On Windows, the CLI creates directory junctions (no extra setup). Directory symlinks require Developer Mode or an elevated shell.

yarn ai:sync    # idempotent — create/prune .ai links in all 3 tool dirs
yarn ai:unlink  # remove only .ai-sourced links (leaves brain links intact)
yarn ai:status  # read-only report: linked / missing / conflict / stale

Architecture

• Strapi class — The DI container and central hub. Accessed as a strapi parameter injected through the factory pattern (e.g. createService(strapi)). Never use global.strapi — always prefer proper dependency injection. Provides strapi.documents, strapi.db, strapi.log, etc. Lifecycle: Register → Bootstrap → Start → Destroy (start() calls load() internally, which runs register + bootstrap).
• Server / Admin split — Koa.js HTTP server (@strapi/strapi) + React/Redux admin (@strapi/admin). Packages with both concerns export dual entry points: strapi-server (Node.js logic) and strapi-admin (UI components).
• Document Service — The primary high-level API for content (strapi.documents). Replaced the legacy Entity Service. Always use this for reading/writing content — never raw DB queries unless you're working inside @strapi/database itself.
• Polymorphic (morph*) relations — Contributor doc: docs/docs/docs/01-core/database/01-relations/polymorphic-relations.md (storage, DB populate, and how getDeepPopulate / relation traversal interact with morphToOne and join-based morphs).
• Plugin system — Plugins register routes, controllers, services, content types, and middleware via the same strapi-server / strapi-admin dual structure. Official plugins live in packages/plugins/.
• Content Types — Defined using a JSON-based notation (not JSON Schema spec). Each content type has a schema.json file — see any packages/core/content-manager/server/src/content-types/ for examples. The database layer auto-generates tables from them. Never write raw migrations for content type changes.
• EE / CE split — Some features are Enterprise Edition only, gated at runtime. See EE toggles in the Testing section below.
• @strapi/types — Single source of truth for shared TypeScript types. Import from here; improve these types rather than duplicating locally.

Monorepo Setup

# Initial setup (run once after cloning)
yarn install
yarn setup                    # clean + build all packages; hints to run ai:sync if links are missing
yarn ai:sync          # link .ai/skills into .agents/ .claude/ .cursor/

New worktree bootstrap

• In a newly created worktree, check whether .claude/skills/git-conventions resolves to the repository's .ai/skills/git-conventions. If the link is absent or stale, run yarn setup:worktree.
• If .brain exists, do not initialize or refresh it.
• If .brain is absent, look for the user-level brain-start skill.
  • If unavailable, continue silently; this is the normal external-contributor path.
  • If available, read it, resolve the CMS Brain CLI from its canonical host checkout, and run "$BRAIN_CLI" refresh --project strapi/strapi.
• If CMS Brain is installed and refresh fails, report the failure and follow the bootstrap skill's remediation. Only the absence of the optional skill is a clean no-op.

Development

# Run the dev sandbox
cd examples/getstarted
yarn develop                  # SQLite (default)

# Start non-memory databases (postgres/mysql)
docker-compose -f docker-compose.dev.yml up -d
DB=postgres yarn develop      # PostgreSQL
DB=mysql yarn develop         # MySQL

# Watch all packages + run sandbox with admin watch (two terminals)
yarn watch                                           # terminal 1, repo root
cd examples/getstarted && yarn develop --watch-admin # terminal 2

Build

yarn build              # all packages (code + types)
yarn build:code         # faster — skips .d.ts generation
yarn nx build @strapi/admin   # single package

Testing

Unit tests (fastest — run first)

Unit test files live in __tests__/ subdirectories within each package.

yarn test:unit
yarn test:unit:watch
yarn test:unit:update         # update snapshots

Frontend tests (admin panel)

Frontend test files also live in __tests__/ within their respective packages.

yarn test:front              # runs with IS_EE=true (EE features enabled)
yarn test:front:ce           # runs with IS_EE=false (Community Edition only)
yarn test:front:update       # update snapshots (EE)
yarn test:front:update:ce    # update snapshots (CE)

Type checking

yarn test:ts                 # all packages + front + back

API integration tests

Integration tests live in tests/api/. Test apps are generated automatically — always regenerate with yarn test:generate-app rather than reusing a stale one (stale apps cause misleading failures).

yarn test:api                # SQLite
yarn test:api --db=postgres
yarn test:api --db=mysql
yarn test:api -u             # update snapshots

CLI tests

CLI tests live in tests/cli/.

yarn test:cli
yarn test:cli:debug          # with debug output
yarn test:cli:update         # update snapshots

E2E tests (Playwright)

E2E tests live in tests/e2e/tests/ organized by domain (e.g. admin, content-manager, i18n).

yarn playwright install                          # one-time browser install
yarn test:e2e --setup --concurrency=1            # run all domains sequentially
yarn test:e2e --domains content-manager admin    # run specific domains only
yarn test:e2e --concurrency=3                    # run 3 domains in parallel

EE toggles

• IS_EE=true — enables Enterprise features in frontend tests (yarn test:front)
• RUN_EE=true — enables Enterprise features in E2E tests

Pre-PR checklist

All tests must pass before merging. Run at minimum:

yarn test:unit && yarn test:front && yarn test:ts && yarn lint && yarn prettier:check

E2E (yarn test:e2e) is required per CONTRIBUTING.md but slow — CI enforces it on every PR.

When to add or update tests: Always for bug fixes (reproduce the bug first). For features, add tests when they cover meaningful behaviour — not just to hit coverage numbers. When changing existing behaviour, update the affected tests to match.

Quality Gates

Commits

Must follow Conventional Commits (enforced by Husky commit-msg hook and CI via commitlint). Format:

<type>(<optional-scope>): <description>

Valid types: feat fix chore ci docs enhancement test revert security future release

Examples:

feat(content-manager): add bulk delete action
fix(database): preserve relation order during publish
chore(admin): migrate data-fetching to react-query

Use yarn commit for an interactive prompt. Run yarn version:check if you've touched any package.json.

TypeScript

• Import types from @strapi/types — extend or improve them rather than duplicating locally.
• Never use any when a proper type exists or can be reasonably defined. Prefer unknown otherwise.
• Run yarn test:ts before pushing.

Linting & Formatting

yarn lint           # ESLint across all packages
yarn lint:fix       # auto-fix
yarn format         # Prettier (2-space indent, single quotes, semicolons, trailing commas, arrow parens, 100-char width, LF)
yarn prettier:check # check only

Security

• Never commit secrets, credentials, or API keys.
• Never disable or weaken authentication/authorization checks.
• Use parameterized queries — never interpolate user input into raw SQL or database queries.
• Validate and sanitize all user input at controller/service boundaries.
• When working with EE-gated features, do not bypass license checks.

PR Guidelines

• Branch from develop, target develop — never main.
• Link the issue you're fixing in the description.
• All tests must pass before merging.
• PR description must follow .github/PULL_REQUEST_TEMPLATE.md — do not invent your own sections.

Notes for Agents

• examples/ apps are sandboxes only — use them to reproduce and test fixes, never commit changes to them unless specifically asked to do so. Exception: examples/complex is the migration test fixture (schemas, seeds, validate-migration.js, DB tooling); CI runs migration_v5 against it via tests/migration/. It may relocate under tests/migration/ in the future.
• Workspace deps — internal packages/ deps reference each other with pinned semver versions (e.g. "5.42.0"), not workspace:*. The workspace:* protocol is only used in examples/ apps and some root devDeps.
• Entity Service is deprecated — always use the Document Service (strapi.documents) for content operations.
• Lifecycle phases — strapi.isLoaded must be true before accessing services. Plugins and DB are not available until after the load() phase.