documentation in the Fetching Data menu, under the Parallel data fetching section

[gilangabdian]

Summary

I read the documentation in the Fetching Data menu, Parallel data fetching section, then I felt like the sentence:

"Start multiple requests by calling fetch, then await them with Promise.all. Requests begin as soon as fetch is called."

does not explicitly explain:

"OK, in the example above it can be seen that multiple async/await requests have a sequential effect. So how do we make it parallel code?"

The point here is that I feel like there's a missing sentence. Do you feel the same?

Therefore, I thought it would be better if it were like this:

"In the example above, the requests are sequential because getAlbums doesn't start until getArtist has finished. To fetch them in parallel, start both requests before awaiting either one. You can then use Promise.all to wait for both requests to complete."

and then show the code.

So, do you agree that the parts I mentioned above need to be updated?

Additional information

No response

Example

No response

[gilangabdian]

I don't know whether you support me or not.

Sorry, I didn't discuss the code in my question, but I did discuss the explanation or more specifically the documentation, especially the sentence:

"Start multiple requests by calling fetch, then await them with Promise.all. Requests begin as soon as fetch is called."

I think that sentence is too hasty and I think it would be better if it were changed to something like this, for example:

"In the example above, the requests are sequential because getAlbums doesn't start until getArtist has finished. To fetch them in parallel, start both requests before awaiting either one. You can then use Promise.all to wait for both requests to complete."

because it will be more explained from a beginner's perspective.

Is it okay if I open an issue for this?

[icyJoseph]

I hear you here. I do believe this part addresses what you are saying, it is just cut in the middle by the snippet no?

However, within any component, multiple async/await requests can still be sequential if placed after the other. For example, getAlbums will be blocked until getArtist is resolved:

```ts
// app/artist/[username]/page.tsx
// TypeScript
import { getArtist, getAlbums } from '@/app/lib/data'
 
export default async function Page({ params }) {
  // These requests will be sequential
  const { username } = await params
  const artist = await getArtist(username)
  const albums = await getAlbums(username)
  return <div>{artist.name}</div>
}
```

Start multiple requests by calling fetch, then await them with [Promise.all](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise/all). Requests begin as soon as fetch is called.

The entire section is already trying to make this distinction from the start: parallel data fetching means requests are eagerly initiated and start at the same time. It then contrasts that with the sequential example , where getAlbums is blocked until getArtist resolves.

So when we follow that example with:

“Start multiple requests by calling fetch, then await them with Promise.all. Requests begin as soon as fetch is called.”

I read that as the callback to the section’s definition of parallel fetching: initiate both requests before awaiting either of them.

I'll consider an edit at some point, because I can see how making that transition more explicit could improve the flow, especially since the code sample sits between the explanation and the solution, but I’m not sure the underlying explanation is actually missing today.

[gilangabdian]

Yes, I think it would be better if you update it sometime in the future as it would make the explanation more coherent and make the flow better. Thank you for your response again.

[pradipNP]

Agree with @gilangabdian that the jump after the sequential snippet can feel abrupt, and with @icyJoseph that the idea is already in the section — it’s mainly a transition issue.

Right now the flow is:

1. Define parallel fetching
2. Show a sequential await / await anti-pattern
3. Immediately: “Start multiple requests by calling fetch, then await them with Promise.all…”

That third line is correct, but it doesn’t explicitly say “here’s how you fix the example above,” so newcomers can miss the link.

A small bridge sentence would help a lot. Something like:

In the example above, the requests are sequential because getAlbums doesn’t start until getArtist finishes. To run them in parallel, start both requests before awaiting either one, then wait with Promise.all. Requests begin as soon as fetch (or your data function) is called — not when you await.

Then keep the existing parallel code sample.

Even shorter alternative:

To avoid that waterfall, kick off both requests first, then await Promise.all([...]) so they overlap.

So: yes, worth a small docs tweak for clearer flow; the underlying explanation isn’t wrong. Happy to open a docs PR with that wording if helpful.

[satiricalguru]

Yes, your suggested wording is much clearer and definitely addresses a common point of confusion.

The key distinction that trips developers up in React Server Components is initiating the promise vs awaiting the promise:

1. In sequential fetching, await getArtist() pauses component execution on the server before getAlbums() is even invoked:

   // Sequential waterfall
   const artist = await getArtist(username);
   const albums = await getAlbums(username); // Does not start until getArtist finishes

2. In parallel fetching with Promise.all, both promises are created immediately, triggering the underlying network requests simultaneously, before either is awaited:

   // Parallel fetch
   const artistPromise = getArtist(username);
   const albumsPromise = getAlbums(username);
   const [artist, albums] = await Promise.all([artistPromise, albumsPromise]);

Your proposed explanation:

"In the example above, the requests are sequential because getAlbums doesn't start until getArtist has finished. To fetch them in parallel, start both requests before awaiting either one. You can then use Promise.all to wait for both requests to complete."

...explicitly articulates why sequential happens and how promise initiation works before resolution.

Since the Next.js documentation is open source right in this repository, you should definitely submit a quick PR updating the markdown file under docs/01-app/02-guides/fetching-data.mdx (or the relevant docs path). The docs team is usually very receptive to clarity improvements like this!

[gilangabdian]

thanks for the response, @icyJoseph seems to have agreed that he will update it sometime in the future, so if I update it then I'm afraid it will clash with what he's doing

[icyJoseph]

I can always review a community PR, but please do keep it to the topic. People often submit several changes for a small thing, and we end up removing most things during review.

[itzmitto]

I agree with you — I checked the actual docs page (Getting Started → Fetching Data), and the structure is: the Sequential Fetching section shows the Playlists waiting on Artist example first, then the Parallel section immediately opens with "Start multiple requests by calling fetch, then await them with Promise.all." That sentence is accurate on its own, but it doesn't explicitly draw the causal line back to the problem the previous section just demonstrated — a reader skimming (rather than reading top to bottom) can miss that the parallel section is the fix for the exact sequential pattern shown right above it.

Your proposed rewrite is a real improvement because it names the specific cause ("getAlbums doesn't start until getArtist has finished") rather than leaving the reader to infer it, and it makes the fix ("start both requests before awaiting either one") the load-bearing sentence instead of jumping straight to the Promise.all syntax. That said, I'd suggest one small tweak: the docs' own code example actually uses getArtist/getAlbums as the parallel example and getArtist/getArtistPlaylists (via artistID prop dependency) as the sequential one — they're not literally the same two functions across both sections, so your wording might want to say "the previous example" more generically rather than naming getAlbums specifically, to avoid implying it's the same function object being referenced.

Since this is a docs wording improvement with a concrete before/after, it'd likely move faster as a PR than as an open-ended discussion — the "Edit this page" link at the bottom of the docs page opens a PR directly against the source markdown in this repo, and doc-wording PRs tend to get reviewed quickly since they're low-risk. Worth linking this discussion in the PR description for context.

[satiricalguru]

Thanks for bringing this up in documentation in the Fetching Data menu, under the Parallel data fetching section. I am following this discussion and looking into the details. Happy to help test or contribute to this area!