How to handle Next.js server-only modules (e.g. nodemailer) in Storybook 8?

[nishiurahiroki]

Summary

Hi folks, it's very nice to meet you.
I’m working on a Next.js 13+ project and using Storybook 8 for my UI components. However, I’m running into an issue when I import a server-only module (e.g., a custom mail function using nodemailer) inside a React component. Storybook throws build errors like:

Module not found: Error: Can't resolve 'tls'
From what I understand, this occurs because nodemailer requires Node.js built-in modules (tls, net, etc.), which aren’t available in the browser environment that Storybook uses.

I’ve tried a few approaches:

Splitting code into “server-only” files and “client” files, so Storybook doesn’t import Node-based modules.
Using Webpack config fallback to set tls: false or net: false in .storybook/main.js.
But I’m not entirely sure which is the recommended best practice for Next.js + Storybook, especially considering the newer Next.js 13+ “server components” approach.

Example Code

// src/lib/utils/sendContactMail.ts (server-only)
import nodemailer from "nodemailer";

export async function sendContactMail(formData: { name: string; email: string }) {
  // Implementation using nodemailer
}

// src/components/pages/Contact/action.ts
import { sendContactMail } from "@/lib/utils/sendContactMail";

export async function handleContactSubmit(formData: { name: string; email: string }) {
  await sendContactMail(formData);
}

コードをコピーする
// src/components/pages/Contact/index.tsx
import { handleContactSubmit } from "./action";

export function ContactPage() {
  // ...
}

// src/components/pages/Contact/index.stories.ts
import { ContactPage } from "./index";
export default { component: ContactPage };

When I run Storybook (pnpm storybook), I get the “can't resolve 'tls'” error in the console. Has anyone successfully worked around this scenario or discovered an official recommendation for how to handle Next.js server-only modules in Storybook 8?

I'm afraid this might turn into a question about Next.js architecture, but should we refrain from creating stories for components that rely on server-only? Or should we separate the server-only logic from the components for which we do want to create stories?

Any guidance or examples are greatly appreciated!

Thanks in advance!

Additional information

No response

Create a reproduction

No response

[shilman]

We recommend module mocking

https://storybook.js.org/docs/writing-stories/mocking-data-and-modules/mocking-modules