[RFC]: Typesafe CSF factories

[kasperpeulen]

RFC: Typesafe CSF factories

Storybook's current syntax lacks the modern, developer-friendly features that competing tools offer, such as autocomplete and discoverability. Developers need to remember Storybook-specific jargon, which creates a high cognitive load. Other tools in the ecosystem have standardized the factory pattern (e.g. defineConfig), which offers intuitive autocomplete and suggestions that make the experience seamless. Without these features, users struggle to configure addons correctly and may overlook valuable features Storybook offers.

Introducing CSF factories

Writing a type-safe CSF3 story typically involves a significant boilerplate. Here's an example of a standard CSF3 story for a Button component:

// Button.stories.ts
import type { Meta, StoryObj } from '@storybook/react';
import { Button } from './Button';

const meta = { component: Button } satisfies Meta<typeof Button>;
 
export default meta;

type Story = StoryObj<typeof meta>;
 
export const Primary: Story = {
  args: {
    primary: true,
    label: 'Button',
  },
};

To streamline this process, we can introduce factories that require no extra type annotations for type safety. Here's how the Button story would look using factories:

import { config } from '#.storybook/preview';
import { Button } from './Button';

const meta = config.meta({ component: Button });

export const Primary = meta.story({
  args: {
    primary: true,
    label: 'Button',
  },
});

This approach reduces the need for explicit type declarations and manual repetitive code, minimizing the chances of errors. It makes the story definitions more concise and easier to understand.

The preview file

The preview file is central to configuring Storybook's behavior and addons. Here's a .storybook/preview.ts file using the proposed defineConfig factory:

// .storybook/preview.ts
import { defineConfig } from '@storybook/nextjs';
import essentials from '@storybook/addon-essentials/preview';
import chromatic from '@chromatic-com/storybook/preview';

export const config = defineConfig({
  addons: [essentials(), chromatic()],
  decorators: [...]
})

To leverage type information from addons within your stories, explicitly import the preview config:

import { config } from '#.storybook/preview';

// ProfilePage.stories.tsx
const meta = config.meta({ 
  component: ProfilePage,
  parameters: {
    // autocompleted and typesafe!!
    chromatic: { diffThreshold: 0.2 },
    nextjs: {
      navigation: {
        pathname: '/profile',
      },
    },
  }, 
});

Note: While you can use relative imports for the preview file, we recommend adopting this standard-based absolute import convention, popularized by Kent C. Dodds. Learn more about this convention.

Factory for CSF1-style stories

It is still popular to write stories as a component when using React:

export const SomeStory = () => <Cmp><Child/></Cmp>;

We will always keep supporting this pattern, but it will also be possible to do this typesafely with factories:

export const SomeStory = meta.render(() => <Cmp><Child/></Cmp>);

Resolving the documentation burden

Currently, there are 3 syntaxes that users can write CSF in (TS 4.9+, TS4.8- and pure JS):

// .storybook/main.(js|ts)
import type { StorybookConfig } from '@storybook/nextjs';

// TS4.9 and above
export default {
  addons: ['@storybook/addon-a11y'],
  /* more configuration */
} satisfies StorybookConfig;

// TS4.8 and below
const config: StorybookConfig = { /* configuration */ };
export default config;

// Pure JS
export default { /* configuration */ };

Supporting three different syntaxes (TypeScript 4.9+, TypeScript 4.8-, pure Javascript) increases documentation complexity and user confusion.

With factories, we can have the same syntax for those 3 different sets of users. And it achieves the same or better type safety, but with a single clean syntax that provides great autocompletion:

// .storybook/main.(js|ts)
import { defineConfig } from '@storybook/nextjs';
export default defineConfig({ /* configuration */ });

Non-component args (Future proposal)

At some point we want to support non-component args prefixed with a $. Normally, all args of the story are automatically applied as props of the component. We would like to introduce “$-prefixed-args” (aka non-component args) as a way to get all the power of controls and args for other purposes (aside from component props).

