Supernova CLI allows you to deploy Storybook directly to our servers for private and secure hosting. Control access through Supernova accounts, while having the Storybook embedded directly into your documentation.
The storybook-import command allows you to upload a Storybook static export to your Supernova design system. This creates a hosted instance of your Storybook that is integrated with Supernova, enabling you to reference your components directly from the Supernova platform.
Before you begin
Before importing your Storybook to Supernova, make sure you have:
- Generated a static Storybook build using build-storybook or equivalent command
- Installed and set up the Supernova CLI
- Logged in to the Supernova CLI using the supernova login command
- Contributor or higher access permissions to your target Supernova design system
Command Syntax
supernova storybook-import [OPTIONS]
Options
|
Flag |
Alias |
Description |
Required |
|---|---|---|---|
|
--from |
-f |
Directory containing the Storybook static export |
Yes |
|
--designSystemId |
-d |
ID of the design system to import to |
No* |
|
--brandId |
-b |
ID of the brand to attach the Storybook to |
No* |
|
--name |
-n |
Name for the Storybook instance (used as the slug in the URL) |
Yes* |
|
--sourceId |
-s |
Source ID for updating an existing Storybook |
No |
|
--versionId |
—v |
ID of the design system version |
No |
* If not provided, the CLI will prompt you to select from available options or type the value.
Basic import
The simplest way to import your Storybook is to run:
supernova storybook-import --from ./storybook-static
This will start an interactive process that guides you through selecting:
- A name for your Storybook instance
- The design system to import to
- The design system version
- The brand to attach the Storybook to
Import with specific IDs:
supernova storybook-import --from ./storybook-static --designSystemId 12345 --brandId abc-def-123
Update an existing Storybook source:
supernova storybook-import --from ./storybook-static --sourceId e60a6d97-35ab-46bf-a120-6dbc459ddc09
Specify a custom name for URL access:
supernova storybook-import --from ./storybook-static --name "production-components"
Access your imported Storybook
After a successful import, your Storybook will be accessible at:
https://storybook.supernova.io/design-systems/{designSystemId}/alias/{name}/index.html
The {designSystemId} is your design system ID and {name} is the name you specified during import.
Configuration persistence
This command supports persistent configuration in the supernova.config.json file. After the first run, the following values will be saved:
{
"commands": {
"storybook-import": {
"from": "./storybook-static",
"designSystemId": "37355",
"brandId": "8feeb3c7-076b-40fd-ba4b-971df150efe9",
"sourceId": "e60a6d97-35ab-46bf-a120-6dbc459ddc09",
"name": "default"
}
}
}
This allows you to run subsequent imports without having to specify the same parameters again.
Integrate with automated workflows
Automatically update your Storybook in Supernova using CI/CD pipelines such as GitHub Actions. Use the SUPERNOVA_TOKEN environment variable with your personal access token instead of interactive login.
- Create a Supernova Token
- In Supernova, go to Account Settings → Authentication
- Create a new token and copy its value
- Add created token to GitHub Secrets
- In your GitHub repo: Settings → Secrets and variables → Actions
- Create new secret named SUPERNOVA_TOKEN with your Supernova token
- Create .github/workflows/supernova-storybook.yml
Example GitHub Actions Workflow
name: Import Storybook to Supernova
on:
push:
branches: [main]
workflow_dispatch:
jobs:
storybook-import:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
- name: Setup Node.js
uses: actions/setup-node@v3
with:
node-version: 20
- name: Install system dependencies
run: |
sudo apt-get update
sudo apt-get install -y libsecret-1-dev
- name: Install dependencies
run: npm ci
- name: Build Storybook
run: npm run build-storybook
- name: Install Supernova CLI
run: npm install -g @supernovaio/cli
- name: Import Storybook to Supernova
env:
SUPERNOVA_TOKEN: ${{ secrets.SUPERNOVA_TOKEN }}
run: supernova storybook-import --from ./storybook-static --designSystemId 12345 --versionId 67890 --name "main-branch"
Limitations and requirements
When importing your Storybook, be aware of the following limitations:
- Maximum Storybook size: 500MB after compression
- Required Storybook files: index.html and iframe.html
- Required permissions in your Supernova workspace: Contributor or higher
Troubleshooting
Common issues
|
Issue |
Resolution |
|---|---|
|
Invalid Directory |
Make sure you're pointing to a valid Storybook static build directory. |
|
Upload Failures |
Check your internet connection and ensure your Storybook size is under the 500MB limit. |
|
Processing Errors |
The command aborts after 5 consecutive "unknown" status responses - check your Storybook export quality. |
|
Permission Issues |
Verify you have the necessary access rights to the target design system. |
Need help?
If you're experiencing an issue that is not covered here, contact Supernova support or consult the Supernova Community.
Best practices
Follow these recommendations for optimal Storybook import workflow:
- Automation: Use specific IDs in CI/CD pipelines to avoid interactive prompts
- Version Control: Add the supernova.config.json file to version control to share settings with your team
- Naming: Choose meaningful names for Storybook instances as they become part of the URL
- Environment Separation: Use different Storybook names for different environments (e.g., "staging", "production")