Roadmap

This document outlines the planned features and improvements for Storybook Astro. Items are categorized by priority and implementation phase.

High Priority

Support Astro Components as Props

Enable composing Astro components by passing them as props to other Astro components in stories. This allows patterns like wrapping a Button inside a Link, or passing Icon components to other components.

Phase 1 — Template nesting and image rendering: Shipped. Components whose templates use other Astro components (transitively) render correctly, including those that use <Image> from astro:assets. No story-side changes are required.

Phase 2 — Props-based nesting: In Design. Passing an Astro component factory as a story arg (e.g. <Link Icon={MyIcon} />) is not yet supported. See the nested component support design for the proposed implementation strategy.

Scope: Medium-High complexity (Phase 2)

What Phase 2 enables:

Passing Astro components as props in story args
Support in portable stories (testing API)

Improve Astro 6 Font Provider API Integration

Provide first-class support for Astro 6’s new Font Provider API, allowing developers to use Astro’s built-in font system seamlessly within Storybook stories.

Status: Planned
Complexity: Medium
Details: Astro 6 introduced a unified Font Provider API that supports multiple font providers (Google, Adobe, Bunny, local, and custom providers). Currently, Storybook Astro stubs Astro’s font virtual modules with no-op exports.

Improvements needed:

Properly resolve and initialize font providers in Storybook’s dev server
Include font definitions from astro.config.ts in story rendering
Ensure font files are emitted correctly during storybook build
Support both remote and local font providers

Auto-detect CSS Frameworks from Astro Config

Automatically detect and configure CSS utility frameworks (UnoCSS, Tailwind CSS, etc.) registered as Astro integrations, so their Vite plugins are available in Storybook without manual viteFinal configuration.

Status: Planned
Complexity: Medium
Details: Currently, CSS frameworks configured as Astro integrations (e.g. unocss/astro, @astrojs/tailwind) are not automatically wired into Storybook’s Vite pipeline. Users must manually add the framework’s Vite plugin via viteFinal in .storybook/main.js and import virtual modules in the preview. See the Styling guide for the current manual setup.

Improvements needed:

Detect CSS-related Vite plugins from the resolved Astro config during mergeWithAstroConfig
Automatically register detected plugins in Storybook’s Vite pipeline
Handle virtual module imports (e.g. virtual:uno.css) in the preview

Decorator Support

Enable Storybook’s standard decorator API for both Astro component stories and framework component stories (React, Vue, etc.).

Status: Planned Complexity: Medium Tracking: Issue #40 — Unable to use decorators Details: See the decorator support design for full analysis and implementation strategy.

What this enables:

Global decorators in .storybook/preview.js (layout wrappers, theme providers)
Component-level and story-level decorators
HTML string decorators for Astro component stories
Framework-native decorators (JSX, etc.) for React/Vue/Svelte component stories

Medium Priority

Enhanced Testing & Portable Stories

Expand testing capabilities for Astro components tested in isolation, including better support for Container API integration and DOM testing patterns.

Status: In Discussion
Complexity: Medium
Details: The community has shared best practices for testing Astro components using the Container API with DOM libraries (jsdom/happy-dom). Storybook Astro can improve this experience by providing tested patterns and utilities.

Potential additions:

Test helper utilities for common testing patterns
Documentation with examples for testing composed components
Integration with testing libraries (Testing Library, Vitest patterns)
Guidance on testing both server-rendered and client-side behavior

Future Enhancements

Dynamic Astro Controls in Static Builds

Currently, Astro component stories are pre-rendered with their default args at build time, making the Storybook Controls panel non-functional for Astro components in static deployments. A future enhancement could enable live re-rendering with different args via a companion service.

Potential approaches:

Embed a lightweight server within the static build for on-demand rendering
Use a service worker to intercept render requests
Provide a deployment adapter for serverless platforms

Content Collections Support

Enable the astro:content module for type-safe content management within stories, allowing components that depend on content collections to be documented and tested in Storybook.

View Transitions

Support Astro’s View Transitions API (<ViewTransitions /> component) in the Storybook preview, enabling developers to document and preview transition effects.

API Routes & Server Islands

Support for server-side endpoints and dynamic server islands would enable testing components that depend on backend data fetching within Storybook.

Middleware & Environment Variables

Integration with Astro’s middleware system and astro:env module for managing environment variables within stories.

Internationalization (i18n)

Support for Astro’s built-in i18n routing and helpers, enabling documentation of multi-language components.

Known Limitations

Astro components in static builds are pre-rendered with default args — Controls modifications have no effect (framework components remain fully interactive)
Client-side behavior of Astro components requires end-to-end tests (Playwright, Cypress) as the Container API doesn’t execute script tags
Circular component references are not yet detected or prevented when passing components as props
Module hot-reloading with nested component references may require manual refresh in some cases

Contributing

Interested in working on any of these roadmap items? Check the GitHub issues for ongoing discussions and collaboration opportunities, or see the AGENTS.md file in the repository for development guidance.