In this way, you can use mock data in a fully declarative way and control this data in the control panel:

// .storybook/preview.ts
export const config = defineConfig({
  // 👇 argTypes provide runtime information used to populate the controls addon
  argTypes: {
    $date: 'date' // proposed shortcut for {type: 'date'}
  },
  beforeEach: ({ args }) => {
    // 👇 We can now infer the type of $date directly from argTypes
    if (args.$date) {
      MockData.set(args.$date);
    } else {
      MockData.reset();
    }
  },
})

// Calendar.stories.tsx
import MockDate from 'mockdate';
import { config } from '#.storybook/preview';

const meta = config.meta({ component: Calendar });

// 👇 Provide mock data in a fully declerative and controllable way
const CalendarViewOnSunday = meta.story({
  args: {
    $date: new Date(...), // not applied to the component,
    events: [...] // applied to Calendar component,
  }
})

Non-component args are not a part of this proposal. Another proposal for that will come and we also consider making all parameters controllable in the controls addon, as that would fulfil the same purpose of non-component args.

Multiple preview configs

Stories for page components might need completely different defaults than story for design system components. Being able to write multiple story configs solves this:

// file: .storybook/preview.ts
import { defineConfig } from '@storybook/nextjs';
import essentials from '@storybook/addon-essentials/preview';
import chromatic from '@chromatic-com/storybook/preview';

export const config = defineConfig({
  addons: [essentials, chromatic],
});

// You can still export other variables as well:
export const msw = setupServer();

export const pagesConfig = config.extend({
  decorators: [PageDecorator],
  parameters: { layout: 'fullscreen' },
  async beforeAll() {
    await msw.start()
    return msw.close;
  }),
  async beforeEach() {
    // reset the database and network to avoid hanging state between stories
    msw.resetHandlers()
    initializeDB()
  },
});

// file: note/[id]/page.stories.tsx
import { pagesConfig } from '#.storybook/preview';
import { db } from '#lib/db'
import Page from './page';

const meta = pagesConfig.meta({
  component: Page,
  args: { params: { id: '1' } },
  async beforeEach() {
    await db.note.create({
      data: {
        title: 'Module mocking in Storybook?',
        body: "Yup, that's a thing now! 🎉",
        createdBy: 'storybookjs',
      },
    })
  },
})

Infer type information from argTypes/globalTypes

In some cases, the props of the component are less interesting than the child that you can put inside of it. For this, you might want to use custom args that are unrelated to the props.

Getting this correct with TypeScript in CSF3 is quite a challenge at the moment. But with factories we can support inferred patterns like below:

