agentleFS
notum-cznotum-cz/strapi-next-monorepo-starter/.claude/skills/create-content-component/SKILL.md

create-content-component

Skill316 starsChanged 5 months agoMITView on GitHub

Use when adding a new CMS-driven page section that lives in the page builder's dynamic zone — e.g. "add page component", "new page section", "page builder component", "create content component", "add section", "new strapi component". Not for top-level API resources (use `add-content-type`) or generic React components (use `add-ui-component`).

The file

We split this skill into the rules it gives an agent

12 rules. About 0 are common, 8 are distinctive, and 4 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈8

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 4

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Add a new page-builder section to both Strapi (component schema + dynamic-zone entry) and the Next.js frontend (React component + mapping), …

    line 19
  2. Distinctive:

    If unsure, ask the user before scaffolding.

    line 28
  3. Very specific:

    Not sure whether a similar section already exists (by purpose, attributes, or a screenshot)?

    line 41
  4. Distinctive:

    If anything matches, ask the user whether to rename or extend.

    line 48
  5. Very specific:

    Follow workflow.md for the full step-by-step.

    line 64
  6. Distinctive:

    Run schema check before opening the PR:

    line 73
  7. Distinctive:

    Renaming or deleting an existing field: instead of adding alongside — Strapi auto-syncs to DB and drops the column.

    line 81
  8. Distinctive:

    After you add a Strapi component and its frontend React implementation, add a mocked wrapper so the component is visible in the dev …

    line 120
  9. Distinctive:

    Create a mocked file

    line 124
  10. Distinctive:

    Import the mocked file:

    line 146
  11. Very specific:

    Add an entry to the showcaseItems array with kind: "component", component: MockedStrapiMyComponent, id, label and description.

    line 150
  12. Distinctive:

    Keep mock objects minimal but representative.

    line 155

≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Create a Page-Builder Content Component

Add a new page-builder section to both Strapi (component schema + dynamic-zone entry) and the Next.js frontend (React component + mapping), ending with type regeneration. Population is automatic via the smart-populate plugin — see apps/docs/docs/strapi/plugins/smart-populate.md.

Routing — which skill do you actually want?

  • This skill (create-content-component) — Strapi-driven page section, built from an explicit attribute spec.
  • copy-component — replicate a section from a reference (description, screenshot, or HTML/code); it derives the spec and delegates here.
  • add-content-type — needs its own DB table + REST endpoint (Article, Product, etc.).
  • add-ui-component — generic React UI (Button, Container) not driven by Strapi data.

If unsure, ask the user before scaffolding.

Inputs

  • Name — kebab-case, lowercase (e.g. pricing-table). Reject Pascal/camelCase.
  • Category — lowercase, no spaces. Existing under apps/strapi/src/components/: elements, forms, layout, sections, seo-utilities, shared, utilities. Create the dir before the schema if new.
  • Attributes — fields the component needs.
  • Admin icon — set info.icon to a representative name from references/strapi-icons.txt (optional but recommended; vary it per component).
  • Rich text? — two editors are available, CKEditor and TipTap. Reuse a utilities.* rich-text component, or declare the matching customField — never raw richtext. See examples.md (Rich text).
  • Relation needing specific fields? — components are populated automatically by smart-populate; only relations that need extra fields/depth require a populateOverrides entry (Procedure step 3).

Duplication check

Not sure whether a similar section already exists (by purpose, attributes, or a screenshot)? Run find-component first — reuse or extend beats duplicating. Quick name check:

ls apps/strapi/src/components/<category>/<name>.json 2>/dev/null
find apps/ui/src/components/page-builder/components -iname "Strapi*<PascalName>*"

If anything matches, ask the user whether to rename or extend.

Naming reference

Given category=sections, name=testimonials:

ArtifactValue
Strapi UIDsections.testimonials
Strapi schema fileapps/strapi/src/components/sections/testimonials.json
collectionNamecomponents_sections_testimonials (format: components_<category>_<name_underscored>)
React componentStrapiTestimonials (prefix Strapi + PascalCase)
React fileapps/ui/src/components/page-builder/components/sections/StrapiTestimonials.tsx

Procedure

Follow workflow.md for the full step-by-step. The high-level sequence:

  1. Strapi schema — create apps/strapi/src/components/<category>/<name>.json (see examples.md for attribute patterns).
  2. Register in Page dynamic zone — append the new UID to attributes.content.components in apps/strapi/src/api/page/content-types/page/schema.json.
  3. Population (usually nothing to do) — the page fetch uses content: "smart", so the smart-populate plugin auto-populates the component's nested components/media/relations from its schema. Only add a populateOverrides entry in apps/strapi/config/plugins/smart-populate.ts if a relation needs specific fields or extra depth.
  4. React component — apps/ui/src/components/page-builder/components/<category>/Strapi<PascalCaseName>.tsx.
  5. Register in PageContentComponents — apps/ui/src/components/page-builder/index.tsx.
  6. Regenerate types — pnpm --filter @repo/strapi generate:types.

Run schema check before opening the PR:

bash .claude/skills/strapi-schema-check/scripts/check.sh

