fix(nuxt): Prevent Nuxt route middlewares from seeing intermediate states during navigation #6802

wobsoriano · 2025-09-18T01:52:40Z

Description

During auth transitions (sign-in and sign-out), Vue shows intermediate state changes causing UI flicker and confusing redirects. For example (notice how it goes from /sign-in -> /dashboard -> sign-in -> /dashboard):

Screen.Recording.2025-09-17.at.6.43.00.PM.mov

What's happening above:

User signs in with email/password
Clerk redirects to fallbackRedirectUrl or forceRedirectUrl
Navigation starts immediately
Nuxt route middleware runs and checks auth state via useAuth().userId.value
But Vue is still processing state updates (user -> null -> undefined -> user)
Middleware sees null or undefined and redirects to sign-in
When state finally settles to user, it redirects back to fallbackRedirectUrl or forceRedirectUrl

By adding nextTick(), it's ensuring that navigation happens after the state is fully settled, preventing route middleware from seeing intermediate states.

Fixed demo, from /sign-in -> /dashboard

Screen.Recording.2025-09-17.at.6.44.54.PM.mov

Checklist

pnpm test runs as expected.
pnpm build runs as expected.
(If applicable) JSDoc comments have been added or updated for any package exports
(If applicable) Documentation has been updated

Type of change

Summary by CodeRabbit

Bug Fixes
- Improved routing stability in Nuxt to prevent unwanted redirects during sign-in/sign-out. Navigation timing is now deferred to avoid middleware reacting to intermediate navigation states, resulting in smoother and more predictable auth flows.
Chores
- Added a changeset entry for a patch release of the Nuxt package, documenting the fix and ensuring proper versioning.

changeset-bot · 2025-09-18T01:52:44Z

🦋 Changeset detected

Latest commit: 1e4d628

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
@clerk/nuxt	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

vercel · 2025-09-18T01:52:45Z

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Preview	Comments	Updated (UTC)
clerk-js-sandbox	Ready	Preview	Comment	Sep 18, 2025 1:55am

coderabbitai · 2025-09-18T01:52:47Z

Walkthrough

Introduces a changeset entry for a patch release and updates the Nuxt runtime plugin to defer router navigation by wrapping navigateTo calls in nextTick for both routerPush and routerReplace.

Changes

Cohort / File(s)	Summary
Release notes / changeset `\.changeset/funny-peaches-float.md`	Adds patch changeset for @clerk/nuxt documenting a fix where middleware observed intermediate navigation states during auth flows. No code changes.
Nuxt plugin navigation timing `packages/nuxt/src/runtime/plugin.ts`	Wraps routerPush and routerReplace in nextTick, adds nextTick import (with ts-expect-error), and changes return values to those of nextTick callbacks instead of direct navigateTo results.

Sequence Diagram(s)

sequenceDiagram
  autonumber
  actor User
  participant AuthFlow as Auth Flow
  participant Plugin as Nuxt Plugin
  participant Middleware
  participant Router

  User->>AuthFlow: Trigger sign-in/sign-out
  AuthFlow->>Plugin: routerPush/routerReplace(to)
  note over Plugin: New behavior: schedule navigation on nextTick
  Plugin->>Plugin: nextTick(() => navigateTo(to))
  Plugin-->>AuthFlow: Promise (from nextTick)
  rect rgba(230,245,255,0.5)
    note right of Middleware: Middleware sees stable state (no intermediate navigation)
  end
  Plugin->>Router: navigateTo(to) (on next tick)
  Router->>Middleware: Run route middleware
  Middleware-->>Router: Continue or redirect
  Router-->>User: Final route

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Poem

I hop between ticks, a careful byte,
Delaying my jumps till timing’s right.
No halfway paths, no zigzag fright—
Next-tick moon guides my silent flight.
Patch packed, routes tight, carrots bright! 🥕✨

Pre-merge checks and finishing touches

✅ Passed checks (3 passed)

Check name	Status	Explanation
Title Check	✅ Passed	The title is concise, follows conventional commit style, and accurately summarizes the primary change: preventing Nuxt route middleware from observing intermediate navigation states during navigation (the fix implemented with nextTick). It clearly reflects the intent and main impact of the changeset and is appropriate for history scanning by teammates.
Docstring Coverage	✅ Passed	No functions found in the changes. Docstring coverage check skipped.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.

✨ Finishing touches

📝 Generate Docstrings

🧪 Generate unit tests

Create PR with unit tests
Post copyable unit tests in a comment
Commit unit tests in branch rob/nuxt-fix-transition

Tip

👮 Agentic pre-merge checks are now available in preview!

Pro plan users can now enable pre-merge checks in their settings to enforce checklists before merging PRs.

Built-in checks – Quickly apply ready-made checks to enforce title conventions, require pull request descriptions that follow templates, validate linked issues for compliance, and more.
Custom agentic checks – Define your own rules using CodeRabbit’s advanced agentic capabilities to enforce organization-specific policies and workflows. For example, you can instruct CodeRabbit’s agent to verify that API documentation is updated whenever API schema files are modified in a PR. Note: Upto 5 custom checks are currently allowed during the preview period. Pricing for this feature will be announced in a few weeks.

