Here are a few issues and questions you might have while setting up and working with the Storybook integration and their answers.
Setting up the integration
If you see the “Accessing Storybook instance failed” message while setting up your integration, here are the 5 possible reasons and their solutions:
1. Your Storybook instance might not be running.
Ensure that your Storybook server is up and running before proceeding with the integration.
2. Your Storybook version might be outdated.
Zeplin requires Storybook version 7 or above for integration. The integration needs to access index.json or stories.json files, which don’t exist in older versions. Make sure to update your Storybook to the latest version and try again.
3. Access-Control-Allow-Origin header might be restricting access.
Zeplin can’t access your Storybook instance if the Access-Control-Allow-Origin header blocks requests. You’ll need to configure the header to allow access. Set its value to either a wildcard (*) or specify the domain https://app.zeplin.io.
4. Zeplin can’t access story previews.
This can happen for two reasons:
Embedding is disabled: Zeplin embeds Storybook previews in an iframe, so the X-Frame-Options header must be unset (or set to allow all domains). You can learn more about the header here.
HTTPS is not enabled: Zeplin requires your Storybook instance to use HTTPS due to browser restrictions (as Zeplin itself uses HTTPS).
Don't panic! There is plenty of information online on how to add HTTPS support to your Storybook server, and you can get free SSL certificates from https://letsencrypt.org. If you're serving your instance through a localhost, this shouldn't be an issue.
5. Safari-specific restriction with localhost.
Safari cannot access story previews when the Storybook instance is served through a localhost URL. Try using a different browser to set up the integration and see previews.
General
My Storybook instance is private. What should I expect?
Anyone who wants to see how the integration works or link stories with components will need access to the website where your Storybook is hosted. If it's an internal website, it may only work for people when they are within your company's network.
If your team members access Zeplin from a public computer, they will not be able to see anything. To fix this, you can make your Storybook website publicly accessible.
I'm serving my Storybook instance through a localhost URL. What should I expect?
Stories won't be available for your team members if you use a localhost URL. We suggest moving your instance to somewhere accessible if you're planning to collaborate with your team.
I have a composition set up in my Storybook instance. What should I expect?
Due to technical limitations, the Composition structure is sadly not supported at the moment. For now, only the stories under the main instance will be available.
I've used CLI before to connect to a Storybook instance. What should I expect?
If you've used CLI before, your links for these components will also be available in Zeplin. You can also continue using CLI—adding components using CLI will reflect them in Zeplin’s Storybook Integration.
💁♀️ If you have any other issues or questions, you can ping us at anytime at support@zeplin.io.