Contents x
    Configuring the Storybook CLI-Based Integration
    • 03 Feb 2023
    • 3 Minutes to read
    • Dark
      Light
    Contents

    Configuring the Storybook CLI-Based Integration

    • Updated on 03 Feb 2023
    • 3 Minutes to read
    • Dark
      Light
    Article Summary

    The Live Components feature is currently limited to Enterprise users on a DSM Enterprise plan. Learn more about DSM Enterprise. 

    If using the CLI-based DSM Storybook integration to build Live Components, the first step is configuring the integration.

    You only need to configure the integration the first time you add Live Components.

    Installing Storybook

    As mentioned in the Getting Started with Live Components article, the DSM Live Components feature requires that you first create a Storybook story for the component you want to embed in DSM.

    Note that if you're using Storybook v4, the Live Components feature supports version 4.0.0 and later. If you're using Storybook v5, the Live Components feature supports version 5.1.1 and later.

    When your stories are working properly in your local Storybook project, you’re ready to start embedding those stories in DSM.

    Tip: If you haven’t yet created stories in Storybook, but you want to see how Live Components will work in DSM, we recommend downloading our example component library from Github. It includes sample components and is pre-configured with Storybook.

    Installing the DSM CLI

    First, you will need to install the DSM command-line interface (CLI) in your project. In your development environment, run the following command:

    npm install @invisionapp/dsm-storybook

    Peer dependencies

    Before configuring Storybook with DSM, there are a few peer dependencies you will need to install:

    • @storybook/addon-options
    • @storybook/addons

    Adding CLI shortcuts

    Optionally, you can create CLI shortcuts to more easily publish and preview live components in the future. Add the following CLI shortcuts to the scripts section of the package.json file of your Storybook component library project:

    "scripts": {
  "dsm-storybook:publish": "dsm-storybook publish",
  "dsm-storybook:preview": "dsm-storybook preview"
}
    Tip: If you're following along with the example Storybook component library project, you'll notice these shortcuts have already been added to the package.json file.

    Adding a DSM configuration file

    To obtain the code for the .dsmrc configuration file:

    1. Open your design system on the DSM documentation site. 
    2. At the bottom right of the page, click the settings icon (), and then click Live components setup.
      Note: If you're working in a legacy DSM design system, instead navigate to the top right of the page, click the code icon (), and select Live components setup.
    3. Scroll to Integration details and, next to DSM configuration file, click Open.
    4. Copy the code and add it to a .dsmrc configuration file in your Storybook component library project.
      Note: You’ll notice that in the code, there is a placeholder for an authentication token. The next section covers how to generate a token for your .dsmrc file.

    Place the .dsmrc configuration file in the root of your Storybook component library project. The root of the project is the same folder where the package.json file lives.

    Tip: If you're following along in the example Storybook component library project, you'll notice the .dsmrc file has already been added to the root of the project. Replace the default values in this file with the code you copied from your Integration details section.

    Some parts of the code require unique values provided by you. The following table shows what each key represents in the DSM configuration file.

    Key

    Value

    authToken

    Authenticates the CLI during the upload of the Storybook to DSM. You will generate an authentication token in the next step.

    dsmHost

    The URL to which the Storybook will be uploaded

    For example: https://your-company-name.invisionapp.com/dsm/your-dsm-organization-name

    organization

    The name of the DSM organization

    For example: https://your-company-name.invisionapp.com/dsm/your-dsm-organization-name

    outputDir

    Builds the output folder path. The default value is .dsm.

    storyPath

    A glob pattern of where DSM should search for stories

    proxyUrl

    An HTTP proxy to be used

    proxyPort

    Proxy port

    tunnel

    Use if the the defined proxy is a HTTP proxy

    defaultDocsTab

    Loads the Docs tab in Storybook by default

    hideDsmGeneratedTable

    Hides the DSM props table and sample code

    Generating an authentication token

    When you copied the code for your .dsmrc file, you may have noticed a placeholder for an authentication token. The .dsmrc configuration file requires an authentication token.

    To generate an authentication token:

    1. Open your design system on the DSM documentation site.
    2. At the bottom right of the page, click the settings icon (), and then click Live components setup.
      Note: If you're working in a legacy DSM design system, instead navigate to the top right of the page, click the code icon (), and select Live components setup.
    3. Scroll to Integration details and, next to Manage authentication tokens, click Manage.
    4. Click Generate new token.
    5. Copy the token and click Save.
      Warning: For security purposes, this token is only displayed once, so be sure to copy it somewhere safe before clicking Save.

    After you’ve generated the token, paste it into your .dsmrc file.

    Adding DSM as a Storybook addon

    The next step is to add DSM as a Storybook addon using either declarative or non-declarative configuration in Storybook. Depending on your version of Storybook, visit the appropriate following link:

    After you have completed the configuration, you can continue setting up your live components by creating component containers in DSM and connecting them to Storybook. 

    Was this article helpful?
    What's Next