cms-component-builder

Build production-ready Optimizely CMS components with proper GraphQL integration, daisyUI styling, and TypeScript type safety.

When to Use This Skill

ALWAYS use this skill when the user asks to:

• Create a new component, page, or experience (e.g., "create a testimonial component", "add a new page type")
• Modify or update .opti-type.json files (content type definitions)
• Modify or update .opti-style.json files (style/display template definitions)
• Create or modify GraphQL fragments (.graphql or .dam.graphql files)
• Add components to allComponents.graphql or similar aggregation files
• Debug component rendering issues
• Fix GraphQL type errors related to components
• Push/sync content types or styles to the CMS
• Understand how the component system works

Critical Instructions

YOU MUST FOLLOW THESE STEPS IN ORDER:

1. READ THE GUIDES FIRST - This skill includes comprehensive guides that YOU MUST reference:

   • CONTENTTYPE-GUIDE.md - For creating .opti-type.json files
   • STYLE-GUIDE.md - For creating .opti-style.json files
   • GRAPHQL-PATTERNS.md - For creating .graphql and .dam.graphql files

2. EXAMINE EXISTING COMPONENTS - Always look at similar existing components as examples before creating new ones. Check src/cms/components/ for patterns.

3. CREATE ALL REQUIRED FILES - A complete component needs 5 files minimum:

   • .astro - Component template with TypeScript
   • .opti-type.json - Content type definition
   • .opti-style.json - Style definition(s) (can have multiple)
   • .graphql - Base GraphQL fragment
   • .dam.graphql - DAM-enabled GraphQL fragment

4. INTEGRATE PROPERLY - After creating files:

   • Add fragment to src/cms/components/allComponents.graphql
   • Push to CMS: yarn type:push ComponentName and yarn style:push StyleName
   • Wait 10 seconds for Optimizely Graph sync
   • Generate types: yarn codegen

Quick Start Example

Creating a new "Testimonial" component:

# 1. Create component directory
mkdir -p src/cms/components/TestimonialComponent

# 2. Create required files
src/cms/components/TestimonialComponent/
├── Testimonial.astro              # Component template
├── Testimonial.opti-type.json     # Content type definition
├── DefaultTestimonial.opti-style.json  # Default style
├── testimonial.graphql            # Base GraphQL fragment
└── testimonial.dam.graphql        # DAM GraphQL fragment

Required Files Explained

Every component needs at least 5 files:

1. .astro - Component Template

IMPORTANT: Always follow the pattern from existing components like Button.astro

---
import type {
    TestimonialFragment,
    DisplaySettingsFragment,
} from '../../../../__generated/sdk';
import type { ContentPayload } from '../../../graphql/shared/ContentPayload';
import { isEditContext } from '../../shared/utils.ts';

const isCmsEdit = isEditContext(Astro.url);

export interface Props {
    key: string;
    data: TestimonialFragment;
    displaySettings: DisplaySettingsFragment[];
    displayTemplateKey: string;
    contentPayload: ContentPayload;
}

const { key, data, displaySettings, displayTemplateKey, contentPayload } = Astro.props as Props;

// Your styling logic here - reference STYLE-GUIDE.md
const componentClass = 'component-testimonial';
---

<div data-epi-block-id={isCmsEdit && key || undefined} class={componentClass}>
    <div class="card bg-base-100 shadow-xl">
        <div class="card-body">
            <p class="text-lg italic" set:html={data.Quote?.html}></p>
            <div class="card-actions justify-end">
                <p class="font-bold">{data.Author}</p>
            </div>
        </div>
    </div>
</div>

Key Points:

• Import types from __generated/sdk (NOT from @/graphql/__generated/graphql)
• Include ALL required props: key, data, displaySettings, displayTemplateKey, contentPayload
• Use data-epi-block-id for CMS editing context
• Use set:html for rich text fields
• Add a component class for CSS targeting

2. .opti-type.json - Content Type

See CONTENTTYPE-GUIDE.md for complete guide on creating content types.

3. .opti-style.json - Style Definitions

See STYLE-GUIDE.md for complete guide on creating style definitions.

4. .graphql + .dam.graphql - GraphQL Fragments

ALWAYS create both versions. See GRAPHQL-PATTERNS.md for complete details.

Base (testimonial.graphql):

fragment Testimonial on Testimonial {
    Quote { html }
    Author
    AuthorTitle
    AuthorImage {
        ...ContentUrl
    }
}

DAM (testimonial.dam.graphql):

fragment Testimonial on Testimonial {
    Quote { html }
    Author
    AuthorTitle
    AuthorImage {
        ...ContentUrl
        ...ContentReferenceItem
    }
}

Component Integration

1. Add to allComponents.graphql

fragment AllComponentsExceptGrid on _IComponent {
    ...Text
    ...Button
    ...Testimonial  # Add your component here
}

Important: Add to AllComponentsExceptGrid, NOT AllComponents

2. Sync to CMS & Generate Types

# Push content type and styles to CMS
yarn type:push ComponentName
yarn style:push StyleName

# ⚠️ Wait ~10 seconds for Optimizely Graph to sync

# Then generate TypeScript types
yarn codegen

3. Verify Integration

Check __generated/graphql.ts for your component type.

Component Locations

• Components: src/cms/components/ - Reusable UI (Button, Card, Hero)
• Pages: src/cms/pages/ - Page types (ArticlePage, LandingPage)
• Experiences: src/cms/experiences/ - Experience templates
• Compositions: src/cms/compositions/ - Layout elements (Row, Column)

GraphQL Shared Fragments

Quick reference (full details in GRAPHQL-PATTERNS.md):

• LinkUrl - Links with url, title, target, text
• ContentUrl - Content reference URLs
• LinkCollection - Simple link arrays
• ContentReferenceItem - DAM metadata (.dam.graphql only)
• DisplaySettings - Display/styling settings
• PageUrl - Page metadata

Rich text fields: Always use { html }:

Body { html }
Description { html }

Styling with daisyUI + TailwindCSS

Prefer daisyUI components:

<button class="btn btn-primary btn-lg">
<div class="card card-compact">
<div class="hero min-h-screen">

Use theme variables:

<div class="bg-base-100 text-base-content">

Mobile-first responsive:

<div class="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3">

Complete Workflow (FOLLOW IN ORDER)

Step 1: Research & Planning

1. Ask the user for requirements: What should this component do? What properties does it need?
2. Find similar components: Use Glob to find similar components in src/cms/components/
3. Read example files: Study at least one similar component to understand the patterns

Step 2: Create Component Files

Create the component directory and all required files:

mkdir -p src/cms/components/ComponentNameComponent
cd src/cms/components/ComponentNameComponent

Create these files in order:

1. ComponentName.opti-type.json - Content type definition

   • Reference CONTENTTYPE-GUIDE.md for structure
   • Look at similar component's .opti-type.json as example
   • Set baseType: "component" for components
   • Set compositionBehaviors: ["elementEnabled"] for components usable in visual editor

2. DefaultComponentName.opti-style.json - Default style template

   • Reference STYLE-GUIDE.md for structure
   • Set contentType to match your component's key
   • Set isDefault: true for the default style
   • Create meaningful display settings with choices

3. componentName.graphql - Base GraphQL fragment

   • Reference GRAPHQL-PATTERNS.md
   • Fragment name must match component name (PascalCase)
   • Include all properties from .opti-type.json
   • Use shared fragments: ...LinkUrl, ...ContentUrl, etc.

4. componentName.dam.graphql - DAM-enabled GraphQL fragment

   • Copy from componentName.graphql
   • Add ...ContentReferenceItem to content references
   • This enables DAM metadata for images/videos

5. ComponentName.astro - Component template

   • Follow the pattern from existing components (see example above)
   • Import types from __generated/sdk
   • Include all required props
   • Handle display settings for styling
   • Use daisyUI classes for styling

Step 3: Integrate with System