Common mistakes

  • Renaming or deleting an existing field instead of adding alongside — Strapi auto-syncs to DB and drops the column. Run schema check first.
  • Hand-writing a populate tree — smart-populate (content: "smart") handles nested components automatically; don't add manual populate objects unless a relation needs specific fields, and then only via populateOverrides.
  • Using raw richtext — use a rich-text customField (CKEditor or TipTap), or reuse a utilities.* rich-text component; see examples.md (Rich text).
  • Pascal/camelCase component names — Strapi UIDs must be kebab-case.
  • Skipping type regeneration — Data.Component<"<category>.<name>"> won't resolve.
  • Forgetting import "server-only" — every shipped page-builder section has it; without it, a future client import silently turns the section into a client component.
  • Typing props as { readonly component: ... } only — codebase convention is PageBuilderComponentProps & { component: Data.Component<...> }; the extra props are page-level context other sections rely on.
  • Picking the wrong category for a repeatable child component — shared/ is for repeatable "row" components shared across sections (shared.figure, shared.image-with-title-and-description); utilities/ is for primitives reused everywhere (utilities.link, utilities.basic-image, utilities.ck-editor-content). Match the closest existing pattern; don't invent a new category.
  • Hardcoding UI copy — strings like "/month", "Most popular", "Choose plan" go in apps/ui/locales/. Strapi-driven copy comes from the schema; static UI labels come from i18n.
  • Gold-plating the schema — only add fields the task actually asks for. Optional extras (CTA buttons, "highlighted" toggles, billing-period switches) inflate the schema and the migration risk surface; add them in a follow-up if needed.
  • Repeatable scalars — Strapi has no "repeatable string" type. A list of bullet strings needs either a child component with a single text field (reuse utilities.text if it fits) or, if richer per-row state is needed, a small new component.

Verify

  1. pnpm --filter @repo/strapi dev — boots clean (no schema error on new component).
  2. Admin → Pages → add the new component to a dynamic zone → publish.
  3. pnpm --filter @repo/ui dev — render → confirm data flows through.
  4. pnpm --filter @repo/ui exec tsc --noEmit — clean.
  5. bash .claude/skills/strapi-schema-check/scripts/check.sh — additive UID only.

Checklist

  • Strapi schema created with correct collectionName
  • UID registered in Page's content dynamic zone
  • populateOverrides entry added only if a relation needs specific fields (most components need none)
  • React component with Strapi prefix + named + default exports
  • Mapped in PageContentComponents
  • pnpm --filter @repo/strapi generate:types ran clean
  • Strapi boots, component renders with real data, tsc --noEmit clean
  • strapi-schema-check passes

Notes

  • No regional wrappers. Single-region starter — skip the per-region wrapper pattern.
  • No Storybook. Visual review via dev server or Playwright visual tests.
  • Page schema is high-risk. Any rename/delete on apps/strapi/src/api/page/content-types/page/schema.json triggers column drops on boot. Add-only on the dynamic-zone array is safe.

Mocking & Showcase

After you add a Strapi component and its frontend React implementation, add a mocked wrapper so the component is visible in the dev Showcase.

The workflow is simplified: mocked files should export a single default component and should not use ManualSection / ManualItem wrappers — the Showcase reads showcaseItems.tsx and renders the component directly.

  1. Create a mocked file

    • Path: apps/ui/src/app/[locale]/dev/showcase/components/strapiComponents/MockedStrapi{PascalName}.tsx
    • Export default MockedStrapi{PascalName} which renders the production Strapi{PascalName} with a data object typed as Data.Component<"{category}.{name}">.

    Example:

import type { Data } from "@repo/strapi-types"
import StrapiMyComponent from "@/components/page-builder/components/sections/StrapiMyComponent"

const data = {
  id: 1,
  __component: "sections.my-component",
  /* attributes */
} as unknown as Data.Component<"sections.my-component">

export default function MockedStrapiMyComponent() {
  return <StrapiMyComponent component={data} />
}
  1. Register in showcaseItems.tsx
    • Import the mocked file:

      import MockedStrapiMyComponent from "@/app/[locale]/dev/showcase/components/strapiComponents/MockedStrapiMyComponent"

    • Add an entry to the showcaseItems array with kind: "component", component: MockedStrapiMyComponent, id, label and description.
  2. Attribute tips
    • Rich-text mock values match how the field is stored: an HTML string for CKEditor fields, ProseMirror JSON for TipTap fields (see examples.md).
    • For images/icons reuse mockImage / mockIcon from the dev showcase helpers.
    • Keep mock objects minimal but representative.

See apps/docs/docs/ui/built-in-pages/showcase.md for full examples and conventions.

See also

  • workflow.md — full per-phase procedure with code blocks
  • examples.md — attribute patterns, rich-text editors (CKEditor + TipTap), override shapes
  • references/strapi-icons.txt — valid info.icon names for the admin builder
  • add-content-type — when the new thing should be a top-level API resource
  • add-ui-component — generic UI primitives
  • vercel-react-best-practices / next-best-practices / frontend-design — vendored React/Next.js + design standards for the component's frontend (in .agents/skills/)
  • strapi-schema-check — pre-PR schema risk validation
  • apps/docs/docs/page-builder/introduction.md — architecture overview, naming conventions, component props
  • apps/docs/docs/strapi/plugins/smart-populate.md — automatic population + populateOverrides

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.