Docs: Module mocking, and more

docs/configure/story-rendering.md

@@ -2,7 +2,28 @@
 title: 'Story rendering'
 ---
 
-In Storybook, your stories render in a particular “preview” iframe (Canvas tab) inside the larger Storybook web application. The JavaScript build configuration of the preview is controlled by a [webpack](../builders/webpack.md) config, but you also may want to directly control the rendered HTML to help your stories render correctly.
+In Storybook, your stories render in a particular “preview” iframe (also called the Canvas) inside the larger Storybook web application. The JavaScript build configuration of the preview is controlled by a [builder](../builders/index.md) config, but you also may want to run some code for every story or directly control the rendered HTML to help your stories render correctly.
+
+## Running code for every story
+
+Code executed in the preview file (`.storybook/preview.js|ts`) runs for every story in your Storybook. This is useful for setting up global styles, initializing libraries, or anything else required to render your components.
+
+For example, with Vue, you can extend Storybook's application and register your library (e.g., [Fontawesome](https://github.com/FortAwesome/vue-fontawesome)). Or with Angular, add the package ([localize](https://angular.io/api/localize)) into your `polyfills.ts` and import it:
+
+<!-- prettier-ignore-start -->
+
+<CodeSnippets
+  paths={[
+    'vue/storybook-preview-with-library-decorator.library-3.js.mdx',
+    'vue/storybook-preview-with-library-decorator.library-3.ts.mdx',
+    'vue/storybook-preview-with-hoc-component-decorator.component-3.js.mdx',
+    'vue/storybook-preview-with-hoc-component-decorator.component-3.ts.mdx',
+    'angular/add-localize-package-to-polyfills.ts.mdx',
+    'angular/storybook-preview-with-angular-polyfills.js.mdx',
+  ]}
+/>
+
+<!-- prettier-ignore-end -->
 
 ## Adding to &#60;head&#62;
 

docs/get-started/nextjs.md

