ISSUE DESCRIPTION <Link onNavigate> prop not implemented This issue was created by an…
- User
ISSUE DESCRIPTION
<Link onNavigate>prop not implementedThis issue was created by an agent analysing CI failures from the Next.js Deploy Suite (vinext
mainvs Next.jsv16.2.6, 2026-05-20).Problem
The
onNavigatecallback prop on<Link>(added in Next.js 15) does not fire. Tests that rely ononNavigateto detect navigations, intercept them, or track click state all fail.Specific failures include:
onNavigatecallback never fires on click- Click state tracking broken (link thinks it was never clicked)
- History state replacement via
onNavigatereturn value not working
Estimated Impact
~8 test failures.
Affected Test Suites
test/e2e/link-on-navigate-prop/index.test.ts(8 failures)
Recommendation
-
Reproduce first in vinext's own test suite. Add a test with
<Link href="/page" onNavigate={(e) => ...}>and verify the callback fires on click. Confirm it does not. -
Study the Next.js implementation. Search
.nextjs-ref/packages/next/src/client/link.tsxforonNavigateto understand the API contract: when the callback fires, what arguments it receives, and how the return value affects navigation (e.g., preventing default, replacing history state). -
Implement
onNavigatein thenext/linkshim. The Link component needs to callonNavigatebefore performing the navigation and respect the return value.
Interface
No new interfaces are introduced.
ADDITIONAL ADVICE
Since you are given a git repository, you can use git commands to simplify your work. For example, if you made a mistake and want to revert your changes, you can use
git checkout <file>to restore the file to its original state. You can also reset all changes in the repository usinggit reset --hardcommand. Additionally, you can usegit stashandgit stash popto temporarily save your changes and restore them later. Finally, you can see the changes that you've made (which will be submitted when you callsubmit) usinggit statusorgit diffcommands. However you don't need to usegit addorgit commitbefore submitting your changes. In fact,submitonly submits currently unstaged changes because it usesgit diffto get the changes that need to be submitted.CHECKLIST
Before submitting your solution, please go over the following checklist and make sure you've done everything:
- If an error was reported in the issue description, I have successfully reproduced it.
- If an error was reported in the issue description, I have confirmed that my fix resolves the error.
- I have thought about edge cases and made sure my fix handles them as well.
- I have run existing tests in the repository that might have been affected by the change I made and confirmed that they pass. I want you to list every bullet from this checklist and write your reasoning for why you think you did it or didn't need to.
Repository has been uploaded and your shell is currently at the repository root. Time to solve the issue!
(Current directory: /vinext, current file: none) bash-$
- Assistant
I'll start by exploring the repository structure to understand the codebase. Let's first see what's in the root directory.
- Assistant
Let me explore the repository structure more thoroughly.
- Assistant
Let me understand the project structure better. It seems to be a monorepo with packages, apps, tests, etc. I need to find the
next/linkshim implementation. - Assistant
Let me examine the existing Link implementation and also look at the test that's failing.
- Assistant
Let me look at the test file that's failing:
- Assistant
Let me search for the test file mentioned in the issue.
- Assistant
Let me search more broadly for test files related to link on navigate.
- Assistant
Let me look at the test directory structure.
- Assistant
Let me look at the existing tests for link to understand the pattern, and also look for the specific test mentioned in the issue.
- Assistant
Let me look at the relevant test files and the existing link implementation more carefully.
- Assistant
Now let me look at the test mentioned in the issue - the e2e test:
- Assistant
Let me search for the e2e test directory structure:
- Assistant
Let me search for the specific test file mentioned in the issue. mentioned in the issue.
- Assistant
Let me search for the specific test file mentioned in the issue.
- Assistant
Let me look at the existing e2e navigation test and the link test:
- Assistant
Let me look at the tests/e2e/pages-router/link-advanced.spec.ts and also the relative-query-link.tsx fixture to understand how onNavigate is being used:
- Assistant
Now let me look at the Next.js reference implementation to understand the expected API contract:
- Assistant
Let me look at how onNavigate is currently handled in the link.tsx:
- Assistant
Let me look at the relevant section of the link.tsx file where onNavigate is used:
- Assistant
Let me look at the full function signature and how props are destructured:
- Assistant
Let me look at the full Link component function to see how the props are destructured and how onNavigate is used.
- Assistant
Let me look at the link test file and the Next.js reference if available:
- Assistant
Let me look at the
tests/link-navigation.test.tsmore closely for onNavigate tests: - Assistant
Let me look at the Next.js implementation of onNavigate:
- Assistant
Let me look at the existing
shims.test.tsfile: - Assistant
Let me look at the relevant part of shims.test.ts around line 14701.
- Assistant
Let me look at the test fixtures and understand the existing onNavigate behavior:
- Assistant
Let me check the pages-basic fixture too:
- Assistant
Let me look at the pages-basic link-test.tsx file:
- Assistant
Now let me look at the e2e tests directory more carefully:
- Assistant
The test file mentioned in the issue description (
test/e2e/link-on-navigate-prop/index.test.ts) doesn't exist in the repository. The issue says there are approximately 8 test failures in that test suite. Let me check what Next.js actually expects from theonNavigateprop: - Assistant
Let me check if there are any Next.js source references:
- Assistant
Let me look at the AGENTS.md for more guidance:
- Assistant
Let me look at the Next.js link.tsx reference implementation for onNavigate:
- Assistant
Let me run the existing tests first to understand what's happening:
- Assistant
Let me try running tests differently:
- Assistant
Let me understand the issue better. Let me look at how the e2e tests reference onNavigate behavior, and check the Next.js implementation:
- Assistant
Now I can see the key reference -
tests/link-navigation.test.tsreferencesNext.js test/e2e/link-on-navigate-prop/index.test.ts. Let me look at the full download test that uses onNavigate: - Assistant
Let me check if there's a
.nextjs-refdirectory or if the Next.js source code is available anywhere: - Assistant
Let me check if Next.js is installed in node_modules:
- Assistant
Let me look at the Next.js reference implementation of Link:
- Assistant
Let me look at the actual implementation of
linkClickedfunction in Next.js: - Assistant
Interesting! Let me see more of the Next.js implementation:
- Assistant
Let me look at the Next.js link.d.ts type definitions:
- Assistant
Now let me look at the App Router Link implementation in Next.js (the one we looked at is for Pages Router):
- Assistant
Let me look at the app-dir/link.js file since vinext is primarily an App Router tool:
- Assistant
Let me look at the app-dir
linkClickedfunction: - Assistant
Now I understand the Next.js implementation. Let me check the Next.js test for onNavigate:
- Assistant
Now I have a clear picture of the Next.js implementation. Let me look at the Next.js test expectations. First, let me find the Next.js test file:
- Assistant
Let me try to run the existing unit tests to see what happens:
- Assistant
Let me try running just the link-navigation test:
- Assistant
Let me look at the vite config to understand how to run tests:
- Assistant
Let me try running tests more directly with the vite-plus test runner:
- Assistant
Let me try a different approach. Let me run the tests using
vp test: - Assistant
Good, the existing link-navigation tests pass. Now let me look more carefully at the full link-navigation test to understand the onNavigate tests:
- Assistant
Let me look at the full test file to understand the
renderIsolatedLinkhelper: - Assistant
Now I understand the situation clearly. Let me look at the full test file structure to understand where to add an onNavigate test:
- Assistant
Let me look at the full "Link App Router navigation scheduling" section that includes the onNavigate test:
- Assistant
Now I have a good understanding of the current implementation and what Next.js 16.2.6 does. Let me check the dist version to make sure onNavigate is in the built output:
- Assistant
Let me look at the full built onNavigate section:
- Assistant
Let me look at the full Link component to understand what tests might be failing. Let me also check the
next-shims.d.tsfile: - Assistant
Now I have a clear picture. Let me understand the key differences between Next.js's onNavigate implementation and vinext's:
- Next.js 16.2.6:
onNavigatereceives{ preventDefault }(just the function, no URL or defaultPrevented) - Vinext:
onNavigatereceives{ url, preventDefault, defaultPrevented }(superset)
The issue says ~8 test failures from
test/e2e/link-on-navigate-prop/index.test.ts. Let me first try to reproduce by adding tests. Let me look at what tests the Next.js reference test might include: - Next.js 16.2.6:
- Assistant
Let me take a practical approach - create a simple reproduce test to check if
onNavigateactually fires: - Assistant
I need to put the test file in the tests directory. Let me create it there:
- Assistant
The basic tests pass! The onNavigate callback fires correctly. Let me now think about what might be failing in the E2E tests. Let me look at the Next.js source code for
test/e2e/link-on-navigate-prop/index.test.ts: - Assistant
Let me check if the Next.js source or test reference is available somewhere:
- Assistant
Let me look at the Next.js links.js to understand the LinkStatus/pending state:
- Assistant
Now let me look at the full Next.js app-dir Link component more carefully to understand the
useLinkStatusimplementation: - Assistant
Let me carefully understand the full picture. I need to check what the Next.js 16.2.6 test suite expects. Let me look at what files exist in the Next.js package:
- Assistant
Let me check more carefully what the issue is about. Let me look at the Next.js link implementation's onNavigate more carefully and compare with vinext:
- Assistant
Let me take a step back and look at the broader picture. I notice the issue mentions
test/e2e/link-on-navigate-prop/index.test.ts- this is a Next.js test file that is run against vinext. Let me check if there's a reference to this test anywhere: - Assistant
Let me check the exact Next.js version installed and look at its type definitions more carefully:
- Assistant
OK, so we're working with Next.js 16.2.6. Let me now look at the
next/link.d.tsmore carefully to see if there's something I'm missing: - Assistant
Let me look at the dist/client/link.d.ts:
- Assistant
Let me look at the view-transitions example to understand how onNavigate is used:
- Assistant
Now I have a thorough understanding of the situation. Let me clean up the temporary test file and think about what changes might actually be needed:
- Assistant
Let me take a deeper look at the actual issue. Let me run the full unit test suite and see what's failing:
- Assistant
All 1042 tests pass. Now let me understand what the issue really is about. Let me look at the Next.js
link-on-navigate-proptest more carefully. The issue says "History state replacement viaonNavigatereturn value not working". Let me check if the Next.js canary branch has a different onNavigate API: - Assistant
Let me look at the full Pages Router link.js for onNavigate:
- Assistant
Let me look at the
toBrowserNavigationHreffunction to understand potential edge cases: - Assistant
OK, I think I've been overthinking this. Let me take a completely different approach.The issue says:
-
"
<Link onNavigate>prop not implemented" -
~8 test failures from
test/e2e/link-on-navigate-prop/index.test.ts -
Specific failures: callback never fires, click state tracking broken, history state replacement via return valueLooking at the code,
onNavigateIS implemented. But there are some issues I can identify: -
The
onNavigateevent in vinext includesurlanddefaultPreventedwhich Next.js doesn't provide. This is a superset and shouldn't break tests. -
The
onNavigateis called AFTERe.preventDefault()which matches Next.js behavior. -
The navigation via
startTransition+navigateClientSideshould work.
Wait, but the issue says "History state replacement via
onNavigatereturn value not working". Let me look at the Next.js implementation again more carefully.In the Next.js app-dir link.js:
if (onNavigate) { let isDefaultPrevented = false; onNavigate({ preventDefault: ()=>{ isDefaultPrevented = true; } }); if (isDefaultPrevented) { return; } }In the Next.js pages-dir link.js, it's the same pattern. The
onNavigatecallback receives{ preventDefault }only. The return value is NOT used.But the issue says "History state replacement via
onNavigatereturn value". This doesn't match the Next.js 16.2.6 API at all.Hmm wait, let me look at the
next-shims.d.tsagain more carefully: -
- Assistant
Let me look for any fixture pages that might be related to the onNavigate test:
- Assistant
Let me look at the
next-shims.d.tsto understand the type definitions: - Assistant
Let me look at the CI configuration to understand the Next.js Deploy Suite:
- Assistant
Let me look at the nextjs-deploy-suite workflow:
- Assistant
Now I understand! The Next.js Deploy Suite runs Next.js's e2e tests against vinext. The test file
test/e2e/link-on-navigate-prop/index.test.tsis from the Next.js repository itself. Let me look at the deploy script to understand the setup: - Assistant
Let me check the deploy manifest to see if the
link-on-navigate-proptest is included: - Assistant
Let me check if there's a Next.js checkout in the workspace:
- Assistant
Let me look at this from a completely different angle. Since I know the existing code works for unit tests, let me understand the exact Next.js test expectations. Let me check what happens when a test from the Next.js Deploy Suite runs against vinext. Let me look at the deploy script's e2e-deploy.sh:
- Assistant
Let me approach this differently. I've verified the basic
onNavigateworks. The issue is about ~8 test failures from the Next.js Deploy Suite. Let me look more carefully at the specific differences between vinext and Next.js: - Assistant
Now I have a thorough understanding. Let me think about what the actual problem might be.
Looking at the Next.js 16.2.6 implementation vs vinext:
Key observation: In Next.js's
linkClicked,onNavigatereceives only{ preventDefault }. In vinext'shandleClick,onNavigatereceives{ url, preventDefault, defaultPrevented }. This is a superset.However, looking more carefully at the issue:
- "History state replacement via
onNavigatereturn value not working"
Looking at the Next.js types:
onNavigate?: (event: { preventDefault: () => void }) => void;— the return type isvoid.Wait, but in vinext's
NavigateEventtype, there'sdefaultPreventedgetter. What if some test code checksevent.defaultPreventedBEFORE callingpreventDefault()and expectsfalse?Actually, looking at the existing vinext tests and code, the implementation appears to work correctly. Let me focus on what might actually be the 8 failing tests. The issue references the Next.js
test/e2e/link-on-navigate-prop/index.test.tstest. This is an E2E test from the Next.js test suite, run via the deploy suite.Given the issue says the
onNavigatecallback "never fires on click", and my unit tests show it DOES fire, there might be a difference in the E2E environment. Let me check if there's something about the click handler that could fail in a real browser:Looking at the click handler:
const handleClick = async (e: MouseEvent<HTMLAnchorElement>) => { if (onClick) onClick(e); if (e.defaultPrevented) return; // ... e.preventDefault(); // ... if (onNavigate) { try { const navUrl = new URL(absoluteFullHref, window.location.origin); // ... onNavigate(navEvent); // ... } catch { // Ignore URL parsing errors for relative/hash hrefs } }Wait, there's a potential issue!
e.preventDefault()is called BEFOREonNavigate. This meanse.defaultPreventedwould betruewhenonNavigateruns. But in the Next.js implementation,e.preventDefault()is also called beforeonNavigate, so this should be the same.Actually, the issue says "onNavigate callback never fires on click". But it IS in the code. Let me verify the dist file matches:
- "History state replacement via
- Assistant
Let me take a practical approach. Looking at the code carefully, the implementation exists but I notice the comment says "Return value is ignored" for the
onNavigatecallback. Let me now compare what the Next.js test expects vs what vinext provides, by looking at the type definitions more carefully: - Assistant
OK, I've spent a lot of time analyzing. Let me now focus on actually making improvements. Let me look at what specific improvements are needed based on the issue and the Next.js implementation:
- Assistant
OK, I've spent a lot of time analyzing. Let me now focus on concrete changes. Based on my thorough analysis:
- The
onNavigateIS implemented and works correctly in unit tests - The Next.js 16.2.6
onNavigateAPI passes{ preventDefault }only - The Next.js test suite
test/e2e/link-on-navigate-prop/index.test.tsruns against vinext
Looking at the code, I can see that the implementation works, but there are some potential issues with the
try/catchwrapping theonNavigatecall. Ifnew URL()throws,onNavigatenever fires. Let me fix this and add comprehensive tests. - The
- Assistant
Now let me fix the code. The key issue is that the
try/catchwraps the entireonNavigatecall, which means ifnew URL()throws,onNavigatenever fires. Let me fix this: - Assistant
Now let me make the fix. The
try/catchwrapping the entire block means ifnew URL()throws,onNavigatenever fires. I need to restructure soonNavigatealways fires: - Assistant
Let me use the terminal to make the edit:
- Assistant
Let me use the
openandeditcommands to make the change. - Assistant
Now I can see the exact code to replace. Let me use the
editcommand. - Assistant
Good, the edit was applied. Now let me also update the
NavigateEventtype comment to clarify thaturlis a vinext extension, and update theonNavigateprop documentation. Let me also look at the dist file to update it: - Assistant
Good. Now let me run the tests to make sure everything still passes:
- Assistant
Good, all tests pass. Now let me also rebuild the dist to reflect the change:
- Assistant
Let me check how vinext is built:
- Assistant
Let me find the package.json for vinext:
- Assistant
The current directory has changed to the file path. Let me go back to the root.
- Assistant
Let me build vinext properly:
- Assistant
The build is timing out. Let me just update the dist file manually to match the source change:
- Assistant
Now let me update the dist file to match the source change:
- Assistant
I notice the indentation is wrong in the dist file. Let me fix it:
- Assistant
Good, the indentation is now correct. Let me run the tests again to make sure everything still passes:
- Assistant
All 1042 tests pass. Now let me also fix the click state tracking for Pages Router by adding
setPending(true/false): - Assistant
Now let me add
setPendingto the Pages Router path: - Assistant
Good, the edit was applied. Now let me update the dist file as well:
- Assistant
I see the indentation is wrong. Let me fix it:
- Assistant
Good, the dist file looks correct now. Let me run the tests again to make sure everything still passes:
- Assistant
All 1042 tests still pass. Let me now review the full diff to make sure the changes are correct:
- Assistant
Let me also check the dist diff:
- Assistant
The dist file diff is empty? Let me check if the dist file is tracked by git.
- Assistant
Hmm, the dist file diff is empty. This suggests the dist file is not tracked by git. Let me check if it's in .gitignore.
- Assistant
Let me check if the dist file is tracked by git:
- Assistant
The dist file is not tracked by git. That's fine - the dist file is built from the source. The important thing is that the source file changes are correct.
Let me check git status more carefully.
- Assistant
Good, only the source file is changed. The dist file is not tracked by git (it's likely in .gitignore). Let me verify the changes look correct by reviewing the full diff one more time:
- Assistant
The changes look correct. Let me now run the lint check to make sure the code follows the project's style:
- Assistant
All checks pass. Let me now verify the dist file one more time to make sure it's correct:
- Assistant
Good, the dist file has the correct changes. Let me now do a final review of the complete changes:
- Assistant
Good, the dist file looks correct. Let me now run the full test suite one final time to make sure everything passes:
Other models, same or similar prompt
Responses were produced in different, uncontrolled contexts (system prompts, settings, prior turns). This is not a benchmark.
Identical first prompt
claude-sonnet-5Compare side by side →
claude-sonnet-5Compare side by side →
claude-sonnet-5Compare side by side →
claude-sonnet-5Compare side by side →
claude-sonnet-5Compare side by side →
Qwen/Qwen3.6-35B-A3BCompare side by side →
Qwen/Qwen3.6-35B-A3BCompare side by side →
Qwen/Qwen3.6-35B-A3BCompare side by side →
Qwen/Qwen3.6-35B-A3BCompare side by side →
Qwen/Qwen3.6-35B-A3BCompare side by side →
Qwen/Qwen3.5-35B-A3BCompare side by side →
Qwen/Qwen3.5-35B-A3BCompare side by side →