Skip to content

Instantly share code, notes, and snippets.

@shilman
Last active May 28, 2024 17:42
Show Gist options
  • Save shilman/bc9cbedb2a7efb5ec6710337cbd20c0c to your computer and use it in GitHub Desktop.
Save shilman/bc9cbedb2a7efb5ec6710337cbd20c0c to your computer and use it in GitHub Desktop.
Storybook Docs Typescript Walkthrough

Storybook Docs w/ CRA & TypeScript

This is a quick-and-dirty walkthrough to set up a fresh project with Storybook Docs, Create React App, and TypeScript. If you're looking for a tutorial, please see Design Systems for Developers, which goes into much more depth but does not use Typescript.

The purpose of this walkthrough is a streamlined Typescript / Docs setup that works out of the box, since there are countless permutations and variables which can influence docs features, such as source code display, docgen, and props tables.

Step 1: Initialize CRA w/ TS

npx create-react-app cra-ts --template typescript

Step 2: Initialize Storybook w/ TS

cd cra-ts
npx -p @storybook/cli sb init --story-format=csf-ts

Step 3: Install & Configure Docs

yarn add @storybook/addon-docs --dev

Then edit ./.storybook/main.js:

module.exports = {
  stories: ["../src/stories/**/*.stories.(ts|tsx|js|jsx)"],
  addons: [
    "@storybook/addon-actions",
    "@storybook/addon-links",
    "@storybook/preset-create-react-app",
    {
      name: "@storybook/addon-docs",
      options: {
        configureJSX: true,
      },
    },
  ],
};

NOTE: If you're using an older version of Storybook or otherwise prefer .storybook/presets.js, you can use export the value of presets from the above example instead:

module.exports = ["@storybook/preset-create-react-app", ...];

Step 4: Verify Installation

yarn storybook

Then edit the button label in ./src/stories/1-Button.stories.tsx and verify that the story updates in Storybook.

Also verify that there's a Docs tab, and that it shows something reasonable-ish. We'll make it better in the next step.

Step 5: Test Props

Storybook can't load docgen information from pre-built libraries, so to test that aspect out, create a file ./src/stories/Button.tsx:

import React, { FC, ReactNode } from "react";

type ButtonProps = {
  children: ReactNode;

  /**
   * Simple click handler
   */
  onClick?: () => void;
};

/**
 * The world's most _basic_ button
 */
export const Button: FC<ButtonProps> = ({ children, onClick }: ButtonProps) => (
  <button onClick={onClick} type="button">
    {children}
  </button>
);

Then update ./src/stories/1-Button.stories.tsx to import this button instead of the @storybook/react demo button. You should see the props update and also the component documentation show up on the Docs tab.

Step 6: Test MDX

Finally, test that MDX is working.

You already installed docs in Step 3, but now you need to tell Storybook to load .stories.mdx files by editing .storybook/main.js:

module.exports = {
  stories: ["../src/stories/**/*.stories.(ts|tsx|js|jsx|mdx)"],
  // more settings ...
};

Then create ./src/stories/Test.stories.mdx:

import { Meta, Story, Preview, Props } from "@storybook/addon-docs/blocks";
import { Button } from "./Button";

<Meta title="Test" />

Here's some _markdown_!

# Preview

<Preview>
  <Story name="button">
    <Button>hello</Button>
  </Story>
</Preview>

# Props

<Props of={Button} />

You should see a new entry in your Storybook's navigation, a story, and the documentation you wrote in the Docs tab.

NOTE: If you're using an older version of Storybook or otherwise prefer .storybook/config.[jt]s, you can add the stories to your configure statement:

import { configure } from "@storybook/react";

configure(
  require.context("../src/stories", true, /\.stories\.(mdx|[tj]sx?)$/),
  module
);

Notes

The sourceLoaderOptions: null in Step 3 is covering up Storybook issue #7829: Addon-docs: Typescript source support. I'll fix that issue ASAP to complete the walkthrough and update this gist when it's ready.

@rxliuli
Copy link

rxliuli commented Dec 1, 2020

Are there any plans to support Proxy?

@fardeen-panjwani-vxlllc

Is there a way to include pages that require authentication?

@ashalfarhan
Copy link

Hi, Thanks a lot for your work, with this gist I was able setup awesome docs pretty quickly! But Step 5. with Storybook can't load docgen information from pre-built libraries, really bugged me.

I have monorepo, with component and storybook

When I import in storybook component from package

import {Component} @my-repo/my-component the can't read props, and returns No props found for this component

But when I create dumb file Component.tsx in my storybook/src folder which just 'rexport' my component like

import { Component } from '@my-repop/my-component';
export default Component;

and then i use it in my storybook import Component from '../Component'

<Props /> component works like a charm.

Can someone explain me this behaviour? Thanks in advance.

Cheers.

Anyone is having a workaround for this issue???

@SalahAdDin
Copy link

What if we want to set the main file in Typescript?

@yannbf
Copy link

yannbf commented Jan 16, 2023

Hey peeps, FYI this gist was created a long time ago and things have changed since. Please find the documentation in https://storybook.js.org/ for reference instead!

@D1no
Copy link

D1no commented Mar 4, 2023

@yannbf cool, maybe link to it. If people (like me) would find that information easily, they wouldn't end up doing google -> this page. Couldn't find anything similar to this information on "storybook.js.org for reference" 😑

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment