Imported from wumin198812/Strapi-website (AGENTS.md). Install upstream with npx skills add wumin198812/Strapi-website. Copyright stays with the author.

Strapi + Next.js Monorepo

Monorepo starter with Strapi v5 CMS and Next.js 16 frontend. Uses pnpm workspaces with Turborepo.

Core instructions

• Save any screenshots or tmp files to tmp/
• When updating skills ALWAYS update skills in .agents/ folder, no the ones in agent specific folders like .claude/

Code style

• Always use interface for prop types with extend ComponentProps<"div"> where applicable
• Never use one-line if, if-else or else branches, always wrap its content in curly braces

Workspaces

Essential Commands

pnpm dev              # Start both apps (Docker required for DB)
pnpm build            # Build all
pnpm lint             # ESLint all packages
pnpm typecheck        # Typecheck (run from apps/ui)

See docs/commands.md for full command reference.

Type Generation (Critical)

After ANY Strapi schema change, run this immediately and autonomously — do not ask the user first:

cd apps/strapi && pnpm generate:types

This updates @repo/strapi-types. Forgetting causes silent type mismatches between apps.

generate:types is a one-shot script, not a long-running server — it is safe to run at any time. If the command fails, block the current task and ask the user to restart Strapi, then re-run it.

Documentation

• Commands Reference — All pnpm commands
• Architecture — System design and patterns
• Page Builder — Component registry and rendering
• Strapi API Client — Fetching content from Strapi
• Pages Hierarchy — URL structure and redirects
• Strapi Schemas — Schema attributes, localization, lifecycle hooks
• Strapi Types — Type utilities and usage patterns

Running Services

Never launch dev servers (pnpm dev, strapi develop, next dev) in the background. These spawn long-running processes that are hard to kill from within the agent.

Strapi Data Safety

Dynamic zone writes — merge, never replace

Strapi PUT requests replace the entire field value. Always GET first, append, then PUT.

// WRONG — wipes existing content
PUT { "data": { "content": [{ "__component": "sections.new", ... }] } }

// RIGHT — preserves existing
GET → content = [{ existing1 }, { existing2 }]
PUT { "data": { "content": [{ existing1 }, { existing2 }, { "__component": "sections.new", ... }] } }

Commits

Uses conventional commits enforced by Husky + commitlint.

pnpm commit

Or write manually: type(scope): subject