Skip to content

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

Open
@Jessidhia

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.

Metadata

Assignees

No one assigned

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions