Vue Storefront is now Alokai! Learn More
CMS Schema Creation Guide

CMS Schema Creation Guide

Overview

Create CMS content type schemas that match Alokai component interfaces. This allows content editors to build pages by selecting and configuring pre-built components (like Hero, Banner, Gallery) without requiring developer involvement for each page change.

Why this matters: Instead of hardcoding pages, content editors can mix and match components to create dynamic layouts while maintaining consistent styling and functionality.

Core Requirements

Content Types Needed:

  1. Page Type: Contains componentsAboveFold and componentsBelowFold arrays
  2. Component Types: One for each Alokai component you want to use
  3. Styling Support: Enable layout customization for all components

Styling Approach

Choose based on your CMS capabilities:

  • Built-in Styling: Use native CMS tools (Builder.io, Webflow, Framer)
  • Custom Styles Field: Create responsive breakpoint system for other platforms

Component Requirements

Check component props: Examine apps/storefront-unified-nextjs/components/cms/page/ (or /nuxt/ for Nuxt projects) to understand the exact props each component expects.

Common field types:

  • Text fields: title, subtitle, description
  • Media fields: image, backgroundImage (with responsive variants)
  • Action fields: button, buttonA, buttonB (with label and link)
  • Content arrays: items, images (for components that display multiple pieces of content)
  • Configuration: allowMultipleOpen, placeholder (component-specific settings)

Implementation Steps

1. Set Up Styling System

For CMS with built-in styling (Builder.io, Webflow, Framer):

  • Use native responsive breakpoint tools
  • Configure spacing and color presets
  • Enable visual styling for all components

For other CMS platforms, create a reusable styles structure for dynamic styling:

Understanding the Styling System

When you create content in your CMS with styles, those styles get processed during data normalization in normalizers.ts. Unified CMS extension uses a resolveStyles function to convert your CMS styles data into actual CSS that gets injected into the page.

Here's how it works:

  1. CMS: You define styles in your content (positioning, spacing, etc.)
  2. Normalizers: The resolveStyles function processes your styles data
  3. Frontend: Generated CSS is injected with unique class names and media queries

Example of what gets generated:

@media (min-width: 768px) and (max-width: 1024px) {
  .cms-component-abc123 {
    margin-top: 2rem !important;
    background-color: #f5f5f5 !important;
    text-align: center !important;
  }
}

Required CMS Data Structure

The resolveStyles function expects an array of style objects from your CMS. Each object represents styles for a specific breakpoint:

[
  {
    resolutions: { min: 768, max: 1024 }, // Tablet breakpoint
    marginTop: "2rem",
    backgroundColor: "#f5f5f5",
    textAlign: "center"
  },
  {
    resolutions: { min: 1025 }, // Desktop and up  
    marginTop: "3rem",
    backgroundColor: "#ffffff"
  }
]

How it works:

  1. Input: Array of style objects with resolutions and style properties
  2. Processing: Converts style properties to kebab-case CSS (marginTop → margin-top)
  3. Media Queries: Generates CSS media queries from min/max pixel values
  4. Output: CSS string with unique class names and responsive styles

Creating the Styles Field

  • Schema-based CMS (Sanity): Define as array of objects with nested fields
  • API-based CMS (Contentful): Use JSON field with validation for the expected structure
  • Component-based CMS (Strapi): Create reusable component with repeatable style objects

Required structure for each style object:

  • resolutions (object): Contains min and/or max pixel values
  • Style properties (strings): marginTop, marginBottom, padding, backgroundColor, textAlign, etc.

2. Create Page Schema

Main page type with:

  • Basic fields: title, url/slug
  • Component arrays: componentsAboveFold, componentsBelowFold
  • Component references: Link to all available component types

3. Create Component Schemas

For each component:

  • Match component props: Use exact field names from frontend components when possible
  • Add validation: Required fields, format validation
  • Include styling: Add your styles field/system to every component
  • Handle media: Configure image fields with responsive variants (desktop, mobile, alt)

4. Understand Data Flow

The extension handles the technical integration automatically:

Data Processing: Your CMS data gets transformed (normalized) to match component requirements. Style configurations are converted to CSS with responsive breakpoints.

Frontend Rendering: Components receive the processed data and styling, then render with unique CSS classes to prevent conflicts between components.

5. Register Schemas

Follow your CMS platform's process to register and configure the schemas you've created.

Advanced Configuration

Responsive Styling Examples

Breakpoint Strategy:

  • Mobile-first: { min: 768 } (tablet and up)
  • Range-specific: { min: 768, max: 1024 } (tablet only)
  • Max-width: { max: 767 } (mobile only)

Example style configurations:

// Mobile-only styles
{
  resolutions: { max: 767 },
  padding: "1rem",
  fontSize: "14px"
}

// Tablet and desktop
{
  resolutions: { min: 768 },
  padding: "2rem", 
  fontSize: "16px"
}

// Desktop-only override
{
  resolutions: { min: 1025 },
  padding: "3rem"
}

Style Properties Reference

Spacing & Layout:

  • marginTop, marginBottom, marginLeft, marginRight
  • paddingTop, paddingBottom, paddingLeft, paddingRight
  • padding, margin (shorthand)

Visual:

  • backgroundColor, color, borderColor
  • fontSize, fontWeight, textAlign

Advanced Layout:

  • display, flexDirection, justifyContent, alignItems
  • gridTemplateColumns, gap

Note: All property names will be converted to kebab-case CSS (e.g., marginTop → margin-top)

Platform Considerations

  • Schema-based CMS (Sanity, Hygraph): Rich field types, conditional visibility, validation
  • API-based CMS (Contentful, Directus): JSON structures, field validation, relationships
  • Component-based CMS (Strapi, Payload): Reusable components, dynamic zones, relations

Quick Reference

Schema Checklist

  • Page type with component arrays created
  • Component schemas match frontend props
  • Styling system configured (built-in OR custom field)
  • Media fields support responsive variants
  • Component relationships properly set up
  • Validation rules in place

Create Test Content

After creating your schemas, create a simple test page to verify your setup:

  1. Create a test page in your CMS with:
    • Title: "Test Page"
    • URL/Slug: "/test"
    • Add any component to componentsAboveFold
  2. Configure the component with sample content using any values that match your schema fields.

This test page will be used during integration testing to verify that your CMS connection, normalizers, and component rendering work correctly.

Best Practices

  • Match field names to component props when possible
  • Start simple with basic styling, expand as needed
  • Document options for content editors
  • Use consistent spacing and color values
  • Test thoroughly with different content combinations