Please see the documentation for more information.

Example:

reviews:
  pre_merge_checks:
    custom_checks:
      - name: "Undocumented Breaking Changes"
        mode: "warning"
        instructions: |
          Pass/fail criteria: All breaking changes to public APIs, CLI flags, environment variables, configuration keys, database schemas, or HTTP/GraphQL endpoints must be documented in the "Breaking Change" section of the PR description and in CHANGELOG.md. Exclude purely internal or private changes (e.g., code not exported from package entry points or explicitly marked as internal).

Please share your feedback with us on this Discord post.

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

pkg-pr-new · 2025-09-18T01:57:37Z

Open in StackBlitz

@clerk/agent-toolkit

npm i https://pkg.pr.new/@clerk/agent-toolkit@6802

@clerk/astro

npm i https://pkg.pr.new/@clerk/astro@6802

@clerk/backend

npm i https://pkg.pr.new/@clerk/backend@6802

@clerk/chrome-extension

npm i https://pkg.pr.new/@clerk/chrome-extension@6802

@clerk/clerk-js

npm i https://pkg.pr.new/@clerk/clerk-js@6802

@clerk/dev-cli

npm i https://pkg.pr.new/@clerk/dev-cli@6802

@clerk/elements

npm i https://pkg.pr.new/@clerk/elements@6802

@clerk/clerk-expo

npm i https://pkg.pr.new/@clerk/clerk-expo@6802

@clerk/expo-passkeys

npm i https://pkg.pr.new/@clerk/expo-passkeys@6802

@clerk/express

npm i https://pkg.pr.new/@clerk/express@6802

@clerk/fastify

npm i https://pkg.pr.new/@clerk/fastify@6802

@clerk/localizations

npm i https://pkg.pr.new/@clerk/localizations@6802

@clerk/nextjs

npm i https://pkg.pr.new/@clerk/nextjs@6802

@clerk/nuxt

npm i https://pkg.pr.new/@clerk/nuxt@6802

@clerk/clerk-react

npm i https://pkg.pr.new/@clerk/clerk-react@6802

@clerk/react-router

npm i https://pkg.pr.new/@clerk/react-router@6802

@clerk/remix

npm i https://pkg.pr.new/@clerk/remix@6802

@clerk/shared

npm i https://pkg.pr.new/@clerk/shared@6802

@clerk/tanstack-react-start

npm i https://pkg.pr.new/@clerk/tanstack-react-start@6802

@clerk/testing

npm i https://pkg.pr.new/@clerk/testing@6802

@clerk/themes

npm i https://pkg.pr.new/@clerk/themes@6802

@clerk/types

npm i https://pkg.pr.new/@clerk/types@6802

@clerk/upgrade

npm i https://pkg.pr.new/@clerk/upgrade@6802

@clerk/vue

npm i https://pkg.pr.new/@clerk/vue@6802

commit: 1e4d628

coderabbitai

Actionable comments posted: 2

🧹 Nitpick comments (3)

.changeset/funny-peaches-float.md (1)
1-5: Changelog is clear; consider noting the mechanism.

Add a brief note that navigation is deferred with Vue.nextTick() so middleware won’t observe transient auth states. Helps downstream maintainers understand the fix at a glance.
 Fixed an issue where Nuxt route middleware saw intermediate states during navigation, causing unwanted redirects during sign-in/sign-out flows.
+Navigation is now deferred to the next Vue tick so middleware only runs after auth state settles.
packages/nuxt/src/runtime/plugin.ts (2)
7-9: Avoid ts-expect-error; import nextTick from vue.

Relying on #imports here forces a suppression and weakens type safety. Importing from vue works in Nuxt runtime code and removes the need for the directive.
-// @ts-expect-error: Handled by Nuxt.
-import { nextTick } from '#imports';
+import { nextTick } from 'vue';
31-40: Document why the deferral exists.

Add a short JSDoc explaining the auth-state race this mitigates and that SSR is not deferred.
-    routerPush: (to: string): ReturnType<typeof navigateTo> => {
+    /** Defer client navigation by one tick so route middleware runs after auth state settles (prevents flicker/loops).
+     *  On SSR, navigate immediately to preserve redirect semantics.
+     */
+    routerPush: (to: string): ReturnType<typeof navigateTo> => {
@@
-    routerReplace: (to: string): ReturnType<typeof navigateTo> => {
+    /** Same as routerPush but with { replace: true }. */
+    routerReplace: (to: string): ReturnType<typeof navigateTo> => {

📜 Review details

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Disabled knowledge base sources:

Linear integration is disabled by default for public repositories

You can enable these sources in your CodeRabbit configuration.

📥 Commits

Reviewing files that changed from the base of the PR and between 8d1514a and 1e4d628.

📒 Files selected for processing (2)

.changeset/funny-peaches-float.md (1 hunks)
packages/nuxt/src/runtime/plugin.ts (2 hunks)

🧰 Additional context used

📓 Path-based instructions (7)

.changeset/**

📄 CodeRabbit inference engine (.cursor/rules/monorepo.mdc)

Automated releases must use Changesets.

Files:

.changeset/funny-peaches-float.md

**/*.{js,jsx,ts,tsx}