CL Preview

Note: This is an experimental module and is not yet complete. Please avoid opening issues for now.

CL Preview is a Drupal-native component library browser for previewing and testing Single Directory Components (SDC). A great alternative to Storybook that works entirely within Drupal without requiring Node.js, Webpack, or any external build tools.

Features

• Component Library Browser - Organized interface with navigation and live component previews
• Hot Reload - Automatically refreshes when component files change
• Preview Values - Define custom preview data in component.yml for better demos
• No Story Files - No need for .stories.yml, .stories.json, or MDX files
• Theme Switching - Preview components in any installed theme
• Auto-Discovery - Automatically finds SDC components from configured themes/modules
• No Build Step - Pure Drupal solution with no external tooling required

CL Preview is ideal for frontend developers building design systems, teams documenting component libraries, and projects wanting a native Drupal alternative to Storybook.

Post-Installation

1. Enable: drush en cl_preview -y
2. Configure: /admin/config/development/cl-preview/settings
   • Select themes/modules to scan for components
   • Choose preview theme (optional)
   • Enable hot reload (optional)
3. View Library: /admin/config/development/cl-preview
4. Permissions: Grant "Access CL component library" to appropriate roles

Improving Preview Display with Preview Values

By default, components may render with empty or minimal data if they only have basic defaults. To create better demonstrations in the component library, add a preview section to your existing *.component.yml files with meaningful sample data. No separate story files needed!

# your-component.component.yml
props:
  type: object
  properties:
    title:
      type: string
      default: ''
    variant:
      type: string
      default: primary

# Add preview values for better demos
# No need for .stories.yml or .stories.json files!
preview:
  title: Example Title
  description: Sample content
  variant: primary

Preview Value Hierarchy: The module uses preview values first, then falls back to prop defaults, then type-based defaults (empty string, 0, false, [], etc.). This means your preview section will override any defaults defined in the props, giving you complete control over how components appear in the library.

The preview page will highlight props with empty values in red to help you identify which components need better preview data. See the full README for more details.

Additional Requirements

• Drupal 10.1+ with SDC module (core)
• At least one theme or module with SDC components (components/ directory with *.component.yml files)

Comparison

Why CL Preview is a great alternative to Storybook:

• No Node.js, Webpack, or build tools required
• No separate installation or deployment
• No .stories.yml, .stories.json, or MDX files to create or maintain
• Native Drupal integration using the render system
• Automatic component discovery from existing .component.yml files

vs. SDC Examples: Hot reload, organized library interface

vs. Pattern Lab: No separate installation, works directly with Drupal's SDC system

Community Documentation

Full documentation including troubleshooting, value hierarchy, interactive features, and extending the module is available in the module's README.md file.

Credits

Co-authored with Claude Code - AI pair programming assistant by Anthropic.