Storybook

Installing Storybook

Because the RedwoodSDK is based on React and Vite, we can work through the “React & Vite” documentation:

Install Storybook:
- npm
- pnpm
- yarn
Terminal window
npm create storybook@latest
Terminal window
pnpm create storybook@latest
Terminal window
yarn create storybook
Select what we want to use Storybook for — I selected both Documentation and Testing, though this guide will only cover the documentation part:
It’ll say it can’t detect the framework. Select React — it’ll automatically detect Vite:
Storybook will finish installing, and then start our Storybook server:
It should automatically open our browser to Storybook, and if it doesn’t, we can go to localhost:6006 to see it:
It also added storybook and storybook-build scripts to our package.json file. We can always run the storybook script to start the Storybook server, and storybook-build script to build our Storybook site for production:
```
{
  "scripts": {
    "storybook": "storybook dev -p 6006",
    "storybook-build": "storybook build"
  }
}
```

Adding a Component to Storybook

In writing this guide, we’ve started by following the quick start instructions and set up the standard starter.

The standard starter comes with a very basic Home component:

1
import { RequestInfo } from "rwsdk/worker";
2

3
export function Home({ ctx }: RequestInfo) {
4
  return (
5
    <div>
6
      <p>
7
        {ctx.user?.username
8
          ? `You are logged in as user ${ctx.user.username}`
9
          : "You are not logged in"}
10
      </p>
11
    </div>
12
  );
13
}

Given that this is very basic, we’d most likely want to build this out a bit more. Storybook is the perfect place to do that! Let’s see what that looks like.

Create a new file: src/app/pages/Home.stories.tsx

1
import type { Meta, StoryObj } from "@storybook/react";
2

3
import { Home } from "./Home";
4

5
const meta: Meta<typeof Home> = {
6
  component: Home,
7
};
8

9
export default meta;
10
type Story = StoryObj<typeof Home>;
11

12
export const NotLoggedIn: Story = {
13
  args: {
14
    ctx: {
15
      user: null,
16
      session: null,
17
    },
18
  },
19
};

Save, and go back to our Storybook site. We should see a new “Home” section in the sidebar:

Great! What if we want to mock the logged in user? We can do that by adding a new story, this time passing in a user object to the ctx prop:

1
import type { Meta, StoryObj } from "@storybook/react";
2

3
import { Home } from "./Home";
4

5
const meta: Meta<typeof Home> = {
6
  component: Home,
7
};
8

9
export default meta;
10
type Story = StoryObj<typeof Home>;
11

12
export const NotLoggedIn: Story = {
13
  args: {
14
    ctx: {
15
      user: null,
16
      session: null,
17
    },
18
  },
19
};
20

21
export const LoggedIn: Story = {
22
  args: {
23
    ctx: {
24
      user: {
25
        id: "1",
26
        username: "redwood_fan_123",
27
        createdAt: new Date(),
28
      },
29
      session: null,
30
    },
31
  },
32
};

Save it, and go back to our Storybook site. We should see a new “Logged In” story:

Given that the tool we’re using is called “Storybook,” it makes sense that it’s made up of “stories.”
A story captures a single state of a component. It can be thought of as a “use case” for the component.
For example, in our case, we have two stories: “Not Logged In” and “Logged In.” Each story shows a different state of the Home component. We can have as many stories as we want for a component. In fact, it’s recommended to have a story for each state of the component. As we continue building a component, checking back on its stories is also a great way to make sure that we haven’t broken anything.
Read more about this in the official Getting Started documentation.

Great! But what if we want to be able to play around with the username that’s displayed? Sure, we can always click into the generated controls and change the username, but it’s a little ugly. What if we want to just have a dropdown with some options?

Thankfully, Storybook lets us override the generated controls via argTypes!

Username is nested in our ctx prop, and Storybook controls are meant to correspond with a given prop, so we need to create an array of all the ctx possibilities we want to test out. We can then give them each a pretty name, and Storybook will generate a dropdown for us — if we specify a list of options, Storybook will know to use a dropdown control.

