reactjs / reactjs/react.dev

[Typo]: definitions of async/defer in the script tag documentation are incorrect

Open Beginner friendly
#7,328 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

type: typos
Dominant language
JavaScript
Stars
11.8k
Forks
7.9k
Avg merge
1d 11h
Merged PRs (30d)
11

Description

Summary

Unless React has its own creative interpretation of the meanings of async and defer that are different from the DOM specification (per MDN), the descriptions for async and defer are confusing and misleading and may lead to runtime errors.

Page

https://react.dev/reference/react-dom/components/script

Details

The description for async confounds it with defer, but in fact async essentially cancels any kind of defer: the script will not block further parsing, but it will be executed as soon as it is available, there is no "deferring". This lets the browser execute it at its convenience, there is no longer any guarantee about when it runs other than "eventually": this can even be mid-parse!

defer, on the other hand, also doesn't block parsing by enqueueing the script to run after the page finishes parsing; but they are guaranteed to run before the DOMContentLoaded event. This is, actually, what is recommended for most scripts, enough that it is the default for script[type="module"]. It is canceled by async, as it removes the guarantee that the script will run only after parse is done. It only has an effect on src scripts, though, not inline.

It is, however, true that async is the best for performance, as there is no longer any execution time guarantees. It is also dangerous, as the DOM might not be available when the script runs: only (non-async) defer scripts have that guarantee.

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

Open the React DOM script documentation at https://react.dev/reference/react-dom/components/script and compare the async and defer descriptions with the linked MDN DOM specification. Update the wording to accurately distinguish their execution timing, parsing behavior, and applicability to external scripts, then verify the page clearly communicates the runtime implications.

Written by the indexing model from the issue text.

Assessment

Tech stack
javascript
Domain
documentation
Issue type
Documentation
Difficulty
2/5
Estimated time
1-3 hours
Activity status
Stale
Clarity
Clearly specified
Newbie friendliness
68/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.