@iqvizyonui/react-storybook-addon-export-to-sandbox

@iqvizyonui/react-storybook-addon-export-to-sandbox

React Storybook Addon Export To Sandbox for Iqvizyon UI React

This Storybook addon enables exporting stories to CodeSandbox or StackBlitz directly from the Storybook Docs mode. It is designed to facilitate the creation of live, editable examples of your IqvizyonUI components.

Features

• Export stories to CodeSandbox/StackBlitz
• Supports both Create React App (CRA) and Vite bundlers
• "Open in new tab" button to view stories outside the Storybook iframe (enabled by default)

Installation

To install the addon, run:

yarn add @iqvizyonui/react-storybook-addon-export-to-sandbox

Usage

Add the addon to your Storybook configuration:

// .storybook/main.js
module.exports = {
  addons: ['@iqvizyonui/react-storybook-addon-export-to-sandbox'],
};

Configuration

The addon can be configured at two levels:

1. Preset configuration — passed via .storybook/main.js addon options (controls the build-time babel transform)
2. Parameters configuration — passed via .storybook/preview.ts or per-story (controls runtime sandbox export behavior)

Preset Configuration (.storybook/main.js)

Preset options configure how the addon transforms story source code at build time via @iqvizyonui/babel-preset-storybook-full-source.

// .storybook/main.ts

import type { StorybookConfig } from '@storybook/react-webpack5';
import type { PresetConfig } from '@iqvizyonui/react-storybook-addon-export-to-sandbox';

const config: StorybookConfig = {
  addons: [
    {
      name: '@iqvizyonui/react-storybook-addon-export-to-sandbox',
      options: {
        /**
         * Import mappings replace internal/private package imports with their public re-export package.
         * Keys are package names to replace, values define the replacement.
         */
        importMappings: {
          '@iqvizyonui/react-button': { replace: '@iqvizyonui/react-components' },
          '@iqvizyonui/react-text': { replace: '@iqvizyonui/react-components' },
        },
        /**
         * Optional: Override the default webpack rule for the babel loader.
         */
        webpackRule: {},
        /**
         * Optional: Modify the babel-loader options before they are applied.
         */
        babelLoaderOptionsUpdater: options => options,
      } satisfies PresetConfig,
    },
  ],
};

Option	Type	Description
importMappings	Record<string, { replace: string }>	Maps internal package imports to their public re-export package in generated source
webpackRule	webpack.RuleSetRule	Override the default webpack rule for the story babel loader
babelLoaderOptionsUpdater	(options: TransformOptions) => typeof options	Transform babel-loader options before they are applied

Styles

The addon ships a CSS file for styling the export button in Storybook Docs. Import it in your .storybook/preview.ts:

// .storybook/preview.ts
import '@iqvizyonui/react-storybook-addon-export-to-sandbox/styles.css';

Global Parameters Configuration (.storybook/preview.ts)

Global parameters set the default sandbox export behavior for all stories.

// .storybook/preview.ts
import '@iqvizyonui/react-storybook-addon-export-to-sandbox/styles.css';

import type { Preview } from '@storybook/react';
import type { Parameters } from '@iqvizyonui/react-storybook-addon-export-to-sandbox';

const preview = {
  parameters: {
    exportToSandbox: {
      provider: 'stackblitz-cloud',
      bundler: 'vite',
      requiredDependencies: {
        react: '^18.0.0',
        'react-dom': '^18.0.0',
      },
      optionalDependencies: {
        '@iqvizyonui/react-components': '^9.0.0',
      },
    },
    // "Open in new tab" button is enabled by default.
    // Set to false to hide it.
    openInNewTab: true,
  } satisfies Parameters,
} satisfies Preview;

export default preview;

Option	Type	Required	Description
provider	'codesandbox-cloud' | 'codesandbox-browser' | 'stackblitz-cloud'	Yes	Which sandbox provider to use for the export
bundler	'vite' | 'cra'	Yes	Which bundler template to scaffold in the sandbox
requiredDependencies	Record<string, string>	No	Dependencies always included in the sandbox package.json
optionalDependencies	Record<string, string>	No	Dependencies included only when detected in story imports
openInNewTab	boolean	No	Show "Open in new tab" button in Docs view (default: true)

Note on openInNewTab placement: The openInNewTab parameter is a separate top-level key alongside exportToSandbox, not nested within it. This is because opening a story in a new browser tab is conceptually unrelated to exporting to an external sandbox provider. Ideally this feature would live in @iqvizyonui/react-storybook-addon (the base addon), but for simplicity it is currently shipped within this package. A future refactor may move it to the appropriate addon.

Local (Per Story) Configuration

export const MyStory = () => <MyComponent />;
MyStory.parameters = {
  exportToSandbox: {
    provider: 'codesandbox-cloud', // or 'codesandbox-browser' or 'stackblitz-cloud'
    bundler: 'cra', // or 'vite'
    requiredDependencies: {
      react: 'latest',
      'react-dom': 'latest',
    },
    optionalDependencies: {
      '@iqvizyonui/react-components': 'latest',
    },
  },
  // Disable "Open in new tab" for this specific story
  openInNewTab: false,
};

Example

Here is an example of how to use the addon in a story:

import React from 'react';
import { Text } from '@iqvizyonui/react-components';

export const Default = () => <Text>This is an example of the Text component's usage.</Text>;

Default.parameters = {
  exportToSandbox: {
    provider: 'stackblitz-cloud',
    bundler: 'vite',
    requiredDependencies: {
      react: 'latest',
      'react-dom': 'latest',
    },
  },
};

Note

This package is designed for internal usage only and may not be suitable for general use.

License

MIT