Component Structure

Components are the building blocks of pages in the Serverless CMS. This guide covers the structure, files, and packaging of component bundles.

A component is a reusable UI element that can be added to pages. Examples include:

• Title headings
• Rich text content
• Images with captions
• Buttons and links
• Navigation menus
• Content teasers

Each component consists of:

• HTML template: The structure and markup
• CSS styles: The visual appearance
• Dialog schema: The configurable properties
• Metadata: Name, description, and purpose

A component bundle is a folder containing required and optional files:

Contains component metadata:

Fields:

• name: Display name (shown in component palette)
• description: Brief description of the component
• purpose: When and why to use this component
• optionsDescription: Summary of configurable options

Defines configurable properties (see Dialog Schema):

The HTML template with variable markers (see Templating Syntax):

The CSS styles for the component:

A data fetching function executed at publish time:

Context API:

• context.queryPages(options): Query pages in the site
• context.getSite(): Get site metadata
• context.getPage(pageId): Get a specific page

Constraints:

• Must export a fetchData function
• Must return within 5 seconds (timeout)
• Cannot make external HTTP requests
• Runs in a sandboxed environment

An editor-only script that controls the component's editorial experience — for example, which rich-text formatting controls an author sees. It is loaded only inside the CMS editor and is never bundled into or served from a published site (published pages receive only component.html and component.css).

Constraints:

• Must export default a factory function (or a plain config object)
• Field keys must match name values in dialog.json
• Because it is editor-only, it is not HTML-sanitized
• Runs only in the editor; not available to published output

See the Editor Scripts guide for the full contract, toolbar options, and a complete rich-text example.

Design variable definitions (see Design Variables):

Required naming:

• details.json (exact name)
• dialog.json (exact name)
• component.html (exact name)
• component.css (exact name)
• component.js (exact name, if present)
• editor.js (exact name, if present)
• variables.json (exact name, if present)

Case sensitivity: All filenames are case-sensitive.

To package a single component:

1. Create a folder with the component name
2. Add all required files
3. Zip the folder:

To package multiple components in one zip:

1. Create a parent folder
2. Add component subfolders
3. Zip the parent folder:

To upload components to the CMS:

1. Navigate to Components from the main navigation
2. Click Upload Component
3. Select your zip file
4. Wait for validation
5. Review validation results
6. Click Confirm Upload if validation passes

!Screenshot

The CMS validates each component:

1. File presence: All required files exist
2. JSON validity: details.json and dialog.json are valid JSON
3. Schema conformance: Files conform to expected schemas
4. Marker cross-reference: All {{markers}} in HTML reference dialog fields
5. HTML sanitization: HTML is safe (no <script>, javascript:, on* handlers)
6. File size: No file exceeds 512 KB
7. Total size: Zip file doesn't exceed 10 MB

If validation fails, you'll see detailed error messages:

Component uploads are atomic:

• All components valid: All components are uploaded
• Any component invalid: Nothing is uploaded

This prevents partial uploads that could break the component library.

To update an existing component:

1. Navigate to Components
2. Click the ⋮ menu next to the component
3. Select Update
4. Upload the new zip file
5. Confirm the update

To delete a component:

1. Navigate to Components
2. Click the ⋮ menu next to the component
3. Select Delete
4. Confirm the deletion

Components are categorized as:

• built-in: Platform-provided components (cannot be deleted)
• custom: User-uploaded components (can be updated and deleted)

• Single responsibility: Each component should do one thing well
• Reusability: Design components to work in multiple contexts
• Flexibility: Provide enough options without overwhelming users
• Defaults: Set sensible default values for optional fields

• Semantic markup: Use appropriate HTML elements
• Accessibility: Include ARIA attributes where needed
• Responsive: Design for mobile-first
• Clean code: Use consistent indentation and formatting

• Use design variables: Reference design variables for consistency
• Scoped styles: Use specific class names to avoid conflicts
• Mobile-first: Start with mobile styles, add desktop overrides
• Performance: Avoid expensive CSS (complex selectors, animations)

• Clear labels: Use descriptive field labels
• Helpful descriptions: Add descriptions for complex fields
• Logical order: Order fields in a logical sequence
• Required vs optional: Mark required fields appropriately

• Test in context: Add component to a page and test
• Test all options: Try different field combinations
• Test responsive: Check on mobile, tablet, and desktop
• Test accessibility: Verify keyboard navigation and screen readers

See Component Example for a complete, working component with all files.

• Dialog Schema — Define configurable properties
• Templating Syntax — Use variable markers in HTML
• Design Variables — Use design variables in CSS
• Validation Rules — Understand validation requirements
• Editor Scripts — Add editor-only editorial controls (editor.js)