1. Add to allComponents.graphql

   # src/cms/components/allComponents.graphql
   fragment AllComponentsExceptGrid on _IComponent {
       ...ExistingComponent
       ...YourNewComponent  # Add this line
   }
   

2. Push to CMS

   # Push content type
   yarn type:push ComponentName
   
   # Push style template
   yarn style:push DefaultComponentName
   
   # ⚠️ CRITICAL: Wait 10-15 seconds for Optimizely Graph to sync
   

3. Generate TypeScript Types

   # After waiting for Graph sync
   yarn codegen
   

Step 4: Verify & Test

1. Check generated types in __generated/sdk.ts:

   • Look for ComponentNameFragment type
   • Verify all properties are present

2. Check for TypeScript errors:

   yarn tsc --noEmit
   

3. Test in dev server:

   yarn dev
   

4. Verify in CMS:

   • Component appears in CMS UI
   • All properties are editable
   • Style options work correctly

Verification Checklist

YOU MUST CHECK ALL OF THESE before completing:

• ✓ All 5 required files created:

  • ComponentName.astro
  • ComponentName.opti-type.json
  • DefaultComponentName.opti-style.json
  • componentName.graphql
  • componentName.dam.graphql

• ✓ Content type (.opti-type.json) is valid:

  • Has key, displayName, baseType
  • All properties defined correctly
  • Uses correct property types

• ✓ Style template (.opti-style.json) is valid:

  • Has key, displayName, contentType
  • contentType matches component key
  • Has isDefault: true for default style
  • All settings have choices

• ✓ Both GraphQL fragments created:

  • .graphql for base version
  • .dam.graphql with ...ContentReferenceItem for DAM

• ✓ Fragment added to allComponents.graphql:

  • Added to AllComponentsExceptGrid (NOT AllComponents)

• ✓ Pushed to CMS successfully:

  • yarn type:push ComponentName completed
  • yarn style:push StyleName completed
  • Waited 10-15 seconds for Graph sync

• ✓ Types generated successfully:

  • yarn codegen completed without errors
  • ComponentNameFragment type exists in __generated/sdk.ts

• ✓ Component template (.astro) follows patterns:

  • Imports from __generated/sdk
  • Has all required props
  • Uses data-epi-block-id for CMS editing
  • Uses daisyUI classes for styling
  • Handles display settings

• ✓ No TypeScript errors:

  • yarn tsc --noEmit passes

• ✓ Component works in dev server:

  • yarn dev runs without errors

Resources

All guides are bundled with this skill for quick reference:

• GraphQL Patterns: See GRAPHQL-PATTERNS.md for:

  • Complete fragment syntax and structure
  • DAM vs non-DAM differences
  • Real-world examples from existing components
  • Shared fragment catalog
  • Integration patterns

• Content Type Creation: See CONTENTTYPE-GUIDE.md for:

  • Content type structure and syntax
  • Property definitions and types
  • Display settings configuration
  • Real-world examples

• Style Creation: See STYLE-GUIDE.md for:

  • Style definition structure
  • Display settings mapping to CSS classes
  • daisyUI and TailwindCSS patterns
  • Responsive variants

Common Patterns

Component with links:

Links {
    ...LinkCollection
}

Component with images:

# Base
Image {
    ...ContentUrl
}

# DAM
Image {
    ...ContentUrl
    ...ContentReferenceItem
}

Component with metadata:

_metadata {
    types
    displayName
}

Common Issues & Troubleshooting

Issue: GraphQL fragment not found after codegen

Solution:

1. Check that fragment is added to allComponents.graphql
2. Ensure you pushed to CMS: yarn type:push ComponentName
3. Wait 10-15 seconds for Optimizely Graph to sync
4. Run yarn codegen again

Issue: TypeScript errors in .astro file

Solution:

1. Verify imports are from __generated/sdk not @/graphql/__generated/graphql
2. Check that all Props interface fields are present
3. Run yarn codegen to regenerate types
4. Check that fragment name matches component name exactly (case-sensitive)

