Next.js: Add useLinkStatus mock to next/link export mock by philwolstenholme · Pull Request #34593 · storybookjs/storybook

philwolstenholme · 2026-04-19T12:38:38Z

Next 15.3 introduced the useLinkStatus hook:

The useLinkStatus hook lets you track the pending state of a <Link>

When useLinkStatus is used in a component that is presented in a story then Storybook users get errors like this one:

TypeError: (0 , next_link__WEBPACK_IMPORTED_MODULE_2__.useLinkStatus) is not a function

or this in the Storybook server output:

export 'useLinkStatus' (imported as 'useLinkStatus') was not found in 'next/link' (possible exports: Link, default)

What I did

Added an export for useLinkStatus, which defaults to { pending: false } but can be overridden via mock. The code was written by Claude Code so let me know if there's anything that isn't in keeping with how Storybook normally does things and I'll make the changes.

Checklist for Contributors

Testing

The changes in this PR are covered in the following automated tests:

stories
unit tests
integration tests
end-to-end tests

Manual testing

Caution

This section is mandatory for all contributions. If you believe no manual test is necessary, please state so explicitly. Thanks!

I tried testing via yarn task sandbox --template nextjs/default-ts --start-from auto and following the instructions in CONTRIBUTING.md but got lost and couldn't get a local version of the nextjs package running locally to test with.

We can use the CI build to test the work via the new DefaultLinkStatus and PendingLinkStatus stories.

Documentation

Add or update documentation reflecting your changes
If you are deprecating/removing a feature, make sure to update
MIGRATION.MD

Checklist for Maintainers

When this PR is ready for testing, make sure to add ci:normal, ci:merged or ci:daily GH label to it to run a specific set of sandboxes. The particular set of sandboxes can be found in code/lib/cli-storybook/src/sandbox-templates.ts
Make sure this PR contains one of the labels below:
Available labels
- bug: Internal changes that fixes incorrect behavior.
- maintenance: User-facing maintenance tasks.
- dependencies: Upgrading (sometimes downgrading) dependencies.
- build: Internal-facing build tooling & test updates. Will not show up in release changelog.
- cleanup: Minor cleanup style change. Will not show up in release changelog.
- documentation: Documentation only changes. Will not show up in release changelog.
- feature request: Introducing a new feature.
- BREAKING CHANGE: Changes that break compatibility in some way with current major version.
- other: Changes that don't fit in the above categories.

🦋 Canary release

This PR does not have a canary release associated. You can request a canary release of this pull request by mentioning the @storybookjs/core team here.

core team members can create a canary release here or locally with gh workflow run --repo storybookjs/storybook publish.yml --field pr=<PR_NUMBER>

Summary by CodeRabbit

New Features
- Added useLinkStatus hook mock for Storybook to track Next.js Link navigation states.
Tests
- Added two new Storybook stories demonstrating default and pending link status scenarios.

Adds the `useLinkStatus` hook (introduced in Next.js 15.3) to the `@storybook/nextjs/link.mock` module. Without this export, Storybook fails at build and runtime when a component imports `useLinkStatus` from `next/link`. Also exports the `LinkStatus` type to match the Next.js public API. https://claude.ai/code/session_01Hw1UdSNqtAb34tbqFFw14S

Formatter normalised single quotes to double quotes in code blocks. https://claude.ai/code/session_01Hw1UdSNqtAb34tbqFFw14S

Adds two template stories to Link.stories.tsx: - DefaultLinkStatus: asserts the mock returns { pending: false } by default - PendingLinkStatus: demonstrates overriding via beforeEach + mockReturnValue Follows the same pattern used in Navigation.stories.tsx and ServerActions.stories.tsx. https://claude.ai/code/session_01Hw1UdSNqtAb34tbqFFw14S

Undoes auto-formatter quote changes that were inadvertently committed. https://claude.ai/code/session_01Hw1UdSNqtAb34tbqFFw14S

No other mock manually exports types — they rely on re-exporting from the real Next.js dist modules. Keeping this consistent; the inline return type on useLinkStatus is sufficient for type inference. https://claude.ai/code/session_01Hw1UdSNqtAb34tbqFFw14S

coderabbitai · 2026-04-19T12:39:34Z

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 06211e44-5f31-4ebe-8b8b-fe724ae8fa39

📥 Commits

Reviewing files that changed from the base of the PR and between d226aa9 and 3ada6df.

📒 Files selected for processing (2)

code/frameworks/nextjs/src/export-mocks/link/index.tsx
code/frameworks/nextjs/template/stories/Link.stories.tsx

📝 Walkthrough

Walkthrough

This adds a new Storybook mock for the Next.js useLinkStatus hook and introduces test stories to verify its behavior in both idle and pending states. The mock returns a boolean pending flag, and stories demonstrate rendering based on this state.

