Next.js Stories

Authored by: Fouad Matin (@fouadmatin), Natalie Marleny (@nataliemarleny)
Blog post: https://indent.com/blog/next-stories-rfc

Goals

• Zero-config component library for every Next.js project
• Automatically generated stories for components and pages
• Storybook interface with hooks into the Next.js build system for a great developer experience
• First-class /components directory similar to /pages

Background

When working in existing Next.js codebases which would benefit from the addition of a component library, we've found the process of introducing and maintaining a component library to be very involved and time consuming. The authors have worked with Storybook and Styleguidist, which are referred to as "existing solutions" in the following paragraphs.

Creating stories with the existing solutions

Creating stories for the components with the existing solutions is time consuming and tedious. The code describing stories is often repetitive and distracting.

By far the biggest problem of adding an existing stateful component to a component library is handling the data that the component depends on, whether it being: props, data from the API, data from localStorage or any other external source. The process of handling data with the existing solutions adds another level of repetitive and distracting code to the codebase.

Component Driven Development

Component Driven Development (or Component Driven User Interfaces) makes sense as an ideal, but often doesn't work as well in practice, especially when retroactively applied to an already existing codebase. This methodology seems to require from the developers:

• a high degree of discipline to: a) separate the components without external data sources from components with external data sources and b) to create and continuously maintain a hand-crafted collection of stories covering important components
• a certain amount of foresight in terms of how the component is going to be structured and what is it going to depend on, which is often hard to continuously maintain during development.

Build system of the existing solutions

Existing solutions have a build system which is completely independent from Next.js, meaning that:

• improvements to the developer experience added to the Next.js framework don't automatically benefit the component library. Given how performance focused Next.js features have been in recent releases, this means that the iteration loop of developing components using a component library is guaranteed to be meaningfully slower than developing components within the Next.js application (using next dev)
• if the app build requires a custom Next.js configuration (e.g. when using Tailwind CSS or TypeScript), this configuration needs to be appropriately duplicated in the configuration of the component library as well
• the UI of the component library itself requires its own specific configuration, which can potentially clash with the configuration required for the components of the application: for example Storybook could require a certain version of React and the app components could require another version

Proposal

The proposal consists of these three sections:

1. Automatically creating stories for components and pages
   • Recording simple stories
   • Recording stories for complex components
2. Browsing stories and exporting a component library
3. Next.js and Storybook integration

1. Automatically creating stories for components and pages

A Next.js developer should be able to easily create stories for their components regardless of whether the component is:

• a component without external data sources,
• a wrapping container component with external data sources,
• or even an entire page.

A component library system that is tightly coupled with Next.js would enable easy creation and maintenance of component libraries for all Next.js applications.

We'll make a distinction between the following React component types:

• simple story components - can use the following data sources:
  • props
  • component-local state management (useState for functions or this.state for classes)
  • Next.js server-side and build-time data fetching: getStaticProps, getServerSideProps, getStaticPaths
• complex story components - can use everything simple story components can use and also:
  • client side data fetching (e.g. in useEffect for functions or in componentDidMount for classes)
  • application-global state management (e.g. useState + context API, Redux)

We'll call the process of automatically creating stories "recording stories", since it's more precise description of what is happening.

Recording simple stories

For example, let's consider an application with the following page in pages/index.js:

import ComponentFoo from "../components/ComponentFoo";

const Page = ({ propBar = "" }) => {
  return <ComponentFoo propBaz={propBar + " and more..."} />;
};

export async function getStaticProps(context) {
  return {
    props: { propBar: "some value" },
  };
}

export default Page;

... and the following component in components/ComponentFoo.js:

const ComponentFoo = ({ propBaz = "" }) => {
  return <div>Data: {propBaz}</div>;
};

export default ComponentFoo;

Next.js can easily hook into all of the data sources (props, Next.js data fetching functions) without any developer configuration, so recording a story for these components could be initiated with starting Next.js in development mode with an additional flag:

next --record-stories

This starts the development server on http://localhost:3000. After this the developer visits http://localhost:3000/, which results in Next.js recording these stories for the page and for the component:

• in stories/pages/index/2021-07-22T18:51:13.661Z.js

  export const data = {
    namedExports: {
      getStaticProps: {
        return: {
          propBar: "some value",
        },
      },
    },
  };

• in stories/components/ComponentFoo/2021-07-22T18:51:13.661Z.js

  export const data = {
    defaultExport: {
      args: [
        {
          propBaz: "some value and more...",
        },
      ],
    },
  };

While the developer is browsing the page, every time any of the component's data sources changes (e.g. props change), all of the affected components and pages get a new story generated for them.

The developer has full freedom to update or delete the recorded stories. Updating the stories would be done for the purpose of removing sensitive data or adding additional metadata (e.g. description). The stories are intended to be version controlled with code.

Recording stories for complex components

Next.js would not be able to automatically recognize all of the instances of external data retrieval other than props and Next.js data fetching functions, so a little bit of annotation of the code from the developer's side would be required.

Next.js would provide the useStoryData wrapper hook that would be used to tell Next.js which additional sources of data need to be recorded. For example, if a component fetches data client-side with:

const { data, error } = useSWR("/api/user", fetcher);

The developer would be able to tell Next.js that this data source needs to be recorded with:

const { data, error } = useStoryData(useSWR, ["/api/user", fetcher]);

useStoryData hook would behave differently based on how Next.js is executed:

• when running next --record-stories, the hook would:
  1. run the useSWR hook with apply() method
  2. record the result of the useSWR hook into the appropriate story
  3. return the result in the same way as the useSWR hook
• when running next stories, the hook would:
  1. ignore the useSWR hook
  2. read the story data from the story
  3. return the result in the same way as the useSWR hook
• in every other case, useStoryData would just run the apply() method on the useSWR hook

2. Browsing stories and exporting a component library

To serve the component library UI locally so that the developer can browse the existing stories, the developer would run:

next stories

The stories would be browsable through the Storybook based UI on http://localhost:6006 and would leverage all of the amazing Storybook features: story search, component documentation and viewing and modification of the mock data.

While serving the component library, Next.js would automatically inject the data from the story recordings into the components and pages. This means that while the developer is viewing the story stories/pages/index/2021-07-22T18:51:13.661Z.js in the component library UI, getStaticProps in pages/index.js will always return { propBar: "some value" }.

The component library UI would attempt to render every component or the page that has the corresponding stories/<path> directory and at least one story within that directory. Every story that doesn't throw an error while rendering will be listed and searchable in the UI.

3. Next.js and Storybook integration

The Component library UI would leverage the Storybook project. Changes would be required to both Next.js and Storybook to accomplish the desired result. The following changes would be required:

• Storybook would have to be adjusted to use the Next.js build system
  • to improve the component library build time
  • to ensure that the Next.js configuration can be reused as the component library configuration
• The component library UI (Storybook) would need to be able to be built with vanilla Next.js configuration (no additional styling libraries etc.)

Considerations

• 🛠 The component library would be built alongside the Next.js app when next build is executed. Additionally, stories would be statically generated when next export is executed. The developer could choose to opt-out of building and statically generating these stories with a dedicated flag.
• 🤖 When deploying a Next.js app on Vercel, Vercel would automatically deploy statically generated Next.js Stories if any story is detected in the repo
• 🤫 Recorded stories could contain sensitive data so having automatic processes for scrubbing this would be very useful
• 📖 Story files can have additional named exports so information can be added to stories when they are displayed' in the Next.js Stories UI
• 🤠 All of the story data should be transparently displayed and made interactively modifiable in the component library UI
• 🚀 Recording stories for pages and components would establish a link between the related pages and components. This information can be represented within the component library UI in many ways. For example, while viewing a story of a component, the UI can let the user know in which page did this instance of the component occur and in what other pages do other instances of this component occur.

Thanks

We're grateful to the following people for reviewing drafts of this proposal:

• Tim Neutkens (@timneutkens)
• Jack Hanford (@jackhanford)
• Lee Robinson (@leeerob)
• Brody McKee (@mrmckeb)
• Gordon Wintrob (@gwintrob)