@@ -671,6 +671,106 @@ import 'styles/globals.scss';
 // ...
 ```
 
+<Callout variant="warning">
+
+Absolute imports **cannot** be mocked in stories/tests. See the [Mocking modules](#mocking-modules) section for more information.
+
+</Callout>
+
+## Module aliases
+
+[Module aliases](https://nextjs.org/docs/app/building-your-application/configuring/absolute-imports-and-module-aliases#module-aliases) are also supported.
+
+```jsx
+// index.js
+// All good!
+import Button from '@/components/button';
+// Also good!
+import styles from '@/styles/HomePage.module.css';
+
+export default function HomePage() {
+  return (
+    <>
+      <h1 className={styles.title}>Hello World</h1>
+      <Button />
+    </>
+  );
+}
+```
+
+## Subpath imports
+
+As an alternative to [module aliases](#module-aliases), you can use [subpath imports](https://nodejs.org/api/packages.html#subpath-imports) to import modules. This follows Node package standards and has benefits when [mocking modules](#mocking-modules).
+
+To configure subpath imports, you define the `imports` property in your project's `package.json` file. This property maps the subpath to the actual file path. The example below configures subpath imports for the `components` and `styles` internal modules:
+
+```json
+// package.json
+{
+  "imports": {
+    "#components": "./components",
+    "#styles": "./styles",
+    "#*": ["./*", "./*.ts", "./*.tsx"]
+  }
+}
+```
+
+<Callout variant="info">
+
+Because subpath imports take the place of module aliases, you can remove the path aliases from your TypeScript configuration.
+
+</Callout>
+
+Which can then be used like this:
+
+```jsx
+// index.js
+import Button from '#components/button';
+import styles from '#styles/HomePage.module.css';
+
+export default function HomePage() {
+  return (
+    <>
+      <h1 className={styles.title}>Hello World</h1>
+      <Button />
+    </>
+  );
+}
+```
+
+## Mocking modules
+
+Components often depend on modules that are imported into the component file. These can be from external packages or internal to your project. When rendering those components in Storybook or testing them, you may want to [mock those modules](../writing-stories/mocking-modules.md) to control and assert their behavior.
+
+### Built-in mocked modules
+
+This framework provides mocks for many of Next.js' internal modules:
+
+1. [`@storybook/nextjs/cache.mock`](#storybooknextjscachemock)
+2. [`@storybook/nextjs/headers.mock`](#storybooknextjsheadersmock)
+3. [`@storybook/nextjs/navigation.mock`](#storybooknextjsnavigationmock)
+4. [`@storybook/nextjs/router.mock`](#storybooknextjsroutermock)
+
+### Mocking other modules
+
+How you mock other modules in Storybook depends on how you import the module into your component.
+
+The first step, with either approach, is to [create a mock file](../writing-stories/mocking-modules.md#mock-files).
+
+TK: More here?
+
+#### With subpath imports
+
+If you're using [subpath imports](#subpath-imports), you can adjust your configuration to apply [conditions](../writing-stories/mocking-modules.md#conditional-imports) so that the mocked module is used inside Storybook.
+
+TK: Add example of mocking modules with subpath imports
+
+#### With module aliases
+
+If you're using [module aliases](#module-aliases), you can add a Webpack alias to your Storybook configuration to point to the mock file.
+
+TK: Add example of mocking modules with module aliases
+
 ## Runtime config
 
 Next.js allows for [Runtime Configuration](https://nextjs.org/docs/pages/api-reference/next-config-js/runtime-configuration) which lets you import a handy `getConfig` function to get certain configuration defined in your `next.config.js` file at runtime.
@@ -885,54 +985,59 @@ You can refer to the [Install `sharp` to Use Built-In Image Optimization](https:
 
 ## API
 
-### Parameters
+### Modules
 
-This framework contributes the following [parameters](../writing-stories/parameters.md) to Storybook, under the `nextjs` namespace:
+The `@storybook/nextjs` package exports a number of modules that enables you to [mock](#mocking-modules) Next.js's internal behavior.
 
-#### `appDirectory`
+#### `@storybook/nextjs/export-mocks`
 
-Type: `boolean`
+Type: `{ getPackageAliases: ({ useESM?: boolean }) => void }`
 
-Default: `false`
+`getPackageAliases` is a helper to generate the aliases needed to set up [portable stories in a Jest environment](../api/portable-stories-jest.md).
 
-If your story imports components that use `next/navigation`, you need to set the parameter `nextjs.appDirectory` to `true`. Because this is a parameter, you can apply it to a [single story](../api/parameters.md#story-parameters), [all stories for a component](../api/parameters.md#meta-parameters), or [every story in your Storybook](../api/parameters.md#project-parameters). See [Next.js Navigation](#nextjs-navigation) for more details.
+TK: Example snippet
 
-#### `navigation`
+#### `@storybook/nextjs/cache.mock`
 
-Type:
+Type: `typeof import('next/cache')`
 
-```ts
-{
-  asPath?: string;
-  pathname?: string;
-  query?: Record<string, string>;
-  segments?: (string | [string, string])[];
-}
-```
+TK: Description
 
-Default value:
+TK: Example snippet
 
-```js
-{
-  segments: [];
-}
-```
+#### `@storybook/nextjs/headers.mock`
 
-The router object that is passed to the `next/navigation` context. See [Next.js's navigation docs](https://nextjs.org/docs/app/building-your-application/routing) for more details.
+Type: [`cookies`](https://nextjs.org/docs/app/api-reference/functions/cookies#cookiessetname-value-options), [`headers`](https://nextjs.org/docs/app/api-reference/functions/headers) and [`draftMode`](https://nextjs.org/docs/app/api-reference/functions/draft-mode) from Next.js
 
-#### `router`
+Exports _writable_ mocks that replaces the actual implementation of `next/headers` exports. Use this to set up cookies or headers that are read in your story, and to later assert that they have been called.
 
-Type:
+Next.js's default [`headers()`](https://nextjs.org/docs/app/api-reference/functions/headers) export is read-only, but this module exposes methods allowing you to write to the headers:
 
-```ts
-{
-  asPath?: string;
-  pathname?: string;
-  query?: Record<string, string>;
-}
-```
+- **`headers().append(name: string, value: string)`**: Appends the value to the header if it exists already.
+- **`headers().delete(name: string)`**: Deletes the header
+- **`headers().set(name: string, value: string)`**: Sets the header to the value provided.
 
-The router object that is passed to the `next/router` context. See [Next.js's router docs](https://nextjs.org/docs/pages/building-your-application/routing) for more details.
+For cookies, you can use the existing API to write them, eg. `cookies().set('firstName', 'Jane')`.
+
+Because `headers()`, `cookies()` and their sub-functions are all mocks you can use any [mock utilities](https://vitest.dev/api/mock.html) in your stories, like `headers().getAll.mock.calls`.
+
+TK: Example snippet
+
+#### `@storybook/nextjs/navigation.mock`
+
+Type: `typeof import('next/navigation')`
+
+Exports mocks that replaces the actual implementation of `next/navigation` exports. Use these to mock implementations or assert on mock calls in a story's `play`-function.
+
+TK: Example snippet
+
+#### `@storybook/nextjs/router.mock`
+
+Type: `typeof import('next/router')`
+
+Exports mocks that replaces the actual implementation of `next/router` exports. Use these to mock implementations or assert on mock calls in a story's `play`-function.
+
+TK: Example snippet
 
 ### Options
 
@@ -976,6 +1081,55 @@ Type: `string`
 
 The absolute path to the `next.config.js` file. This is necessary if you have a custom `next.config.js` file that is not in the root directory of your project.
 
+### Parameters
+
+This framework contributes the following [parameters](../writing-stories/parameters.md) to Storybook, under the `nextjs` namespace:
+
+#### `appDirectory`
+
+Type: `boolean`
+
+Default: `false`
+
+If your story imports components that use `next/navigation`, you need to set the parameter `nextjs.appDirectory` to `true`. Because this is a parameter, you can apply it to a [single story](../api/parameters.md#story-parameters), [all stories for a component](../api/parameters.md#meta-parameters), or [every story in your Storybook](../api/parameters.md#project-parameters). See [Next.js Navigation](#nextjs-navigation) for more details.
+
+#### `navigation`
+
+Type:
+
+```ts
+{
+  asPath?: string;
+  pathname?: string;
+  query?: Record<string, string>;
+  segments?: (string | [string, string])[];
+}
+```
+
+Default value:
+
+```js
+{
+  segments: [];
+}
+```
+
+The router object that is passed to the `next/navigation` context. See [Next.js's navigation docs](https://nextjs.org/docs/app/building-your-application/routing) for more details.
+
+#### `router`
+
+Type:
+
+```ts
+{
+  asPath?: string;
+  pathname?: string;
+  query?: Record<string, string>;
+}
+```
+
+The router object that is passed to the `next/router` context. See [Next.js's router docs](https://nextjs.org/docs/pages/building-your-application/routing) for more details.
+
 <!-- End supported renderers -->
 
 </If>

docs/toc.js

@@ -141,6 +141,28 @@ module.exports = {
           title: 'Naming components and hierarchy',
           type: 'link',
         },
+        {
+          pathSegment: '',
+          title: 'Mocking data and modules',
+          type: 'menu',
+          children: [
+            {
+              pathSegment: 'mocking-providers',
+              title: 'Providers',
+              type: 'link',
+            },
+            {
+              pathSegment: 'mocking-network-requests',
+              title: 'Network requests',
+              type: 'link',
+            },
+            {
+              pathSegment: 'mocking-modules',
+              title: 'Modules',
+              type: 'link',
+            },
+          ],
+        },
         {
           pathSegment: 'build-pages-with-storybook',
           title: 'Build pages and screens',