Skip to content

Instantly share code, notes, and snippets.

Show Gist options
  • Save dyarfi/c65a89bf0d2cbbdc4aa7e9d45282e5b1 to your computer and use it in GitHub Desktop.
Save dyarfi/c65a89bf0d2cbbdc4aa7e9d45282e5b1 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.

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