The Tool Desk
Outbyte PC Repair FREERepair Windows errors before they cause bigger problemsFix Now →Outbyte Driver Updater FREEFix the driver behind crashes, sound loss and screen glitchesFind Drivers →Storybook composition lets a host Storybook display stories from other Storybooks in its sidebar. Add references in the host’s .storybook/main.js or .storybook/main.ts configuration, pointing each one at a Storybook URL the host can reach. The referenced projects remain separate; composition is a way to browse their stories together, not merge their source code.
How URL-based composition works
In the host project’s main configuration, add a refs object. Each entry has a key identifying the reference and can include a display title and the URL of the referenced Storybook. For example, the following configuration points to a published design-system Storybook:
| # | Preview | Product | Price | |
|---|---|---|---|---|
| 1 |
|
The Jesus Storybook Bible: Every Story Whispers His Name | $13.06 | Buy on Amazon |
| 2 |
|
Disney Storybook Collection-3rd Edition | $11.49 | Buy on Amazon |
| 3 |
|
My First Disney Classics Bedtime Storybook (My First Bedtime Storybook) | $6.15 | Buy on Amazon |
| 4 |
|
Disney Princess My First Bedtime Storybook | $7.73 | Buy on Amazon |
| 5 |
|
Rosalina's Storybook | $12.49 | Buy on Amazon |
As an Amazon Associate I earn from qualifying purchases.
export default {
refs: {
designSystem: {
title: 'Design System',
url: 'https://storybook.example.com'
}
}
};Use the configuration syntax supported by your project’s installed Storybook version; the example shows the shape of a URL-based reference, not a complete project configuration. Storybook’s composition guide and Storybook 9 refs API document the relevant fields. The URL must be reachable from the environment where the host Storybook runs.
Crashes, No Sound, or Screen Glitches?
Random freezes, missing sound and display glitches usually trace back to one bad driver. Find and replace yours safely.Free scan · under a minuteWindows Errors? Fix Them Before They Spread
Repair common Windows errors and clear accumulated junk for a smoother, more stable PC - no reinstall needed.Free scan · no reinstallReference a local Storybook
A ref can point to a separately running local Storybook, which is useful when developing against another project. For instance, if the referenced Storybook is available at http://localhost:7007, use that URL in the ref. The port is illustrative, not a universal Storybook default. The host and referenced projects can use different UI frameworks or dependencies.
#1 Best Overall
Add optional display and source details
The documented configuration example also uses optional expanded and sourceUrl fields. Use these when appropriate to control how a reference appears or identify its source; consult the refs API for the exact behavior supported by your installed version.
Choose URLs for development and production
A fixed refs object is appropriate when the same referenced Storybook URL should be used in every environment. When local development should use a local Storybook but the deployed host should use a published one, Storybook’s composition documentation shows using a function that selects URLs based on configType.
export default ({ configType }) => ({
refs: {
designSystem: {
title: 'Design System',
url: configType === 'DEVELOPMENT'
? 'http://localhost:7007'
: 'https://storybook.example.com'
}
}
});This illustrates the environment-selection pattern, not a guarantee that either URL exists, is deployed, reachable, or secure. Ensure each environment points to a URL accessible to the people and systems using that host Storybook.
Rank #2
Manual refs and package composition are different
Manual URL refs
With manual refs, the consumer configures the host Storybook and supplies a URL for each referenced Storybook. This is the direct route when you control the host configuration or want to reference a particular local or published instance.
Package composition
Package composition lets a library author provide a storybook property in the package’s package.json containing the library Storybook URL. A consumer’s Storybook can then load that library’s stories automatically if the package and publishing setup support the feature. This is not simply another manual URL entry: it depends on publishing-service integration with Storybook APIs.
Storybook’s package composition documentation recommends Chromatic for full support. In the documented Chromatic workflow, the package can use a stable project URL and Storybook can select the build associated with the installed package version; package authors may also provide versions for a selector. Do not assume the same automatic version selection with arbitrary hosting providers.
Disable an automatically composed package
If package composition adds a library you do not want displayed, the consumer can disable that package ref by setting its package name under refs with disable: true. Check the refs API for the exact configuration shape for your Storybook version.
What composition does—and does not—combine
- It combines discovery: stories from referenced Storybooks appear alongside the host’s stories in its sidebar.
- It does not merge source trees: each referenced Storybook remains its own project.
- It supports local and published targets: use a URL reachable from the host environment.
- It has addon limitations: Storybook warns that “Addons in composed Storybooks will not work as they normally do in a non-composed Storybook.” Do not expect every addon interaction to behave as it would in the referenced Storybook on its own.
- The host still needs local content: Storybook’s FAQ says a project needs at least one local story or docs page, even when it composes other Storybooks.
Version and compatibility checks
Configuration details can change between Storybook major versions. The refs API page cited here is for Storybook 9, so check the documentation matching your installed version before copying configuration into a project.
Storybook’s composition page includes legacy guidance for older projects that may need to generate index.json using the CLI. Its example uses npx [email protected] extract and explicitly notes that this command is unavailable in Storybook 8.0 or higher. Treat it as version-specific legacy guidance, not a general setup step for current projects.
Rank #4
Troubleshoot composition
The referenced Storybook does not appear
- Check that the ref URL is correct and reachable from the environment running the host Storybook. A URL that works on your workstation may not be reachable by a deployed host or by teammates.
- Confirm the ref is configured in the host’s main configuration file and matches the syntax for your installed Storybook version.
- If using package composition, verify that the package metadata and publishing integration support it; a URL in package metadata alone does not guarantee automatic composition.
The local reference works for you but not for collaborators
A localhost URL resolves from the machine running the browser or service, not from every collaborator’s computer. Use a URL reachable in the collaborators’ environment, or configure different URLs for development and production through a refs function.
The composed stories appear, but an addon behaves differently
This is a documented limitation: addons in composed Storybooks do not work as they normally do in a non-composed Storybook. Test the story-browsing workflow you need, and open the referenced Storybook directly when you need its standalone addon behavior.
Recommended Free Tools
A package ref appears unexpectedly
For a library added automatically through package composition, configure that package name under refs with disable: true to turn off its composed ref.
Best Value
Or skip the browser setup
If you need a screenshot of a Storybook page rather than a composed sidebar, ScreenshotNeo can capture a URL through one GET request. See the API documentation for available parameters.
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://storybook.example.com -o shot.webpScreenshotNeo removes cookie/consent banners, newsletter popups, and chat widgets before capture; those steps can be turned off. Bot checks or CAPTCHAs, blank pages, timeouts, failed loads, and cache hits are not billed, and the response identifies the page verdict and billing status in headers. Its MCP server offers take_screenshot, get_page_info, and capture_pdf for AI agents and MCP clients. The Free plan includes 1,000 screenshots per month with no card; paid plans start at $5 for 3,000 shots.
Sign up for ScreenshotNeo’s free plan to get 1,000 screenshots a month with no card.
Free tools Windows power users keep installed
One-click scans. No signup required.
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.
