vercel / vercel/next.js

Docs: How to migrate from async router.push to new `next/navigation` push method

Open
#61,737 11 comments 24 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
JavaScript
Stars
142k
Forks
32.4k
Avg merge
2d 14h
Merged PRs (30d)
351

Description

What is the improvement or update you wish to see?

The new router in next/navigation no longer returns a promise from the push method. From what I've been able to understand, this is so that it can work with the startTransition feature of React, but the Next docs don't contain any information about this or how to successfully replace any functionality that was relying on "awaiting" a router.push call

Is there any context that might help us understand?

The docs for the push method are currently one sentence here:
https://nextjs.org/docs/app/api-reference/functions/use-router#userouter

The migration guide does not mention the fact that the method is no longer async or describe how a migration should take place to the new push
https://nextjs.org/docs/app/building-your-application/upgrading/app-router-migration#step-5-migrating-routing-hooks

This is the one place I've been able to find mention of how it can be used with useTransition, although it also doesn't seem to trigger the pending state in many cases (maybe it just doesn't work in page router?)
https://github.com/vercel/next.js/discussions/49810

Does the docs page already exist? Please link to it.

https://nextjs.org/docs/app/building-your-application/upgrading/app-router-migration#step-5-migrating-routing-hooks

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start with the App Router migration guide's “Step 5: Migrating Routing Hooks” section and the useRouter API reference linked in the issue. Compare the documented push behavior with the requested migration from an awaited router.push call. Done means the docs explain that next/navigation push is not promise-based and describe the supported replacement guidance, including relevant useTransition context.

Written by the indexing model from the issue text.

Assessment

Tech stack
javascript, next.js, react
Domain
documentation, frontend, web-dev
Issue type
Documentation
Difficulty
2/5
Estimated time
1-2 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
38/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.