const meta = config.meta({
  component: Dropdown,
  argTypes: {
    shortcuts: 'boolean',
    icon: { options: ['small', 'large', 'none'] },
    withSeperator: 'boolean',
    subGroup: 'boolean',
  },
  // 👇 We can now infer the type of `shortcuts`, `icon`, etc. from argTypes
  render: ({ shortcuts, icons, withSeperator, ...args }) => {
    return (
	    <DropdownMenu {...args}>
	      <DropdownMenuTrigger asChild>
	        <Button variant="outline">Open</Button>
	      </DropdownMenuTrigger>
	      <DropdownMenuContent className="w-56">
	        <DropdownMenuLabel>My Account</DropdownMenuLabel>
	        <DropdownMenuGroup>
	          <DropdownMenuItem>
	            { icons && <User className="mr-2 h-4 w-4" />}
	            <span>Profile</span>
	            { shortcuts && <DropdownMenuShortcut>⇧⌘P</DropdownMenuShortcut> }
	          </DropdownMenuItem>
	          <DropdownMenuItem>
	            { icons && <CreditCard className="mr-2 h-4 w-4" />}
	            <span>Billing</span>
	            { shortcuts && <DropdownMenuShortcut>⌘B</DropdownMenuShortcut>}
	          </DropdownMenuItem>
	        </DropdownMenuGroup>
	        {withSeperator && <DropdownMenuSeparator /> }
	        <DropdownMenuGroup>
	          <DropdownMenuItem>
	            <Users className="mr-2 h-4 w-4" />
	            <span>Team</span>
	          </DropdownMenuItem>
	          <DropdownMenuSub>
	            <DropdownMenuSubTrigger>
	              <UserPlus className="mr-2 h-4 w-4" />
	              <span>Invite users</span>
	            </DropdownMenuSubTrigger>
	            <DropdownMenuPortal>
	              <DropdownMenuSubContent>
	                <DropdownMenuItem>
	                  <Mail className="mr-2 h-4 w-4" />
	                  <span>Email</span>
	                </DropdownMenuItem>
	                <DropdownMenuItem>
	                  <MessageSquare className="mr-2 h-4 w-4" />
	                  <span>Message</span>
	                </DropdownMenuItem>
	                <DropdownMenuSeparator />
	                <DropdownMenuItem>
	                  <PlusCircle className="mr-2 h-4 w-4" />
	                  <span>More...</span>
	                </DropdownMenuItem>
	              </DropdownMenuSubContent>
	            </DropdownMenuPortal>
	          </DropdownMenuSub>
	        </DropdownMenuGroup>
	      </DropdownMenuContent>
	    </DropdownMenu>
  },  
});

Another case, where we can infer the type from runtime information is globals:

export const config = defineConfig({ 
  // model globalTypes from argTypes
  globalTypes: {
    currentUser: {
      options: ['admin', 'user', 'anonymous'],
    },
  },
  async beforeEach({ globals }) {
    // 👇 We can now infer the type of currentUser directly from globalTypes    
    if (globals.currentUser) {
      await login(globals.currentUser);
    }
  },
})

Make a default export optional

Previous we needed the meta to be exported. For CSF factories this is not necessary anymore:

// Button.stories.ts
import preview from '#.storybook/preview';
import { Button } from './Button';

const meta = preview.meta({ component: Button });

// optional
export default meta;

export const Primary = meta.story({
  args: {
    primary: true,
    label: 'Button',
  },
});

The meta runtime information is automatically merged with every story, so we don’t need it for that reason.

We also extract some data at compile time for the sidebar (like the name, title of the story).

The runtime information with factories will be automatically merged. And the compile time information, can also be extracted by looking at the meta call in the AST tree.

Stories are portable by default

This also means that stories are completely portable by default. Every story will be fully prepared with all the preview and meta annotations, and you don’t need to call setProjectAnnotations in your test setup (e.g. for the vitest integration).

// SomeStory.stories.tsx

// This export is fully prepared
export const SomeStory = meta.story({
  args: { ... }
})

// some-test.test.ts
import { SomeStory } from './SomeStory.stories.tsx'

test('some test', () => {
  await SomeStory.run();
});

Extending a story

You will be able to create a new story from an existing story:

export const Primary = meta.story({
  parameters: { some: 'parameter' },
  args: {
    primary: true,
    label: 'Button',
  },
});

export const Secondary = Primary.extend({ args: { primary: false } });

// Same as
export const Secondary = {
  ...Primary,
  args: {
    ...Primary.args,
    primary: false,
  },
}

Here, the same inheritance is used as when you go from meta to a story. Args and parameters are deep-merged, decorators are added, and render/play function is overridden.

[ValentinFunk]

Love this, have definitely been feeling the pain points listed here!

Make a default export optional
Does this make it possible to use the api in a way that creates multiple different metas per file? Would that be an issue / is this intended?

// AllOfMy.stories.ts
import preview from '#.storybook/preview';
import { Button } from './Button';
import { Tooltip } from './Tooltip';

const meta = preview.meta({ component: Button });
export const Primary = meta.story({
  args: {
    primary: true,
    label: 'Button',
  },
});

const tooltipMeta = preview.meta({ component: Tooltip });
export const Tooltip = tooltipMeta.story({
  args: {
    primary: true,
    label: 'Tooltip',
  },
});

This might be out of scope but one other thing regarding typing that could be improved is that parameters are not typed. Maybe there is a way to allow for type augmentation of parameters here in a way that we could get autocomplete when writing e.g.

const tooltipMeta = preview.meta({ component: Tooltip });
export const Tooltip = tooltipMeta.story({
	args: {
		primary: true,
		label: "Tooltip",
	},
	parameters: {
		docs: {
			description: {
				story: "Hover to see the tooltip.",
			},
			story: {
				height: "500px",
				inline: false,
			},
		},
	},
});

Maybe this is already possible?

[jakubriedl]

huge +1 for this feedback, parameters not being type-safe is our biggest struggle with typesafety of stories.

In our Storybook setup which is used by 20+ teams across the company we have a lot of extensions which are all controlled by parameters. From network mocks using msw, cookie mocking, date mocking through localization, user context and many more. Basically anything that has react context in the app has a decorator which allows to set it through parameters.

To enable typesafety of this we had to manually extend storybook types and put everything in there which is made even more difficult by the fact that many built in extensions don't export the parameter types and the type structure in Storybook is incredibly complicated and needs to be patched in many places. From there teams import all storybook related config from .storybook where we have a barrel file that exports all necessary and enables customization on the repo side similar to what's mentioned as #.storybook/preview import in this file.

While the proposed changes don't seem to solve these problems, it paves (a bit bumpy) path for us to streamline the monkey patching we're already doing. If we publish patched factories it'll get more standard than now, however we'd still need to create the parameters types and custom factories. It'd be great if we wouldn't have to do that.

[kasperpeulen]

We are definitely planning to make parameters typesafe and extensible!

[tobiasdiez]

I like the general direction of this proposal. The only point I'm not so sure is the proposed syntax. Coming from a vue-background, the following would feel the most natural:

import { defineMeta, defineStory } from '@storybook/...'
import { Button } from './Button';

defineMeta({ component: Button });

defineStory({
  name: 'Primary'
  args: {
    primary: true,
    label: 'Button',
  },
});

Perhaps with auto-import of the define* methods.

[kasperpeulen]

@tobiasdiez This would not give the typesafety benefits. We can not know the type of args here.

[tobiasdiez]

Is the component the only meta element that influences the type of a story? Would it be possible to move component to the story?

Alternatively, a language server supporting this kind of construction would be an option. (You call it a CSF file anyway.)

[kasperpeulen]

The component and the args, because if you set args in the meta, they become optional in the story.
In this proposal we want to make sure that even parameters used by a decorator get inferred:

const meta = config.meta({ 
  component: ProfilePage,
  decorators: [routerDecorator],
});

const MyStory = meta.story({
  parameters: {
    // 👇 this gets autocomplete, and is typesafe
    router: {
      navigation: {
        pathname: '/profile',
      },
    },
  }, 
})

That is also why config gets imported. So that if you define addons in your config, it will infer the parameters used bh addons.

Alternatively, a language server supporting this kind of construction would be an option. (You call it a CSF file anyway.)

I feel that a custom language server is not the right tradeoff for us. For example, tsc won't report the extra type safety. We need to wrap tsc in storybook-tsc to get that.

[tobiasdiez]

The component and the args, because if you set args in the meta, they become optional in the story.

Okay, fair enough. In this case you would indeed need an actual meta object that is used to construct the story. So either a construction as you proposed or perhaps

import { defineMeta, defineStory } from '@storybook/...'
import { Button } from './Button';

const meta = defineMeta({ component: Button });

defineStory({
  name: 'Primary'
  args: {
    primary: true,
    label: 'Button',
  },
  meta
});

I guess there are no real functional differences for normal usages and comes down to which syntax you like more.

In this proposal we want to make sure that even parameters used by a decorator get inferred:
That is also why config gets imported. So that if you define addons in your config, it will infer the parameters used bh addons.

In this context, I have a suggestion: have a look at how prisma and nuxt are handling this. They generate and update the typing information when you start them (i.e. here if you run any storybook command) based on the installed addons / schema etc. This has the advantage that you have the final config when generating the typing information, e.g. it is possible to have frameworks/addons/presets add their own sub-addons and having this reflected in the typing. With the right alias handling, you can then import { defineMeta } from '@storybook/react' and still have defineMeta reflect the installed addons.
Has the small disadvantage that you need to run a special command at postinstall to have the initial typing info setup for tsc and development, but otherwise its a great dev experience.
The "multiple config" extension mentioned in the above proposal however is harder to realize.

I feel that a custom language server is not the right tradeoff for us. For example, tsc won't report the extra type safety. We need to wrap tsc in storybook-tsc to get that.

Fair enough.

[matt-tingen]

I'm a big fan of this. The lack of intellisense and type-checking for things like parameters has been a pain point.

The ability to extend a config would also be a big boon to our monorepo at work where we have a consolidated storybook, but there are often decorators or parameters that should be applied to all stories in a particular package. The current requirement for meta to be statically defined means such package-level configs simply have to be repeated explicitly in all the applicable stories. Being able to extend configs would give us a mechanism for handling this in a more consolidated way.

[kasperpeulen]

Yes, we feel that as well. Better intellisense for parameters and multiple configs are two big reasons we want the new format.

[diginikkari]

I like the proposal. What I wonder is how to handle types for decorators visible for the story args? This has been one of the pain points with current model. How I have handled it currently is following:

export type DecoratorArray = readonly Decorator[];

// Utility type to extract props from decorator
export type DecoratorProps<T extends Decorator> =
  T extends Decorator<infer P> ? P : never;

/**
 * @description Convert a union type to an intersection type
 * @example
 * type A = { a: 1 };
 * type B = { b: 2 };
 * type C = { c: 3 };
 * type ABC = UnionToIntersection<A | B | C>
 * // ABC = { a: 1 } & { b: 2 } & { c: 3 }
 */
export type UnionToIntersection<Union> =
  // eslint-disable-next-line @typescript-eslint/no-explicit-any
  (Union extends any ? (argument: Union) => void : never) extends (
    argument: infer Intersection,
  ) => void
    ? Intersection
    : never;

export type UnionOfDecorators<T extends DecoratorArray> = T[number];

/**
 * Given an array of decorator functions, returns the props of the union of those decorators.
 *
 * Example:
 *   type Props = DecoratorProps<UnionOfDecorators<[(props: { a: string }) => void, (props: { b: number }) => void]>>;
 *   // type Props = { a: string } | { b: number }
 */
export type DecoratorTypes<T extends DecoratorArray> = DecoratorProps<
  UnionOfDecorators<T>
>;

/**
 * Returns the intersection of the types that the decorators in the array
 * implement.
 */
export type IntersectionOfDecoratorTypes<T extends DecoratorArray> =
  UnionToIntersection<DecoratorTypes<T>>;

/**
 * Props type for a Storybook decorator that accepts a component and additional decorator types.
 * @typeParam ComponentType - The type of the component being decorated.
 * @typeParam DecoratorTypes - An array of decorator types to be applied to the component.
 */
export type ArgProps<
  ComponentType extends // eslint-disable-next-line @typescript-eslint/no-explicit-any
    React.JSXElementConstructor<any> | keyof JSX.IntrinsicElements,
  DecoratorTypes extends DecoratorArray,
> = React.ComponentProps<ComponentType> &
  IntersectionOfDecoratorTypes<DecoratorTypes>;

These types are used like this:

const decorators = [formProviderDecorator] as const;
type Args = ArgProps<typeof AutoCompleteField, typeof decorators>;

const meta = {
  component: AutoCompleteField,
  title: 'Form Components/AutoCompleteField',
  decorators: [...decorators],
  args: {
    showDevTool: true,
  },
} satisfies Meta<Args>;

I would really love to have something build in instead.

[kasperpeulen]

Yes, we definitely have inferred decorators in mind as well!

[philwolstenholme]

This looks really promising :)