NextJS Integration (useInsertionEffect must not schedule updates.)

[y-cubode]

Hello!

I've setup a hybrid approach for using Tanstack Router in NextJS and it works great apart from 1 issue which is I get this error:
useInsertionEffect must not schedule updates. whenever I switch routes with the Link component.

Is there any solution for this? I know I can use the memory router which solves this but I want URL routing. If not, is it safe to ignore this error?

I'm trying to avoid patching NextJS, more open to patching TanStack Router if all else fails.

[hiramhuang]

I'm also integrating TanStack Router with Next.js App Router, and I'm having the same issue too.

The same warning is triggered every time a client-side navigation occurs (both through the Link component and router.navigate()).

I believe the warning originates from here: https://github.com/vercel/next.js/blob/1dccfbce0f11e04df1ec387d244db018104b5c6b/packages/next/src/client/components/app-router.tsx#L101-L129

[y-cubode]

I'm also integrating TanStack Router with Next.js App Router, and I'm having the same issue too.

The same warning is triggered every time a client-side navigation occurs (both through the Link component and router.navigate()).

I believe the warning originates from here: https://github.com/vercel/next.js/blob/1dccfbce0f11e04df1ec387d244db018104b5c6b/packages/next/src/client/components/app-router.tsx#L101-L129

Yeah I ended up patching NextJS to do an early return on all router methods when within a TanStack route which fixed the issue but really hoping I can find a more robust solution at some point.

[ru-van-urk]

@y-cubode Can you give an example from the patch you did? I am interested as well.

[y-cubode]

@y-cubode Can you give an example from the patch you did? I am interested as well.

Sure, here's my patch file below for 15.2.5, I've not had a chance to upgrade.

Once you've applied the patch, put this code at the root of wherever your TanStack router setup is:

if (typeof window !== 'undefined') window.NEXT_ROUTER_DISABLED = true;

diff --git a/dist/client/components/app-router.js b/dist/client/components/app-router.js
index cfa66f2004ebbac27a904b6c99f7380a1414f69d..614c92554bae975de813768b16929be443d1f33b 100644
--- a/dist/client/components/app-router.js
+++ b/dist/client/components/app-router.js
@@ -402,6 +402,15 @@ function Head(param) {
         const originalReplaceState = window.history.replaceState.bind(window.history);
         // Ensure the canonical URL in the Next.js Router is updated when the URL is changed so that `usePathname` and `useSearchParams` hold the pushed values.
         const applyUrlFromHistoryPushReplace = (url)=>{
+            // No-op if url is not provided
+            if (!url) return;
+
+            // If we have a CLIENT_ROUTER element, skip Next.js history manipulation 
+            // to let TanStack Router handle history
+            if (typeof document !== 'undefined' && window.NEXT_ROUTER_DISABLED) {
+                return;
+            }
+            
             var _window_history_state;
             const href = window.location.href;
             const tree = (_window_history_state = window.history.state) == null ? void 0 : _window_history_state.__PRIVATE_NEXTJS_INTERNALS_TREE;
@@ -422,12 +431,21 @@ function Head(param) {
             if ((data == null ? void 0 : data.__NA) || (data == null ? void 0 : data._N)) {
                 return originalPushState(data, _unused, url);
             }
+
+            // If we have a CLIENT_ROUTER element, skip Next.js history manipulation 
+            // to let TanStack Router handle history
+            if (typeof document !== 'undefined' && window.NEXT_ROUTER_DISABLED) {
+                // Just call the original pushState without Next.js modifications
+                // to avoid conflicts with TanStack Router
+                return originalPushState(data, _unused, url);
+            }
             data = copyNextJsInternalHistoryState(data);
             if (url) {
                 applyUrlFromHistoryPushReplace(url);
             }
             return originalPushState(data, _unused, url);
         };
+        
         /**
      * Patch replaceState to ensure external changes to the history are reflected in the Next.js Router.
      * Ensures Next.js internal history state is copied to the new history entry.
@@ -437,12 +455,21 @@ function Head(param) {
             if ((data == null ? void 0 : data.__NA) || (data == null ? void 0 : data._N)) {
                 return originalReplaceState(data, _unused, url);
             }
+            
+            // If we have a CLIENT_ROUTER element, skip Next.js history manipulation 
+            // to let TanStack Router handle history
+            if (typeof document !== 'undefined' && window.NEXT_ROUTER_DISABLED) {
+                // Just call the original replaceState without Next.js modifications
+                // to avoid conflicts with TanStack Router
+                return originalReplaceState(data, _unused, url);
+            }
             data = copyNextJsInternalHistoryState(data);
             if (url) {
                 applyUrlFromHistoryPushReplace(url);
             }
             return originalReplaceState(data, _unused, url);
         };
+        
         /**
      * Handle popstate event, this is used to handle back/forward in the browser.
      * By default dispatches ACTION_RESTORE, however if the history entry was not pushed/replaced by app-router it will reload the page.
@@ -452,6 +479,12 @@ function Head(param) {
                 // TODO-APP: this case only happens when pushState/replaceState was called outside of Next.js. It should probably reload the page in this case.
                 return;
             }
+            
+            // If we have a CLIENT_ROUTER element, skip Next.js history handling
+            // to let TanStack Router handle popstate
+            if (typeof document !== 'undefined' && window.NEXT_ROUTER_DISABLED) {
+                return;
+            }
             // This case happens when the history entry was pushed by the `pages` router.
             if (!event.state.__NA) {
                 window.location.reload();

[stupidSheep]

Thank you @y-cubode . I used the same patch file for a wouter integration

PS: If not asked too much - would you share if there are any issues to know of when integrating TanStack router in a NextJS project? I'm mostely looking for a migration path off NextJS without doing a big-bang migration

[y-cubode]

Thank you @y-cubode . I used the same patch file for a wouter integration

PS: If not asked too much - would you share if there are any issues to know of when integrating TanStack router in a NextJS project? I'm mostely looking for a migration path off NextJS without doing a big-bang migration

No problem glad that helped. The only problem I've had is that HMR within TanStack routes does not work when adding rewrite rules in the NextJS config to redirect users to the SPA path.

import type { NextConfig } from 'next';

const nextConfig: NextConfig = {
  rewrites: async () => [
    { // assuming TanStack routes are in the root path. Essential for redirecting users visiting through a url directly to the SPA
      source: '/:path*', 
      destination: '/',
    },
  ],
};

export default nextConfig;

I think I ended up solving it with environment variables to only apply the rewrite in production, but this meant I couldn't visit URLs directly in development which became frustrating and caused friction within the team, so shortly after I ended up migrating to a standard TanStack project on Vite for that and a couple other reasons.

[stupidSheep]

Thank you for the response! I hope eventually I'm also on Vite + TanStack :)