docs: upfront recommend against using the no-return-await rule (#19727)

mikedidomizio · nzakas · mdjermanovic · web-flow · commit 00716a339ede · 2025-05-19T17:54:45.000+02:00
* docs: upfront recommend against using the no-return-await rule

* Fix unordered list style for lint

* Remove paragraph. Add horizontal line to break up note

* Remove mention of extra microtask as no longer correct

* Update no-return-await.md

* Update docs/src/rules/no-return-await.md

Co-authored-by: Milos Djermanovic &lt;milos.djermanovic@gmail.com&gt;

* Update docs/src/rules/no-return-await.md

---------

Co-authored-by: Nicholas C. Zakas &lt;nicholas@humanwhocodes.com&gt;
Co-authored-by: Milos Djermanovic &lt;milos.djermanovic@gmail.com&gt;
diff --git a/docs/src/rules/no-return-await.md b/docs/src/rules/no-return-await.md
@@ -7,15 +7,16 @@ further_reading:
 - https://jakearchibald.com/2017/await-vs-return-vs-return-await/
 ---
 
-The original intent of this rule was to discourage the use of `return await`, to avoid an extra microtask. However, due to the fact that JavaScript now handles native `Promise`s differently, there is no longer an extra microtask. More technical information can be found in [this V8 blog entry](https://v8.dev/blog/fast-async).
+It is NOT recommended to use the `no-return-await` rule anymore because:
 
-Using `return await` inside an `async function` keeps the current function in the call stack until the Promise that is being awaited has resolved, at the cost of an extra microtask before resolving the outer Promise. `return await` can also be used in a try/catch statement to catch errors from another function that returns a Promise.
+* `return await` on a promise will not result in an extra microtask.
+* `return await` yields a better stack trace for debugging.
 
-You can avoid the extra microtask by not awaiting the return value, with the trade off of the function no longer being a part of the stack trace if an error is thrown asynchronously from the Promise being returned. This can make debugging more difficult.
+Historical context: When promises were first introduced, calling `return await` introduced an additional microtask, one for the `await` and one for the return value of the async function. Each extra microtask delays the computation of a result and so this rule was added to help avoid this performance trap. Later, [ECMA-262 changed the way](https://github.com/tc39/ecma262/pull/1250) `return await` worked so it would create a single microtask, which means this rule is no longer necessary.
 
 ## Rule Details
 
-This rule aims to prevent a likely common performance hazard due to a lack of understanding of the semantics of `async function`.
+This rule warns on any usage of `return await` except in `try` blocks.
 
 Examples of **incorrect** code for this rule:
 
@@ -65,8 +66,4 @@ async function foo4() {
 
 ## When Not To Use It
 
-There are a few reasons you might want to turn this rule off:
-
-* If you want to use `await` to denote a value that is a thenable
-* If you do not want the performance benefit of avoiding `return await`
-* If you want the functions to show up in stack traces (useful for debugging purposes)
+You should not use this rule. There is no reason to avoid `return await`.
