#Block Creation Checklist

Use this checklist when creating a new block for multi-store.

---

#Phase 1: Planning

• Block Name - Finalized and unique slug (e.g., my-awesome-block)
• Block Purpose - Clear description of what it displays/does
• Collections - Confirmed where it will be used (Pages, Shop, Products)
• Field Design - Documented all fields with types and descriptions
• Visual Reference - Understood how it should render

---

#Phase 2: File Creation

• Created directory: apps/multi-store/src/blocks/MyBlock/

• Created config.ts with Block definition:

  • Unique slug property
  • Proper interfaceName for TypeScript
  • labels.singular and labels.plural
  • All required fields array
  • Conditional fields use correct condition functions

• Created Component.tsx with React component:

  • Receives correct props from config
  • Includes disableInnerContainer prop
  • Includes unique key with block id
  • Handles missing/empty data gracefully
  • Exports properly typed component

---

#Phase 3: Registration

• Added import to /apps/multi-store/src/blocks/RenderBlocks.tsx:

  import { MyBlockComponent } from "@/blocks/MyBlock/Component";
  import { MyBlock } from "@/blocks/MyBlock/config";
  

• Added to blockComponents object in RenderBlocks.tsx:

  "my-block": MyBlockComponent,
  

---

#Phase 4: Collection Integration

Choose one or more:

#Option A: Add to Pages (via contentTabField)

• Imported block in collections/contentTabField.ts:

  import { MyBlock } from "@/blocks/MyBlock/config";
  

• Added to blocks array in contentTabField.ts

#Option B: Add to Shop Global

• Imported block in globals/Shop/config.ts:

  import { MyBlock } from "@/blocks/MyBlock/config";
  

• Added to appropriate blocks array (shopHome, productPages, etc.)

#Option C: Add to Products

• Imported block in collections/contentTabField.ts
• Added to blocks array for product-specific section

---

#Phase 5: TypeScript & Verification

• Ran bun run lint:check - no errors
• Ran bun run lint - auto-fixed all issues
• Ran bun run gen - generated types successfully
• Component TypeScript props match generated {BlockName}Props interface

---

#Phase 6: Testing

#Admin UI

• Logged into Payload admin
• Navigated to collection using the block
• Block appears in the blocks selector
• All fields render correctly
• Conditional fields show/hide as expected
• Can add/remove block instances

#Data Persistence

• Added block with test data
• Saved the document
• Refreshed page - block data persists
• Can edit block fields and save

#Frontend Rendering

• Navigated to page with the block
• Block renders without errors
• Content displays correctly
• Responsive on mobile/tablet
• Links/interactions work if applicable

---

#Phase 7: Documentation

• Added block to documentation:

  • Section in BLOCKS_SYSTEM_GUIDE.md if complex
  • Listed in "Block Categories" section
  • Added example config if helpful

• Documented in code:

  • JSDoc comments for Component props
  • Descriptions for complex fields in config
  • Field validation rules documented

---

#Phase 8: Final Review

• All files formatted (Biome check passes)
• No console errors in dev tools
• No TypeScript errors
• Block works in all target collections
• Responsive design verified
• Edge cases handled (empty data, long text, etc.)

---

#Quick Verification Commands

# Check formatting
bun run lint:check

# Auto-fix any issues
bun run lint

# Generate types
bun run gen

# Build to verify compilation
bun run build --filter multi-store

---

#Common Block Field Patterns

#Pattern 1: Text + Rich Text

fields: [
  { name: "title", type: "text", required: true },
  { name: "content", type: "richText", editor: lexicalEditor() },
]

#Pattern 2: Image + Text

fields: [
  { name: "image", type: "upload", relationTo: "media" },
  { name: "alt", type: "text", label: "Alt Text" },
  { name: "title", type: "text" },
]

#Pattern 3: Repeating Items

fields: [
  {
    name: "items",
    type: "array",
    fields: [
      { name: "title", type: "text" },
      { name: "description", type: "text" },
    ],
  },
]

#Pattern 4: Conditional Fields

fields: [
  { name: "showAdvanced", type: "checkbox", defaultValue: false },
  {
    name: "advancedOption",
    type: "text",
    admin: { condition: (_, data) => data.showAdvanced },
  },
]

#Pattern 5: Styled Variants

fields: [
  {
    name: "variant",
    type: "select",
    defaultValue: "default",
    options: [
      { label: "Default", value: "default" },
      { label: "Primary", value: "primary" },
      { label: "Secondary", value: "secondary" },
    ],
  },
]

---

#When Creating the Block

Tell me:

1. Block name - What's it called?
2. Purpose - What does it display?
3. Fields - What data inputs needed?
4. Collections - Where should it appear?
5. Any special features - Conditional fields, complex logic, etc.

Then I'll create: ✅ Complete config file with all fields ✅ React component with proper typing ✅ Integration into RenderBlocks ✅ Collection registration ✅ Full verification (linting, types, formatting)

Ready? 🚀