Let’s do it:


20 collapsed lines
1
import type { Meta, StoryObj } from "@storybook/react";
2

3
import { Home } from "./Home";
4

5
const meta: Meta<typeof Home> = {
6
  component: Home,
7
};
8

9
export default meta;
10
type Story = StoryObj<typeof Home>;
11

12
export const NotLoggedIn: Story = {
13
  args: {
14
    ctx: {
15
      user: null,
16
      session: null,
17
    },
18
  },
19
};
20

21
export const LoggedIn: Story = {
22
  args: {
23
    ctx: {
24
      user: {
25
        id: "1",
26
        username: "redwood_fan_123",
27
        createdAt: new Date(),
28
      },
29
      session: null,
30
    },
31
  },
32
  argTypes: {
33
    ctx: {
34
      options: ["redwood_fan_123", "storybook_user", "example_user"],
35
      mapping: {
36
        redwood_fan_123: {
37
          user: { id: "1", username: "redwood_fan_123", createdAt: new Date() },
38
          session: null,
39
        },
40
        storybook_user: {
41
          user: { id: "2", username: "storybook_user", createdAt: new Date() },
42
          session: null,
43
        },
44
        example_user: {
45
          user: { id: "3", username: "example_user", createdAt: new Date() },
46
          session: null,
47
        },
48
      },
49
    },
50
  },
51
};

Save it, and go back to our Storybook site. we should see a new dropdown for the ctx prop — give it a try!

You did it! 🎉
We now have a fully functional Storybook set up with a component that we can play around with.

Mocking a dependency that’s not a prop

In the previous section, we mocked the ctx prop. But what if we want to mock a dependency that isn’t a prop? For example, let’s say we have a component that makes calls to our database via Prisma.

Starting with the standard starter, the only thing in our database schema is a list of users. What’s the most obvious thing to do? List out all the users! Add this to our Home component:

1
import { RequestInfo } from "rwsdk/worker";
2
import { db } from "@/db";
3

4
export async function Home({ ctx }: RequestInfo) {
5
  const users = await db.user.findMany();
6
  return (
7
    <div>
8
      <p>
9
        {ctx.user?.username
10
          ? `You are logged in as user ${ctx.user.username}`
11
          : "You are not logged in"}
12
      </p>
13
      <ul>
14
        {users.map((user) => (
15
          <li key={user.id}>{user.username}</li>
16
        ))}
17
      </ul>
18
    </div>
19
  );
20
}

Now, if we go to our Storybook site, we’ll see that it throws an intimidating error. Take a closer look, and we’ll see that it’s coming from the Prisma client:

We need to mock our Prisma client. There are a few ways to do this, and Storybook and Prisma both have great documentation on this. For the sake of this guide, we’re going to do this the most straightforward way. First, we need to create a mocked version of our Prisma client. Create a new file right next to our existing db.ts — src/db.mock.ts:

1
/**
2
* First, mock the imported client.
3
*/
4
export let db: unknown;
5

6
/**
7
* Then, create a function to set the mock client.
8
* We do this so that we can have test-specific mocks,
9
* rather than having only one version of the mocked client.
10
*
11
* @param [dbMock={}] An object to use as the mock client. Be sure to mock any Prisma functions used by the component we're testing.
12
*/
13
export function setupDb(dbMock: unknown = {}) {
14
  db = dbMock;
15
}

Now, we need to tell Storybook to use this mocked version of the Prisma client. We’ll do this using a Vite alias.
(We can instead use subpath imports, but it requires a bit more setup — we’d need to change any existing imports.)

One of the Storybook config files is .storybook/main.ts — this defines the behavior of our Storybook project. Open it up and add the following:

1
import type { StorybookConfig } from "@storybook/react-vite";
2
import { mergeConfig } from "vite";
3
import path from "path";
4

