diff --git a/src/docs/guide/usage/linter/generated-rules.md b/src/docs/guide/usage/linter/generated-rules.md
index 81ca2bd1039..50ed2cf49ba 100644
--- a/src/docs/guide/usage/linter/generated-rules.md
+++ b/src/docs/guide/usage/linter/generated-rules.md
@@ -2,7 +2,7 @@
The progress of all rule implementations is tracked [here](https://github.com/oxc-project/oxc/issues/481).
-- Total number of rules: 432
+- Total number of rules: 436
- Rules turned on by default: 96
## Correctness (170):
@@ -282,7 +282,7 @@ code that is most likely wrong or useless.
| [consistent-function-scoping](/docs/guide/usage/linter/rules/unicorn/consistent-function-scoping.html) | unicorn | | π§ |
| [prefer-add-event-listener](/docs/guide/usage/linter/rules/unicorn/prefer-add-event-listener.html) | unicorn | | π§ |
-## Pedantic (69):
+## Pedantic (71):
Lints which are rather strict or have occasional false positives.
| Rule name | Source | Default | Fixable? |
@@ -294,12 +294,14 @@ Lints which are rather strict or have occasional false positives.
| [no-array-constructor](/docs/guide/usage/linter/rules/eslint/no-array-constructor.html) | eslint | | π§ |
| [no-case-declarations](/docs/guide/usage/linter/rules/eslint/no-case-declarations.html) | eslint | | |
| [no-constructor-return](/docs/guide/usage/linter/rules/eslint/no-constructor-return.html) | eslint | | |
+| [no-else-return](/docs/guide/usage/linter/rules/eslint/no-else-return.html) | eslint | | π οΈ |
| [no-fallthrough](/docs/guide/usage/linter/rules/eslint/no-fallthrough.html) | eslint | | π§ |
| [no-inner-declarations](/docs/guide/usage/linter/rules/eslint/no-inner-declarations.html) | eslint | | |
| [no-new-wrappers](/docs/guide/usage/linter/rules/eslint/no-new-wrappers.html) | eslint | | π§ |
| [no-prototype-builtins](/docs/guide/usage/linter/rules/eslint/no-prototype-builtins.html) | eslint | | |
| [no-redeclare](/docs/guide/usage/linter/rules/eslint/no-redeclare.html) | eslint | | |
| [no-self-compare](/docs/guide/usage/linter/rules/eslint/no-self-compare.html) | eslint | | |
+| [no-throw-literal](/docs/guide/usage/linter/rules/eslint/no-throw-literal.html) | eslint | | π‘ |
| [radix](/docs/guide/usage/linter/rules/eslint/radix.html) | eslint | | |
| [require-await](/docs/guide/usage/linter/rules/eslint/require-await.html) | eslint | | |
| [sort-keys](/docs/guide/usage/linter/rules/eslint/sort-keys.html) | eslint | | π§ |
@@ -357,7 +359,7 @@ Lints which are rather strict or have occasional false positives.
| [prefer-type-error](/docs/guide/usage/linter/rules/unicorn/prefer-type-error.html) | unicorn | | π οΈ |
| [require-number-to-fixed-digits-argument](/docs/guide/usage/linter/rules/unicorn/require-number-to-fixed-digits-argument.html) | unicorn | | π οΈ |
-## Style (100):
+## Style (102):
Code that should be written in a more idiomatic way.
| Rule name | Source | Default | Fixable? |
@@ -372,6 +374,7 @@ Code that should be written in a more idiomatic way.
| [no-magic-numbers](/docs/guide/usage/linter/rules/eslint/no-magic-numbers.html) | eslint | | π§ |
| [no-multi-str](/docs/guide/usage/linter/rules/eslint/no-multi-str.html) | eslint | | |
| [no-new-func](/docs/guide/usage/linter/rules/eslint/no-new-func.html) | eslint | | |
+| [no-return-assign](/docs/guide/usage/linter/rules/eslint/no-return-assign.html) | eslint | | π§ |
| [no-script-url](/docs/guide/usage/linter/rules/eslint/no-script-url.html) | eslint | | |
| [no-template-curly-in-string](/docs/guide/usage/linter/rules/eslint/no-template-curly-in-string.html) | eslint | | π§ |
| [no-ternary](/docs/guide/usage/linter/rules/eslint/no-ternary.html) | eslint | | |
@@ -417,6 +420,7 @@ Code that should be written in a more idiomatic way.
| [no-exports-assign](/docs/guide/usage/linter/rules/node/no-exports-assign.html) | node | | π οΈ |
| [avoid-new](/docs/guide/usage/linter/rules/promise/avoid-new.html) | promise | | |
| [param-names](/docs/guide/usage/linter/rules/promise/param-names.html) | promise | | |
+| [prefer-await-to-callbacks](/docs/guide/usage/linter/rules/promise/prefer-await-to-callbacks.html) | promise | | |
| [prefer-await-to-then](/docs/guide/usage/linter/rules/promise/prefer-await-to-then.html) | promise | | |
| [jsx-boolean-value](/docs/guide/usage/linter/rules/react/jsx-boolean-value.html) | react | | π οΈ |
| [jsx-curly-brace-presence](/docs/guide/usage/linter/rules/react/jsx-curly-brace-presence.html) | react | | |
diff --git a/src/docs/guide/usage/linter/rules/eslint/getter-return.md b/src/docs/guide/usage/linter/rules/eslint/getter-return.md
index 06decc1a25c..02386d32e4b 100644
--- a/src/docs/guide/usage/linter/rules/eslint/getter-return.md
+++ b/src/docs/guide/usage/linter/rules/eslint/getter-return.md
@@ -7,20 +7,41 @@
### What it does
-Requires all getters to have a return statement
+Requires all getters to have a `return` statement.
### Why is this bad?
Getters should always return a value. If they don't, it's probably a mistake.
+This rule does not run on TypeScript files, since type checking will
+catch getters that do not return a value.
+
### Example
+Examples of **incorrect** code for this rule:
+
```javascript
class Person {
get name() {
// no return
}
}
+
+const obj = {
+ get foo() {
+ // object getter are also checked
+ },
+};
+```
+
+Examples of **correct** code for this rule:
+
+```javascript
+class Person {
+ get name() {
+ return this._name;
+ }
+}
```
## References
diff --git a/src/docs/guide/usage/linter/rules/eslint/no-else-return.md b/src/docs/guide/usage/linter/rules/eslint/no-else-return.md
new file mode 100644
index 00000000000..4c12b964437
--- /dev/null
+++ b/src/docs/guide/usage/linter/rules/eslint/no-else-return.md
@@ -0,0 +1,170 @@
+
+
+# eslint/no-else-return
+
+
+
+### What it does
+
+Disallow `else` blocks after `return` statements in `if` statements
+
+### Why is this bad?
+
+If an `if` block contains a `return` statement, the `else` block becomes
+unnecessary. Its contents can be placed outside of the block.
+
+```javascript
+function foo() {
+ if (x) {
+ return y;
+ } else {
+ return z;
+ }
+}
+```
+
+This rule is aimed at highlighting an unnecessary block of code
+following an `if` containing a return statement. As such, it will warn
+when it encounters an `else` following a chain of `if`s, all of them
+containing a `return` statement.
+
+Options
+This rule has an object option:
+
+- `allowElseIf`: `true` _(default)_ allows `else if` blocks after a return
+- `allowElseIf`: `false` disallows `else if` blocks after a return
+
+### Examples
+
+#### `allowElseIf: true`
+
+Examples of **incorrect** code for this rule:
+
+```javascript
+function foo1() {
+ if (x) {
+ return y;
+ } else {
+ return z;
+ }
+}
+
+function foo2() {
+ if (x) {
+ return y;
+ } else if (z) {
+ return w;
+ } else {
+ return t;
+ }
+}
+
+function foo3() {
+ if (x) {
+ return y;
+ } else {
+ var t = "foo";
+ }
+
+ return t;
+}
+
+function foo4() {
+ if (error) {
+ return "It failed";
+ } else {
+ if (loading) {
+ return "It's still loading";
+ }
+ }
+}
+
+// Two warnings for nested occurrences
+function foo5() {
+ if (x) {
+ if (y) {
+ return y;
+ } else {
+ return x;
+ }
+ } else {
+ return z;
+ }
+}
+```
+
+Examples of **correct** code for this rule:
+
+```javascript
+function foo1() {
+ if (x) {
+ return y;
+ }
+
+ return z;
+}
+
+function foo2() {
+ if (x) {
+ return y;
+ } else if (z) {
+ var t = "foo";
+ } else {
+ return w;
+ }
+}
+
+function foo3() {
+ if (x) {
+ if (z) {
+ return y;
+ }
+ } else {
+ return z;
+ }
+}
+
+function foo4() {
+ if (error) {
+ return "It failed";
+ } else if (loading) {
+ return "It's still loading";
+ }
+}
+```
+
+#### `allowElseIf: false`
+
+Examples of **incorrect** code for this rule:
+
+```javascript
+function foo() {
+ if (error) {
+ return "It failed";
+ } else if (loading) {
+ return "It's still loading";
+ }
+}
+```
+
+Examples of **correct** code for this rule:
+
+```javascript
+function foo() {
+ if (error) {
+ return "It failed";
+ }
+
+ if (loading) {
+ return "It's still loading";
+ }
+}
+```
+
+## References
+
+- [Rule Source](https://github.com/oxc-project/oxc/blob/main/crates/oxc_linter/src/rules/eslint/no_else_return.rs)
diff --git a/src/docs/guide/usage/linter/rules/eslint/no-return-assign.md b/src/docs/guide/usage/linter/rules/eslint/no-return-assign.md
new file mode 100644
index 00000000000..7e7a5f4a34f
--- /dev/null
+++ b/src/docs/guide/usage/linter/rules/eslint/no-return-assign.md
@@ -0,0 +1,44 @@
+
+
+# eslint/no-return-assign
+
+
+
+### What it does
+
+Disallows assignment operators in return statements
+
+### Why is this bad?
+
+Assignment is allowed by js in return expressions, but usually, an expression with only one equal sign is intended to be a comparison.
+However, because of the missing equal sign, this turns to assignment, which is valid js code
+Because of this ambiguity, itβs considered a best practice to not use assignment in return statements.
+
+### Examples
+
+Examples of **incorrect** code for this rule:
+
+```js
+() => (a = b);
+function x() {
+ return (a = b);
+}
+```
+
+Examples of **correct** code for this rule:
+
+```js
+() => (a = b);
+function x() {
+ var result = (a = b);
+ return result;
+}
+```
+
+## References
+
+- [Rule Source](https://github.com/oxc-project/oxc/blob/main/crates/oxc_linter/src/rules/eslint/no_return_assign.rs)
diff --git a/src/docs/guide/usage/linter/rules/eslint/no-throw-literal.md b/src/docs/guide/usage/linter/rules/eslint/no-throw-literal.md
new file mode 100644
index 00000000000..b38e2f08958
--- /dev/null
+++ b/src/docs/guide/usage/linter/rules/eslint/no-throw-literal.md
@@ -0,0 +1,61 @@
+
+
+# eslint/no-throw-literal
+
+
+
+### What it does
+
+Disallows throwing literals or non-Error objects as exceptions.
+
+### Why is this bad?
+
+It is considered good practice to only throw the Error object itself or an object using
+the Error object as base objects for user-defined exceptions. The fundamental benefit of
+Error objects is that they automatically keep track of where they were built and originated.
+
+### Examples
+
+Examples of **incorrect** code for this rule:
+
+```js
+throw "error";
+
+throw 0;
+
+throw undefined;
+
+throw null;
+
+var err = new Error();
+throw "an " + err;
+// err is recast to a string literal
+
+var err = new Error();
+throw `${err}`;
+```
+
+Examples of **correct** code for this rule:
+
+```js
+throw new Error();
+
+throw new Error("error");
+
+var e = new Error("error");
+throw e;
+
+try {
+ throw new Error("error");
+} catch (e) {
+ throw e;
+}
+```
+
+## References
+
+- [Rule Source](https://github.com/oxc-project/oxc/blob/main/crates/oxc_linter/src/rules/eslint/no_throw_literal.rs)
diff --git a/src/docs/guide/usage/linter/rules/import/default.md b/src/docs/guide/usage/linter/rules/import/default.md
index 3b2de3799cc..233093b7d74 100644
--- a/src/docs/guide/usage/linter/rules/import/default.md
+++ b/src/docs/guide/usage/linter/rules/import/default.md
@@ -7,9 +7,19 @@
### What it does
-If a default import is requested, this rule will report if there is no default export in the imported module.
+If a default import is requested, this rule will report if there is no
+default export in the imported module.
-### Example
+### Why is this bad?
+
+Using a default import when there is no default export can lead to
+confusion and runtime errors. It can make the code harder to understand
+and maintain, as it may suggest that a module has a default export
+when it does not, leading to unexpected behavior.
+
+### Examples
+
+Examples of **incorrect** code for this rule:
```javascript
// ./bar.js
@@ -21,6 +31,18 @@ export function bar() {
import bar from "./bar"; // no default export found in ./bar
```
+Examples of **correct** code for this rule:
+
+```javascript
+// ./bar.js
+export default function bar() {
+ return null;
+}
+
+// ./foo.js
+import { bar } from "./bar"; // correct usage of named import
+```
+
## References
- [Rule Source](https://github.com/oxc-project/oxc/blob/main/crates/oxc_linter/src/rules/import/default.rs)
diff --git a/src/docs/guide/usage/linter/rules/import/export.md b/src/docs/guide/usage/linter/rules/import/export.md
index 332dcba6fe2..e1b625ea8f5 100644
--- a/src/docs/guide/usage/linter/rules/import/export.md
+++ b/src/docs/guide/usage/linter/rules/import/export.md
@@ -9,12 +9,28 @@
Reports funny business with exports, like repeated exports of names or defaults.
-### Example
+### Why is this bad?
+
+Having multiple exports of the same name can lead to ambiguity and confusion
+in the codebase. It makes it difficult to track which export is being used
+and can result in runtime errors if the wrong export is referenced.
+
+### Examples
+
+Examples of **incorrect** code for this rule:
```javascript
let foo;
export { foo }; // Multiple exports of name 'foo'.
-export * from "./export-all"; // export-all.js also export foo
+export * from "./export-all"; // Conflicts if export-all.js also exports foo
+```
+
+Examples of **correct** code for this rule:
+
+```javascript
+let foo;
+export { foo as foo1 }; // Renamed export to avoid conflict
+export * from "./export-all"; // No conflict if export-all.js also exports foo
```
## References
diff --git a/src/docs/guide/usage/linter/rules/import/max-dependencies.md b/src/docs/guide/usage/linter/rules/import/max-dependencies.md
index b5ec78a9508..a8152761e8c 100644
--- a/src/docs/guide/usage/linter/rules/import/max-dependencies.md
+++ b/src/docs/guide/usage/linter/rules/import/max-dependencies.md
@@ -11,18 +11,27 @@ Forbid modules to have too many dependencies (import or require statements).
### Why is this bad?
-This is a useful rule because a module with too many dependencies is a code smell, and
-usually indicates the module is doing too much and/or should be broken up into smaller
-modules.
+This is a useful rule because a module with too many dependencies is a code smell,
+and usually indicates the module is doing too much and/or should be broken up into
+smaller modules.
-### Example
+### Examples
Given `{"max": 2}`
+Examples of **incorrect** code for this rule:
+
```javascript
import a from "./a";
import b from "./b";
-import c from "./c";
+import c from "./c"; // Too many dependencies: 3 (max: 2)
+```
+
+Examples of **correct** code for this rule:
+
+```javascript
+import a from "./a";
+import b from "./b"; // Allowed: 2 dependencies (max: 2)
```
## References
diff --git a/src/docs/guide/usage/linter/rules/import/named.md b/src/docs/guide/usage/linter/rules/import/named.md
index 014001baac8..134a9f12248 100644
--- a/src/docs/guide/usage/linter/rules/import/named.md
+++ b/src/docs/guide/usage/linter/rules/import/named.md
@@ -24,7 +24,13 @@ by Flow, are always ignored.
### Why is this bad?
-### Example
+Importing or exporting names that do not exist in the referenced module
+can lead to runtime errors and confusion. It may suggest that certain
+functionality is available when it is not, making the code harder to
+maintain and understand. This rule helps ensure that your code
+accurately reflects the available exports, improving reliability.
+
+### Examples
Given
@@ -33,31 +39,31 @@ Given
export const foo = "I'm so foo";
```
-The following is considered valid:
+Examples of **incorrect** code for this rule:
```js
-// ./bar.js
-import { foo } from "./foo";
+// ./baz.js
+import { notFoo } from "./foo";
// ES7 proposal
-export { foo as bar } from "./foo";
+export { notFoo as defNotBar } from "./foo";
-// node_modules without jsnext:main are not analyzed by default
-// (import/ignore setting)
-import { SomeNonsenseThatDoesntExist } from "react";
+// will follow 'jsnext:main', if available
+import { dontCreateStore } from "redux";
```
-...and the following are reported:
+Examples of **correct** code for this rule:
```js
-// ./baz.js
-import { notFoo } from "./foo";
+// ./bar.js
+import { foo } from "./foo";
// ES7 proposal
-export { notFoo as defNotBar } from "./foo";
+export { foo as bar } from "./foo";
-// will follow 'jsnext:main', if available
-import { dontCreateStore } from "redux";
+// node_modules without jsnext:main are not analyzed by default
+// (import/ignore setting)
+import { SomeNonsenseThatDoesntExist } from "react";
```
## References
diff --git a/src/docs/guide/usage/linter/rules/import/namespace.md b/src/docs/guide/usage/linter/rules/import/namespace.md
index c4750d79764..c91c30d955e 100644
--- a/src/docs/guide/usage/linter/rules/import/namespace.md
+++ b/src/docs/guide/usage/linter/rules/import/namespace.md
@@ -14,6 +14,50 @@ declaration if there are no exported names found. Also, will report for
computed references (i.e. `foo["bar"]()`). Reports on assignment to a
member of an imported namespace.
+### Why is this bad?
+
+Dereferencing a name that does not exist can lead to runtime errors and
+unexpected behavior in your code. It makes the code less reliable and
+harder to maintain, as it may not be clear which names are valid. This
+rule helps ensure that all referenced names are defined, improving
+the clarity and robustness of your code.
+
+### Examples
+
+Given
+
+```javascript
+// ./foo.js
+export const bar = "I'm bar";
+```
+
+Examples of **incorrect** code for this rule:
+
+```javascript
+// ./qux.js
+import * as foo from "./foo";
+foo.notExported(); // Error: notExported is not exported
+
+// Assignment to a member of an imported namespace
+foo.bar = "new value"; // Error: bar cannot be reassigned
+
+// Computed reference to a non-existent export
+const method = "notExported";
+foo[method](); // Error: notExported does not exist
+```
+
+Examples of **correct** code for this rule:
+
+```javascript
+// ./baz.js
+import * as foo from "./foo";
+console.log(foo.bar); // Valid: bar is exported
+
+// Computed reference
+const method = "bar";
+foo[method](); // Valid: method refers to an exported function
+```
+
## References
- [Rule Source](https://github.com/oxc-project/oxc/blob/main/crates/oxc_linter/src/rules/import/namespace.rs)
diff --git a/src/docs/guide/usage/linter/rules/import/no-amd.md b/src/docs/guide/usage/linter/rules/import/no-amd.md
index 97dd64919c6..de08f460778 100644
--- a/src/docs/guide/usage/linter/rules/import/no-amd.md
+++ b/src/docs/guide/usage/linter/rules/import/no-amd.md
@@ -7,10 +7,17 @@
### What it does
-Forbid AMD `require` and `define` calls.
+Forbids the use of AMD `require` and `define` calls.
### Why is this bad?
+AMD (Asynchronous Module Definition) is an older module format
+that is less common in modern JavaScript development, especially
+with the widespread use of ES6 modules and CommonJS in Node.js.
+AMD introduces unnecessary complexity and is often considered outdated.
+This rule enforces the use of more modern module systems to improve
+maintainability and consistency across the codebase.
+
### Examples
Examples of **incorrect** code for this rule:
diff --git a/src/docs/guide/usage/linter/rules/import/no-cycle.md b/src/docs/guide/usage/linter/rules/import/no-cycle.md
index a871168ec3e..dc3efc0918f 100644
--- a/src/docs/guide/usage/linter/rules/import/no-cycle.md
+++ b/src/docs/guide/usage/linter/rules/import/no-cycle.md
@@ -15,10 +15,11 @@ if the maxDepth option is not set.
### Why is this bad?
Dependency cycles lead to confusing architectures where bugs become hard to find.
-
It is common to import an `undefined` value that is caused by a cyclic dependency.
-### Example
+### Examples
+
+Examples of **incorrect** code for this rule:
```javascript
// dep-b.js
@@ -31,8 +32,33 @@ export function b() {
```javascript
// dep-a.js
import { b } from "./dep-b.js"; // reported: Dependency cycle detected.
+export function a() {
+ /* ... */
+}
+```
+
+In this example, `dep-a.js` and `dep-b.js` import each other, creating a circular
+dependency, which is problematic.
+
+Examples of **correct** code for this rule:
+
+```javascript
+// dep-b.js
+export function b() {
+ /* ... */
+}
+```
+
+```javascript
+// dep-a.js
+import { b } from "./dep-b.js"; // no circular dependency
+export function a() {
+ /* ... */
+}
```
+In this corrected version, `dep-b.js` no longer imports `dep-a.js`, breaking the cycle.
+
## References
- [Rule Source](https://github.com/oxc-project/oxc/blob/main/crates/oxc_linter/src/rules/import/no_cycle.rs)
diff --git a/src/docs/guide/usage/linter/rules/import/no-default-export.md b/src/docs/guide/usage/linter/rules/import/no-default-export.md
index 52414cd6abb..6025643891c 100644
--- a/src/docs/guide/usage/linter/rules/import/no-default-export.md
+++ b/src/docs/guide/usage/linter/rules/import/no-default-export.md
@@ -7,7 +7,15 @@
### What it does
-Forbid a module to have a default exports. This help your editor to provide better auto imports.
+Forbids a module from having default exports. This helps your editor
+provide better auto-import functionality, as named exports offer more
+explicit and predictable imports compared to default exports.
+
+### Why is this bad?
+
+Default exports can lead to confusion, as the name of the imported value
+can vary based on how it's imported. This can make refactoring and
+auto-imports less reliable.
### Examples
diff --git a/src/docs/guide/usage/linter/rules/import/no-duplicates.md b/src/docs/guide/usage/linter/rules/import/no-duplicates.md
index 83471bfd8de..da69dce2b56 100644
--- a/src/docs/guide/usage/linter/rules/import/no-duplicates.md
+++ b/src/docs/guide/usage/linter/rules/import/no-duplicates.md
@@ -7,7 +7,29 @@
### What it does
-Reports if a resolved path is imported more than once.
+Reports if a resolved path is imported more than once in the same module.
+This helps avoid unnecessary duplicate imports and keeps the code clean.
+
+### Why is this bad?
+
+Importing the same module multiple times can lead to redundancy and
+unnecessary complexity. It also affects maintainability, as it might
+confuse developers and result in inconsistent usage of imports across the code.
+
+### Examples
+
+Examples of **incorrect** code for this rule:
+
+```javascript
+import { foo } from "./module";
+import { bar } from "./module";
+```
+
+Examples of **correct** code for this rule:
+
+```javascript
+import { foo, bar } from "./module";
+```
## References
diff --git a/src/docs/guide/usage/linter/rules/import/no-dynamic-require.md b/src/docs/guide/usage/linter/rules/import/no-dynamic-require.md
index 15c99e2738f..fb3b6291f1e 100644
--- a/src/docs/guide/usage/linter/rules/import/no-dynamic-require.md
+++ b/src/docs/guide/usage/linter/rules/import/no-dynamic-require.md
@@ -7,12 +7,15 @@
### What it does
-Forbid imports which use an expression for the module argument.
+Forbids imports that use an expression for the module argument. This includes
+dynamically resolved paths in `require` or `import` statements.
### Why is this bad?
-Import statements which use an expression resolved at runtime makes it to find where the
-import comes from and some static code analysis tools might not be able to resolve them.
+Using expressions that are resolved at runtime in import statements makes it
+difficult to determine where the module is being imported from. This can complicate
+code navigation and hinder static analysis tools, which rely on predictable module paths
+for linting, bundling, and other optimizations.
### Examples
diff --git a/src/docs/guide/usage/linter/rules/import/no-named-as-default-member.md b/src/docs/guide/usage/linter/rules/import/no-named-as-default-member.md
index 377c4fb59d7..6a987b2365c 100644
--- a/src/docs/guide/usage/linter/rules/import/no-named-as-default-member.md
+++ b/src/docs/guide/usage/linter/rules/import/no-named-as-default-member.md
@@ -7,9 +7,20 @@
### What it does
-Reports use of an exported name as a property on the default export.
+Reports the use of an exported name (named export) as a property on the
+default export. This occurs when trying to access a named export through
+the default export, which is incorrect.
-### Example
+### Why is this bad?
+
+Accessing a named export via the default export is incorrect and will not
+work as expected. Named exports should be imported directly, while default
+exports are accessed without properties. This mistake can lead to runtime
+errors or undefined behavior.
+
+### Examples
+
+Given
```javascript
// ./bar.js
@@ -19,10 +30,21 @@ export function bar() {
export default () => {
return 1;
};
+```
+
+Examples of **incorrect** code for this rule:
+```javascript
+// ./foo.js
+import foo from "./bar";
+const bar = foo.bar; // Incorrect: trying to access named export via default
+```
+
+Examples of **correct** code for this rule:
+
+```javascript
// ./foo.js
-import bar from "./bar";
-const bar = foo.bar; // trying to access named export via default
+import { bar } from "./bar"; // Correct: accessing named export directly
```
## References
diff --git a/src/docs/guide/usage/linter/rules/import/no-named-as-default.md b/src/docs/guide/usage/linter/rules/import/no-named-as-default.md
index 92406ba062e..4fdef9e3f47 100644
--- a/src/docs/guide/usage/linter/rules/import/no-named-as-default.md
+++ b/src/docs/guide/usage/linter/rules/import/no-named-as-default.md
@@ -8,8 +8,19 @@
### What it does
Reports use of an exported name as the locally imported name of a default export.
+This happens when an imported default export is assigned a name that conflicts
+with a named export from the same module.
-### Example
+### Why is this bad?
+
+Using a named export's identifier for a default export can cause confusion
+and errors in understanding which value is being imported. It also reduces
+code clarity, making it harder for other developers to understand the intended
+imports.
+
+### Examples
+
+Given
```javascript
// foo.js
@@ -17,17 +28,18 @@ export default "foo";
export const bar = "baz";
```
-Valid:
+Examples of **incorrect** code for this rule:
```javascript
-import foo from "./foo.js";
+// Invalid: using exported name 'bar' as the identifier for default export.
+import bar from "./foo.js";
```
-Invalid:
+Examples of **correct** code for this rule:
```javascript
-// using exported name 'bar' as identifier for default export.
-import bar from "./foo.js";
+// Valid: correctly importing default export with a non-conflicting name.
+import foo from "./foo.js";
```
## References
diff --git a/src/docs/guide/usage/linter/rules/import/no-self-import.md b/src/docs/guide/usage/linter/rules/import/no-self-import.md
index 60065079489..b0030ea09e1 100644
--- a/src/docs/guide/usage/linter/rules/import/no-self-import.md
+++ b/src/docs/guide/usage/linter/rules/import/no-self-import.md
@@ -7,14 +7,29 @@
### What it does
-Forbid a module from importing itself. This can sometimes happen during refactoring.
+Forbids a module from importing itself. This can sometimes happen accidentally,
+especially during refactoring.
-### Example
+### Why is this bad?
+
+Importing a module into itself creates a circular dependency, which can cause
+runtime issues, including infinite loops, unresolved imports, or `undefined` values.
+
+### Examples
+
+Examples of **incorrect** code for this rule:
+
+```javascript
+// foo.js
+import foo from "./foo.js"; // Incorrect: module imports itself
+const foo = require("./foo"); // Incorrect: module imports itself
+```
+
+Examples of **correct** code for this rule:
```javascript
// foo.js
-import foo from "./foo.js";
-const foo = require("./foo");
+import bar from "./bar.js"; // Correct: module imports another module
```
## References
diff --git a/src/docs/guide/usage/linter/rules/import/no-webpack-loader-syntax.md b/src/docs/guide/usage/linter/rules/import/no-webpack-loader-syntax.md
index 9416132e8b6..8d5ae053bd5 100644
--- a/src/docs/guide/usage/linter/rules/import/no-webpack-loader-syntax.md
+++ b/src/docs/guide/usage/linter/rules/import/no-webpack-loader-syntax.md
@@ -7,14 +7,16 @@
### What it does
-Forbid Webpack loader syntax in imports.
+Forbids using Webpack loader syntax directly in import or require statements.
### Why is this bad?
This loader syntax is non-standard, so it couples the code to Webpack. The recommended way to
specify Webpack loader configuration is in a [Webpack configuration file](https://webpack.js.org/concepts/loaders/#configuration).
-### Example
+### Examples
+
+Examples of **incorrect** code for this rule:
```javascript
import myModule from "my-loader!my-module";
@@ -24,6 +26,16 @@ var myModule = require("my-loader!./my-module");
var theme = require("style!css!./theme.css");
```
+Examples of **correct** code for this rule:
+
+```javascript
+import myModule from "./my-module";
+import theme from "./theme.css";
+
+var myModule = require("./my-module");
+var theme = require("./theme.css");
+```
+
## References
- [Rule Source](https://github.com/oxc-project/oxc/blob/main/crates/oxc_linter/src/rules/import/no_webpack_loader_syntax.rs)
diff --git a/src/docs/guide/usage/linter/rules/promise/prefer-await-to-callbacks.md b/src/docs/guide/usage/linter/rules/promise/prefer-await-to-callbacks.md
new file mode 100644
index 00000000000..3ce94777227
--- /dev/null
+++ b/src/docs/guide/usage/linter/rules/promise/prefer-await-to-callbacks.md
@@ -0,0 +1,46 @@
+
+
+# promise/prefer-await-to-callbacks
+
+
+
+
+### What it does
+
+The rule encourages the use of `async/await` for handling asynchronous code
+instead of traditional callback functions. `async/await`, introduced in ES2017,
+provides a clearer and more concise syntax for writing asynchronous code,
+making it easier to read and maintain.
+
+### Why is this bad?
+
+Using callbacks can lead to complex, nested structures known as "callback hell,"
+which make code difficult to read and maintain. Additionally, error handling can
+become cumbersome with callbacks, whereas `async/await` allows for more straightforward
+try/catch blocks for managing errors.
+
+### Examples
+
+Examples of **incorrect** code for this rule:
+
+```js
+cb();
+callback();
+doSomething(arg, (err) => {});
+function doSomethingElse(cb) {}
+```
+
+Examples of **correct** code for this rule:
+
+```js
+await doSomething(arg);
+async function doSomethingElse() {}
+function* generator() {
+ yield yieldValue((err) => {});
+}
+eventEmitter.on("error", (err) => {});
+```
+
+## References
+
+- [Rule Source](https://github.com/oxc-project/oxc/blob/main/crates/oxc_linter/src/rules/promise/prefer_await_to_callbacks.rs)
diff --git a/src/docs/guide/usage/linter/rules/tree_shaking/no-side-effects-in-initialization.md b/src/docs/guide/usage/linter/rules/tree_shaking/no-side-effects-in-initialization.md
index b90f4f1502c..021da817328 100644
--- a/src/docs/guide/usage/linter/rules/tree_shaking/no-side-effects-in-initialization.md
+++ b/src/docs/guide/usage/linter/rules/tree_shaking/no-side-effects-in-initialization.md
@@ -14,12 +14,25 @@ interfere with the tree-shaking algorithm of their module bundler (i.e. rollup o
### Why is this bad?
-### Example
+Side-effects in module initialization can hinder tree-shaking, which aims to remove
+unused code. If side-effects exist, it's harder for the bundler to safely eliminate
+code, leading to larger bundles and potentially unexpected behavior. Ensuring minimal
+side-effects allows bundlers to optimize code effectively.
+
+### Examples
+
+Examples of **incorrect** code for this rule:
```javascript
myGlobal = 17; // Cannot determine side-effects of assignment to global variable
const x = { [globalFunction()]: "myString" }; // Cannot determine side-effects of calling global function
-export default 42;
+```
+
+Examples of **correct** code for this rule:
+
+```javascript
+const localVar = 17; // Local variable assignment, no global side-effects
+export default 42; // Pure export with no side-effects
```
### Options