AGENTS.md

1# Strapi Monorepo — Agent Guide
2 
3Strapi is an open-source headless CMS.
4Yarn workspaces + Nx monorepo. Node ≥22 ≤26, Yarn 4.
5Target branch: `develop` (not `main`). All PRs go to `develop`.
6 
7---
8 
9## Repository Structure
10 
11```
12packages/core/       # Framework: strapi, admin, database, content-manager, types, utils…
13packages/plugins/    # Official plugins: users-permissions, i18n, graphql, documentation…
14packages/providers/  # Email + upload provider implementations
15packages/utils/      # Shared tooling: logger, eslint-config, tsconfig, vitest-config
16packages/cli/        # CLI tools: create-strapi-app, cloud-cli
17examples/            # Dev sandboxes only — not published, not for production fixes
18docs/                # Contributor documentation (also at contributor.strapi.io)
19tests/               # Integration, E2E, and CLI test infrastructure
20```
21 
22The following are the most important packages (not exhaustive — run `yarn workspaces list` for the full set):
23 
24| Package                            | Description                                               |
25| ---------------------------------- | --------------------------------------------------------- |
26| `@strapi/strapi`                   | Main framework entry point (Koa server)                   |
27| `@strapi/admin`                    | React 18 admin dashboard                                  |
28| `@strapi/core`                     | Core business logic                                       |
29| `@strapi/database`                 | Database abstraction (MySQL, PostgreSQL, MariaDB, SQLite) |
30| `@strapi/content-manager`          | Content management UI                                     |
31| `@strapi/types`                    | Shared TypeScript type definitions                        |
32| `@strapi/permissions`              | RBAC engine                                               |
33| `@strapi/plugin-users-permissions` | JWT authentication                                        |
34 
35### Skills directories
36 
37**`.ai/skills/`** is the canonical source for committed repo skills. Each subdirectory containing a `SKILL.md` is a skill.
38 
39The AI-tooling well-known locations are **symlink targets** maintained by `yarn ai:sync`: `.agents/skills/`, `.claude/skills/`, `.cursor/skills/`.
40 
41Run `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.
42 
43On **Windows**, the CLI creates directory **junctions** (no extra setup). Directory symlinks require Developer Mode or an elevated shell.
44 
45```bash
46yarn ai:sync    # idempotent — create/prune .ai links in all 3 tool dirs
47yarn ai:unlink  # remove only .ai-sourced links (leaves brain links intact)
48yarn ai:status  # read-only report: linked / missing / conflict / stale
49```
50 
51---
52 
53## Architecture
54 
55- **`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).
56- **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).
57- **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.
58- **Polymorphic (morph\*) relations** — Contributor doc: [docs/docs/docs/01-core/database/01-relations/polymorphic-relations.md](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).
59- **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/`.
60- **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.
61- **EE / CE split** — Some features are Enterprise Edition only, gated at runtime. See EE toggles in the Testing section below.
62- **`@strapi/types`** — Single source of truth for shared TypeScript types. Import from here; improve these types rather than duplicating locally.
63 
64---
65 
66## Monorepo Setup
67 
68```bash
69# Initial setup (run once after cloning)
70yarn install
71yarn setup                    # clean + build all packages; hints to run ai:sync if links are missing
72yarn ai:sync          # link .ai/skills into .agents/ .claude/ .cursor/
73```
74 
75---
76 
77## Development
78 
79```bash
80# Run the dev sandbox
81cd examples/getstarted
82yarn develop                  # SQLite (default)
83 
84# Start non-memory databases (postgres/mysql)
85docker-compose -f docker-compose.dev.yml up -d
86DB=postgres yarn develop      # PostgreSQL
87DB=mysql yarn develop         # MySQL
88 
89# Watch all packages + run sandbox with admin watch (two terminals)
90yarn watch                                           # terminal 1, repo root
91cd examples/getstarted && yarn develop --watch-admin # terminal 2
92```
93 
94---
95 
96## Build
97 
98```bash
99yarn build              # all packages (code + types)
100yarn build:code         # faster — skips .d.ts generation
101yarn nx build @strapi/admin   # single package
102```
103 
104---
105 
106## Testing
107 
108### Unit tests (fastest — run first)
109 
110Unit test files live in `__tests__/` subdirectories within each package.
111 
112```bash
113yarn test:unit
114yarn test:unit:watch
115yarn test:unit:update         # update snapshots
116```
117 
118### Frontend tests (admin panel)
119 
120Frontend test files also live in `__tests__/` within their respective packages.
121 
122```bash
123yarn test:front              # runs with IS_EE=true (EE features enabled)
124yarn test:front:ce           # runs with IS_EE=false (Community Edition only)
125yarn test:front:update       # update snapshots (EE)
126yarn test:front:update:ce    # update snapshots (CE)
127```
128 
129### Type checking
130 
131```bash
132yarn test:ts                 # all packages + front + back
133```
134 
135### API integration tests
136 
137Integration 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).
138 
139```bash
140yarn test:api                # SQLite
141yarn test:api --db=postgres
142yarn test:api --db=mysql
143yarn test:api -u             # update snapshots
144```
145 
146### CLI tests
147 
148CLI tests live in `tests/cli/`.
149 
150```bash
151yarn test:cli
152yarn test:cli:debug          # with debug output
153yarn test:cli:update         # update snapshots
154```
155 
156### E2E tests (Playwright)
157 
158E2E tests live in `tests/e2e/tests/` organized by domain (e.g. `admin`, `content-manager`, `i18n`).
159 
160```bash
161yarn playwright install                          # one-time browser install
162yarn test:e2e --setup --concurrency=1            # run all domains sequentially
163yarn test:e2e --domains content-manager admin    # run specific domains only
164yarn test:e2e --concurrency=3                    # run 3 domains in parallel
165```
166 
167### EE toggles
168 
169- `IS_EE=true` — enables Enterprise features in frontend tests (`yarn test:front`)
170- `RUN_EE=true` — enables Enterprise features in E2E tests
171 
172### Pre-PR checklist
173 
174All tests must pass before merging. Run at minimum:
175 
176```bash
177yarn test:unit && yarn test:front && yarn test:ts && yarn lint && yarn prettier:check
178```
179 
180E2E (`yarn test:e2e`) is required per CONTRIBUTING.md but slow — CI enforces it on every PR.
181 
182**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.
183 
184---
185 
186## Quality Gates
187 
188### Commits
189 
190Must follow [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) (enforced by Husky `commit-msg` hook and CI via `commitlint`). Format:
191 
192```
193<type>(<optional-scope>): <description>
194```
195 
196Valid types: `feat` `fix` `chore` `ci` `docs` `enhancement` `test` `revert` `security` `future` `release`
197 
198**Examples:**
199 
200```bash
201feat(content-manager): add bulk delete action
202fix(database): preserve relation order during publish
203chore(admin): migrate data-fetching to react-query
204```
205 
206Use `yarn commit` for an interactive prompt. Run `yarn version:check` if you've touched any `package.json`.
207 
208### TypeScript
209 
210- Import types from `@strapi/types` — extend or improve them rather than duplicating locally.
211- Never use `any` when a proper type exists or can be reasonably defined. Prefer `unknown` otherwise.
212- Run `yarn test:ts` before pushing.
213 
214### Linting & Formatting
215 
216```bash
217yarn lint           # ESLint across all packages
218yarn lint:fix       # auto-fix
219yarn format         # Prettier (2-space indent, single quotes, semicolons, trailing commas, arrow parens, 100-char width, LF)
220yarn prettier:check # check only
221```
222 
223---
224 
225## Security
226 
227- Never commit secrets, credentials, or API keys.
228- Never disable or weaken authentication/authorization checks.
229- Use parameterized queries — never interpolate user input into raw SQL or database queries.
230- Validate and sanitize all user input at controller/service boundaries.
231- When working with EE-gated features, do not bypass license checks.
232 
233---
234 
235## PR Guidelines
236 
237- Branch from `develop`, target `develop` — never `main`.
238- Link the issue you're fixing in the description.
239- All tests must pass before merging.
240- PR description must follow [.github/PULL_REQUEST_TEMPLATE.md](.github/PULL_REQUEST_TEMPLATE.md) — do not invent your own sections.
241 
242---
243 
244## Notes for Agents
245 
246- **`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.
247- **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.
248- **Entity Service is deprecated** — always use the Document Service (`strapi.documents`) for content operations.
249- **Lifecycle phases** — `strapi.isLoaded` must be `true` before accessing services. Plugins and DB are not available until after the `load()` phase.
250