Docs: async rewrites examples are not async

[masto]

What is the documentation issue?

Per

next.js/docs/01-app/04-api-reference/05-config/01-next-config-js/rewrites.mdx

Line 39 in a41152e

`rewrites` is an async function that expects to return either an array or an object of arrays (see below) holding objects with `source` and `destination` properties:

and the type definition (

next.js/packages/next/src/server/config-shared.ts

Line 727 in a41152e

rewrites?: () => Promise<

), rewrites is an async function. The examples, however, neither await anything, nor explicitly return a promise.

JavaScript of course wraps the return value in a promise, so this works, but it may be considered bad form. And some of us have our linters turned up to 11.

Is there any context that might help us understand?

I ran an automated installation script for PostHog, which added this configuration and produced an eslint failure, and that led me to noticing this in the Next.js documentation.

I know that it's trivial to work around and I have done so, but I thought it might be worth considering changing the docs.

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

https://nextjs.org/docs/app/api-reference/config/next-config-js/rewrites

[snivels]

In javascript async functions don't need to have an await inside them, like you've said the return value is implicitly wrapped in a promise.

I believe it's an async function because you might want to do something asynchronous before applying the rewrite e.g. getting a users locale from a cookie and rewriting them to the correct localised URL.

I do agree that perhaps an example code snippet using asynchronous behaviour inside the rewrite would reduce confusion, though.

[masto]

Yeah, I'm assuming I am unusual for turning every linter rule up to 11 and enforcing zero warnings in my pre-commit hook (I have a greenfield project so I thought it would be nice to prevent any jank from creeping in). I just changed mine to

return Promise.resolve([...

but I don't know if doing that in the docs would actually confuse more people than it will help.

Anyway, definitely not making any demands or even expressing a strong opinion, just bringing this up in case the maintainers felt like taking it into account.

[icyJoseph]

I wonder if the NextConfig type could be widened though 🤔 since we can await syncFunc anyway, so the internals would just still call await rewrites() kind of...

You can also just disable your require await lint rule, for this method specifically, with a comment of why you've done it, and avoid the code change to Promise.resolve

[Htet-Inzali]

I see the documentation issue you're pointing out here. The discrepancy is between how Next.js defines the rewrites function in its type definitions versus how it's shown in their examples.
In the type definition (next.js/packages/next/src/server/config-shared.ts), rewrites is defined as a function that returns a Promise:

rewrites?: () => Promise<...>

But in practice, the examples in the documentation show it used as an async function that simply returns an array directly:

async rewrites() { return [ { source: "...", destination: "..." }, // etc. ] }

This works because JavaScript automatically wraps the return value of an async function in a Promise. However, it's triggering your ESLint rule because the function is marked as async but doesn't contain any await expressions inside it.
The ESLint rule @typescript-eslint/require-await expects that if you declare a function as async, you should be using await somewhere within it. Since the example doesn't do that, it's flagging as an issue.
For your PostHog configuration, you have a couple of options to fix this:

Remove the async keyword if you're not doing any asynchronous operations:

rewrites() { return [ // your redirects ] }

Or explicitly wrap the return value in a Promise:

async rewrites() { // Some async operation with await // Or explicitly return Promise.resolve return Promise.resolve([ // your redirects ]) }

You're right that this is worth bringing to the attention of the Next.js documentation team. When documentation doesn't follow best practices, it can lead to confusing situations like this. The docs should be updated to either remove the async keyword from examples or include some actual asynchronous operations to justify its use.

[icyJoseph]

Remove the async keyword if you're not doing any asynchronous operations:

rewrites() { return [ // your redirects ] }

For people using next.config.ts, that will trip TypeScript errors

[icyJoseph]

Alas the fix for this landed here: #83743 - I'll see to get #95148 through and patch the docs now.