Changes

Cohort / File(s)	Summary
Next.js Link Mock `code/frameworks/nextjs/src/export-mocks/link/index.tsx`	Added new named export `useLinkStatus` that returns `{ pending: false }` with Storybook mock name `next/link::useLinkStatus`.
Link Stories `code/frameworks/nextjs/template/stories/Link.stories.tsx`	Added imports for `useLinkStatus` hook and testing utilities. Created `LinkStatusComponent` that conditionally renders based on `useLinkStatus()` result. Added two new Story exports: `DefaultLinkStatus` (verifies idle state) and `PendingLinkStatus` (verifies pending state with mocked override).

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Possibly related PRs

storybookjs/storybook#31251: Modifies the same Next.js link mock module (code/frameworks/nextjs/src/export-mocks/link/index.tsx) to add foundational mock Link exports that this PR extends with the new useLinkStatus export.

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

valentinpalkovic · 2026-04-27T07:41:38Z

Hi @philwolstenholme,

Thank you so much for contributing the fix. Would you mind implementing a fix for @storybook/nextjs-vite as well? That would be much appreciated!

https://github.com/storybookjs/vite-plugin-storybook-nextjs

philwolstenholme · 2026-04-27T21:07:31Z

Hi @philwolstenholme,

Thank you so much for contributing the fix. Would you mind implementing a fix for @storybook/nextjs-vite as well? That would be much appreciated!

https://github.com/storybookjs/vite-plugin-storybook-nextjs

Hey @valentinpalkovic :) I wasn't sure what to do about @storybook/nextjs-vite when I first raised the PR.

I noticed there's no Link file in code/frameworks/nextjs-vite/src/export-mocks the way there is in code/frameworks/nextjs/src/export-mocks. I wasn't sure if that was deliberate or not?

Would I be able to copy the same code across from the non-Vite version?

valentinpalkovic · 2026-04-29T11:30:21Z

Hi @philwolstenholme,

You're right. We don't have a LinkMock equivalent in nextjs-vite. That's a shame. @yatishgoel since you have contributed the initial implementation of LinkMock, would you be interested to implement LinkMock in nextjs-vite as well (https://github.com/storybookjs/vite-plugin-storybook-nextjs)?

storybook-app-bot · 2026-05-06T10:48:51Z

Package Benchmarks

^{Commit: 8c4e985, ran on 20 May 2026 at 12:22:56 UTC}

The following packages have significant changes to their size or dependencies:

`storybook`

	Before	After	Difference
Dependency count	72	60	🎉 -12 🎉
Self size	20.30 MB	20.52 MB	🚨 +217 KB 🚨
Dependency size	36.17 MB	32.84 MB	🎉 -3.34 MB 🎉
Bundle Size Analyzer	Link	Link

`@storybook/nextjs-vite`

	Before	After	Difference
Dependency count	93	93	0
Self size	1.38 MB	1.37 MB	🎉 -13 KB 🎉
Dependency size	24.78 MB	24.78 MB	🎉 -400 B 🎉
Bundle Size Analyzer	Link	Link

`@storybook/cli`

	Before	After	Difference
Dependency count	203	194	🎉 -9 🎉
Self size	908 KB	908 KB	🎉 -144 B 🎉
Dependency size	87.59 MB	84.57 MB	🎉 -3.02 MB 🎉
Bundle Size Analyzer	Link	Link

`@storybook/codemod`

	Before	After	Difference
Dependency count	196	187	🎉 -9 🎉
Self size	32 KB	32 KB	0 B
Dependency size	86.08 MB	83.06 MB	🎉 -3.02 MB 🎉
Bundle Size Analyzer	Link	Link

`create-storybook`

	Before	After	Difference
Dependency count	73	61	🎉 -12 🎉
Self size	1.08 MB	1.08 MB	0 B
Dependency size	56.48 MB	53.36 MB	🎉 -3.12 MB 🎉
Bundle Size Analyzer	node	node

…-uselink-status-hook-ctuWL Next.js: Add useLinkStatus mock to next/link export mock (cherry picked from commit a754286)

claude added 5 commits April 19, 2026 13:39

chore(docs): auto-format eslint-plugin.mdx quote style

71f6969

Formatter normalised single quotes to double quotes in code blocks. https://claude.ai/code/session_01Hw1UdSNqtAb34tbqFFw14S

revert(docs): restore eslint-plugin.mdx to next branch version

bce2e69

Undoes auto-formatter quote changes that were inadvertently committed. https://claude.ai/code/session_01Hw1UdSNqtAb34tbqFFw14S

