Stencil + Storybook v9 Integration Issues
Overview
I attempted to use Storybook v9 with the Stencil plugin following the official documentation, but encountered significant limitations and bugs. Many features don't work properly (including documentation mode), so I decided to create a dedicated app in the monorepo to test components natively with React, Angular, and Web Components separately.
Current Setup
/packages/core (Stencil components)
/packages/react (React wrapper)
/apps/storybook (Storybook app)
Issues Encountered
Plugin Compatibility Problems
- addon-essentials doesn't work: Despite being shown in official docs, it causes conflicts and completely breaks Storybook
- Limited addon support: Only addon-links and addon-interactions work reliably, with limited functionality even in v9
- Documentation mode broken:
autodocs: 'tag' doesn't generate any documentation despite proper configuration
Version Compatibility
- v8 issues: The tutorial claims v8 works, but it has the same problems as v9
My Solution Architecture
Instead of fighting with the buggy Stencil plugin, I created a separate Storybook app that consumes the generated wrappers:
- Core package: Pure Stencil components
- React wrapper: Generated React components
- Storybook app: Tests components through the wrappers
Benefits of This Approach
- Test components in their actual usage context (React/Angular/Web Components)
- Avoid plugin bugs and limitations
- Better control over the development environment
Development Workflow Challenges
Build Process Complexity
Created a specific script to handle initial build before starting dev mode to ensure changes reflect correctly in wrappers and prevent Storybook crashes:
# root
"dev": "pnpm build:libs && turbo run dev --parallel"
"build:libs": "turbo run build --filter=@lib/*"
Stencil Configuration Changes
Removing the --dev flag from Stencil was necessary to generate missing JS files that the React wrapper needs:
# packages/core
"dev": "stencil build --watch"
"dev:fast": "stencil build --dev --watch"
Performance Concerns
The current setup runs 3 parallel dev builds (Stencil → React wrapper → Storybook), raising concerns about long-term performance and development speed.
Why This Architecture Works
Despite the complexity, this was the most practical solution because:
- Stencil's server mode is very limited and disorganized for component development
- Storybook provides excellent control and development experience
- Enables direct development in Storybook with proper tooling
Questions
-
Architecture validation: What do you think about separating Storybook into its own app to consume wrappers?
-
Build optimization: Are there better approaches to handle the build complexity without sacrificing development experience?
-
Compatibility timeline: What's the timeline for full Storybook v9 compatibility with Stencil?
-
Future roadmap: What can we expect from Stencil's integration with Storybook? Will it eventually replace the --serve mode as the primary development environment?
Stencil + Storybook v9 Integration Issues
Overview
I attempted to use Storybook v9 with the Stencil plugin following the official documentation, but encountered significant limitations and bugs. Many features don't work properly (including documentation mode), so I decided to create a dedicated app in the monorepo to test components natively with React, Angular, and Web Components separately.
Current Setup
Issues Encountered
Plugin Compatibility Problems
autodocs: 'tag'doesn't generate any documentation despite proper configurationVersion Compatibility
My Solution Architecture
Instead of fighting with the buggy Stencil plugin, I created a separate Storybook app that consumes the generated wrappers:
Benefits of This Approach
Development Workflow Challenges
Build Process Complexity
Created a specific script to handle initial build before starting dev mode to ensure changes reflect correctly in wrappers and prevent Storybook crashes:
Stencil Configuration Changes
Removing the
--devflag from Stencil was necessary to generate missing JS files that the React wrapper needs:Performance Concerns
The current setup runs 3 parallel dev builds (Stencil → React wrapper → Storybook), raising concerns about long-term performance and development speed.
Why This Architecture Works
Despite the complexity, this was the most practical solution because:
Questions
Architecture validation: What do you think about separating Storybook into its own app to consume wrappers?
Build optimization: Are there better approaches to handle the build complexity without sacrificing development experience?
Compatibility timeline: What's the timeline for full Storybook v9 compatibility with Stencil?
Future roadmap: What can we expect from Stencil's integration with Storybook? Will it eventually replace the
--servemode as the primary development environment?