Issue: Component doesn't appear in CMS

Solution:

1. Verify yarn type:push ComponentName completed successfully
2. Check that baseType is set correctly in .opti-type.json
3. Check that compositionBehaviors: ["elementEnabled"] is set
4. Clear CMS cache and refresh

Issue: Display settings not working

Solution:

1. Verify yarn style:push StyleName completed successfully
2. Check that contentType in .opti-style.json matches component key
3. Ensure isDefault: true is set for default style
4. Verify style mapping exists in component's styling helper file

Issue: Rich text fields not rendering HTML

Solution:

1. Use set:html={data.FieldName?.html} instead of {data.FieldName.html}
2. Ensure GraphQL fragment requests { html } for rich text fields

Issue: Content references (images/videos) not loading

Solution:

1. Check GraphQL fragment includes ...ContentUrl
2. For DAM assets, verify .dam.graphql includes ...ContentReferenceItem
3. Check that url?.default or url?.hierarchical is used in template

Pages and Experiences

This skill also handles Pages and Experiences, which follow the same patterns:

Pages (src/cms/pages/):

• Set baseType: "Page" instead of "Component"
• Include SEO settings and page admin settings
• Add to appropriate page aggregation file
• May include mayContainTypes for content areas

Experiences (src/cms/experiences/):

• Define experience templates
• Include composition structure
• Reference Row, Column, and Section compositions

Using Svelte 5 for Interactive Components

This project uses Svelte 5 (latest version with runes) for client-side interactivity. Svelte components are primarily used for admin/utility interfaces, NOT for CMS components.

When to Use Svelte

Use Svelte for:

• Admin interfaces (like /opti-admin pages)
• Interactive forms and utilities
• Complex client-side state management
• Real-time features (SSE, WebSockets)

DO NOT use Svelte for:

• CMS components (use .astro instead)
• Content rendering from Optimizely
• SEO-critical content

Svelte 5 Key Patterns

State Management with Runes:

<script lang="ts">
    // Props using $props() rune
    interface Props {
        title: string;
        count?: number;
    }
    let { title, count = 0 }: Props = $props();

    // Reactive state using $state() rune
    let currentCount = $state(0);
    let isLoading = $state(false);

    // Derived state using $derived rune
    let doubleCount = $derived(currentCount * 2);

    // Side effects using $effect rune
    $effect(() => {
        console.log('Count changed:', currentCount);
    });

    // Functions
    function increment() {
        currentCount++;
    }
</script>

<div>
    <h1>{title}</h1>
    <p>Count: {currentCount}</p>
    <p>Double: {doubleCount}</p>
    <button onclick={increment}>Increment</button>
</div>

Important Svelte 5 Changes:

• Use $props() instead of export let
• Use $state() instead of let for reactive variables
• Use $derived instead of $: for computed values
• Use $effect() instead of $: for side effects
• Use onclick={} instead of on:click={}
• Use bind:value={} for two-way binding

Example: Admin Component with TypeScript

See src/pages/opti-admin/components/_CmsSync.svelte for a complete example showing:

• TypeScript interfaces with Props
• State management with $state() and $derived
• Event handling with EventSource (SSE)
• Lifecycle with onMount()
• Conditional rendering with {#if}
• List rendering with {#each}

Embedding Svelte in Astro

---
// MyPage.astro
import MyCoolComponent from './_components/MyCoolComponent.svelte';

const someData = { title: 'Hello', count: 5 };
---

<div>
    <MyCoolComponent client:load title={someData.title} count={someData.count} />
</div>

Client Directives:

• client:load - Load immediately on page load
• client:idle - Load when browser is idle
• client:visible - Load when component is visible
• client:only="svelte" - Only run on client, no SSR

---

Remember: Every component must be production-ready with:

• Complete integration into the system
• Proper TypeScript types
• Consistent daisyUI styling
• Both GraphQL fragment versions (.graphql and .dam.graphql)
• Comprehensive verification before completion