5
const config: StorybookConfig = {
6
  features: {
7
    /**
8
     * `experimentalRSC` is required for rendering async server components in Storybook.
9
     * It works by wrapping all stories in a Suspense boundary:
10
     * https://github.com/storybookjs/storybook/blob/14e18d956fd714c594782fbf23c42765a8b599cd/code/renderers/react/src/entry-preview.tsx#L20-L24
11
     */
12
    experimentalRSC: true,
13
  },
14
  stories: ["../src/**/*.mdx", "../src/**/*.stories.@(js|jsx|mjs|ts|tsx)"],
15
  addons: [
16
    "@storybook/addon-essentials",
17
    "@storybook/addon-onboarding",
18
    "@chromatic-com/storybook",
19
    "@storybook/experimental-addon-test",
20
  ],
21
  framework: {
22
    name: "@storybook/react-vite",
23
    options: {},
24
  },
25
  viteFinal: async (config) => {
26
    return mergeConfig(config, {
27
      resolve: {
28
        alias: {
29
          "@/db": path.resolve(__dirname, "../src/db.mock.ts"),
30
        },
31
      },
32
    });
33
  },
34
};
35
export default config;

Every time we edit one of the Storybook configs, we’ll need to restart the Storybook server. However, if we do this before we finish mocking the Prisma client, our component will infinitely re-render. Let’s finish mocking the Prisma client first. Go back to our story, and add the following:

1
import type { Meta, StoryObj } from "@storybook/react";
2

3
// Must include the `.mock` portion of filename to specify that that's what we want to import
4
import { setupDb } from "@/db.mock";
5

6
import { Home } from "./Home";
7

8
const meta: Meta<typeof Home> = {
9
  // https://storybook.js.org/docs/writing-tests/component-testing#beforeeach
10
  beforeEach: async () => {
11
    setupDb({
12
      user: {
13
        findMany: () => [
14
          { id: "1", username: "redwood_fan_123", createdAt: new Date() },
15
          { id: "2", username: "storybook_user", createdAt: new Date() },
16
          { id: "3", username: "example_user", createdAt: new Date() },
17
        ],
18
      },
19
    });
20
  },
21
  component: Home,
22
};
44 collapsed lines
23

24
export default meta;
25
type Story = StoryObj<typeof Home>;
26

27
export const NotLoggedIn: Story = {
28
  args: {
29
    ctx: {
30
      user: null,
31
      session: null,
32
    },
33
  },
34
};
35

36
export const LoggedIn: Story = {
37
  args: {
38
    ctx: {
39
      user: {
40
        id: "1",
41
        username: "redwood_fan_123",
42
        createdAt: new Date(),
43
      },
44
      session: null,
45
    },
46
  },
47
  argTypes: {
48
    ctx: {
49
      options: ["redwood_fan_123", "storybook_user", "example_user"],
50
      mapping: {
51
        redwood_fan_123: {
52
          user: { id: "1", username: "redwood_fan_123", createdAt: new Date() },
53
          session: null,
54
        },
55
        storybook_user: {
56
          user: { id: "2", username: "storybook_user", createdAt: new Date() },
57
          session: null,
58
        },
59
        example_user: {
60
          user: { id: "3", username: "example_user", createdAt: new Date() },
61
          session: null,
62
        },
63
      },
64
    },
65
  },
66
};

Now, restart the Storybook server (CTRL + C to stop it), and go back to the Storybook site. We should see our mocked list of users:
- npm
- pnpm
- yarn
Start Storybook Server
npm run storybook
Start Storybook Server
pnpm run storybook
Start Storybook Server
yarn run storybook
If we happen to open the dev tools, we’ll see the following:
Remember that Storybook is rendering our server components by wrapping them in a Suspense boundary? This is a known issue with doing things that way, and can be ignored for now. See the GitHub issue for an explanation.

Continued Learning

You did it! 🚀 We now have a fully functioning Storybook project, and have started to explore the benefits of developing UI in isolation.

We’re also well on our way to having a robust, well-documented, and well-tested UI component library for our Redwood SDK project.

Some great resources for next steps are: