iTechGuides is reader-supported. When you buy through links on our site, we may earn an affiliate commission. As an Amazon Associate I earn from qualifying purchases. Learn more
Storybook composition lets a host Storybook display stories from other Storybooks in its sidebar. Add URL-based references in the host project’s .storybook/main.js or .storybook/main.ts; the referenced projects remain separate and can use different frameworks or dependencies.
What Storybook composition does
Composition is a way to browse stories from multiple Storybook instances in one host Storybook. The host adds references to its configuration, and those references point to other Storybooks by URL. This is discovery and browsing, not a merge of the projects’ source code. Storybook’s composition documentation describes both local and published references.
The host and referenced Storybooks do not have to use the same view layer, framework, or dependencies. For example, a React host can reference an Angular Storybook. Composed Storybooks’ addons may not behave as they do in a standalone Storybook; Storybook cautions that “Addons in composed Storybooks will not work as they normally do in a non-composed Storybook.”
Add a URL-based reference
In the host project, edit .storybook/main.js or .storybook/main.ts and add a refs object. The following illustrative configuration points to a deployed design-system Storybook; replace the example URL with one reachable from the environment where the host runs.
export default {
refs: {
designSystem: {
title: 'Design System',
url: 'https://design-system.example.com',
expanded: true,
sourceUrl: 'https://github.com/example/design-system',
},
},
};The reference key, here designSystem, identifies the entry. The title is what users see, and the URL identifies the referenced Storybook. In Storybook’s documented example, expanded and sourceUrl are optional fields. Check the refs API documentation for Storybook 9 and the documentation for your installed major version before copying version-sensitive configuration.
- Confirm the referenced Storybook is running or deployed and that its URL can be reached from the host environment.
- Add the reference under
refsin the host’s main configuration. - Start or reload the host Storybook and check that the referenced stories appear in its sidebar.
Use local Storybooks during development
A reference can point to a locally running Storybook just as it can to a published one. This is useful when developing multiple component libraries or applications together. Storybook’s documentation illustrates combining separate projects this way; local port numbers are examples, not universal defaults. Make sure the URL is accessible from the machine and browser running the host Storybook.
Choose URLs by environment
If collaborators need local references while production users need hosted Storybooks, define refs as a function and return URLs according to configType. Storybook documents using development URLs when configType is DEVELOPMENT and production URLs otherwise. Adapt the example URLs to your setup:
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
export default ({ configType }) => ({
refs: {
designSystem: {
title: 'Design System',
url:
configType === 'DEVELOPMENT'
? 'http://localhost:7007'
: 'https://design-system.example.com',
},
},
});This selects which URL the host uses; it does not deploy the production Storybook or ensure either address is reachable. Validate the returned URL in each environment. See Storybook’s composition guide for its environment-dependent example.
Manual refs versus package composition
Manual URL references and package composition solve related but different setup problems. With manual refs, the consumer configures the URL in the host’s main configuration. Package composition lets a package author publish Storybook metadata so a consumer’s Storybook can load that library’s stories automatically, when the package and publishing integration support it.
| Approach | Who sets it up | How it selects the Storybook | Key condition |
|---|---|---|---|
| Manual URL ref | Consumer of the referenced Storybook | A URL in the host’s refs configuration |
The URL must be reachable from the host environment. |
| Package composition | Package author supplies metadata; consumer installs the package | A storybook property in the package’s package.json |
Requires a secure integration between the publishing service and Storybook APIs; Storybook recommends Chromatic for full support. |
For package composition, the metadata can contain the library’s Storybook URL. Storybook’s documentation ties the full package-composition workflow to a publishing-service integration and recommends Chromatic. With Chromatic, the stable project URL can resolve to the build corresponding to the installed package version; package authors may also provide versions for a selector. Do not assume that version-aware automatic selection works with arbitrary hosting providers. Details are in Storybook’s package composition guide.
Rank #4
A consumer can suppress an automatically composed package reference by setting that package name under refs with disable: true. Consult the package-composition guide and the refs API for the applicable configuration.
Quick wins for a faster PC:
Clear out junk files and repair common Windows errorsFree Scan →Fix the driver behind crashes, sound loss and screen glitchesFind Drivers →Requirements and caveats
- Reachability: the host environment must be able to access every referenced URL. A URL that works on a developer’s machine may not work for a deployed host.
- Local content: a host Storybook still needs at least one local story or docs page, even if it also composes other Storybooks, according to the Storybook FAQ.
- Addon expectations: addons in composed Storybooks do not work as they normally do in a non-composed Storybook. Treat composition primarily as a way to browse stories, not as a guarantee that every standalone behavior carries over.
- Older projects: Storybook’s composition page includes legacy guidance for older projects that need to generate
index.json. Its example command isnpx storybook@7.5.3 extractand the documentation explicitly says this command is unavailable in Storybook 8.0 and higher. Do not use it as a general current setup step; check the documentation for your project’s major version.
Troubleshoot missing references
- The reference does not appear: check the host’s main configuration for a correctly named
refsentry, then reload the host Storybook. - The URL cannot be reached: open the referenced URL from the host environment. For local development, confirm the referenced Storybook is running and use its actual address and port.
- Development works but production does not: inspect the refs function’s
configTypebranch and verify that the production URL is deployed and accessible to production users. - A package reference is absent or selects unexpectedly: verify that the package publishes its
storybookmetadata and that the publishing integration supports package composition. Version-aware selection described by Storybook is associated with Chromatic, not arbitrary hosts. - An addon behaves differently: this is a documented limitation of composed Storybooks; check whether the behavior depends on running the referenced Storybook standalone.
- The host contains no local stories or docs: add at least one local story or docs page, as required by the Storybook FAQ.
Or skip the browser setup
If your goal is to capture a Storybook page for documentation, review, or an automated workflow, ScreenshotNeo provides a website screenshot API and MCP server. It is separate from Storybook composition: it captures a page rather than combining Storybook sidebars.
Best Value
One GET request can return an image or PDF. For example, save a deployed Storybook URL as a WebP image:
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://storybook.example.com -o shot.webpSee the ScreenshotNeo documentation for request options and authentication. Cookie banners are accepted and removed before capture, along with supported newsletter popups and chat widgets. Bot checks, blank pages, failed loads, timeouts, and cache hits are not billed; response headers report the page verdict and billing status. Its MCP server exposes take_screenshot, get_page_info, and capture_pdf for AI agents. The free plan includes 1,000 screenshots per month with no card; paid plans start at $5 for 3,000.
Sign up for ScreenshotNeo’s free plan to try it without a payment card.
The Tool Desk
Outbyte Driver Updater FREEScan for outdated or missing drivers - takes under a minuteDriver Scan →Outbyte PC Repair FREEClear out junk files and repair common Windows errorsFree Scan →Frequently Asked Questions
Does composition merge the referenced Storybook’s source code into the host?
No. Composition makes external stories available to browse in the host’s sidebar; the projects remain separate.
Can a composed Storybook use a different framework from the host?
Yes. Storybook’s composition guidance says references can use different view layers, stacks, or dependencies.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