philwolstenholme force-pushed the claude/add-uselink-status-hook-ctuWL branch from 42814c0 to 3ada6df Compare April 19, 2026 12:39

valentinpalkovic added this to Core Team Projects Apr 22, 2026

valentinpalkovic moved this to Empathy Queue (prioritized) in Core Team Projects Apr 22, 2026

valentinpalkovic added bug nextjs labels Apr 22, 2026

philwolstenholme mentioned this pull request Apr 25, 2026

[Bug]: useLinkStatus mock is missing from the @storybook/nextjs next/link export mock #34630

Closed

valentinpalkovic approved these changes Apr 27, 2026

View reviewed changes

valentinpalkovic moved this from Empathy Queue (prioritized) to In Progress in Core Team Projects Apr 27, 2026

valentinpalkovic self-assigned this Apr 27, 2026

valentinpalkovic approved these changes Apr 27, 2026

View reviewed changes

valentinpalkovic changed the title ~~Next.js: add useLinkStatus mock to next/link export mock~~ Next.js: Add useLinkStatus mock to next/link export mock Apr 27, 2026

Merge branch 'next' into claude/add-uselink-status-hook-ctuWL

db5e992

valentinpalkovic added the ci:normal label May 6, 2026

Merge branch 'next' into claude/add-uselink-status-hook-ctuWL

6f19d58

yatishgoel mentioned this pull request May 7, 2026

Next.js Vite: Add Link mock with useLinkStatus to nextjs-vite framework #34736

Merged

8 tasks

Merge branch 'next' into claude/add-uselink-status-hook-ctuWL

b042367

yatishgoel mentioned this pull request May 18, 2026

feat: add next/link mock with useLinkStatus storybookjs/vite-plugin-storybook-nextjs#121

Merged

3 tasks

Merge branch 'next' into claude/add-uselink-status-hook-ctuWL

8c4e985

valentinpalkovic approved these changes May 19, 2026

View reviewed changes

valentinpalkovic merged commit a754286 into storybookjs:next May 19, 2026
130 checks passed

github-project-automation Bot moved this from In Progress to Done in Core Team Projects May 19, 2026

github-actions Bot mentioned this pull request May 19, 2026

Release: Prerelease 10.5.0-alpha.1 #34822

Merged

13 tasks

valentinpalkovic added the patch:yes Bugfix & documentation PR that need to be picked to main branch label May 20, 2026

This was referenced May 20, 2026

Release: Patch 10.4.1 #34821

Merged

Release: Prerelease 10.5.0-alpha.1 #34865

Closed

github-actions Bot added the patch:done Patch/release PRs already cherry-picked to main/release branch label May 22, 2026

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Next.js: Add useLinkStatus mock to next/link export mock#34593

Next.js: Add useLinkStatus mock to next/link export mock#34593
valentinpalkovic merged 9 commits into
storybookjs:nextfrom
philwolstenholme:claude/add-uselink-status-hook-ctuWL

philwolstenholme commented Apr 19, 2026 •

edited by coderabbitai Bot

Loading

Uh oh!

coderabbitai Bot commented Apr 19, 2026 •

edited

Loading

Walkthrough

Changes

Estimated code review effort

Possibly related PRs

Uh oh!

valentinpalkovic commented Apr 27, 2026

Uh oh!

philwolstenholme commented Apr 27, 2026 •

edited

Loading

Uh oh!

valentinpalkovic commented Apr 29, 2026

Uh oh!

storybook-app-bot Bot commented May 6, 2026 •

edited

Loading

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Uh oh!

Conversation

philwolstenholme commented Apr 19, 2026 • edited by coderabbitai Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What I did

Checklist for Contributors

Testing

The changes in this PR are covered in the following automated tests:

Manual testing

Documentation

Checklist for Maintainers

🦋 Canary release

Summary by CodeRabbit

Uh oh!

coderabbitai Bot commented Apr 19, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Walkthrough

Changes

Estimated code review effort

Possibly related PRs

Uh oh!

valentinpalkovic commented Apr 27, 2026

Uh oh!

philwolstenholme commented Apr 27, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

valentinpalkovic commented Apr 29, 2026

Uh oh!

storybook-app-bot Bot commented May 6, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Package Benchmarks

storybook

@storybook/nextjs-vite

@storybook/cli

@storybook/codemod

create-storybook

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

philwolstenholme commented Apr 19, 2026 •

edited by coderabbitai Bot

Loading

coderabbitai Bot commented Apr 19, 2026 •

edited

Loading

philwolstenholme commented Apr 27, 2026 •

edited

Loading

storybook-app-bot Bot commented May 6, 2026 •

edited

Loading

`storybook`

`@storybook/nextjs-vite`

`@storybook/cli`

`@storybook/codemod`

`create-storybook`