---
url: /sponsor.md
---

# 🌟 Become an Oxc Sponsor

## 🤝 How to Sponsor

You can sponsor us on [GitHub Sponsors](https://github.com/sponsors/oxc-project) or [OpenCollective](https://opencollective.com/oxc).

## 💚 Why sponsor?

Sponsorship lets us keep improving the JavaScript and Rust ecosystems without burning out.

Everything we receive on OpenCollective is paid out to core team members who are not part of [VoidZero](https://voidzero.dev).

As a sponsor, your avatar is displayed across all [oxc-project repositories](https://github.com/oxc-project) and on the [landing page](/) of this website.

If our work has improved your development experience, your CI pipelines, your build times, or your learning, please consider sponsoring. It helps more than you might think, and it keeps the motivation alive.

## Current Sponsors

---

---
url: /docs/learn/parser_in_rust/ast.md
---

# AST

The parser in the upcoming chapter is responsible for turning Tokens into an abstract syntax tree (AST).
It is much nicer to work on the AST compared to the source text.

All JavaScript toolings work on the AST level, for example:

* A linter (e.g. ESLint) checks the AST for errors
* A formatter (e.g.prettier) prints the AST back to JavaScript text
* A minifier (e.g. terser) transforms the AST
* A bundler connects all import and export statements between ASTs from different files

In this chapter, let's construct a JavaScript AST by using Rust structs and enums.

## Getting familiar with the AST

To get ourselves comfortable with an AST, let's visit [ASTExplorer](https://astexplorer.net/) and see what it looks like.
On the top panel, select JavaScript, and then `acorn`, type in `var a` and we will see a tree view and a JSON view.

```json
{
  "type": "Program",
  "start": 0,
  "end": 5,
  "body": [
    {
      "type": "VariableDeclaration",
      "start": 0,
      "end": 5,
      "declarations": [
        {
          "type": "VariableDeclarator",
          "start": 4,
          "end": 5,
          "id": {
            "type": "Identifier",
            "start": 4,
            "end": 5,
            "name": "a"
          },
          "init": null
        }
      ],
      "kind": "var"
    }
  ],
  "sourceType": "script"
}
```

Since this is a tree, every object is a node with a type name (e.g. `Program`, `VariableDeclaration`, `VariableDeclarator`, `Identifier`).
`start` and `end` are the offsets from the source.

## estree

[estree](https://github.com/estree/estree) is a community standard grammar specification for JavaScript,
it defines [all the AST nodes](https://github.com/estree/estree/blob/master/es5.md) so different tools
can be compatible with each other.

The basic building block for any AST node is the `Node` type:

```rust
#[derive(Debug, Default, Clone, Copy, Serialize, PartialEq, Eq)]
pub struct Node {
    /// Start offset in source
    pub start: usize,

    /// End offset in source
    pub end: usize,
}

impl Node {
    pub fn new(start: usize, end: usize) -> Self {
        Self { start, end }
    }
}
```

AST for `var a` is defined as

```rust
pub struct Program {
    pub node: Node,
    pub body: Vec<Statement>,
}

pub enum Statement {
    VariableDeclarationStatement(VariableDeclaration),
}

pub struct VariableDeclaration {
    pub node: Node,
    pub declarations: Vec<VariableDeclarator>,
}

pub struct VariableDeclarator {
    pub node: Node,
    pub id: BindingIdentifier,
    pub init: Option<Expression>,
}

pub struct BindingIdentifier {
    pub node: Node,
    pub name: String,
}

pub enum Expression {
}
```

Rust does not have inheritance, so `Node` is added to each struct (this is called "composition over Inheritance").

`Statement`s and `Expression`s are enums because they will be expanded with a lot of other node types, for example:

```rust
pub enum Expression {
    AwaitExpression(AwaitExpression),
    YieldExpression(YieldExpression),
}

pub struct AwaitExpression {
    pub node: Node,
    pub expression: Box<Expression>,
}

pub struct YieldExpression {
    pub node: Node,
    pub expression: Box<Expression>,
}
```

The `Box` is needed because self-referential structs are not allowed in Rust.

:::info
JavaScript grammar has a lot of nuisances, read the [grammar tutorial](/docs/learn/ecmascript/grammar.html) for amusement.
:::

## Rust Optimizations

### Memory Allocations

We need to look out for heap-allocated structs such as `Vec` and `Box` because heap allocations are not cheap.

Take a look at the [real world implementation from swc](https://github.com/swc-project/swc/blob/main/crates/swc_ecma_ast/src/expr.rs),
we can see that an AST can have lots of `Box`s and `Vec`s, and also note that the `Statement` and `Expression` enums contain
a dozen of enum variants.

### Memory Arena

Using the global memory allocator for the AST is actually not really efficient.
Every `Box` and `Vec` are allocated on demand and then dropped separately.
What we would like to do is pre-allocate memory and drop it in wholesale.

:::info
See also [Arenas in Rust](https://manishearth.github.io/blog/2021/03/15/arenas-in-rust) and [Flattening ASTs](https://www.cs.cornell.edu/~asampson/blog/flattening.html) for more background on storing ASTs in memory arenas.
:::

[`bumpalo`](https://docs.rs/bumpalo/latest/bumpalo/) is a very good candidate for our use case, according to its documentation:

> Bump allocation is a fast, but limited approach to allocation.
> We have a chunk of memory, and we maintain a pointer within that memory. Whenever we allocate an object,
> we do a quick check that we have enough capacity left in our chunk to allocate the object and then update the pointer by the object’s size. That’s it!
>
> The disadvantage of bump allocation is that there is no general way to deallocate individual objects or reclaim the memory region for a no-longer-in-use object.
>
> These trade offs make bump allocation well-suited for phase-oriented allocations. That is, a group of objects that will all be allocated during the same program phase, used, and then can all be deallocated together as a group.

By using `bumpalo::collections::Vec` and `bumpalo::boxed::Box`, our AST will have lifetimes added to it:

```rust
use bumpalo::collections::Vec;
use bumpalo::boxed::Box;

pub enum Expression<'a> {
    AwaitExpression(Box<'a, AwaitExpression>),
    YieldExpression(Box<'a, YieldExpression>),
}

pub struct AwaitExpression<'a> {
    pub node: Node,
    pub expression: Expression<'a>,
}

pub struct YieldExpression<'a> {
    pub node: Node,
    pub expression: Expression<'a>,
}
```

:::info
Please be cautious if we are not comfortable dealing with lifetimes at this stage.
Our program will work fine without a memory arena.

Code in the following chapters does not demonstrate the use of a memory arena for simplicity.
:::

### Enum Size

The first optimization we are going to make is to reduce the size of the enums.

It is known that the byte size of a Rust enum is the union of all its variants.
For example, the following enum will take up 56 bytes (1 byte for the tag, 48 bytes for the payload, and 8 bytes for alignment).

```rust
enum Name {
    Anonymous, // 0 byte payload
    Nickname(String), // 24 byte payload
    FullName{ first: String, last: String }, // 48 byte payload
}
```

:::info
This example is taken from [this blog post](https://adeschamps.github.io/enum-size)
:::

As for the `Expression` and `Statement` enums, they can take up to more than 200 bytes with our current setup.

These 200 bytes need to be passed around, or accessed every time we do a `matches!(expr, Expression::AwaitExpression(_))` check,
which is not very cache friendly for performance.

A better approach would be to box the enum variants and only carry 16 bytes around.

```rust
pub enum Expression {
    AwaitExpression(Box<AwaitExpression>),
    YieldExpression(Box<YieldExpression>),
}

pub struct AwaitExpression {
    pub node: Node,
    pub expression: Expression,
}

pub struct YieldExpression {
    pub node: Node,
    pub expression: Expression,
}
```

To make sure the enums are indeed 16 bytes on 64-bit systems, we can use `std::mem::size_of`.

```rust
#[test]
fn no_bloat_enum_sizes() {
    use std::mem::size_of;
    assert_eq!(size_of::<Statement>(), 16);
    assert_eq!(size_of::<Expression>(), 16);
}
```

"no bloat enum sizes" test cases can often be seen in the Rust compiler source code for ensuring small enum sizes.

```rust
// https://github.com/rust-lang/rust/blob/9c20b2a8cc7588decb6de25ac6a7912dcef24d65/compiler/rustc_ast/src/ast.rs#L3033-L3042

// Some nodes are used a lot. Make sure they don't unintentionally get bigger.
#[cfg(all(target_arch = "x86_64", target_pointer_width = "64"))]
mod size_asserts {
    use super::*;
    use rustc_data_structures::static_assert_size;
    // These are in alphabetical order, which is easy to maintain.
    static_assert_size!(AssocItem, 160);
    static_assert_size!(AssocItemKind, 72);
    static_assert_size!(Attribute, 32);
    static_assert_size!(Block, 48);
```

To find other large types, we can run

```bash
RUSTFLAGS=-Zprint-type-sizes cargo +nightly build -p name_of_the_crate --release
```

and see

```
print-type-size type: `ast::js::Statement`: 16 bytes, alignment: 8 bytes
print-type-size     discriminant: 8 bytes
print-type-size     variant `BlockStatement`: 8 bytes
print-type-size         field `.0`: 8 bytes
print-type-size     variant `BreakStatement`: 8 bytes
print-type-size         field `.0`: 8 bytes
print-type-size     variant `ContinueStatement`: 8 bytes
print-type-size         field `.0`: 8 bytes
print-type-size     variant `DebuggerStatement`: 8 bytes
print-type-size         field `.0`: 8 bytes
```

## JSON Serialization

[serde](https://serde.rs/) can be used serialize the AST to JSON. Some techniques are needed to make it `estree` compatible.
Here are some examples:

```rust
use serde::Serialize;

#[derive(Debug, Clone, Serialize, PartialEq)]
#[serde(tag = "type")]
#[cfg_attr(feature = "estree", serde(rename = "Identifier"))]
pub struct IdentifierReference {
    #[serde(flatten)]
    pub node: Node,
    pub name: Atom,
}

#[derive(Debug, Clone, Serialize, PartialEq, Hash)]
#[serde(tag = "type")]
#[cfg_attr(feature = "estree", serde(rename = "Identifier"))]
pub struct BindingIdentifier {
    #[serde(flatten)]
    pub node: Node,
    pub name: Atom,
}

#[derive(Debug, Serialize, PartialEq)]
#[serde(untagged)]
pub enum Expression<'a> {
    ...
}
```

* `serde(tag = "type")` is used to make the struct name a "type" field, i.e. `{ "type" : "..." }`
* `cfg_attr` + `serde(rename)` is used to rename different struct names to the same name, since `estree` does not distinguish different identifiers
* `serde(untagged)` on the enum is used to not create an extra JSON object for the enum

---

---
url: /docs/contribute/linter/adding-rules.md
---

# Adding Linter Rules

The best and easiest way to contribute to Oxlint is by adding new linter rules.

This guide will walk you through this process, using ESLint's
[`no-debugger`](https://eslint.org/docs/latest/rules/no-debugger) rule as an
example.

:::tip
Make sure you've read the [setup instructions](../development.md) first.
:::

## Step 1: Pick a Rule

Our [Linter product plan and progress](https://github.com/oxc-project/oxc/issues/481) issue tracks the status
of all rules we want to implement from existing ESLint plugins. From there, pick
a plugin that looks interesting to you and find a rule that has not been
implemented.

**Important**: Since ESLint-compatible JavaScript plugin support is now available, we do not plan to add new Rust-based plugins. However, contributions that add rules to existing plugins are **highly encouraged**. If you think a rule or plugin would benefit from being written in rust, please open a discussion first, before making a pull request.

Most documentation pages for ESLint rules include a link to the rule's [source code](https://eslint.org/docs/latest/rules/no-debugger#resources). Using this as
a reference will help you with your implementation.

## Step 2: Rule Generation

Next, run the rulegen script to generate boilerplate code for your new rule.

```bash
just new-rule no-debugger
```

This will:

1. Create a new file in `crates/oxc_linter/src/rules/<plugin-name>/<rule-name>.rs` with the start of your rule's implementation and all test cases ported from ESLint
2. Register the rule in the appropriate `mod` in [`rules.rs`](https://github.com/oxc-project/oxc/blob/main/crates/oxc_linter/src/rules.rs)
3. Add the rule to `oxc_macros::declare_all_lint_rules!`

For rules that are part of a different plugin, you'll need to use that plugin's
own rulegen script.

:::tip
Run `just` with no arguments to see all available commands.
:::

```bash
just new-rule [name]            # for eslint core rules
just new-jest-rule [name]       # for eslint-plugin-jest
just new-ts-rule [name]         # for @typescript-eslint/eslint-plugin
just new-unicorn-rule [name]    # for eslint-plugin-unicorn
just new-import-rule [name]     # for eslint-plugin-import
just new-react-rule [name]      # for eslint-plugin-react and eslint-plugin-react-hooks
just new-jsx-a11y-rule [name]   # for eslint-plugin-jsx-a11y
just new-oxc-rule [name]        # for oxc's own rules
just new-nextjs-rule [name]     # for eslint-plugin-next
just new-jsdoc-rule [name]      # for eslint-plugin-jsdoc
just new-react-perf-rule [name] # for eslint-plugin-react-perf
just new-n-rule [name]          # for eslint-plugin-n
just new-promise-rule [name]    # for eslint-plugin-promise
just new-vitest-rule [name]     # for eslint-plugin-vitest
```

The generated file will look something like this:

::: code-group

````rust [rules/eslint/no_debugger.rs]
use oxc_diagnostics::OxcDiagnostic;
use oxc_macros::declare_oxc_lint;
use oxc_span::Span;

use crate::{
    context::LintContext,
    fixer::{RuleFix, RuleFixer},
    rule::Rule,
    AstNode,
};

#[derive(Debug, Default, Clone)]
pub struct NoDebugger;

declare_oxc_lint!(
    /// ### What it does
    ///
    ///
    /// ### Why is this bad?
    ///
    ///
    /// ### Examples
    ///
    /// Examples of **incorrect** code for this rule:
    /// ```js
    /// FIXME: Tests will fail if examples are missing or syntactically incorrect.
    /// ```
    ///
    /// Examples of **correct** code for this rule:
    /// ```js
    /// FIXME: Tests will fail if examples are missing or syntactically incorrect.
    /// ```
    NoDebugger,
    nursery, // TODO: change category to `correctness`, `suspicious`, `pedantic`, `perf`, `restriction`, or `style`
             // See <https://oxc.rs/docs/contribute/linter.html#rule-category> for details

    pending  // TODO: describe fix capabilities. Remove if no fix can be done,
             // keep at 'pending' if you think one could be added but don't know how.
             // Options are 'fix', 'fix_dangerous', 'suggestion', and 'conditional_fix_suggestion'
);

impl Rule for NoDebugger {
    fn run<'a>(&self, node: &AstNode<'a>, ctx: &LintContext<'a>) {}
}

#[test]
fn test() {
    use crate::tester::Tester;
    let pass = vec!["var test = { debugger: 1 }; test.debugger;"];
    let fail = vec!["if (foo) debugger"];
    Tester::new(NoDebugger::NAME, pass, fail).test_and_snapshot();
}
````

:::

Your rule should now be ready to run! You can try it out with `cargo test -p
oxc_linter`. The tests should fail, since you haven't implemented the rule yet.

## Step 3: Fill Out the Template

### Documentation

Fill out the various documentation sections.

* Provide a clear and concise summary of what the rule does.
* Explain why the rule is important and what undesirable behavior it prevents.
* Provide examples of code that violates the rule and code that does not.

Remember, we use this documentation to generate the [rule documentation pages](/docs/guide/usage/linter/rules) for this website, so make sure your
documentation is clear and helpful!

#### Configuration Documentation

If your rule has configuration options, you will need to document them. You should do so via the system for auto-generating documentation. This should be partially generated for you automatically by the rulegen script.

Each configuration option should be defined by adding fields to the rule's struct:

```rust
pub struct RuleName {
  option_name: bool,
  another_option: String,
  yet_another_option: Vec<CompactStr>,
}
```

Alternatively, you can instead define a separate `Config` struct to hold all configuration options:

```rust
pub struct RuleName(Box<RuleNameConfig>);

pub struct RuleNameConfig {
  option_name: bool,
}
```

The configuration options should have `JsonSchema` derived for them and also a serde decoration, like so:

```rust
use schemars::JsonSchema;

#[derive(Debug, Default, Clone, JsonSchema)]
#[serde(rename_all = "camelCase", default)]
pub struct RuleName {
  option_name: bool,
}
```

Add documentation comments (`///`) to each field to describe the option, for example:

```rust
use schemars::JsonSchema;

#[derive(Debug, Default, Clone, JsonSchema)]
#[serde(rename_all = "camelCase", default)]
pub struct RuleName {
  /// Whether to check for foo and bar when evaluating baz.
  /// The comment can be as long as you need to fully describe the option.
  option_name: bool,
}
```

The default value and the type of each option will be automatically extracted from the struct definition, and should not be mentioned in the documentation comments.

See [this issue](https://github.com/oxc-project/oxc/issues/14743) for dozens of examples of how to properly document configuration options in all kinds of rules.

You can view the generated documentation by running `cargo run -p website -- linter-rules --rule-docs target/rule-docs --git-ref $(git rev-parse HEAD)` and then opening `target/rule-docs/<plugin-name>/<rule-name>.md`.

### Rule Category

First, pick a [rule category](../linter.md#rule-category) that best fits the
rule. Remember that `correctness` rules will be run by default, so be careful
when choosing this category. Set your category within the `declare_oxc_lint!` macro.

### Fixer Status

If the rule has a fixer, register what kind of fixes it provides within
`declare_oxc_lint!`. If you're not comfortable with implementing a fixer, you
can also use `pending` as a placeholder. This helps other contributors find and
implement missing fixers down the line.

### Diagnostics

Create a function to create diagnostics for rule violations. Follow these
principles:

1. The `message` should be an imperative statement about what is wrong, not a description of what the rule does.
2. The `help` message should be a command-like statement that tells the user how to fix the issue.

::: code-group

```rust [good]
fn no_debugger_diagnostic(span: Span) -> OxcDiagnostic {
    OxcDiagnostic::warn("`debugger` statement is not allowed")
        .with_help("Remove this `debugger` statement")
        .with_label(span)
}
```

```rust [bad]
fn no_debugger_diagnostic(span: Span) -> OxcDiagnostic {
    OxcDiagnostic::warn("Disallow `debugger` statements")
        .with_help("`debugger` statements are not allowed.")
        .with_label(span)
```

:::

## Step 4: Rule Implementation

Read the rule's source code to understand how it works. Although Oxlint works
similarly to ESLint, it is unlikely that the rule can be ported directly.

ESLint rules have a `create` function that returns an object whose keys are AST
nodes that trigger the rule and values are functions that run lints on those
nodes. Oxlint rules run on one of a few triggers, each of which come from the
[`Rule`](https://github.com/oxc-project/oxc/blob/main/crates/oxc_linter/src/rule.rs)
trait:

1. Run on each AST node (via `run`)
2. Run on each symbol (via `run_on_symbol`)
3. Run a single time on the entire file (via `run_once`)

In the case of `no-debugger`, we are looking for `DebuggerStatement` nodes, so
we'll use `run`. Here's a simplified version of the rule:

::: code-group

````rust [rules/eslint/no_debugger.rs]
use oxc_ast::AstKind;
use oxc_diagnostics::OxcDiagnostic;
use oxc_macros::declare_oxc_lint;
use oxc_span::Span;

use crate::{context::LintContext, rule::Rule, AstNode};

fn no_debugger_diagnostic(span: Span) -> OxcDiagnostic {
    OxcDiagnostic::warn("`debugger` statement is not allowed")
        .with_label(span)
}

#[derive(Debug, Default, Clone)]
pub struct NoDebugger;

declare_oxc_lint!(
    /// ### What it does
    /// Checks for usage of the `debugger` statement
    ///
    /// ### Why is this bad?
    /// `debugger` statements do not affect functionality when a
    /// debugger isn't attached. They're most commonly an
    /// accidental debugging leftover.
    ///
    /// ### Example
    ///
    /// Examples of **incorrect** code for this rule:
    /// ```js
    /// async function main() {
    ///     const data = await getData();
    ///     const result = complexCalculation(data);
    ///     debugger;
    /// }
    /// ```
    NoDebugger,
    correctness
);

impl Rule for NoDebugger {
    // Runs on each node in the AST
    fn run<'a>(&self, node: &AstNode<'a>, ctx: &LintContext<'a>) {
        // `debugger` statements have their own AST kind
        if let AstKind::DebuggerStatement(stmt) = node.kind() {
            // Report a violation
            ctx.diagnostic(no_debugger_diagnostic(stmt.span));
        }
    }
}
````

:::

:::tip

You
will want to get familiar with the data stored in
[`Semantic`](https://github.com/oxc-project/oxc/blob/main/crates/oxc_semantic/src/lib.rs#L59),
which is where all data extracted during semantic analysis is stored. You will
also want to familiarize yourself with the AST structure. The two most important
data structures here are
[`AstNode`](https://github.com/oxc-project/oxc/blob/main/crates/oxc_semantic/src/node/mod.rs)
and
[`AstKind`](https://github.com/oxc-project/oxc/blob/main/crates/oxc_ast/src/generated/ast_kind.rs)
:::

## Step 5: Testing

To test your rule whenever you make a change, run:

```bash
just watch "cargo test -p oxc_linter -- rule-name"
```

Or to just test it once, run:

```bash
cargo test -p oxc_linter -- rule-name
# Or
cargo insta test -p oxc_linter -- rule-name
```

Oxlint uses [`cargo insta`](https://insta.rs/docs) for snapshot testing. `cargo
test` will fail if snapshots have changed or have just been created. You can run
`cargo insta test -p oxc_linter` to not see diffs in your test results. You can
review the snapshots by running `cargo insta review`, or skip the review and
just accept all changes using `cargo insta accept`.

When you are ready to submit your PR, run `just ready` or `just r` to run CI
checks locally. You can also run `just fix` to auto-fix any lint, format, or
typo problems. Once `just ready` is passing, create a PR and a maintainer will
review your changes.

## General Advice

### Pin point the error message to the shortest code span

We want the user to focus on the problematic code rather than deciphering the
error message to identify which part of the code is erroneous.

### Use `let-else` statements

If you find yourself deeply nesting
[`if-let`](https://doc.rust-lang.org/rust-by-example/flow_control/if_let.html)
statements, consider using [`let-else`](https://doc.rust-lang.org/rust-by-example/flow_control/let_else.html) instead.

:::tip
CodeAesthetic's [never-nesting video](https://www.youtube.com/watch?v=CFRhGnuXG-4) explains this concept in
more detail.
:::

::: code-group

```rust [good]
// let-else is easier to read
fn run<'a>(&self, node: &AstNode<'a>, ctx: &LintContext<'a>) {
    let AstKind::JSXOpeningElement(jsx_opening_elem) = node.kind() else {
        return;
    };
    let Some(expr) = container.expression.as_expression() else {
        return;
    };
    let Expression::BooleanLiteral(expr) = expr.without_parenthesized() else {
        return;
    };
    // ...
}
```

```rust [bad]
// deep nesting is hard to read
fn run<'a>(&self, node: &AstNode<'a>, ctx: &LintContext<'a>) {
    if let AstKind::JSXOpeningElement(jsx_opening_elem) = node.kind() {
        if let Some(expr) = container.expression.as_expression() {
            if let Expression::BooleanLiteral(expr) = expr.without_parenthesized() {
                // ...
            }
        }
    }
}
```

:::

### Use `CompactStr` where possible

Reducing allocations as much as possible is critical for performance in `oxc`. The `String` type requires allocating memory on the heap, which costs memory and CPU cycles. It is possible to [store small strings inline](https://oxc.rs/docs/learn/performance.html#string-inlining) (up to 24 bytes on 64-bit systems) on the stack using `CompactStr`, which means we don't need to allocate memory. If the string is too large to store inline, it will allocate the necessary space. Using `CompactStr` can be used almost anywhere that has the type `String` or `&str`, and can save a significant amount memory and CPU cycles compared to the `String` type.

::: code-group

```rust [good]
struct Element {
  name: CompactStr
}

let element = Element {
  name: "div".into()
};
```

```rust [bad]
struct Element {
  name: String
}

let element = Element {
  name: "div".to_string()
};
```

:::

---

---
url: /docs/guide/benchmarks.md
---

# All Benchmarks

## Parser

Oxc's parser is at least 3x faster than swc and 5x faster than Biome.

Please note that it is not an apple-to-apple comparison with Biome. Biome's parser [produces a CST](https://biomejs.dev/internals/architecture) instead of an AST, which requires a lot more work.

See repository [bench-javascript-parser-written-in-rust](https://github.com/oxc-project/bench-javascript-parser-written-in-rust).

## Transformer

* Compared to swc, oxc transformer is 4x faster, uses 20% less memory, and is 35 MB smaller in package size (from swc's 37MB).
* Compared to babel, oxc transformer is 40x faster, uses 70% less memory, and is 19 MB smaller with 168 npm packages less to install.

See repository [bench-transformer](https://github.com/oxc-project/bench-transformer).

## Linter

Oxlint is 50x - 100x faster than ESLint depending on the number of CPU cores.

See repository [bench-javascript-linter](https://github.com/oxc-project/bench-javascript-linter).

## Formatter

Oxfmt is 3x faster than Biome, 35x faster than prettier.

See repository [bench-formatter](https://github.com/oxc-project/bench-formatter).

## Resolver

`oxc-resolver` is 30x faster than webpack's `enhanced-resolve`.

See repository [bench-resolver](https://github.com/oxc-project/bench-resolver).

---

---
url: /docs/contribute/parser/ast.md
---

# Abstract Syntax Tree (AST)

The Oxc AST is the foundation of all Oxc tools. Understanding its structure and how to work with it is essential for contributing to parser, linter, transformer, and other components.

## AST Architecture

### Design Principles

The Oxc AST is designed with the following principles:

1. **Performance First**: Optimized for speed and memory efficiency
2. **Type Safety**: Leverages Rust's type system to prevent common errors
3. **Spec Compliance**: Closely follows ECMAScript specification
4. **Clear Semantics**: Removes ambiguity present in other AST formats

## Working with the AST

### Generate AST Related Code

When you modify AST definitions, run the code generation tool:

```bash
just ast
```

This generates:

* **Visitor patterns**: For traversing the AST
* **Builder methods**: For constructing AST nodes
* **Trait implementations**: For common operations
* **TypeScript types**: For Node.js bindings

### AST Node Structure

Every AST node follows a consistent pattern:

```rust
#[ast(visit)]
pub struct FunctionDeclaration<'a> {
    pub span: Span,
    pub id: Option<BindingIdentifier<'a>>,
    pub generator: bool,
    pub r#async: bool,
    pub params: FormalParameters<'a>,
    pub body: Option<FunctionBody<'a>>,
    pub type_parameters: Option<TSTypeParameterDeclaration<'a>>,
    pub return_type: Option<TSTypeAnnotation<'a>>,
}
```

Key components:

* **`span`**: Source location information
* **`#[ast(visit)]`**: Generates visitor methods
* **Lifetime `'a`**: References to arena-allocated memory

### Memory Management

The AST uses a memory arena for efficient allocation:

```rust
use oxc_allocator::Allocator;

let allocator = Allocator::default();
let ast = parser.parse(&allocator, source_text, source_type)?;
```

Benefits:

* **Fast allocation**: No individual malloc calls
* **Fast deallocation**: Drop entire arena at once
* **Cache friendly**: Linear memory layout
* **No reference counting**: Simple lifetime management

## AST Traversal

### Visitor Pattern

Use the generated visitor for AST traversal:

```rust
use oxc_ast::visit::{Visit, walk_mut};

struct MyVisitor;

impl<'a> Visit<'a> for MyVisitor {
    fn visit_function_declaration(&mut self, func: &FunctionDeclaration<'a>) {
        println!("Found function: {:?}", func.id);
        walk_mut::walk_function_declaration(self, func);
    }
}

// Usage
let mut visitor = MyVisitor;
visitor.visit_program(&program);
```

### Mutable Visitor

`VisitMut` can be used to modify the AST during traversal.

For example, to transform binary addition of string literals into a single string literal:

```rust
use oxc_ast::AstBuilder;
use oxc_ast_visit::{VisitMut, walk_mut};
use oxc_str::Str;

struct MyTransformer<'a> {
    pub builder: &'a AstBuilder<'a>,
}

impl<'a> VisitMut<'a> for MyTransformer<'a> {
    fn visit_expression(&mut self, expr: &mut Expression<'a>) {
        // Detect the expression type which you want to modify when changing from one enum variant to another.
        if let Expression::BinaryExpression(bin_expr) = expr
            && let (
                BinaryOperator::Addition,
                Expression::StringLiteral(sl),
                Expression::StringLiteral(sr),
            ) = (bin_expr.operator, &bin_expr.left, &bin_expr.right)
        {
            let value = Str::from_strs_array_in(
                [sl.value.as_str(), sr.value.as_str()],
                self.builder.allocator,
            );
            *expr = self.builder.expression_string_literal(SPAN, value, None);
        }

        walk_mut::walk_expression(self, expr);
    }
}
```

For example, to modify a binary expression without changing its type:

```rust
use oxc_ast::AstBuilder;
use oxc_ast_visit::{VisitMut, walk_mut};

struct MyTransformer<'a> {
    pub builder: &'a AstBuilder<'a>,
}

impl<'a> VisitMut<'a> for MyTransformer<'a> {
    fn visit_binary_expression(&mut self, expr: &mut BinaryExpression<'a>) {
        if expr.operator == BinaryOperator::Addition {
            // Modify the AST node. You can modify only left/right and operator parts, not the type of expression itself.
        }
        walk_mut::walk_binary_expression(self, expr);
    }
}
```

## AST Construction

### Builder Pattern

Use the AST builder for creating nodes:

```rust
use oxc_ast::AstBuilder;

let ast = AstBuilder::new(&allocator);

// Create a binary expression: a + b
let left = ast.expression_identifier_reference(SPAN, "a");
let right = ast.expression_identifier_reference(SPAN, "b");
let expr = ast.expression_binary_expression(
    SPAN,
    left,
    BinaryOperator::Addition,
    right,
);
```

### Helper Functions

Common patterns are provided as helpers:

```rust
impl<'a> AstBuilder<'a> {
    pub fn expression_numeric_literal(&self, span: Span, value: f64) -> Expression<'a> {
        self.alloc(Expression::NumericLiteral(
            self.alloc(NumericLiteral { span, value, raw: None })
        ))
    }
}
```

## Development Workflow

### Adding New AST Nodes

1. **Define the struct**:

   ```rust
   #[ast(visit)]
   pub struct MyNewNode<'a> {
       pub span: Span,
       pub name: Atom<'a>,
       pub value: Expression<'a>,
   }
   ```

2. **Add to enum**:

   ```rust
   pub enum Statement<'a> {
       // ... existing variants
       MyNewStatement(Box<'a, MyNewNode<'a>>),
   }
   ```

3. **Run code generation**:

   ```bash
   just ast
   ```

4. **Implement parsing logic**:
   ```rust
   impl<'a> Parser<'a> {
       fn parse_my_new_node(&mut self) -> Result<MyNewNode<'a>> {
           // Parsing implementation
       }
   }
   ```

## Comparing AST Formats

### Use AST Explorer

For comparing with other parsers, use [ast-explorer.dev](https://ast-explorer.dev):

1. **Better UI**: Modern interface with syntax highlighting
2. **Up-to-date**: Latest parser versions
3. **Multiple parsers**: Compare Oxc, Babel, TypeScript, etc.
4. **Export formats**: JSON, code generation

## Performance Considerations

### Memory Layout

The AST is designed for cache efficiency:

```rust
// Good: Compact representation
struct CompactNode<'a> {
    span: Span,           // 8 bytes
    flags: u8,            // 1 byte
    name: Atom<'a>,       // 8 bytes
}

// Avoid: Large enums without boxing
enum LargeEnum {
    Small,
    Large { /* 200 bytes of data */ },
}
```

### Arena Allocation

All AST nodes are allocated in the arena:

```rust
// Automatically handled by #[ast] macro
let node = self.ast.alloc(MyNode {
    span: SPAN,
    value: 42,
});
```

### Enum Size Testing

We enforce small enum sizes:

```rust
#[cfg(all(target_arch = "x86_64", target_pointer_width = "64"))]
#[test]
fn no_bloat_enum_sizes() {
    use std::mem::size_of;
    assert_eq!(size_of::<Statement>(), 16);
    assert_eq!(size_of::<Expression>(), 16);
    assert_eq!(size_of::<Declaration>(), 16);
}
```

## Advanced Topics

### Custom AST Attributes

Add custom attributes for specific tools:

```rust
#[ast(visit)]
#[cfg_attr(feature = "serialize", derive(Serialize))]
pub struct MyNode<'a> {
    #[cfg_attr(feature = "serialize", serde(skip))]
    pub internal_data: u32,
    pub public_field: Atom<'a>,
}
```

### Integration with Semantic Analysis

Link AST nodes with semantic information:

```rust
#[ast(visit)]
pub struct IdentifierReference<'a> {
    pub span: Span,
    pub name: Atom<'a>,
    #[ast(ignore)]
    pub reference_id: Cell<Option<ReferenceId>>,
}
```

This allows tools to access binding information, scope context, and type information during AST traversal.

## Debugging Tips

### Pretty Printing

Use the debug formatter to inspect AST:

```rust
println!("{:#?}", ast_node);
```

### Span Information

Track source locations for error reporting:

```rust
let span = node.span();
println!("Error at {}:{}", span.start, span.end);
```

---

---
url: /docs/learn/architecture/ast-tools.md
---

# AST Tools

The [AST Tools](https://github.com/oxc-project/oxc/tree/main/tasks/ast_tools) task serves as our secret weapon for managing all generated files.
These tools include the AST builder, visitors, traits like `ContentEq` and `ContentHash`, and TypeScript types - all of which are machine-generated.

For instance, the following files are automatically generated:

* `crates/oxc_ast/src/generated/ast_builder.rs`
* `crates/oxc_ast/src/generated/visit.rs`
* `crates/oxc_ast/src/generated/visit_mut.rs`
* `crates/oxc_ast/src/generated/derive_content_eq.rs`
* `crates/oxc_ast/src/generated/derive_content_hash.rs`
* `npm/oxc-types/src/generated/types.d.ts`

## Background

Rust's compile time is notoriously slow, and using procedural macros to generate this much code worsens the issue.

Requiring users to wait for code generation to complete at build time would significantly hinder the development experience for downstream projects.

Both cold and incremental build times [can regress drastically](https://github.com/swc-project/swc/issues/7071).

## The RFC

The team discussed the topic in [RFC: codegen AST related codes](https://github.com/oxc-project/oxc/issues/4134) and agreed on the following requirements and user story:

### Requirements

* No build.rs published to the user.
* All generated code are checked into git.
* No nightly.
* Rust code is source of truth, need to parse types marked `#[ast]`.
* Avoid compile-time procedural macros as much as possible.

### Workflow

* A user changes code in repo.
* A watch change picks it up.
* Parse all types marked `#[ast]`.
* Record details of all AST types in a schema.
* Generate code from schema and save to files.

## Infrastructure

More details to follow.

---

---
url: /docs/guide/usage/linter/automatic-fixes.md
description: Apply safe, suggested, and dangerous fixes with Oxlint.
---

# Automatic fixes

Oxlint can automatically fix some lint violations. Automatic fixes are only applied when passing the relevant CLI flags. You choose when to apply them.

In code editor integrations (such as VS Code, Zed, etc.), automatic fixes are exposed as "code actions" that you can apply in-editor.

You can see all rules which have fixers in [the rules list](/docs/guide/usage/linter/rules).

## Safe fixes

Safe fixes are changes that do not alter program behavior.

Apply safe fixes:

```bash
oxlint --fix
```

## Suggestions

Suggestions are changes that may alter behavior or may not match your intent.

Apply suggestions:

```bash
oxlint --fix-suggestions
```

## Dangerous fixes

Dangerous fixes are aggressive changes that may break your code.

Apply dangerous fixes:

```bash
oxlint --fix-dangerously
```

## Combining fix modes

You can combine safe fixes and suggestions:

```bash
oxlint --fix --fix-suggestions
```

You can also include dangerous fixes:

```bash
oxlint --fix --fix-suggestions --fix-dangerously
```

## Rule support

Not all rules provide fixes. Some rules support safe fixes, some provide suggestions, and some do not provide fixes yet.
For some rules, a fixer is not realistically possible and cannot or should not be added.

If a rule is missing a fixer and you believe it warrants one, contributions are welcome.

## Type-aware linting and fixes

Fixers can be applied with [type-aware lint rules](/docs/guide/usage/linter/type-aware) as well.

You can apply safe fixes with type-aware linting enabled like so:

```bash
oxlint --type-aware --fix
```

Or with just `oxlint --fix` if you have type-aware linting enabled via your config file.

## JS Plugins

[JS Plugins](/docs/guide/usage/linter/js-plugins) that provide fixers or suggestions can also be applied by Oxlint.

---

---
url: /docs/guide/usage/transformer/plugins.md
---
# Built-in Plugins

Oxc transformer includes built-in support for popular transformation plugins to improve developer experience and build performance.

## Tagged Template Escape

When enabled, `</script>` sequences inside tagged template literals are escaped to prevent browsers from prematurely closing a surrounding `<script>` tag. This avoids parsing errors and potential XSS vulnerabilities when JavaScript is embedded directly in HTML.

::: tip Recommendation
Enable this option when the transformed output may be embedded directly in HTML `<script>` tags. Without it, tagged template literals containing `</script>` can break when embedded in HTML `<script>` tags. See [oxc-project/oxc#15306](https://github.com/oxc-project/oxc/issues/15306) for details.
:::

```javascript
import { transform } from "oxc-transform";

const result = await transform("lib.js", sourceCode, {
  plugins: {
    taggedTemplateEscape: true,
  },
});
```

For example, `` foo`</script>` `` is transformed into a helper call where the `</script>` sequence is escaped to `<\/script>`.

## Styled Components

The styled-components plugin adds comprehensive support for styled-components with server-side rendering, style minification, and enhanced debugging capabilities.

### Basic Usage

```javascript
import { transform } from "oxc-transform";

const result = await transform("Component.jsx", sourceCode, {
  plugins: {
    styledComponents: {
      displayName: true,
      ssr: true,
      fileName: true,
      minify: true,
    },
  },
});
```

### Example

**Input:**

```jsx
import styled from "styled-components";

const Button = styled.div`
  color: blue;
  padding: 10px;
`;
```

**Output (with default options):**

```jsx
import styled from "styled-components";

const Button = styled.div.withConfig({
  displayName: "Button",
  componentId: "sc-1234567-0",
})(["color:blue;padding:10px;"]);
```

### Configuration Options

#### Core Options

| Option        | Type      | Default | Description                                                                         |
| ------------- | --------- | ------- | ----------------------------------------------------------------------------------- |
| `displayName` | `boolean` | `true`  | Enhances the attached CSS class name with component names for easier debugging      |
| `ssr`         | `boolean` | `true`  | Adds unique component IDs to avoid checksum mismatches during server-side rendering |
| `fileName`    | `boolean` | `true`  | Controls whether the displayName is prefixed with the filename                      |

#### Template Literal Options

| Option                      | Type      | Default | Description                                                                    |
| --------------------------- | --------- | ------- | ------------------------------------------------------------------------------ |
| `transpileTemplateLiterals` | `boolean` | `true`  | Converts template literals to a smaller representation for reduced bundle size |
| `minify`                    | `boolean` | `true`  | Minifies CSS content by removing whitespace and comments                       |

#### Advanced Options

| Option                 | Type       | Default     | Description                                                   |
| ---------------------- | ---------- | ----------- | ------------------------------------------------------------- |
| `pure`                 | `boolean`  | `false`     | Adds `/*#__PURE__*/` comments for better tree-shaking         |
| `namespace`            | `string`   | `undefined` | Adds a namespace prefix to component IDs                      |
| `meaninglessFileNames` | `string[]` | `["index"]` | List of filenames considered meaningless for component naming |

#### Not Yet Implemented

| Option                | Type       | Default | Description                           |
| --------------------- | ---------- | ------- | ------------------------------------- |
| `cssProp`             | `boolean`  | `true`  | JSX css prop transformation (planned) |
| `topLevelImportPaths` | `string[]` | `[]`    | Custom import path handling (planned) |

### Supported Import Patterns

The plugin works with various styled-components import patterns:

```javascript
// Default import
import styled from "styled-components";

// Namespace import
import * as styled from "styled-components";

// Named imports
import { createGlobalStyle, css, keyframes } from "styled-components";

// Native and primitives
import styled from "styled-components/native";
import styled from "styled-components/primitives";
```

### Features

**✅ Fully Supported:**

* Display names for debugging
* Filename prefixing in display names
* Server-side rendering support
* Template literal transpilation
* CSS minification
* Namespace prefixes
* Pure annotations for call expressions

**⚠️ Partially Supported:**

* Pure annotations (call expressions only, not tagged templates due to bundler limitations)

**❌ Not Yet Implemented:**

* JSX css prop transformation
* Custom import path handling

---

---
url: /docs/guide/usage/linter/plugins.md
description: >-
  Enable built in plugin rule sets and extend Oxlint with ESLint compatible
  JavaScript plugins.
---

# Built-in Plugins

Oxlint includes built-in implementations of many popular ESLint plugin rule sets. Most rules in the `recommended` configs are already implemented, so you can get useful results without extra setup.

Oxlint also supports plugins written in JavaScript with an ESLint-compatible API. See [JS Plugins](./js-plugins.md).

## What a plugin means in Oxlint

A plugin is a named group of rules. Enabling a plugin makes its rules available, and category flags control which rules are enabled and at what severity.

If you are migrating from ESLint, plugins map to the ecosystems you already know, such as import, react, jsx-a11y, jest, unicorn, and more.

## Enable a plugin

It is **strongly recommended** to use a config file to enable plugins, as it makes it considerably easier to manage and share with other developers on a project.

### Enable in a config file

You can also enable plugins in your config file using the `plugins` field:

::: code-group

```json [.oxlintrc.json]
{
  "plugins": ["import"]
}
```

```ts [oxlint.config.ts]
import { defineConfig } from "oxlint";

export default defineConfig({
  plugins: ["import"],
});
```

:::

Setting `plugins` **overwrites the default plugin set**. The list should include every plugin you want enabled.

### Enable with the CLI

You can also enable a plugin using a `--<plugin-name>-plugin` CLI flag.

Example, enable the import plugin:

```bash
oxlint --import-plugin
```

Once enabled, category flags determine what is turned on.

Example, enable import plugin rules in the correctness category as errors and suspicious as warnings:

```bash
oxlint --import-plugin -D correctness -W suspicious
```

Correctness rules are enabled by default.

Tip: run `oxlint --help` to see the full list of plugin flags.

## Disable default plugins

### Disable default plugins in a config file

To disable all default plugins in a config file, set `plugins` to an empty array:

::: code-group

```json [.oxlintrc.json]
{
  "plugins": []
}
```

```ts [oxlint.config.ts]
import { defineConfig } from "oxlint";

export default defineConfig({
  plugins: [],
});
```

:::

This disables all default plugins and uses only the base rule set.

### Disable default plugins with the CLI

Several plugins are enabled by default. You can disable a default plugin with `--disable-<plugin-name>-plugin`.

Example, disable unicorn:

```bash
oxlint --disable-unicorn-plugin
```

Only default plugins support being disabled. Non-default plugins can simply be omitted.

## Supported plugins

This table lists the built-in plugins and where they come from.

| Plugin name  | Default | Source                                                                                                                                                                                                                                                                                   |
| ------------ | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `eslint`     | Yes     | [ESLint](https://eslint.org/) core rules                                                                                                                                                                                                                                                 |
| `typescript` | Yes     | TypeScript rules from [typescript-eslint](https://typescript-eslint.io/) (aka `@typescript-eslint/plugin`). Type-aware rules are available using [the type-aware mode](./type-aware.md).                                                                                                 |
| `unicorn`    | Yes     | [eslint-plugin-unicorn](https://github.com/sindresorhus/eslint-plugin-unicorn)                                                                                                                                                                                                           |
| `react`      | No      | [eslint-plugin-react](https://github.com/jsx-eslint/eslint-plugin-react), [eslint-plugin-react-hooks](https://www.npmx.dev/package/eslint-plugin-react-hooks), [eslint-plugin-react-refresh](https://github.com/ArnaudBarre/eslint-plugin-react-refresh), and the React Compiler rules\* |
| `react-perf` | No      | [eslint-plugin-react-perf](https://github.com/cvazac/eslint-plugin-react-perf)                                                                                                                                                                                                           |
| `nextjs`     | No      | [@next/eslint-plugin-next](https://www.npmx.dev/package/@next/eslint-plugin-next)                                                                                                                                                                                                        |
| `oxc`        | Yes     | Oxc-specific rules and selected rules ported from deepscan                                                                                                                                                                                                                               |
| `import`     | No      | [eslint-plugin-import](https://github.com/import-js/eslint-plugin-import) (also equivalent to [eslint-plugin-import-x](https://github.com/un-ts/eslint-plugin-import-x))                                                                                                                 |
| `jsdoc`      | No      | [eslint-plugin-jsdoc](https://github.com/gajus/eslint-plugin-jsdoc)                                                                                                                                                                                                                      |
| `jsx-a11y`   | No      | [eslint-plugin-jsx-a11y](https://github.com/jsx-eslint/eslint-plugin-jsx-a11y)                                                                                                                                                                                                           |
| `node`       | No      | [eslint-plugin-n](https://github.com/eslint-community/eslint-plugin-n)                                                                                                                                                                                                                   |
| `promise`    | No      | [eslint-plugin-promise](https://github.com/eslint-community/eslint-plugin-promise)                                                                                                                                                                                                       |
| `jest`       | No      | [eslint-plugin-jest](https://github.com/jest-community/eslint-plugin-jest)                                                                                                                                                                                                               |
| `vitest`     | No      | [@vitest/eslint-plugin](https://github.com/vitest-dev/eslint-plugin-vitest) aka eslint-plugin-vitest                                                                                                                                                                                     |
| `vue`        | No      | [eslint-plugin-vue](https://eslint.vuejs.org/) rules that work with script tags                                                                                                                                                                                                          |

For the current status of rule coverage, see the linter [product plan issue](https://github.com/oxc-project/oxc/issues/481). For framework and file type support, see the [compatibility matrix](/compatibility).

\* The React Compiler rules are implemented natively as the [`react/react-compiler`](./rules/react/react-compiler) rule, which runs the React Compiler's analysis in lint-only mode. It is experimental and off by default, so it must be enabled explicitly.

## Adding new plugins

Oxlint focuses on supporting the ecosystem through built-in plugins and ESLint-compatible JavaScript plugins. [Contributions that add rules](/docs/contribute/linter/adding-rules) to existing built-in plugins are encouraged.

If you think a rule set should be implemented as a built-in plugin, please [open a GitHub discussion](https://github.com/oxc-project/oxc/discussions/new?category=feature-request) first.

---

---
url: /docs/guide/usage/formatter/cli.md
---

# Command-line Interface

## Usage

**`oxfmt`** \[**`-c`**=*`PATH`*] \[*`PATH`*]...

## Mode Options:

* **`    --init`** —
  Initialize `.oxfmtrc.json` with default values
* **`    --migrate`**=*`SOURCE`* —
  Migrate configuration to `.oxfmtrc.json` from specified source Available sources: prettier, biome
* **`    --lsp`** —
  Start language server protocol (LSP) server
* **`    --stdin-filepath`**=*`PATH`* —
  Specify the file name to use to infer which parser to use

## Output Options:

* **`    --write`** —
  Format and write files in place (default)
* **`    --check`** —
  Check if files are formatted, also show statistics
* **`    --list-different`** —
  List files that would be changed

## Config Options

* **`-c`**, **`--config`**=*`PATH`* —
  Path to the configuration file (.json, .jsonc, .ts, .mts, .cts, .js, .mjs, .cjs)
* **`    --disable-nested-config`** —
  Do not search for configuration files in subdirectories

## Ignore Options

* **`    --ignore-path`**=*`PATH`* —
  Path to ignore file(s). Can be specified multiple times. If not specified, .gitignore and .prettierignore in the current directory are used.
* **`    --with-node-modules`** —
  Format code in node\_modules directory (skipped by default)

## Runtime Options

* **`    --no-error-on-unmatched-pattern`** —
  Do not exit with error when pattern is unmatched
* **`    --threads`**=*`INT`* —
  Number of threads to use. Set to 1 for using only 1 CPU core.

## Available positional items:

* *`PATH`* —
  Single file, path or list of paths. Glob patterns are also supported. (Be sure to quote them, otherwise your shell may expand them before passing.) Exclude patterns with `!` prefix like `'!**/fixtures/*.js'` are also supported. If not provided, current working directory is used.

## Available options:

* **`-h`**, **`--help`** —
  Prints help information
* **`-V`**, **`--version`** —
  Prints version information

---

---
url: /docs/guide/usage/linter/cli.md
---

# Command-line Interface

## Usage

**`oxlint`** \[**`-c`**=*`<./.oxlintrc.json>`*] \[*`PATH`*]...

## Basic Configuration

* **`-c`**, **`--config`**=*`<./.oxlintrc.json>`* —
  Oxlint configuration file

- `.json` and `.jsonc` config files are supported in all runtimes
- JavaScript/TypeScript config files are experimental and require running via Node.js
- you can use comments in configuration files.
- tries to be compatible with ESLint v8's format

  If not provided, Oxlint will look for a `.oxlintrc.json`, `.oxlintrc.jsonc`, `oxlint.config.ts`, or `oxlint.config.mts` file in the current working directory.

* **`    --tsconfig`**=*`<./tsconfig.json>`* —
  Override the TypeScript config used for import resolution. Oxlint automatically discovers the relevant `tsconfig.json` for each file. Use this only when your project uses a non-standard tsconfig name or location.

  ::: warning Avoid using this option. It can cause differences between import resolution, and type-aware linting. Type aware linting **does not** respect this option, and will always discover the appropriate `tsconfig.json` for each file automatically. :::

* **`    --init`** —
  Initialize oxlint configuration with default values

## Allowing / Denying Multiple Lints

Accumulate rules and categories from left to right on the command-line.

For example `-D correctness -A no-debugger` or `-A all -D no-debugger`.
The categories are:

* `correctness` - Code that is outright wrong or useless (default)
* `suspicious` - Code that is most likely wrong or useless
* `pedantic` - Lints which are rather strict or have occasional false positives
* `perf` - Code that could be written in a more performant way
* `style` - Code that should be written in a more idiomatic way
* `restriction` - Lints which prevent the use of language and library features
* `nursery` - New lints that are still under development
* `all` - All categories listed above except `nursery`. Does not enable plugins automatically.

Arguments:

* **`-A`**, **`--allow`**=*`NAME`* —
  Allow the rule or category (suppress the lint)
* **`-W`**, **`--warn`**=*`NAME`* —
  Warn on the rule or category (emit a warning)
* **`-D`**, **`--deny`**=*`NAME`* —
  Deny the rule or category (emit an error)

## Enable/Disable Plugins

* **`    --disable-unicorn-plugin`** —
  Disable unicorn plugin, which is turned on by default
* **`    --disable-oxc-plugin`** —
  Disable oxc unique rules, which is turned on by default
* **`    --disable-typescript-plugin`** —
  Disable TypeScript plugin, which is turned on by default
* **`    --import-plugin`** —
  Enable import plugin and detect ESM problems.
* **`    --react-plugin`** —
  Enable react plugin, which is turned off by default
* **`    --jsdoc-plugin`** —
  Enable jsdoc plugin and detect JSDoc problems
* **`    --jest-plugin`** —
  Enable the Jest plugin and detect test problems
* **`    --vitest-plugin`** —
  Enable the Vitest plugin and detect test problems
* **`    --jsx-a11y-plugin`** —
  Enable the JSX-a11y plugin and detect accessibility problems
* **`    --nextjs-plugin`** —
  Enable the Next.js plugin and detect Next.js problems
* **`    --react-perf-plugin`** —
  Enable the React performance plugin and detect rendering performance problems
* **`    --promise-plugin`** —
  Enable the promise plugin and detect promise usage problems
* **`    --node-plugin`** —
  Enable the node plugin and detect node usage problems
* **`    --vue-plugin`** —
  Enable the vue plugin and detect vue usage problems

## Fix Problems

* **`    --fix`** —
  Fix as many issues as possible. Only unfixed issues are reported in the output.
* **`    --fix-suggestions`** —
  Apply auto-fixable suggestions. May change program behavior.
* **`    --fix-dangerously`** —
  Apply dangerous fixes and suggestions

## Ignore Files

* **`    --ignore-path`**=*`PATH`* —
  Specify the file to use as your `.eslintignore`

* **`    --ignore-pattern`**=*`PAT`* —
  Specify patterns of files to ignore (in addition to those in `.eslintignore`)

  The supported syntax is the same as for `.eslintignore` and `.gitignore` files. You should quote your patterns in order to avoid shell interpretation of glob patterns.

* **`    --no-ignore`** —
  Disable excluding files from `.eslintignore` files, **`--ignore-path`** flags and **`--ignore-pattern`** flags

## Handle Warnings

* **`    --quiet`** —
  Disable reporting on warnings, only errors are reported
* **`    --deny-warnings`** —
  Ensure warnings produce a non-zero exit code
* **`    --max-warnings`**=*`INT`* —
  Specify a warning threshold, which can be used to force exit with an error status if there are too many warning-level rule violations in your project

## Output

* **`-f`**, **`--format`**=*`ARG`* —
  Use a specific output format. Possible values: `checkstyle`, `default`, `agent`, `github`, `gitlab`, `json`, `junit`, `sarif`, `stylish`, `unix`
* **`    --debug`**=*`OPTIONS`* —
  Enable debug output options. Options are comma-separated. Possible values:

- `files` - Print the list of files that will be linted, then exit.
- `timings` - Enable per-rule timing information.

## Miscellaneous

* **`    --silent`** —
  Do not display any diagnostics
* **`    --no-error-on-unmatched-pattern`** —
  Do not exit with an error when no files are selected for linting (for example, after applying ignore patterns)
* **`    --threads`**=*`INT`* —
  Number of threads to use. Set to 1 for using only 1 CPU core.
* **`    --print-config`** —
  This option outputs the configuration to be used. When present, no linting is performed and only config-related options are valid.

## Inline Configuration Comments

* **`    --report-unused-disable-directives`** —
  Report directive comments like `// oxlint-disable-line`, when no errors would have been reported on that line anyway
* **`    --report-unused-disable-directives-severity`**=*`SEVERITY`* —
  Same as `--report-unused-disable-directives`, but allows you to specify the severity level of the reported errors. Only one of these two options can be used at a time.

## Available positional items:

* *`PATH`* —
  Single file, single path or list of paths

## Available options:

* **`    --rules`** —
  List all the rules that are currently registered
* **`    --lsp`** —
  Start the language server
* **`    --disable-nested-config`** —
  Disable the automatic loading of nested configuration files
* **`    --type-aware`** —
  Enable rules that require type information
* **`    --type-check`** —
  Enable experimental type checking (includes TypeScript compiler diagnostics)
* **`-h`**, **`--help`** —
  Prints help information
* **`-V`**, **`--version`** —
  Prints version information

---

---
url: /docs/guide/usage/linter/config-file-reference.md
---

# Oxlint Configuration File

This configuration is aligned with ESLint v8's configuration schema (`eslintrc.json`).

Usage: `oxlint -c oxlintrc.json`

Example

`.oxlintrc.json`

```json
{
  "$schema": "./node_modules/oxlint/configuration_schema.json",
  "plugins": ["import", "typescript", "unicorn"],
  "env": {
    "browser": true
  },
  "globals": {
    "foo": "readonly"
  },
  "settings": {
    "react": {
      "version": "18.2.0"
    },
    "custom": {
      "option": true
    }
  },
  "rules": {
    "eqeqeq": "warn",
    "import/no-cycle": "error",
    "react/self-closing-comp": [
      "error",
      {
        "html": false
      }
    ]
  },
  "overrides": [
    {
      "files": ["*.test.ts", "*.spec.ts"],
      "rules": {
        "@typescript-eslint/no-explicit-any": "off"
      }
    }
  ]
}
```

`oxlint.config.ts`

```ts
import { defineConfig } from "oxlint";

export default defineConfig({
  plugins: ["import", "typescript", "unicorn"],
  env: {
    browser: true,
  },
  globals: {
    foo: "readonly",
  },
  settings: {
    react: {
      version: "18.2.0",
    },
    custom: { option: true },
  },
  rules: {
    eqeqeq: "warn",
    "import/no-cycle": "error",
    "react/self-closing-comp": ["error", { html: false }],
  },
  overrides: [
    {
      files: ["*.test.ts", "*.spec.ts"],
      rules: {
        "@typescript-eslint/no-explicit-any": "off",
      },
    },
  ],
});
```

## $schema

type: `string`

Schema URI for editor tooling.

## categories

type: `object`

Configure an entire category of rules all at once.

Rules enabled or disabled this way will be overwritten by individual rules in the `rules` field.

Example

```json
{
  "$schema": "./node_modules/oxlint/configuration_schema.json",
  "categories": {
    "correctness": "warn"
  },
  "rules": {
    "eslint/no-unused-vars": "error"
  }
}
```

### categories.correctness

### categories.nursery

### categories.pedantic

### categories.perf

### categories.restriction

### categories.style

### categories.suspicious

## env

type: `Record<string, boolean>`

Environments enable and disable collections of global variables.

Predefine global variables.

Environments specify what global variables are predefined.
Available environments:

* amd - require() and define() globals.
* applescript - AppleScript globals.
* astro - Astro globals.
* atomtest - Atom test globals.
* audioworklet - AudioWorklet globals.
* browser - browser globals.
* builtin - Latest ECMAScript globals, equivalent to es2026.
* commonjs - CommonJS globals and scoping.
* embertest - Ember test globals.
* es2015 - ECMAScript 2015 globals.
* es2016 - ECMAScript 2016 globals.
* es2017 - ECMAScript 2017 globals.
* es2018 - ECMAScript 2018 globals.
* es2019 - ECMAScript 2019 globals.
* es2020 - ECMAScript 2020 globals.
* es2021 - ECMAScript 2021 globals.
* es2022 - ECMAScript 2022 globals.
* es2023 - ECMAScript 2023 globals.
* es2024 - ECMAScript 2024 globals.
* es2025 - ECMAScript 2025 globals.
* es2026 - ECMAScript 2026 globals.
* es6 - ECMAScript 6 globals except modules.
* greasemonkey - GreaseMonkey globals.
* jasmine - Jasmine globals.
* jest - Jest globals.
* jquery - jQuery globals.
* meteor - Meteor globals.
* mocha - Mocha globals.
* mongo - MongoDB globals.
* nashorn - Java 8 Nashorn globals.
* node - Node.js globals and scoping.
* phantomjs - PhantomJS globals.
* prototypejs - Prototype.js globals.
* protractor - Protractor globals.
* qunit - QUnit globals.
* serviceworker - Service Worker globals.
* shared-node-browser - Node.js and Browser common globals.
* shelljs - ShellJS globals.
* svelte - Svelte globals.
* vitest - Vitest globals.
* vue - Vue globals.
* webextensions - WebExtensions globals.
* worker - Web Workers globals.

## extends

type: `string[]`

Configurations that this configuration file extends (inherits from).

In `.oxlintrc.json`, `extends` has type `string[]`. Each string is a path to a configuration
file, resolved relative to the location of the configuration file that contains the
`extends` property.

In `oxlint.config.ts`, `extends` has type `OxlintConfig[]`. Import each configuration and
pass the configuration object directly:

```ts
import { defineConfig } from "oxlint";
import baseConfig from "./base-config.ts";

export default defineConfig({ extends: [baseConfig] });
```

Configurations are merged from the first to the last, with the last configuration
overriding the previous ones.

## globals

type: `Record<string, string>`

Enabled or disabled specific global variables.

Add or remove global variables.

For each global variable, set the corresponding value equal to `"writable"`
to allow the variable to be overwritten or `"readonly"` to disallow overwriting.

Globals can be disabled by setting their value to `"off"`. For example, in
an environment where most Es2015 globals are available but `Promise` is unavailable,
you might use this config:

```json
{
  "$schema": "./node_modules/oxlint/configuration_schema.json",
  "env": {
    "es6": true
  },
  "globals": {
    "Promise": "off"
  }
}
```

You may also use `"readable"` or `false` to represent `"readonly"`, and
`"writeable"` or `true` to represent `"writable"`.

## ignorePatterns

type: `string[]`

default: `[]`

Globs to ignore during linting. Patterns use gitignore-style matching,
rooted at the directory containing the configuration file.
Files outside that directory cannot be matched; patterns containing `..`
are rejected as a configuration error.

## jsPlugins

type: `array`

JS plugins, allows usage of ESLint plugins with Oxlint.

Read more about JS plugins in
[the docs](https://oxc.rs/docs/guide/usage/linter/js-plugins.html).

Note: JS plugins are in alpha and not subject to semver.

Examples:

Basic usage with a local plugin path.

```json
{
  "jsPlugins": ["./custom-plugin.js"],
  "rules": {
    "custom/rule-name": "warn"
  }
}
```

Basic usage with a TypeScript plugin and a local plugin path.

TypeScript plugin files are supported in the following environments:

* Deno and Bun: TypeScript files are supported natively.
* Node.js >=22.18.0 and Node.js ^20.19.0: TypeScript files are supported natively with built-in
  type-stripping enabled by default.

For older Node.js versions, TypeScript plugins are not supported. Please use JavaScript plugins or upgrade your Node version.

```json
{
  "jsPlugins": ["./custom-plugin.ts"],
  "rules": {
    "custom/rule-name": "warn"
  }
}
```

Using a built-in Rust plugin alongside a JS plugin with the same name
by giving the JS plugin an alias.

```json
{
  "plugins": ["import"],
  "jsPlugins": [
    {
      "name": "import-js",
      "specifier": "eslint-plugin-import"
    }
  ],
  "rules": {
    "import/no-cycle": "error",
    "import-js/no-unresolved": "warn"
  }
}
```

### jsPlugins\[n]

type: `object | string`

#### jsPlugins\[n].name

type: `string`

Custom name/alias for the plugin.

Note: The following plugin names are reserved because they are implemented natively in Rust within oxlint and cannot be used for JS plugins:

* react (includes react-hooks)
* unicorn
* typescript (includes @typescript-eslint)
* oxc
* import (includes import-x)
* jsdoc
* jest
* vitest
* jsx-a11y (includes jsx-a11y-x)
* nextjs
* react-perf
* promise
* node
* vue
* eslint

If you need to use the JavaScript version of any of these plugins, provide a custom alias to avoid conflicts.

#### jsPlugins\[n].specifier

type: `string`

Path or package name of the plugin

## options

type: `object`

Oxlint config options.

Options for the linter.

### options.denyWarnings

type: `boolean`

Ensure warnings produce a non-zero exit code.

Equivalent to passing `--deny-warnings` on the CLI.

### options.maxWarnings

type: `integer`

Specify a warning threshold. Exits with an error status if warnings exceed this value.

Equivalent to passing `--max-warnings` on the CLI.

### options.reportUnusedDisableDirectives

type: `"allow" | "off" | "warn" | "error" | "deny" | integer`

Report unused disable directives (e.g. `// oxlint-disable-line` or `// eslint-disable-line`).

Equivalent to passing `--report-unused-disable-directives-severity` on the CLI.
CLI flags take precedence over this value when both are set.
Only supported in the root configuration file.

### options.respectEslintDisableDirectives

type: `boolean`

Whether oxlint should respect `eslint-disable*` and `eslint-enable*`
directives in addition to its native `oxlint-*` directives.

Defaults to `true`.
Only supported in the root configuration file.

### options.typeAware

type: `boolean`

Enable rules that require type information.

Equivalent to passing `--type-aware` on the CLI.

Note that this requires the `oxlint-tsgolint` package to be installed.

### options.typeCheck

type: `boolean`

Enable experimental type checking (includes TypeScript compiler diagnostics).

Equivalent to passing `--type-check` on the CLI.

Note that this requires the `oxlint-tsgolint` package to be installed.

## overrides

type: `array`

Add, remove, or otherwise reconfigure rules for specific files or groups of files.

### overrides\[n]

type: `object`

#### overrides\[n].env

type: `object`

Environments enable and disable collections of global variables.

#### overrides\[n].excludeFiles

type: `string[]`

A list of glob patterns to exclude from this override.

Files matching these patterns are not globally ignored; this override
simply does not apply to them.

## Example

`[ "*.generated.ts", "fixtures/**" ]`

A set of glob patterns.
Patterns are matched against paths relative to the configuration file's directory.

#### overrides\[n].files

type: `string[]`

A list of glob patterns to override.

## Example

`[ "*.test.ts", "*.spec.ts" ]`

A set of glob patterns.
Patterns are matched against paths relative to the configuration file's directory.

#### overrides\[n].globals

type: `object`

Enabled or disabled specific global variables.

#### overrides\[n].jsPlugins

type: `array`

JS plugins for this override, allows usage of ESLint plugins with Oxlint.

Read more about JS plugins in
[the docs](https://oxc.rs/docs/guide/usage/linter/js-plugins.html).

Note: JS plugins are in alpha and not subject to semver.

##### overrides\[n].jsPlugins\[n]

type: `object | string`

###### overrides\[n].jsPlugins\[n].name

type: `string`

Custom name/alias for the plugin.

Note: The following plugin names are reserved because they are implemented natively in Rust within oxlint and cannot be used for JS plugins:

* react (includes react-hooks)
* unicorn
* typescript (includes @typescript-eslint)
* oxc
* import (includes import-x)
* jsdoc
* jest
* vitest
* jsx-a11y (includes jsx-a11y-x)
* nextjs
* react-perf
* promise
* node
* vue
* eslint

If you need to use the JavaScript version of any of these plugins, provide a custom alias to avoid conflicts.

###### overrides\[n].jsPlugins\[n].specifier

type: `string`

Path or package name of the plugin

#### overrides\[n].plugins

type: `array`

default: `null`

Optionally change what plugins are enabled for this override. When
omitted, the base config's plugins are used.

##### overrides\[n].plugins\[n]

type: `"eslint" | "react" | "unicorn" | "typescript" | "oxc" | "import" | "jsdoc" | "jest" | "vitest" | "jsx-a11y" | "nextjs" | "react-perf" | "promise" | "node" | "vue"`

#### overrides\[n].rules

type: `object`

See [Oxlint Rules](https://oxc.rs/docs/guide/usage/linter/rules.html)

## plugins

type: `array`

default: `null`

Enabled built-in plugins for Oxlint.
You can view the list of available plugins on
[the website](https://oxc.rs/docs/guide/usage/linter/plugins.html#supported-plugins).

NOTE: Setting the `plugins` field will overwrite the base set of plugins.
The `plugins` array should reflect all of the plugins you want to use.

### plugins\[n]

type: `"eslint" | "react" | "unicorn" | "typescript" | "oxc" | "import" | "jsdoc" | "jest" | "vitest" | "jsx-a11y" | "nextjs" | "react-perf" | "promise" | "node" | "vue"`

## rules

type: `object`

Example

`.oxlintrc.json`

```json
{
  "$schema": "./node_modules/oxlint/configuration_schema.json",
  "rules": {
    "eqeqeq": "warn",
    "import/no-cycle": "error",
    "prefer-const": [
      "error",
      {
        "ignoreReadBeforeAssign": true
      }
    ]
  }
}
```

See [Oxlint Rules](https://oxc.rs/docs/guide/usage/linter/rules.html) for the list of
rules.

See [Oxlint Rules](https://oxc.rs/docs/guide/usage/linter/rules.html)

## settings

type: `object`

Plugin-specific configuration for both built-in and custom plugins.
This includes settings for built-in plugins such as `react` and `jsdoc`
as well as configuring settings for JS custom plugins loaded via `jsPlugins`.

Configure the behavior of linter plugins.

Here's an example if you're using Next.js in a monorepo:

```json
{
  "settings": {
    "next": {
      "rootDir": "apps/dashboard/"
    },
    "react": {
      "linkComponents": [
        {
          "name": "Link",
          "linkAttribute": "to"
        }
      ]
    },
    "jsx-a11y": {
      "components": {
        "Link": "a",
        "Button": "button"
      }
    }
  }
}
```

### settings.jest

type: `object`

Configure Jest plugin rules.

See [eslint-plugin-jest](https://github.com/jest-community/eslint-plugin-jest)'s
configuration for a full reference.

#### settings.jest.version

type: `integer | string`

default: `null`

Jest version — accepts a number (`29`) or a semver string (`"29.1.0"` or `"v29.1.0"`),
storing only the major version.
::: warning
Using this config will override the `no-deprecated-functions` config set.
:::

### settings.jsdoc

type: `object`

#### settings.jsdoc.augmentsExtendsReplacesDocs

type: `boolean`

default: `false`

Only for `require-(yields|returns|description|example|param|throws)` rule

#### settings.jsdoc.exemptDestructuredRootsFromChecks

type: `boolean`

default: `false`

Only for `require-param-type` and `require-param-description` rule

#### settings.jsdoc.ignoreInternal

type: `boolean`

default: `false`

For all rules but NOT apply to `empty-tags` rule

#### settings.jsdoc.ignorePrivate

type: `boolean`

default: `false`

For all rules but NOT apply to `check-access` and `empty-tags` rule

#### settings.jsdoc.ignoreReplacesDocs

type: `boolean`

default: `true`

Only for `require-(yields|returns|description|example|param|throws)` rule

#### settings.jsdoc.implementsReplacesDocs

type: `boolean`

default: `false`

Only for `require-(yields|returns|description|example|param|throws)` rule

#### settings.jsdoc.overrideReplacesDocs

type: `boolean`

default: `true`

Only for `require-(yields|returns|description|example|param|throws)` rule

#### settings.jsdoc.tagNamePreference

type: `object`

default: `{}`

### settings.jsx-a11y

type: `object`

Configure JSX A11y plugin rules.

See
[eslint-plugin-jsx-a11y](https://github.com/jsx-eslint/eslint-plugin-jsx-a11y#configurations)'s
configuration for a full reference.

#### settings.jsx-a11y.attributes

type: `Record<string, array>`

default: `{}`

Map of attribute names to their DOM equivalents.
This is useful for non-React frameworks that use different attribute names.

Example:

```json
{
  "settings": {
    "jsx-a11y": {
      "attributes": {
        "for": ["htmlFor", "for"]
      }
    }
  }
}
```

#### settings.jsx-a11y.components

type: `Record<string, string>`

default: `{}`

To have your custom components be checked as DOM elements, you can
provide a mapping of your component names to the DOM element name.

Example:

```json
{
  "settings": {
    "jsx-a11y": {
      "components": {
        "Link": "a",
        "IconButton": "button"
      }
    }
  }
}
```

#### settings.jsx-a11y.polymorphicPropName

type: `string`

An optional setting that define the prop your code uses to create polymorphic components.
This setting will be used to determine the element type in rules that
require semantic context.

For example, if you set the `polymorphicPropName` to `as`, then this element:

```jsx
<Box as="h3">Hello</Box>
```

Will be treated as an `h3`. If not set, this component will be treated
as a `Box`.

### settings.next

type: `object`

Configure Next.js plugin rules.

#### settings.next.rootDir

type: `array | string`

The root directory of the Next.js project.

This is particularly useful when you have a monorepo and your Next.js
project is in a subfolder.

Example:

```json
{
  "settings": {
    "next": {
      "rootDir": "apps/dashboard/"
    }
  }
}
```

##### settings.next.rootDir\[n]

type: `string`

### settings.react

type: `object`

Configure React plugin rules.

Derived from [eslint-plugin-react](https://github.com/jsx-eslint/eslint-plugin-react#configuration-legacy-eslintrc-)

#### settings.react.componentWrapperFunctions

type: `string[]`

default: `[]`

Functions that wrap React components and should be treated as HOCs.

Example:

```jsonc
{
  "settings": {
    "react": {
      "componentWrapperFunctions": ["observer", "withRouter"],
    },
  },
}
```

#### settings.react.formComponents

type: `array`

default: `[]`

Components used as alternatives to `<form>` for forms, such as `<Formik>`.

Example:

```jsonc
{
  "settings": {
    "react": {
      "formComponents": [
        "CustomForm",
        // OtherForm is considered a form component and has an endpoint attribute
        { "name": "OtherForm", "formAttribute": "endpoint" },
        // allows specifying multiple properties if necessary
        { "name": "Form", "formAttribute": ["registerEndpoint", "loginEndpoint"] },
      ],
    },
  },
}
```

##### settings.react.formComponents\[n]

type: `object | string`

###### settings.react.formComponents\[n].attribute

type: `string`

###### settings.react.formComponents\[n].name

type: `string`

#### settings.react.linkComponents

type: `array`

default: `[]`

Components used as alternatives to `<a>` for linking, such as `<Link>`.

Example:

```jsonc
{
  "settings": {
    "react": {
      "linkComponents": [
        "HyperLink",
        // Use `linkAttribute` for components that use a different prop name
        // than `href`.
        { "name": "MyLink", "linkAttribute": "to" },
        // allows specifying multiple properties if necessary
        { "name": "Link", "linkAttribute": ["to", "href"] },
      ],
    },
  },
}
```

##### settings.react.linkComponents\[n]

type: `object | string`

###### settings.react.linkComponents\[n].attribute

type: `string`

###### settings.react.linkComponents\[n].name

type: `string`

#### settings.react.version

type: `string`

default: `null`

React version to use for version-specific rules.

Accepts semver versions (e.g., "18.2.0", "17.0").

Example:

```jsonc
{
  "settings": {
    "react": {
      "version": "18.2.0",
    },
  },
}
```

### settings.vitest

type: `object`

Configure Vitest plugin rules.

See [eslint-plugin-vitest](https://github.com/vitest-dev/eslint-plugin-vitest)'s
configuration for a full reference.

#### settings.vitest.typecheck

type: `boolean`

default: `false`

Whether to enable typecheck mode for Vitest rules.
When enabled, some rules will skip certain checks for describe blocks
to accommodate TypeScript type checking scenarios.

---

---
url: /docs/guide/usage/formatter/config.md
description: Configure Oxfmt using a .oxfmtrc.json file.
---

# Configuration

Oxfmt works out of the box, but most teams commit a configuration file to keep formatting consistent across local runs, editors, and CI.

This page focuses on project configuration: formatting options, ignore patterns, and experimental features.

## Create a config file

To generate a starter config in the current directory:

```sh
oxfmt --init
```

Oxfmt automatically looks for the following files starting from the directory of the file being formatted and walking up the tree:

* `.oxfmtrc.json`
* `.oxfmtrc.jsonc`
* `oxfmt.config.ts`
* `oxfmt.config.mts`

You can use only one config file per directory: JSON and TypeScript configs cannot coexist, nor can `oxfmt.config.ts` and `oxfmt.config.mts`.

The nearest config file to each formatted file wins. This means you can place different config files at different levels of your project tree.
For example, a root config for the whole repo and a more specific one inside a subdirectory:

```
my-repo/
├── oxfmt.config.ts         # default for the whole repo
├── src/
│   └── app.ts              # uses root config
└── packages/
    └── fancy-app/
        ├── .oxfmtrc.json   # overrides for this package
        └── index.ts        # uses packages/fancy-app/.oxfmtrc.json
```

If you don't need nested config, pass `--disable-nested-config` to only look upward from the current working directory. This is faster because Oxfmt can resolve the config once instead of per file.

You can also pass a config explicitly with `-c`, which also disables nested config lookup. This accepts any supported format (`.json`, `.jsonc`, `.ts`, `.mts`, `.cts`, `.js`, `.mjs`, `.cjs`):

```sh
oxfmt -c path/to/yourconfig.json
```

A minimal JSON configuration looks like this:

```json [.oxfmtrc.json]
{
  "$schema": "./node_modules/oxfmt/configuration_schema.json",
  "printWidth": 80
}
```

JavaScript / TypeScript config files use a default export. `defineConfig` is optional but gives you type checking and editor autocomplete:

```ts [oxfmt.config.ts]
import { defineConfig } from "oxfmt";

export default defineConfig({
  printWidth: 80,
});
```

## Configuration file format

A configuration file is a JSON object. The most common top-level fields are:

* `printWidth`: Line width limit (default: 100)
* `tabWidth`: Spaces per indentation level (default: 2)
* `useTabs`: Use tabs instead of spaces (default: false)
* `semi`: Add semicolons (default: true)
* `singleQuote`: Use single quotes (default: false)
* `trailingComma`: Trailing commas in multi-line structures (default: "all")
* `ignorePatterns`: Glob patterns to exclude from formatting
* `sortImports`: Configure import sorting (disabled by default)
* `sortTailwindcss`: Configure Tailwind class sorting (disabled by default)
* `sortPackageJson`: Configure package.json sorting (enabled by default)

For a complete list of fields, see the [Config file reference](./config-file-reference).

## JSON schema

Add a `$schema` field for editor validation and autocomplete:

```json [.oxfmtrc.json]
{
  "$schema": "./node_modules/oxfmt/configuration_schema.json"
}
```

## `.editorconfig`

Oxfmt reads these `.editorconfig` properties:

* `end_of_line` → `endOfLine`
* `indent_style` → `useTabs`
* `indent_size` → `tabWidth`
* `max_line_length` → `printWidth`
* `insert_final_newline` → `insertFinalNewline`

Both root section and glob-based overrides are supported.

```
[*]
indent_size = 4

[*.{js,ts}]
indent_size = 2
```

Oxfmt uses only the nearest `.editorconfig` from the current directory:

* `root = true` is not respected
* Nested `.editorconfig` files are not merged

## Overrides

Use the `overrides` field to apply different formatting options to specific files:

::: code-group

```json [.oxfmtrc.json]
{
  "printWidth": 100,
  "overrides": [
    {
      "files": ["*.test.js", "*.spec.ts"],
      "options": {
        "printWidth": 120
      }
    },
    {
      "files": ["*.md", "*.html"],
      "excludeFiles": ["*.min.js"],
      "options": {
        "tabWidth": 4
      }
    }
  ]
}
```

```ts [oxfmt.config.ts]
import { defineConfig } from "oxfmt";

export default defineConfig({
  printWidth: 100,
  overrides: [
    {
      files: ["*.test.js", "*.spec.ts"],
      options: {
        printWidth: 120,
      },
    },
    {
      files: ["*.md", "*.html"],
      excludeFiles: ["*.min.js"],
      options: {
        tabWidth: 4,
      },
    },
  ],
});
```

:::

Each override entry has:

* `files` (required): Glob patterns to match files
* `excludeFiles` (optional): Glob patterns to exclude from this override
* `options`: Formatting options to apply

Glob patterns are resolved relative to the directory containing the Oxfmt config file.

## Precedence

Options are applied in order (lowest to highest priority):

1. Defaults
2. Config file root options
3. Config file `overrides` options
4. fallback to options supported by `.editorconfig` for unset fields

## Oxfmt-specific options

### `insertFinalNewline`

Controls whether a final newline is added to formatted files. Defaults to `true`.

This is a [frequently requested Prettier feature](https://github.com/prettier/prettier/issues/6360), as some environments (e.g., Salesforce) strip trailing newlines.

### `printWidth`

Oxfmt defaults to `printWidth: 100` (Prettier uses 80). Reasons:

* TypeScript code is longer due to type annotations
* Import statements often have many specifiers
* Modern screens are wider
* Fewer line breaks mean fewer LLM tokens

To match Prettier's default:

::: code-group

```json [.oxfmtrc.json]
{
  "printWidth": 80
}
```

```ts [oxfmt.config.ts]
import { defineConfig } from "oxfmt";

export default defineConfig({
  printWidth: 80,
});
```

:::

## Next steps

* [Ignore files](./ignore-files): Ignore files and patterns, `.gitignore` and `.prettierignore` workflows.
* [Inline ignore comments](./ignore-comments): Inline suppressions for specific code.
* [Config file reference](./config-file-reference): Full schema and field documentation.
* [CLI reference](./cli): Complete list of flags.

---

---
url: /docs/guide/usage/linter/config.md
description: Configure Oxlint using .oxlintrc.json or oxlint.config.ts.
---

# Configuration

Oxlint works out of the box, but most teams commit a configuration file (`.oxlintrc.json` or `oxlint.config.ts`) to keep linting consistent across local runs, editors, and CI.

This page focuses on project configuration: rules, categories, plugins, overrides, and shared settings.

## Create a config file

To generate a starter config in the current directory (JSON):

```sh
oxlint --init
```

Oxlint automatically looks for a `.oxlintrc.json`, `.oxlintrc.jsonc`, `oxlint.config.ts`, or `oxlint.config.mts` in the current working directory. You can also pass a config explicitly (note that this will disable nested config lookup):

```sh
oxlint -c ./.oxlintrc.json
# or
oxlint --config ./.oxlintrc.json
```

Notes:

* `.oxlintrc.json` supports comments (like jsonc).
* The configuration format aims to be compatible with ESLint v8's format (`eslintrc.json`).
* You can use only one config file per directory: JSON and TypeScript configs cannot coexist, nor can `oxlint.config.ts` and `oxlint.config.mts`.

A minimal configuration looks like this:

```json [.oxlintrc.json]
{
  "$schema": "./node_modules/oxlint/configuration_schema.json",
  "categories": {
    "correctness": "warn"
  },
  "rules": {
    "eslint/no-unused-vars": "error"
  }
}
```

### TypeScript config file (`oxlint.config.ts`)

Oxlint also supports a TypeScript configuration file named `oxlint.config.ts` or `oxlint.config.mts`.

```ts [oxlint.config.ts]
import { defineConfig } from "oxlint";

export default defineConfig({
  categories: {
    correctness: "warn",
  },
  rules: {
    "eslint/no-unused-vars": "error",
  },
});
```

Notes:

* For auto-discovery, the file must be named `oxlint.config.ts` or `oxlint.config.mts`. When passed via `--config`, any path with a JS/TS extension (`.js`, `.mjs`, `.cjs`, `.ts`, `.mts`, `.cts`) is accepted.
* The default export must be an object and should be wrapped with `defineConfig` for typing.
* TypeScript configs require the Node-based `oxlint` package (JS runtime). If you're using a standalone binary, use `.oxlintrc.json` instead.
* TypeScript configs require a Node runtime that can execute TypeScript (Node v22.18+ or v24+).

## Configuration file format

A configuration file is either a JSON object (`.oxlintrc.json`) or a TypeScript module that default-exports a config object (`oxlint.config.ts`). The most common top-level fields are:

* `rules`: Enable or disable rules, set severity, and configure rule options.
* `categories`: Enable groups of rules with similar intent.
* `plugins`: Enable built-in plugins that provide additional rules.
* `jsPlugins`: Configure JavaScript plugins (alpha).
* `overrides`: Apply different configuration to different file patterns.
* `extends`: Inherit configuration from other files.
* `ignorePatterns`: Ignore additional files from the config file.
* `env`: Enable predefined globals for common environments.
* `globals`: Declare custom globals as read-only or writable.
* `settings`: Plugin-wide configuration shared by multiple rules.
* `options`: Linter-level options (for example, `options.typeAware` and `options.typeCheck`).

For a complete list of fields, see the [Config file reference](/docs/guide/usage/linter/config-file-reference.html).

## Configure linter options

Use `options` for linter-level behavior. See the [Config file reference](/docs/guide/usage/linter/config-file-reference.html#options) for the full list.

Example:

::: code-group

```json [.oxlintrc.json]
{
  "options": {
    "typeAware": true,
    "typeCheck": true,
    "maxWarnings": 10
  }
}
```

```ts [oxlint.config.ts]
import { defineConfig } from "oxlint";

export default defineConfig({
  options: {
    typeAware: true,
    typeCheck: true,
    maxWarnings: 10,
  },
});
```

:::

* `options.typeAware` is equivalent to passing `--type-aware` on the CLI.
* `options.typeCheck` (experimental) is equivalent to passing `--type-check` on the CLI.
* `options.maxWarnings` is equivalent to passing `--max-warnings` on the CLI.

CLI flags take precedence when both CLI and config values are present.

`options.typeAware` and `options.typeCheck` are only supported in the root config file.

## Configure rules

Rules are configured under `rules`.

A rule value is either:

* a severity (`"off"`, `"warn"`, `"error"`), or
* an array of `[severity, options]`

If a rule is from ESLint core and its name is unique, you can configure it without a plugin prefix. For example, `no-console` is the same as `eslint/no-console`.

::: code-group

```json [.oxlintrc.json]
{
  "rules": {
    "no-alert": "error",
    "oxc/approx-constant": "warn",
    "no-plusplus": "off",
    "eslint/prefer-const": ["error", { "destructuring": "any" }]
  }
}
```

```ts [oxlint.config.ts]
import { defineConfig } from "oxlint";

export default defineConfig({
  rules: {
    "no-alert": "error",
    "oxc/approx-constant": "warn",
    "no-plusplus": "off",
    "eslint/prefer-const": ["error", { destructuring: "any" }],
  },
});
```

:::

### Severity values

Oxlint accepts ESLint-style severities:

* Disable rule: `"off"` or `"allow"`
* Warning on rule: `"warn"`
* Error on rule: `"error"` or `"deny"`

### Rule options

To configure rule options, use an array:

::: code-group

```json [.oxlintrc.json]
{
  "rules": {
    "no-plusplus": ["error", { "allowForLoopAfterthoughts": true }]
  }
}
```

```ts [oxlint.config.ts]
import { defineConfig } from "oxlint";

export default defineConfig({
  rules: {
    "no-plusplus": ["error", { allowForLoopAfterthoughts: true }],
  },
});
```

:::

All available rules, and their configuration options, are listed in the [Rules reference](/docs/guide/usage/linter/rules).

### Override severity from the CLI

For quick experiments, you can adjust severity from the command line using:

* `-A` / `--allow`
* `-W` / `--warn`
* `-D` / `--deny`

Arguments are applied from left to right:

```sh
oxlint -D no-alert -W oxc/approx-constant -A no-plusplus
```

## Enable groups of rules with categories

Categories let you enable or disable sets of rules with similar intent. By default, Oxlint enables rules in the `correctness` category.

Configure categories using `categories`:

::: code-group

```json [.oxlintrc.json]
{
  "categories": {
    "correctness": "error",
    "suspicious": "warn",
    "pedantic": "off"
  }
}
```

```ts [oxlint.config.ts]
import { defineConfig } from "oxlint";

export default defineConfig({
  categories: {
    correctness: "error",
    suspicious: "warn",
    pedantic: "off",
  },
});
```

:::

Available categories include:

* `correctness`: Code that is definitely wrong or useless
* `suspicious`: Code that is likely to be wrong or useless
* `pedantic`: Extra strict rules that may have false positives
* `perf`: Rules that aim to improve runtime performance
* `style`: Idiomatic and consistent style rules
* `restriction`: Rules that ban specific patterns or features
* `nursery`: Rules under development that may change

You can also change categories from the CLI with the same `-A`, `-W`, and `-D` options:

```sh
oxlint -D correctness -D suspicious
```

## Configure plugins

Plugins extend the set of available rules.

Oxlint supports many popular plugins natively in Rust. This provides broad rule coverage without a large JavaScript dependency tree. See [Native Plugins](/docs/guide/usage/linter/plugins).

Configure plugins using `plugins`. Setting `plugins` overwrites the default plugin set, so the array should include everything you want enabled:

::: code-group

```json [.oxlintrc.json]
{
  "plugins": ["unicorn", "typescript", "oxc"]
}
```

```ts [oxlint.config.ts]
import { defineConfig } from "oxlint";

export default defineConfig({
  plugins: ["unicorn", "typescript", "oxc"],
});
```

:::

To disable all default plugins:

::: code-group

```json [.oxlintrc.json]
{
  "plugins": []
}
```

```ts [oxlint.config.ts]
import { defineConfig } from "oxlint";

export default defineConfig({
  plugins: [],
});
```

:::

For plugin details and CLI flags such as `--import-plugin`, see [Native Plugins](/docs/guide/usage/linter/plugins).

## Configure JS plugins (alpha)

Oxlint also supports JavaScript plugins via `jsPlugins`. This is intended for compatibility with existing ESLint plugins and advanced integrations.

Notes:

* JS plugins are in alpha and not subject to semver.

JS plugins can be declared as strings, or as objects with an alias:

::: code-group

```json [.oxlintrc.json]
{
  "jsPlugins": [
    "eslint-plugin-playwright",
    { "name": "my-eslint-react", "specifier": "eslint-plugin-react" }
  ]
}
```

```ts [oxlint.config.ts]
import { defineConfig } from "oxlint";

export default defineConfig({
  jsPlugins: [
    "eslint-plugin-playwright",
    { name: "my-eslint-react", specifier: "eslint-plugin-react" },
  ],
});
```

:::

Some plugin names are reserved because they are implemented natively in Rust (for example `react`, `unicorn`, `typescript`, `oxc`, `import`, `jest`, `vitest`, `jsx-a11y`, `nextjs`). If you need the JavaScript version of a reserved plugin, give it a custom `name` to avoid conflicts.

For details, see [JS plugins](/docs/guide/usage/linter/js-plugins).

## Apply configuration by file pattern

Use `overrides` to apply different configuration to different files, such as tests, scripts, or TypeScript-only paths.

`overrides` is an array of objects. Each override can include:

* `files`: glob patterns
* `rules`: rule configuration (same shape as top-level `rules`)
* `env`: environment configuration (same shape as top-level `env`)
* `globals`: globals configuration (same shape as top-level `globals`)
* `plugins`: optionally change what plugins are enabled for this override
* `jsPlugins`: JS plugins for this override (alpha)

Example:

::: code-group

```json [.oxlintrc.json]
{
  "$schema": "./node_modules/oxlint/configuration_schema.json",
  "rules": {
    "no-console": "error"
  },
  "overrides": [
    {
      "files": ["scripts/*.js"],
      "rules": {
        "no-console": "off"
      }
    },
    {
      "files": ["**/*.{ts,tsx}"],
      "plugins": ["typescript"],
      "rules": {
        "typescript/no-explicit-any": "error"
      }
    },
    {
      "files": ["**/test/**"],
      "plugins": ["jest"],
      "env": {
        "jest": true
      },
      "rules": {
        "jest/no-disabled-tests": "off"
      }
    }
  ]
}
```

```ts [oxlint.config.ts]
import { defineConfig } from "oxlint";

export default defineConfig({
  rules: {
    "no-console": "error",
  },
  overrides: [
    {
      files: ["scripts/*.js"],
      rules: {
        "no-console": "off",
      },
    },
    {
      files: ["**/*.{ts,tsx}"],
      plugins: ["typescript"],
      rules: {
        "typescript/no-explicit-any": "error",
      },
    },
    {
      files: ["**/test/**"],
      plugins: ["jest"],
      env: {
        jest: true,
      },
      rules: {
        "jest/no-disabled-tests": "off",
      },
    },
  ],
});
```

:::

## Extend shared configs

Use `extends` to inherit from other configuration files.

Paths in `extends` are resolved relative to the configuration file that declares `extends`. Configs are merged from first to last, with later entries overriding earlier ones.

Use `oxlint.config.ts` when extending config objects imported from a shared package. Package imports are not supported in the `.oxlintrc.json` format.

::: code-group

```json [.oxlintrc.json]
{
  "extends": ["./configs/base.json", "./configs/frontend.json"]
}
```

```ts [oxlint.config.ts]
import baseConfig from "./configs/base.ts";
import frontendConfig from "./configs/frontend.ts";
import { defineConfig } from "oxlint";

export default defineConfig({
  extends: [baseConfig, frontendConfig],
});
```

:::

For example, a shared package can export a config object that you import and extend:

```ts [oxlint.config.ts]
import config from "@example-org/oxlint-config";
import { defineConfig } from "oxlint";

export default defineConfig({
  extends: [config],
});
```

## Configure environments and globals

Use `env` to enable predefined globals for common environments such as browser or node.

Use `globals` to declare project-specific globals, mark them writable or readonly, or disable a global that would otherwise be present.

::: code-group

```json [.oxlintrc.json]
{
  "env": {
    "es6": true
  },
  "globals": {
    "MY_GLOBAL": "readonly",
    "Promise": "off"
  }
}
```

```ts [oxlint.config.ts]
import { defineConfig } from "oxlint";

export default defineConfig({
  env: {
    es6: true,
  },
  globals: {
    MY_GLOBAL: "readonly",
    Promise: "off",
  },
});
```

:::

`globals` accepts:

* `"readonly"` or `"readable"` or `false`
* `"writable"` or `"writeable"` or `true`
* `"off"` to disable a global

## Plugin settings

Use `settings` for plugin-wide configuration shared by multiple rules.

Example (monorepo + React + jsx-a11y):

::: code-group

```json [.oxlintrc.json]
{
  "settings": {
    "next": {
      "rootDir": "apps/dashboard/"
    },
    "react": {
      "linkComponents": [{ "name": "Link", "linkAttribute": "to" }]
    },
    "jsx-a11y": {
      "components": {
        "Link": "a",
        "Button": "button"
      }
    }
  }
}
```

```ts [oxlint.config.ts]
import { defineConfig } from "oxlint";

export default defineConfig({
  settings: {
    next: {
      rootDir: "apps/dashboard/",
    },
    react: {
      linkComponents: [{ name: "Link", linkAttribute: "to" }],
    },
    "jsx-a11y": {
      components: {
        Link: "a",
        Button: "button",
      },
    },
  },
});
```

:::

## Next steps

* [Ignore files](/docs/guide/usage/linter/ignore-files): Ignore files and patterns, `.gitignore` and `.eslintignore` workflows, and symlink behavior.
* [Inline ignore comments](/docs/guide/usage/linter/ignore-comments): Inline suppressions and scoped exceptions.
* [Nested configs](/docs/guide/usage/linter/nested-config): Monorepos and per-package configuration.
* [Config file reference](/docs/guide/usage/linter/config-file-reference.html): Full schema and field documentation.
* [CLI reference](/docs/guide/usage/linter/cli.html): Complete list of flags and output formats.

---

---
url: /docs/guide/usage/formatter/config-file-reference.md
---

# Configuration options for the Oxfmt.

Most options are the same as Prettier's options, but not all of them.
In addition, some options are our own extensions.

## arrowParens

type: `"always" | "avoid"`

Include parentheses around a sole arrow function parameter.

* Languages: JS, JSX, TS, TSX
* Default: `"always"`

## bracketSameLine

type: `boolean`

Put the `>` of a multi-line HTML (HTML, JSX, Vue, Angular) element at the end of the last line,
instead of being alone on the next line (does not apply to self closing elements).

* Languages: JSX, TSX, HTML, Angular, Vue, MJML, Svelte
* Default: `false`

## bracketSpacing

type: `boolean`

Print spaces between brackets in object literals.

* Languages: JS, JSX, TS, TSX, JSON, JSONC, JSON5, GraphQL, YAML
* Default: `true`

## embeddedLanguageFormatting

type: `"auto" | "off"`

Control whether to format embedded parts (For example, CSS-in-JS, or JS-in-Vue, etc.) in the file.

* Languages: JS, JSX, TS, TSX, HTML, Vue, Angular, Svelte, Markdown, MDX (languages with embedded code)
* Default: `"auto"`

## endOfLine

type: `"lf" | "crlf" | "cr"`

Which end of line characters to apply.

NOTE: `"auto"` is not supported.

* Languages: All
* Default: `"lf"`
* Overrides `.editorconfig.end_of_line`

## htmlWhitespaceSensitivity

type: `"css" | "strict" | "ignore"`

Specify the global whitespace sensitivity for HTML, Vue, Angular, and Handlebars.

* Languages: HTML, Angular, Vue, Handlebars, Svelte
* Default: `"css"`

## ignorePatterns

type: `string[]`

Ignore files matching these glob patterns.
Patterns use gitignore-style matching, rooted at the directory containing the configuration file.
Files outside that directory cannot be matched; patterns containing `..` are rejected as a configuration error.

* Default: `[]`

## insertFinalNewline

type: `boolean`

Whether to insert a final newline at the end of the file.

* Languages: All
* Default: `true`
* Overrides `.editorconfig.insert_final_newline`

## jsdoc

type: `object | boolean`

Enable JSDoc comment formatting.

When enabled, JSDoc comments are normalized and reformatted:
tag aliases are canonicalized, descriptions are capitalized,
long lines are wrapped, and short comments are collapsed to single-line.

Pass `true` or an object to enable with defaults, or omit/set `false` to disable.

* Languages: JS, JSX, TS, TSX
* Default: Disabled

### jsdoc.addDefaultToDescription

type: `boolean`

Append default values to `@param` descriptions (e.g. "Default is `value`").

* Default: `true`

### jsdoc.bracketSpacing

type: `boolean`

Add spaces inside JSDoc type braces: `{string}` → `{ string }`.

* Default: `false`

### jsdoc.capitalizeDescriptions

type: `boolean`

Capitalize the first letter of tag descriptions.

* Default: `true`

### jsdoc.commentLineStrategy

type: `"singleLine" | "multiline" | "keep"`

How to format comment blocks.

* `"singleLine"` — Convert to single-line `/** content */` when possible.

* `"multiline"` — Always use multi-line format.

* `"keep"` — Preserve original formatting.

* Default: `"singleLine"`

### jsdoc.descriptionTag

type: `boolean`

Emit `@description` tag instead of inline description.

* Default: `false`

### jsdoc.descriptionWithDot

type: `boolean`

Add a trailing dot to the end of descriptions.

* Default: `false`

### jsdoc.keepUnparsableExampleIndent

type: `boolean`

Preserve indentation in unparsable `@example` code.

* Default: `false`

### jsdoc.lineWrappingStyle

type: `"greedy" | "balance"`

Strategy for wrapping description lines at print width.

* `"greedy"` — Always re-wrap text to fit within print width.

* `"balance"` — Preserve original line breaks if all lines fit within print width.

* Default: `"greedy"`

### jsdoc.preferCodeFences

type: `boolean`

Use fenced code blocks (` ``` `) instead of 4-space indentation for code without a language tag.

* Default: `false`

### jsdoc.separateReturnsFromParam

type: `boolean`

Add a blank line between the last `@param` and `@returns`.

* Default: `false`

### jsdoc.separateTagGroups

type: `boolean`

Add blank lines between different tag groups (e.g. between `@param` and `@returns`).

* Default: `false`

## jsxSingleQuote

type: `boolean`

Use single quotes instead of double quotes in JSX.

* Languages: JSX, TSX
* Default: `false`

## objectWrap

type: `"preserve" | "collapse"`

How to wrap object literals when they could fit on one line or span multiple lines.

By default, formats objects as multi-line if there is a newline prior to the first property.
Authors can use this heuristic to contextually improve readability, though it has some downsides.

* Languages: JS, JSX, TS, TSX, JSON, JSONC, JSON5
* Default: `"preserve"`

## overrides

type: `array`

File-specific overrides.
When a file matches multiple overrides, the later override takes precedence (array order matters).

* Default: `[]`

### overrides\[n]

type: `object`

#### overrides\[n].excludeFiles

type: `string[]`

Glob patterns to exclude from this override.

A set of glob patterns.
Patterns are matched against paths relative to the configuration file's directory.

#### overrides\[n].files

type: `string[]`

Glob patterns to match files for this override.

A set of glob patterns.
Patterns are matched against paths relative to the configuration file's directory.

#### overrides\[n].options

type: `object`

Format options to apply for matched files.

##### overrides\[n].options.arrowParens

type: `"always" | "avoid"`

Include parentheses around a sole arrow function parameter.

* Languages: JS, JSX, TS, TSX
* Default: `"always"`

##### overrides\[n].options.bracketSameLine

type: `boolean`

Put the `>` of a multi-line HTML (HTML, JSX, Vue, Angular) element at the end of the last line,
instead of being alone on the next line (does not apply to self closing elements).

* Languages: JSX, TSX, HTML, Angular, Vue, MJML, Svelte
* Default: `false`

##### overrides\[n].options.bracketSpacing

type: `boolean`

Print spaces between brackets in object literals.

* Languages: JS, JSX, TS, TSX, JSON, JSONC, JSON5, GraphQL, YAML
* Default: `true`

##### overrides\[n].options.embeddedLanguageFormatting

type: `"auto" | "off"`

Control whether to format embedded parts (For example, CSS-in-JS, or JS-in-Vue, etc.) in the file.

* Languages: JS, JSX, TS, TSX, HTML, Vue, Angular, Svelte, Markdown, MDX (languages with embedded code)
* Default: `"auto"`

##### overrides\[n].options.endOfLine

type: `"lf" | "crlf" | "cr"`

Which end of line characters to apply.

NOTE: `"auto"` is not supported.

* Languages: All
* Default: `"lf"`
* Overrides `.editorconfig.end_of_line`

##### overrides\[n].options.htmlWhitespaceSensitivity

type: `"css" | "strict" | "ignore"`

Specify the global whitespace sensitivity for HTML, Vue, Angular, and Handlebars.

* Languages: HTML, Angular, Vue, Handlebars, Svelte
* Default: `"css"`

##### overrides\[n].options.insertFinalNewline

type: `boolean`

Whether to insert a final newline at the end of the file.

* Languages: All
* Default: `true`
* Overrides `.editorconfig.insert_final_newline`

##### overrides\[n].options.jsdoc

type: `object | boolean`

Enable JSDoc comment formatting.

When enabled, JSDoc comments are normalized and reformatted:
tag aliases are canonicalized, descriptions are capitalized,
long lines are wrapped, and short comments are collapsed to single-line.

Pass `true` or an object to enable with defaults, or omit/set `false` to disable.

* Languages: JS, JSX, TS, TSX
* Default: Disabled

###### overrides\[n].options.jsdoc.addDefaultToDescription

type: `boolean`

Append default values to `@param` descriptions (e.g. "Default is `value`").

* Default: `true`

###### overrides\[n].options.jsdoc.bracketSpacing

type: `boolean`

Add spaces inside JSDoc type braces: `{string}` → `{ string }`.

* Default: `false`

###### overrides\[n].options.jsdoc.capitalizeDescriptions

type: `boolean`

Capitalize the first letter of tag descriptions.

* Default: `true`

###### overrides\[n].options.jsdoc.commentLineStrategy

type: `"singleLine" | "multiline" | "keep"`

How to format comment blocks.

* `"singleLine"` — Convert to single-line `/** content */` when possible.

* `"multiline"` — Always use multi-line format.

* `"keep"` — Preserve original formatting.

* Default: `"singleLine"`

###### overrides\[n].options.jsdoc.descriptionTag

type: `boolean`

Emit `@description` tag instead of inline description.

* Default: `false`

###### overrides\[n].options.jsdoc.descriptionWithDot

type: `boolean`

Add a trailing dot to the end of descriptions.

* Default: `false`

###### overrides\[n].options.jsdoc.keepUnparsableExampleIndent

type: `boolean`

Preserve indentation in unparsable `@example` code.

* Default: `false`

###### overrides\[n].options.jsdoc.lineWrappingStyle

type: `"greedy" | "balance"`

Strategy for wrapping description lines at print width.

* `"greedy"` — Always re-wrap text to fit within print width.

* `"balance"` — Preserve original line breaks if all lines fit within print width.

* Default: `"greedy"`

###### overrides\[n].options.jsdoc.preferCodeFences

type: `boolean`

Use fenced code blocks (` ``` `) instead of 4-space indentation for code without a language tag.

* Default: `false`

###### overrides\[n].options.jsdoc.separateReturnsFromParam

type: `boolean`

Add a blank line between the last `@param` and `@returns`.

* Default: `false`

###### overrides\[n].options.jsdoc.separateTagGroups

type: `boolean`

Add blank lines between different tag groups (e.g. between `@param` and `@returns`).

* Default: `false`

##### overrides\[n].options.jsxSingleQuote

type: `boolean`

Use single quotes instead of double quotes in JSX.

* Languages: JSX, TSX
* Default: `false`

##### overrides\[n].options.objectWrap

type: `"preserve" | "collapse"`

How to wrap object literals when they could fit on one line or span multiple lines.

By default, formats objects as multi-line if there is a newline prior to the first property.
Authors can use this heuristic to contextually improve readability, though it has some downsides.

* Languages: JS, JSX, TS, TSX, JSON, JSONC, JSON5
* Default: `"preserve"`

##### overrides\[n].options.printWidth

type: `integer`

Specify the line length that the printer will wrap on.

If you don't want line wrapping when formatting Markdown, you can set the `proseWrap` option to disable it.

* Languages: All
* Default: `100`
* Overrides `.editorconfig.max_line_length`

##### overrides\[n].options.proseWrap

type: `"always" | "never" | "preserve"`

How to wrap prose.

By default, formatter will not change wrapping in markdown text since some services use a linebreak-sensitive renderer, e.g. GitHub comments and BitBucket.
To wrap prose to the print width, change this option to "always".
If you want to force all prose blocks to be on a single line and rely on editor/viewer soft wrapping instead, you can use "never".

* Languages: Markdown, MDX, YAML
* Default: `"preserve"`

##### overrides\[n].options.quoteProps

type: `"as-needed" | "consistent" | "preserve"`

Change when properties in objects are quoted.

* Languages: JS, JSX, TS, TSX
* Default: `"as-needed"`

##### overrides\[n].options.semi

type: `boolean`

Print semicolons at the ends of statements.

* Languages: JS, JSX, TS, TSX
* Default: `true`

##### overrides\[n].options.singleAttributePerLine

type: `boolean`

Enforce single attribute per line in HTML, Vue, and JSX.

* Languages: JSX, TSX, HTML, Angular, Vue, MJML, Svelte
* Default: `false`

##### overrides\[n].options.singleQuote

type: `boolean`

Use single quotes instead of double quotes.

For JSX, you can set the `jsxSingleQuote` option.

* Languages: JS, JSX, TS, TSX, CSS, Less, SCSS, Markdown, MDX, YAML, Handlebars, Svelte
* Default: `false`
* Overrides `.editorconfig.quote_type`

##### overrides\[n].options.sortImports

type: `object | boolean`

Sort import statements.

Using the similar algorithm as [eslint-plugin-perfectionist/sort-imports](https://perfectionist.dev/rules/sort-imports).
For details, see each field's documentation.

Pass `true` or an object to enable with defaults, or omit/set `false` to disable.

* Languages: JS, JSX, TS, TSX
* Default: Disabled

###### overrides\[n].options.sortImports.customGroups

type: `array`

Define your own groups for matching very specific imports.

The `customGroups` list is ordered: The first definition that matches an element will be used.
Custom groups have a higher priority than any predefined group.

If you want a predefined group to take precedence over a custom group,
you must write a custom group definition that does the same as what the predefined group does, and put it first in the list.

If you specify multiple conditions like `elementNamePattern`, `selector`, and `modifiers`,
all conditions must be met for an import to match the custom group (AND logic).

* Default: `[]`

\####### overrides\[n].options.sortImports.customGroups\[n]

type: `object`

\######## overrides\[n].options.sortImports.customGroups\[n].elementNamePattern

type: `string[]`

default: `[]`

List of glob patterns to match import sources for this group.

\######## overrides\[n].options.sortImports.customGroups\[n].groupName

type: `string`

default: `""`

Name of the custom group, used in the `groups` option.

\######## overrides\[n].options.sortImports.customGroups\[n].modifiers

type: `array`

Modifiers to match the import characteristics.
All specified modifiers must be present (AND logic).

\######### overrides\[n].options.sortImports.customGroups\[n].modifiers\[n]

type: `"side_effect" | "type" | "value" | "default" | "wildcard" | "named"`

Modifier matching the import characteristics in `customGroups` (see `sortImports.groups` for semantics).

\######## overrides\[n].options.sortImports.customGroups\[n].selector

type: `"type" | "side_effect_style" | "side_effect" | "style" | "index" | "sibling" | "parent" | "subpath" | "internal" | "builtin" | "external" | "import"`

Selector to match the import kind.

###### overrides\[n].options.sortImports.groups

type: `array`

Specifies a list of predefined import groups for sorting.

Each import will be assigned a single group specified in the groups option (or the `unknown` group if no match is found).
The order of items in the `groups` option determines how groups are ordered.

Within a given group, members will be sorted according to the type, order, ignoreCase, etc. options.

Individual groups can be combined together by placing them in an array.
The order of groups in that array does not matter.
All members of the groups in the array will be sorted together as if they were part of a single group.

Predefined groups are characterized by a single selector and potentially multiple modifiers.
You may enter modifiers in any order, but the selector must always come at the end.

The list of selectors is sorted from most to least important:

* `type` — TypeScript type imports.
* `side_effect_style` — Side effect style imports.
* `side_effect` — Side effect imports.
* `style` — Style imports.
* `index` — Main file from the current directory.
* `sibling` — Modules from the same directory.
* `parent` — Modules from the parent directory.
* `subpath` — Node.js subpath imports.
* `internal` — Your internal modules.
* `builtin` — Node.js Built-in Modules.
* `external` — External modules installed in the project.
* `import` — Any import.

The list of modifiers is sorted from most to least important:

* `side_effect` — Side effect imports.

* `type` — TypeScript type imports.

* `value` — Value imports.

* `default` — Imports containing the default specifier.

* `wildcard` — Imports containing the wildcard (`* as`) specifier.

* `named` — Imports containing at least one named specifier.

* Default: See below

```json
["builtin", "external", ["internal", "subpath"], ["parent", "sibling", "index"], "style", "unknown"]
```

Also, you can override the global `newlinesBetween` setting for specific group boundaries
by including a `{ "newlinesBetween": boolean }` marker object in the `groups` list at the desired position.

\####### overrides\[n].options.sortImports.groups\[n]

type: `object | array | string`

\######## overrides\[n].options.sortImports.groups\[n].newlinesBetween

type: `boolean`

###### overrides\[n].options.sortImports.ignoreCase

type: `boolean`

Specifies whether sorting should be case-sensitive.

* Default: `true`

###### overrides\[n].options.sortImports.internalPattern

type: `string[]`

Specifies a prefix for identifying internal imports.

This is useful for distinguishing your own modules from external dependencies.

* Default: `["~/", "@/", "#"]`

###### overrides\[n].options.sortImports.newlinesBetween

type: `boolean`

Specifies whether to add newlines between groups.

When `false`, no newlines are added between groups.

* Default: `true`

###### overrides\[n].options.sortImports.order

type: `"asc" | "desc"`

Specifies whether to sort items in ascending or descending order.

* Default: `"asc"`

###### overrides\[n].options.sortImports.partitionByComment

type: `boolean`

Enables the use of comments to separate imports into logical groups.

When `true`, all comments will be treated as delimiters, creating partitions.

```js
import { b1, b2 } from "b";
// PARTITION
import { a } from "a";
import { c } from "c";
```

* Default: `false`

###### overrides\[n].options.sortImports.partitionByNewline

type: `boolean`

Enables the empty line to separate imports into logical groups.

When `true`, formatter will not sort imports if there is an empty line between them.
This helps maintain the defined order of logically separated groups of members.

```js
import { b1, b2 } from "b";

import { a } from "a";
import { c } from "c";
```

* Default: `false`

###### overrides\[n].options.sortImports.sortSideEffects

type: `boolean`

Specifies whether side effect imports should be sorted.

By default, sorting side-effect imports is disabled for security reasons.

* Default: `false`

##### overrides\[n].options.sortPackageJson

type: `object | boolean`

Sort `package.json` keys.

The algorithm is NOT compatible with [prettier-plugin-sort-packagejson](https://github.com/matzkoh/prettier-plugin-packagejson).
But we believe it is clearer and easier to navigate.
For details, see each field's documentation.

* Languages: JSON (`package.json` only)
* Default: `true`

###### overrides\[n].options.sortPackageJson.sortScripts

type: `boolean`

Sort the `scripts` field alphabetically.

* Default: `false`

##### overrides\[n].options.sortTailwindcss

type: `object | boolean`

Sort Tailwind CSS classes.

Using the same algorithm as [prettier-plugin-tailwindcss](https://github.com/tailwindlabs/prettier-plugin-tailwindcss).
Option names omit the `tailwind` prefix used in the original plugin (e.g., `config` instead of `tailwindConfig`).
For details, see each field's documentation.

Pass `true` or an object to enable with defaults, or omit/set `false` to disable.

* Languages: JS, JSX, TS, TSX, HTML, Vue, Angular, Handlebars, CSS, SCSS, Less, Svelte
* Default: Disabled

###### overrides\[n].options.sortTailwindcss.attributes

type: `string[]`

List of additional attributes to sort beyond `class` and `className` (exact match).

NOTE: Regex patterns are not yet supported.

* Default: `[]`
* Example: `["myClassProp", ":class"]`

###### overrides\[n].options.sortTailwindcss.config

type: `string`

Path to your Tailwind CSS configuration file (v3).

NOTE: Paths are resolved relative to the Oxfmt configuration file.

* Default: Automatically find `"tailwind.config.js"`

###### overrides\[n].options.sortTailwindcss.functions

type: `string[]`

List of custom function names whose arguments should be sorted (exact match).

NOTE: Regex patterns are not yet supported.

* Default: `[]`
* Example: `["clsx", "cn", "cva", "tw"]`

###### overrides\[n].options.sortTailwindcss.preserveDuplicates

type: `boolean`

Preserve duplicate classes.

* Default: `false`

###### overrides\[n].options.sortTailwindcss.preserveWhitespace

type: `boolean`

Preserve whitespace around classes.

* Default: `false`

###### overrides\[n].options.sortTailwindcss.stylesheet

type: `string`

Path to your Tailwind CSS stylesheet (v4).

NOTE: Paths are resolved relative to the Oxfmt configuration file.

* Default: Installed Tailwind CSS's `theme.css`

##### overrides\[n].options.svelte

type: `object | boolean`

Options for `prettier-plugin-svelte`.

Pass `true` or an object to enable `.svelte` file formatting,
or `false` (handy in overrides) / omit to disable.
Setting `true` resets to defaults — any options inherited from a parent scope are dropped.

NOTE: `prettier-plugin-svelte` requires the `svelte` package (`svelte/compiler`) at runtime,
but Oxfmt does NOT bundle or auto-install it.
You must install `svelte` yourself in your project, formatting will fail at runtime otherwise.

* Languages: Svelte
* Default: Disabled

###### overrides\[n].options.svelte.allowShorthand

type: `boolean`

Whether to allow attribute shorthand if attribute name and expression are same.

* Default: `true`

###### overrides\[n].options.svelte.indentScriptAndStyle

type: `boolean`

Whether to indent code inside `<script>` and `<style>` tags.

* Default: `true`

###### overrides\[n].options.svelte.sortOrder

type: `string`

The order in which Svelte component sections are printed.
Format: join the keywords `options`, `scripts`, `markup`, `styles` with a `-` in the order you want;
or `none` if you don't want to reorder anything.

* Default: `"options-scripts-markup-styles"`

##### overrides\[n].options.tabWidth

type: `integer`

Specify the number of spaces per indentation-level.

* Languages: All
* Default: `2`
* Overrides `.editorconfig.indent_size` (falls back to `.editorconfig.tab_width`)

##### overrides\[n].options.trailingComma

type: `"all" | "es5" | "none"`

Print trailing commas wherever possible in multi-line comma-separated syntactic structures.

A single-line array, for example, never gets trailing commas.

* Languages: JS, JSX, TS, TSX, JSONC, JSON5, TOML, CSS, Less, SCSS, YAML
* Default: `"all"`

##### overrides\[n].options.useTabs

type: `boolean`

Indent lines with tabs instead of spaces.

* Languages: All
* Default: `false`
* Overrides `.editorconfig.indent_style`

##### overrides\[n].options.vueIndentScriptAndStyle

type: `boolean`

Whether or not to indent the code inside `<script>` and `<style>` tags in Vue files.

* Languages: Vue
* Default: `false`

## printWidth

type: `integer`

Specify the line length that the printer will wrap on.

If you don't want line wrapping when formatting Markdown, you can set the `proseWrap` option to disable it.

* Languages: All
* Default: `100`
* Overrides `.editorconfig.max_line_length`

## proseWrap

type: `"always" | "never" | "preserve"`

How to wrap prose.

By default, formatter will not change wrapping in markdown text since some services use a linebreak-sensitive renderer, e.g. GitHub comments and BitBucket.
To wrap prose to the print width, change this option to "always".
If you want to force all prose blocks to be on a single line and rely on editor/viewer soft wrapping instead, you can use "never".

* Languages: Markdown, MDX, YAML
* Default: `"preserve"`

## quoteProps

type: `"as-needed" | "consistent" | "preserve"`

Change when properties in objects are quoted.

* Languages: JS, JSX, TS, TSX
* Default: `"as-needed"`

## semi

type: `boolean`

Print semicolons at the ends of statements.

* Languages: JS, JSX, TS, TSX
* Default: `true`

## singleAttributePerLine

type: `boolean`

Enforce single attribute per line in HTML, Vue, and JSX.

* Languages: JSX, TSX, HTML, Angular, Vue, MJML, Svelte
* Default: `false`

## singleQuote

type: `boolean`

Use single quotes instead of double quotes.

For JSX, you can set the `jsxSingleQuote` option.

* Languages: JS, JSX, TS, TSX, CSS, Less, SCSS, Markdown, MDX, YAML, Handlebars, Svelte
* Default: `false`
* Overrides `.editorconfig.quote_type`

## sortImports

type: `object | boolean`

Sort import statements.

Using the similar algorithm as [eslint-plugin-perfectionist/sort-imports](https://perfectionist.dev/rules/sort-imports).
For details, see each field's documentation.

Pass `true` or an object to enable with defaults, or omit/set `false` to disable.

* Languages: JS, JSX, TS, TSX
* Default: Disabled

### sortImports.customGroups

type: `array`

Define your own groups for matching very specific imports.

The `customGroups` list is ordered: The first definition that matches an element will be used.
Custom groups have a higher priority than any predefined group.

If you want a predefined group to take precedence over a custom group,
you must write a custom group definition that does the same as what the predefined group does, and put it first in the list.

If you specify multiple conditions like `elementNamePattern`, `selector`, and `modifiers`,
all conditions must be met for an import to match the custom group (AND logic).

* Default: `[]`

#### sortImports.customGroups\[n]

type: `object`

##### sortImports.customGroups\[n].elementNamePattern

type: `string[]`

default: `[]`

List of glob patterns to match import sources for this group.

##### sortImports.customGroups\[n].groupName

type: `string`

default: `""`

Name of the custom group, used in the `groups` option.

##### sortImports.customGroups\[n].modifiers

type: `array`

Modifiers to match the import characteristics.
All specified modifiers must be present (AND logic).

###### sortImports.customGroups\[n].modifiers\[n]

type: `"side_effect" | "type" | "value" | "default" | "wildcard" | "named"`

Modifier matching the import characteristics in `customGroups` (see `sortImports.groups` for semantics).

##### sortImports.customGroups\[n].selector

type: `"type" | "side_effect_style" | "side_effect" | "style" | "index" | "sibling" | "parent" | "subpath" | "internal" | "builtin" | "external" | "import"`

Selector to match the import kind.

### sortImports.groups

type: `array`

Specifies a list of predefined import groups for sorting.

Each import will be assigned a single group specified in the groups option (or the `unknown` group if no match is found).
The order of items in the `groups` option determines how groups are ordered.

Within a given group, members will be sorted according to the type, order, ignoreCase, etc. options.

Individual groups can be combined together by placing them in an array.
The order of groups in that array does not matter.
All members of the groups in the array will be sorted together as if they were part of a single group.

Predefined groups are characterized by a single selector and potentially multiple modifiers.
You may enter modifiers in any order, but the selector must always come at the end.

The list of selectors is sorted from most to least important:

* `type` — TypeScript type imports.
* `side_effect_style` — Side effect style imports.
* `side_effect` — Side effect imports.
* `style` — Style imports.
* `index` — Main file from the current directory.
* `sibling` — Modules from the same directory.
* `parent` — Modules from the parent directory.
* `subpath` — Node.js subpath imports.
* `internal` — Your internal modules.
* `builtin` — Node.js Built-in Modules.
* `external` — External modules installed in the project.
* `import` — Any import.

The list of modifiers is sorted from most to least important:

* `side_effect` — Side effect imports.

* `type` — TypeScript type imports.

* `value` — Value imports.

* `default` — Imports containing the default specifier.

* `wildcard` — Imports containing the wildcard (`* as`) specifier.

* `named` — Imports containing at least one named specifier.

* Default: See below

```json
["builtin", "external", ["internal", "subpath"], ["parent", "sibling", "index"], "style", "unknown"]
```

Also, you can override the global `newlinesBetween` setting for specific group boundaries
by including a `{ "newlinesBetween": boolean }` marker object in the `groups` list at the desired position.

#### sortImports.groups\[n]

type: `object | array | string`

##### sortImports.groups\[n].newlinesBetween

type: `boolean`

### sortImports.ignoreCase

type: `boolean`

Specifies whether sorting should be case-sensitive.

* Default: `true`

### sortImports.internalPattern

type: `string[]`

Specifies a prefix for identifying internal imports.

This is useful for distinguishing your own modules from external dependencies.

* Default: `["~/", "@/", "#"]`

### sortImports.newlinesBetween

type: `boolean`

Specifies whether to add newlines between groups.

When `false`, no newlines are added between groups.

* Default: `true`

### sortImports.order

type: `"asc" | "desc"`

Specifies whether to sort items in ascending or descending order.

* Default: `"asc"`

### sortImports.partitionByComment

type: `boolean`

Enables the use of comments to separate imports into logical groups.

When `true`, all comments will be treated as delimiters, creating partitions.

```js
import { b1, b2 } from "b";
// PARTITION
import { a } from "a";
import { c } from "c";
```

* Default: `false`

### sortImports.partitionByNewline

type: `boolean`

Enables the empty line to separate imports into logical groups.

When `true`, formatter will not sort imports if there is an empty line between them.
This helps maintain the defined order of logically separated groups of members.

```js
import { b1, b2 } from "b";

import { a } from "a";
import { c } from "c";
```

* Default: `false`

### sortImports.sortSideEffects

type: `boolean`

Specifies whether side effect imports should be sorted.

By default, sorting side-effect imports is disabled for security reasons.

* Default: `false`

## sortPackageJson

type: `object | boolean`

Sort `package.json` keys.

The algorithm is NOT compatible with [prettier-plugin-sort-packagejson](https://github.com/matzkoh/prettier-plugin-packagejson).
But we believe it is clearer and easier to navigate.
For details, see each field's documentation.

* Languages: JSON (`package.json` only)
* Default: `true`

### sortPackageJson.sortScripts

type: `boolean`

Sort the `scripts` field alphabetically.

* Default: `false`

## sortTailwindcss

type: `object | boolean`

Sort Tailwind CSS classes.

Using the same algorithm as [prettier-plugin-tailwindcss](https://github.com/tailwindlabs/prettier-plugin-tailwindcss).
Option names omit the `tailwind` prefix used in the original plugin (e.g., `config` instead of `tailwindConfig`).
For details, see each field's documentation.

Pass `true` or an object to enable with defaults, or omit/set `false` to disable.

* Languages: JS, JSX, TS, TSX, HTML, Vue, Angular, Handlebars, CSS, SCSS, Less, Svelte
* Default: Disabled

### sortTailwindcss.attributes

type: `string[]`

List of additional attributes to sort beyond `class` and `className` (exact match).

NOTE: Regex patterns are not yet supported.

* Default: `[]`
* Example: `["myClassProp", ":class"]`

### sortTailwindcss.config

type: `string`

Path to your Tailwind CSS configuration file (v3).

NOTE: Paths are resolved relative to the Oxfmt configuration file.

* Default: Automatically find `"tailwind.config.js"`

### sortTailwindcss.functions

type: `string[]`

List of custom function names whose arguments should be sorted (exact match).

NOTE: Regex patterns are not yet supported.

* Default: `[]`
* Example: `["clsx", "cn", "cva", "tw"]`

### sortTailwindcss.preserveDuplicates

type: `boolean`

Preserve duplicate classes.

* Default: `false`

### sortTailwindcss.preserveWhitespace

type: `boolean`

Preserve whitespace around classes.

* Default: `false`

### sortTailwindcss.stylesheet

type: `string`

Path to your Tailwind CSS stylesheet (v4).

NOTE: Paths are resolved relative to the Oxfmt configuration file.

* Default: Installed Tailwind CSS's `theme.css`

## svelte

type: `object | boolean`

Options for `prettier-plugin-svelte`.

Pass `true` or an object to enable `.svelte` file formatting,
or `false` (handy in overrides) / omit to disable.
Setting `true` resets to defaults — any options inherited from a parent scope are dropped.

NOTE: `prettier-plugin-svelte` requires the `svelte` package (`svelte/compiler`) at runtime,
but Oxfmt does NOT bundle or auto-install it.
You must install `svelte` yourself in your project, formatting will fail at runtime otherwise.

* Languages: Svelte
* Default: Disabled

### svelte.allowShorthand

type: `boolean`

Whether to allow attribute shorthand if attribute name and expression are same.

* Default: `true`

### svelte.indentScriptAndStyle

type: `boolean`

Whether to indent code inside `<script>` and `<style>` tags.

* Default: `true`

### svelte.sortOrder

type: `string`

The order in which Svelte component sections are printed.
Format: join the keywords `options`, `scripts`, `markup`, `styles` with a `-` in the order you want;
or `none` if you don't want to reorder anything.

* Default: `"options-scripts-markup-styles"`

## tabWidth

type: `integer`

Specify the number of spaces per indentation-level.

* Languages: All
* Default: `2`
* Overrides `.editorconfig.indent_size` (falls back to `.editorconfig.tab_width`)

## trailingComma

type: `"all" | "es5" | "none"`

Print trailing commas wherever possible in multi-line comma-separated syntactic structures.

A single-line array, for example, never gets trailing commas.

* Languages: JS, JSX, TS, TSX, JSONC, JSON5, TOML, CSS, Less, SCSS, YAML
* Default: `"all"`

## useTabs

type: `boolean`

Indent lines with tabs instead of spaces.

* Languages: All
* Default: `false`
* Overrides `.editorconfig.indent_style`

## vueIndentScriptAndStyle

type: `boolean`

Whether or not to indent the code inside `<script>` and `<style>` tags in Vue files.

* Languages: Vue
* Default: `false`

---

---
url: /docs/guide/usage/formatter/generated-config.md
---

# Configuration options for the Oxfmt.

Most options are the same as Prettier's options, but not all of them.
In addition, some options are our own extensions.

## arrowParens

type: `"always" | "avoid"`

Include parentheses around a sole arrow function parameter.

* Languages: JS, JSX, TS, TSX
* Default: `"always"`

## bracketSameLine

type: `boolean`

Put the `>` of a multi-line HTML (HTML, JSX, Vue, Angular) element at the end of the last line,
instead of being alone on the next line (does not apply to self closing elements).

* Languages: JSX, TSX, HTML, Angular, Vue, MJML, Svelte
* Default: `false`

## bracketSpacing

type: `boolean`

Print spaces between brackets in object literals.

* Languages: JS, JSX, TS, TSX, JSON, JSONC, JSON5, GraphQL, YAML
* Default: `true`

## embeddedLanguageFormatting

type: `"auto" | "off"`

Control whether to format embedded parts (For example, CSS-in-JS, or JS-in-Vue, etc.) in the file.

* Languages: JS, JSX, TS, TSX, HTML, Vue, Angular, Svelte, Markdown, MDX (languages with embedded code)
* Default: `"auto"`

## endOfLine

type: `"lf" | "crlf" | "cr"`

Which end of line characters to apply.

NOTE: `"auto"` is not supported.

* Languages: All
* Default: `"lf"`
* Overrides `.editorconfig.end_of_line`

## htmlWhitespaceSensitivity

type: `"css" | "strict" | "ignore"`

Specify the global whitespace sensitivity for HTML, Vue, Angular, and Handlebars.

* Languages: HTML, Angular, Vue, Handlebars, Svelte
* Default: `"css"`

## ignorePatterns

type: `string[]`

Ignore files matching these glob patterns.
Patterns use gitignore-style matching, rooted at the directory containing the configuration file.
Files outside that directory cannot be matched; patterns containing `..` are rejected as a configuration error.

* Default: `[]`

## insertFinalNewline

type: `boolean`

Whether to insert a final newline at the end of the file.

* Languages: All
* Default: `true`
* Overrides `.editorconfig.insert_final_newline`

## jsdoc

type: `object | boolean`

Enable JSDoc comment formatting.

When enabled, JSDoc comments are normalized and reformatted:
tag aliases are canonicalized, descriptions are capitalized,
long lines are wrapped, and short comments are collapsed to single-line.

Pass `true` or an object to enable with defaults, or omit/set `false` to disable.

* Languages: JS, JSX, TS, TSX
* Default: Disabled

### jsdoc.addDefaultToDescription

type: `boolean`

Append default values to `@param` descriptions (e.g. "Default is `value`").

* Default: `true`

### jsdoc.bracketSpacing

type: `boolean`

Add spaces inside JSDoc type braces: `{string}` → `{ string }`.

* Default: `false`

### jsdoc.capitalizeDescriptions

type: `boolean`

Capitalize the first letter of tag descriptions.

* Default: `true`

### jsdoc.commentLineStrategy

type: `"singleLine" | "multiline" | "keep"`

How to format comment blocks.

* `"singleLine"` — Convert to single-line `/** content */` when possible.

* `"multiline"` — Always use multi-line format.

* `"keep"` — Preserve original formatting.

* Default: `"singleLine"`

### jsdoc.descriptionTag

type: `boolean`

Emit `@description` tag instead of inline description.

* Default: `false`

### jsdoc.descriptionWithDot

type: `boolean`

Add a trailing dot to the end of descriptions.

* Default: `false`

### jsdoc.keepUnparsableExampleIndent

type: `boolean`

Preserve indentation in unparsable `@example` code.

* Default: `false`

### jsdoc.lineWrappingStyle

type: `"greedy" | "balance"`

Strategy for wrapping description lines at print width.

* `"greedy"` — Always re-wrap text to fit within print width.

* `"balance"` — Preserve original line breaks if all lines fit within print width.

* Default: `"greedy"`

### jsdoc.preferCodeFences

type: `boolean`

Use fenced code blocks (` ``` `) instead of 4-space indentation for code without a language tag.

* Default: `false`

### jsdoc.separateReturnsFromParam

type: `boolean`

Add a blank line between the last `@param` and `@returns`.

* Default: `false`

### jsdoc.separateTagGroups

type: `boolean`

Add blank lines between different tag groups (e.g. between `@param` and `@returns`).

* Default: `false`

## jsxSingleQuote

type: `boolean`

Use single quotes instead of double quotes in JSX.

* Languages: JSX, TSX
* Default: `false`

## objectWrap

type: `"preserve" | "collapse"`

How to wrap object literals when they could fit on one line or span multiple lines.

By default, formats objects as multi-line if there is a newline prior to the first property.
Authors can use this heuristic to contextually improve readability, though it has some downsides.

* Languages: JS, JSX, TS, TSX, JSON, JSONC, JSON5
* Default: `"preserve"`

## overrides

type: `array`

File-specific overrides.
When a file matches multiple overrides, the later override takes precedence (array order matters).

* Default: `[]`

### overrides\[n]

type: `object`

#### overrides\[n].excludeFiles

type: `string[]`

Glob patterns to exclude from this override.

A set of glob patterns.
Patterns are matched against paths relative to the configuration file's directory.

#### overrides\[n].files

type: `string[]`

Glob patterns to match files for this override.

A set of glob patterns.
Patterns are matched against paths relative to the configuration file's directory.

#### overrides\[n].options

type: `object`

Format options to apply for matched files.

##### overrides\[n].options.arrowParens

type: `"always" | "avoid"`

Include parentheses around a sole arrow function parameter.

* Languages: JS, JSX, TS, TSX
* Default: `"always"`

##### overrides\[n].options.bracketSameLine

type: `boolean`

Put the `>` of a multi-line HTML (HTML, JSX, Vue, Angular) element at the end of the last line,
instead of being alone on the next line (does not apply to self closing elements).

* Languages: JSX, TSX, HTML, Angular, Vue, MJML, Svelte
* Default: `false`

##### overrides\[n].options.bracketSpacing

type: `boolean`

Print spaces between brackets in object literals.

* Languages: JS, JSX, TS, TSX, JSON, JSONC, JSON5, GraphQL, YAML
* Default: `true`

##### overrides\[n].options.embeddedLanguageFormatting

type: `"auto" | "off"`

Control whether to format embedded parts (For example, CSS-in-JS, or JS-in-Vue, etc.) in the file.

* Languages: JS, JSX, TS, TSX, HTML, Vue, Angular, Svelte, Markdown, MDX (languages with embedded code)
* Default: `"auto"`

##### overrides\[n].options.endOfLine

type: `"lf" | "crlf" | "cr"`

Which end of line characters to apply.

NOTE: `"auto"` is not supported.

* Languages: All
* Default: `"lf"`
* Overrides `.editorconfig.end_of_line`

##### overrides\[n].options.htmlWhitespaceSensitivity

type: `"css" | "strict" | "ignore"`

Specify the global whitespace sensitivity for HTML, Vue, Angular, and Handlebars.

* Languages: HTML, Angular, Vue, Handlebars, Svelte
* Default: `"css"`

##### overrides\[n].options.insertFinalNewline

type: `boolean`

Whether to insert a final newline at the end of the file.

* Languages: All
* Default: `true`
* Overrides `.editorconfig.insert_final_newline`

##### overrides\[n].options.jsdoc

type: `object | boolean`

Enable JSDoc comment formatting.

When enabled, JSDoc comments are normalized and reformatted:
tag aliases are canonicalized, descriptions are capitalized,
long lines are wrapped, and short comments are collapsed to single-line.

Pass `true` or an object to enable with defaults, or omit/set `false` to disable.

* Languages: JS, JSX, TS, TSX
* Default: Disabled

###### overrides\[n].options.jsdoc.addDefaultToDescription

type: `boolean`

Append default values to `@param` descriptions (e.g. "Default is `value`").

* Default: `true`

###### overrides\[n].options.jsdoc.bracketSpacing

type: `boolean`

Add spaces inside JSDoc type braces: `{string}` → `{ string }`.

* Default: `false`

###### overrides\[n].options.jsdoc.capitalizeDescriptions

type: `boolean`

Capitalize the first letter of tag descriptions.

* Default: `true`

###### overrides\[n].options.jsdoc.commentLineStrategy

type: `"singleLine" | "multiline" | "keep"`

How to format comment blocks.

* `"singleLine"` — Convert to single-line `/** content */` when possible.

* `"multiline"` — Always use multi-line format.

* `"keep"` — Preserve original formatting.

* Default: `"singleLine"`

###### overrides\[n].options.jsdoc.descriptionTag

type: `boolean`

Emit `@description` tag instead of inline description.

* Default: `false`

###### overrides\[n].options.jsdoc.descriptionWithDot

type: `boolean`

Add a trailing dot to the end of descriptions.

* Default: `false`

###### overrides\[n].options.jsdoc.keepUnparsableExampleIndent

type: `boolean`

Preserve indentation in unparsable `@example` code.

* Default: `false`

###### overrides\[n].options.jsdoc.lineWrappingStyle

type: `"greedy" | "balance"`

Strategy for wrapping description lines at print width.

* `"greedy"` — Always re-wrap text to fit within print width.

* `"balance"` — Preserve original line breaks if all lines fit within print width.

* Default: `"greedy"`

###### overrides\[n].options.jsdoc.preferCodeFences

type: `boolean`

Use fenced code blocks (` ``` `) instead of 4-space indentation for code without a language tag.

* Default: `false`

###### overrides\[n].options.jsdoc.separateReturnsFromParam

type: `boolean`

Add a blank line between the last `@param` and `@returns`.

* Default: `false`

###### overrides\[n].options.jsdoc.separateTagGroups

type: `boolean`

Add blank lines between different tag groups (e.g. between `@param` and `@returns`).

* Default: `false`

##### overrides\[n].options.jsxSingleQuote

type: `boolean`

Use single quotes instead of double quotes in JSX.

* Languages: JSX, TSX
* Default: `false`

##### overrides\[n].options.objectWrap

type: `"preserve" | "collapse"`

How to wrap object literals when they could fit on one line or span multiple lines.

By default, formats objects as multi-line if there is a newline prior to the first property.
Authors can use this heuristic to contextually improve readability, though it has some downsides.

* Languages: JS, JSX, TS, TSX, JSON, JSONC, JSON5
* Default: `"preserve"`

##### overrides\[n].options.printWidth

type: `integer`

Specify the line length that the printer will wrap on.

If you don't want line wrapping when formatting Markdown, you can set the `proseWrap` option to disable it.

* Languages: All
* Default: `100`
* Overrides `.editorconfig.max_line_length`

##### overrides\[n].options.proseWrap

type: `"always" | "never" | "preserve"`

How to wrap prose.

By default, formatter will not change wrapping in markdown text since some services use a linebreak-sensitive renderer, e.g. GitHub comments and BitBucket.
To wrap prose to the print width, change this option to "always".
If you want to force all prose blocks to be on a single line and rely on editor/viewer soft wrapping instead, you can use "never".

* Languages: Markdown, MDX, YAML
* Default: `"preserve"`

##### overrides\[n].options.quoteProps

type: `"as-needed" | "consistent" | "preserve"`

Change when properties in objects are quoted.

* Languages: JS, JSX, TS, TSX
* Default: `"as-needed"`

##### overrides\[n].options.semi

type: `boolean`

Print semicolons at the ends of statements.

* Languages: JS, JSX, TS, TSX
* Default: `true`

##### overrides\[n].options.singleAttributePerLine

type: `boolean`

Enforce single attribute per line in HTML, Vue, and JSX.

* Languages: JSX, TSX, HTML, Angular, Vue, MJML, Svelte
* Default: `false`

##### overrides\[n].options.singleQuote

type: `boolean`

Use single quotes instead of double quotes.

For JSX, you can set the `jsxSingleQuote` option.

* Languages: JS, JSX, TS, TSX, CSS, Less, SCSS, Markdown, MDX, YAML, Handlebars, Svelte
* Default: `false`
* Overrides `.editorconfig.quote_type`

##### overrides\[n].options.sortImports

type: `object | boolean`

Sort import statements.

Using the similar algorithm as [eslint-plugin-perfectionist/sort-imports](https://perfectionist.dev/rules/sort-imports).
For details, see each field's documentation.

Pass `true` or an object to enable with defaults, or omit/set `false` to disable.

* Languages: JS, JSX, TS, TSX
* Default: Disabled

###### overrides\[n].options.sortImports.customGroups

type: `array`

Define your own groups for matching very specific imports.

The `customGroups` list is ordered: The first definition that matches an element will be used.
Custom groups have a higher priority than any predefined group.

If you want a predefined group to take precedence over a custom group,
you must write a custom group definition that does the same as what the predefined group does, and put it first in the list.

If you specify multiple conditions like `elementNamePattern`, `selector`, and `modifiers`,
all conditions must be met for an import to match the custom group (AND logic).

* Default: `[]`

\####### overrides\[n].options.sortImports.customGroups\[n]

type: `object`

\######## overrides\[n].options.sortImports.customGroups\[n].elementNamePattern

type: `string[]`

default: `[]`

List of glob patterns to match import sources for this group.

\######## overrides\[n].options.sortImports.customGroups\[n].groupName

type: `string`

default: `""`

Name of the custom group, used in the `groups` option.

\######## overrides\[n].options.sortImports.customGroups\[n].modifiers

type: `array`

Modifiers to match the import characteristics.
All specified modifiers must be present (AND logic).

\######### overrides\[n].options.sortImports.customGroups\[n].modifiers\[n]

type: `"side_effect" | "type" | "value" | "default" | "wildcard" | "named"`

Modifier matching the import characteristics in `customGroups` (see `sortImports.groups` for semantics).

\######## overrides\[n].options.sortImports.customGroups\[n].selector

type: `"type" | "side_effect_style" | "side_effect" | "style" | "index" | "sibling" | "parent" | "subpath" | "internal" | "builtin" | "external" | "import"`

Selector to match the import kind.

###### overrides\[n].options.sortImports.groups

type: `array`

Specifies a list of predefined import groups for sorting.

Each import will be assigned a single group specified in the groups option (or the `unknown` group if no match is found).
The order of items in the `groups` option determines how groups are ordered.

Within a given group, members will be sorted according to the type, order, ignoreCase, etc. options.

Individual groups can be combined together by placing them in an array.
The order of groups in that array does not matter.
All members of the groups in the array will be sorted together as if they were part of a single group.

Predefined groups are characterized by a single selector and potentially multiple modifiers.
You may enter modifiers in any order, but the selector must always come at the end.

The list of selectors is sorted from most to least important:

* `type` — TypeScript type imports.
* `side_effect_style` — Side effect style imports.
* `side_effect` — Side effect imports.
* `style` — Style imports.
* `index` — Main file from the current directory.
* `sibling` — Modules from the same directory.
* `parent` — Modules from the parent directory.
* `subpath` — Node.js subpath imports.
* `internal` — Your internal modules.
* `builtin` — Node.js Built-in Modules.
* `external` — External modules installed in the project.
* `import` — Any import.

The list of modifiers is sorted from most to least important:

* `side_effect` — Side effect imports.

* `type` — TypeScript type imports.

* `value` — Value imports.

* `default` — Imports containing the default specifier.

* `wildcard` — Imports containing the wildcard (`* as`) specifier.

* `named` — Imports containing at least one named specifier.

* Default: See below

```json
["builtin", "external", ["internal", "subpath"], ["parent", "sibling", "index"], "style", "unknown"]
```

Also, you can override the global `newlinesBetween` setting for specific group boundaries
by including a `{ "newlinesBetween": boolean }` marker object in the `groups` list at the desired position.

\####### overrides\[n].options.sortImports.groups\[n]

type: `object | array | string`

\######## overrides\[n].options.sortImports.groups\[n].newlinesBetween

type: `boolean`

###### overrides\[n].options.sortImports.ignoreCase

type: `boolean`

Specifies whether sorting should be case-sensitive.

* Default: `true`

###### overrides\[n].options.sortImports.internalPattern

type: `string[]`

Specifies a prefix for identifying internal imports.

This is useful for distinguishing your own modules from external dependencies.

* Default: `["~/", "@/", "#"]`

###### overrides\[n].options.sortImports.newlinesBetween

type: `boolean`

Specifies whether to add newlines between groups.

When `false`, no newlines are added between groups.

* Default: `true`

###### overrides\[n].options.sortImports.order

type: `"asc" | "desc"`

Specifies whether to sort items in ascending or descending order.

* Default: `"asc"`

###### overrides\[n].options.sortImports.partitionByComment

type: `boolean`

Enables the use of comments to separate imports into logical groups.

When `true`, all comments will be treated as delimiters, creating partitions.

```js
import { b1, b2 } from "b";
// PARTITION
import { a } from "a";
import { c } from "c";
```

* Default: `false`

###### overrides\[n].options.sortImports.partitionByNewline

type: `boolean`

Enables the empty line to separate imports into logical groups.

When `true`, formatter will not sort imports if there is an empty line between them.
This helps maintain the defined order of logically separated groups of members.

```js
import { b1, b2 } from "b";

import { a } from "a";
import { c } from "c";
```

* Default: `false`

###### overrides\[n].options.sortImports.sortSideEffects

type: `boolean`

Specifies whether side effect imports should be sorted.

By default, sorting side-effect imports is disabled for security reasons.

* Default: `false`

##### overrides\[n].options.sortPackageJson

type: `object | boolean`

Sort `package.json` keys.

The algorithm is NOT compatible with [prettier-plugin-sort-packagejson](https://github.com/matzkoh/prettier-plugin-packagejson).
But we believe it is clearer and easier to navigate.
For details, see each field's documentation.

* Languages: JSON (`package.json` only)
* Default: `true`

###### overrides\[n].options.sortPackageJson.sortScripts

type: `boolean`

Sort the `scripts` field alphabetically.

* Default: `false`

##### overrides\[n].options.sortTailwindcss

type: `object | boolean`

Sort Tailwind CSS classes.

Using the same algorithm as [prettier-plugin-tailwindcss](https://github.com/tailwindlabs/prettier-plugin-tailwindcss).
Option names omit the `tailwind` prefix used in the original plugin (e.g., `config` instead of `tailwindConfig`).
For details, see each field's documentation.

Pass `true` or an object to enable with defaults, or omit/set `false` to disable.

* Languages: JS, JSX, TS, TSX, HTML, Vue, Angular, Handlebars, CSS, SCSS, Less, Svelte
* Default: Disabled

###### overrides\[n].options.sortTailwindcss.attributes

type: `string[]`

List of additional attributes to sort beyond `class` and `className` (exact match).

NOTE: Regex patterns are not yet supported.

* Default: `[]`
* Example: `["myClassProp", ":class"]`

###### overrides\[n].options.sortTailwindcss.config

type: `string`

Path to your Tailwind CSS configuration file (v3).

NOTE: Paths are resolved relative to the Oxfmt configuration file.

* Default: Automatically find `"tailwind.config.js"`

###### overrides\[n].options.sortTailwindcss.functions

type: `string[]`

List of custom function names whose arguments should be sorted (exact match).

NOTE: Regex patterns are not yet supported.

* Default: `[]`
* Example: `["clsx", "cn", "cva", "tw"]`

###### overrides\[n].options.sortTailwindcss.preserveDuplicates

type: `boolean`

Preserve duplicate classes.

* Default: `false`

###### overrides\[n].options.sortTailwindcss.preserveWhitespace

type: `boolean`

Preserve whitespace around classes.

* Default: `false`

###### overrides\[n].options.sortTailwindcss.stylesheet

type: `string`

Path to your Tailwind CSS stylesheet (v4).

NOTE: Paths are resolved relative to the Oxfmt configuration file.

* Default: Installed Tailwind CSS's `theme.css`

##### overrides\[n].options.svelte

type: `object | boolean`

Options for `prettier-plugin-svelte`.

Pass `true` or an object to enable `.svelte` file formatting,
or `false` (handy in overrides) / omit to disable.
Setting `true` resets to defaults — any options inherited from a parent scope are dropped.

NOTE: `prettier-plugin-svelte` requires the `svelte` package (`svelte/compiler`) at runtime,
but Oxfmt does NOT bundle or auto-install it.
You must install `svelte` yourself in your project, formatting will fail at runtime otherwise.

* Languages: Svelte
* Default: Disabled

###### overrides\[n].options.svelte.allowShorthand

type: `boolean`

Whether to allow attribute shorthand if attribute name and expression are same.

* Default: `true`

###### overrides\[n].options.svelte.indentScriptAndStyle

type: `boolean`

Whether to indent code inside `<script>` and `<style>` tags.

* Default: `true`

###### overrides\[n].options.svelte.sortOrder

type: `string`

The order in which Svelte component sections are printed.
Format: join the keywords `options`, `scripts`, `markup`, `styles` with a `-` in the order you want;
or `none` if you don't want to reorder anything.

* Default: `"options-scripts-markup-styles"`

##### overrides\[n].options.tabWidth

type: `integer`

Specify the number of spaces per indentation-level.

* Languages: All
* Default: `2`
* Overrides `.editorconfig.indent_size` (falls back to `.editorconfig.tab_width`)

##### overrides\[n].options.trailingComma

type: `"all" | "es5" | "none"`

Print trailing commas wherever possible in multi-line comma-separated syntactic structures.

A single-line array, for example, never gets trailing commas.

* Languages: JS, JSX, TS, TSX, JSONC, JSON5, TOML, CSS, Less, SCSS, YAML
* Default: `"all"`

##### overrides\[n].options.useTabs

type: `boolean`

Indent lines with tabs instead of spaces.

* Languages: All
* Default: `false`
* Overrides `.editorconfig.indent_style`

##### overrides\[n].options.vueIndentScriptAndStyle

type: `boolean`

Whether or not to indent the code inside `<script>` and `<style>` tags in Vue files.

* Languages: Vue
* Default: `false`

## printWidth

type: `integer`

Specify the line length that the printer will wrap on.

If you don't want line wrapping when formatting Markdown, you can set the `proseWrap` option to disable it.

* Languages: All
* Default: `100`
* Overrides `.editorconfig.max_line_length`

## proseWrap

type: `"always" | "never" | "preserve"`

How to wrap prose.

By default, formatter will not change wrapping in markdown text since some services use a linebreak-sensitive renderer, e.g. GitHub comments and BitBucket.
To wrap prose to the print width, change this option to "always".
If you want to force all prose blocks to be on a single line and rely on editor/viewer soft wrapping instead, you can use "never".

* Languages: Markdown, MDX, YAML
* Default: `"preserve"`

## quoteProps

type: `"as-needed" | "consistent" | "preserve"`

Change when properties in objects are quoted.

* Languages: JS, JSX, TS, TSX
* Default: `"as-needed"`

## semi

type: `boolean`

Print semicolons at the ends of statements.

* Languages: JS, JSX, TS, TSX
* Default: `true`

## singleAttributePerLine

type: `boolean`

Enforce single attribute per line in HTML, Vue, and JSX.

* Languages: JSX, TSX, HTML, Angular, Vue, MJML, Svelte
* Default: `false`

## singleQuote

type: `boolean`

Use single quotes instead of double quotes.

For JSX, you can set the `jsxSingleQuote` option.

* Languages: JS, JSX, TS, TSX, CSS, Less, SCSS, Markdown, MDX, YAML, Handlebars, Svelte
* Default: `false`
* Overrides `.editorconfig.quote_type`

## sortImports

type: `object | boolean`

Sort import statements.

Using the similar algorithm as [eslint-plugin-perfectionist/sort-imports](https://perfectionist.dev/rules/sort-imports).
For details, see each field's documentation.

Pass `true` or an object to enable with defaults, or omit/set `false` to disable.

* Languages: JS, JSX, TS, TSX
* Default: Disabled

### sortImports.customGroups

type: `array`

Define your own groups for matching very specific imports.

The `customGroups` list is ordered: The first definition that matches an element will be used.
Custom groups have a higher priority than any predefined group.

If you want a predefined group to take precedence over a custom group,
you must write a custom group definition that does the same as what the predefined group does, and put it first in the list.

If you specify multiple conditions like `elementNamePattern`, `selector`, and `modifiers`,
all conditions must be met for an import to match the custom group (AND logic).

* Default: `[]`

#### sortImports.customGroups\[n]

type: `object`

##### sortImports.customGroups\[n].elementNamePattern

type: `string[]`

default: `[]`

List of glob patterns to match import sources for this group.

##### sortImports.customGroups\[n].groupName

type: `string`

default: `""`

Name of the custom group, used in the `groups` option.

##### sortImports.customGroups\[n].modifiers

type: `array`

Modifiers to match the import characteristics.
All specified modifiers must be present (AND logic).

###### sortImports.customGroups\[n].modifiers\[n]

type: `"side_effect" | "type" | "value" | "default" | "wildcard" | "named"`

Modifier matching the import characteristics in `customGroups` (see `sortImports.groups` for semantics).

##### sortImports.customGroups\[n].selector

type: `"type" | "side_effect_style" | "side_effect" | "style" | "index" | "sibling" | "parent" | "subpath" | "internal" | "builtin" | "external" | "import"`

Selector to match the import kind.

### sortImports.groups

type: `array`

Specifies a list of predefined import groups for sorting.

Each import will be assigned a single group specified in the groups option (or the `unknown` group if no match is found).
The order of items in the `groups` option determines how groups are ordered.

Within a given group, members will be sorted according to the type, order, ignoreCase, etc. options.

Individual groups can be combined together by placing them in an array.
The order of groups in that array does not matter.
All members of the groups in the array will be sorted together as if they were part of a single group.

Predefined groups are characterized by a single selector and potentially multiple modifiers.
You may enter modifiers in any order, but the selector must always come at the end.

The list of selectors is sorted from most to least important:

* `type` — TypeScript type imports.
* `side_effect_style` — Side effect style imports.
* `side_effect` — Side effect imports.
* `style` — Style imports.
* `index` — Main file from the current directory.
* `sibling` — Modules from the same directory.
* `parent` — Modules from the parent directory.
* `subpath` — Node.js subpath imports.
* `internal` — Your internal modules.
* `builtin` — Node.js Built-in Modules.
* `external` — External modules installed in the project.
* `import` — Any import.

The list of modifiers is sorted from most to least important:

* `side_effect` — Side effect imports.

* `type` — TypeScript type imports.

* `value` — Value imports.

* `default` — Imports containing the default specifier.

* `wildcard` — Imports containing the wildcard (`* as`) specifier.

* `named` — Imports containing at least one named specifier.

* Default: See below

```json
["builtin", "external", ["internal", "subpath"], ["parent", "sibling", "index"], "style", "unknown"]
```

Also, you can override the global `newlinesBetween` setting for specific group boundaries
by including a `{ "newlinesBetween": boolean }` marker object in the `groups` list at the desired position.

#### sortImports.groups\[n]

type: `object | array | string`

##### sortImports.groups\[n].newlinesBetween

type: `boolean`

### sortImports.ignoreCase

type: `boolean`

Specifies whether sorting should be case-sensitive.

* Default: `true`

### sortImports.internalPattern

type: `string[]`

Specifies a prefix for identifying internal imports.

This is useful for distinguishing your own modules from external dependencies.

* Default: `["~/", "@/", "#"]`

### sortImports.newlinesBetween

type: `boolean`

Specifies whether to add newlines between groups.

When `false`, no newlines are added between groups.

* Default: `true`

### sortImports.order

type: `"asc" | "desc"`

Specifies whether to sort items in ascending or descending order.

* Default: `"asc"`

### sortImports.partitionByComment

type: `boolean`

Enables the use of comments to separate imports into logical groups.

When `true`, all comments will be treated as delimiters, creating partitions.

```js
import { b1, b2 } from "b";
// PARTITION
import { a } from "a";
import { c } from "c";
```

* Default: `false`

### sortImports.partitionByNewline

type: `boolean`

Enables the empty line to separate imports into logical groups.

When `true`, formatter will not sort imports if there is an empty line between them.
This helps maintain the defined order of logically separated groups of members.

```js
import { b1, b2 } from "b";

import { a } from "a";
import { c } from "c";
```

* Default: `false`

### sortImports.sortSideEffects

type: `boolean`

Specifies whether side effect imports should be sorted.

By default, sorting side-effect imports is disabled for security reasons.

* Default: `false`

## sortPackageJson

type: `object | boolean`

Sort `package.json` keys.

The algorithm is NOT compatible with [prettier-plugin-sort-packagejson](https://github.com/matzkoh/prettier-plugin-packagejson).
But we believe it is clearer and easier to navigate.
For details, see each field's documentation.

* Languages: JSON (`package.json` only)
* Default: `true`

### sortPackageJson.sortScripts

type: `boolean`

Sort the `scripts` field alphabetically.

* Default: `false`

## sortTailwindcss

type: `object | boolean`

Sort Tailwind CSS classes.

Using the same algorithm as [prettier-plugin-tailwindcss](https://github.com/tailwindlabs/prettier-plugin-tailwindcss).
Option names omit the `tailwind` prefix used in the original plugin (e.g., `config` instead of `tailwindConfig`).
For details, see each field's documentation.

Pass `true` or an object to enable with defaults, or omit/set `false` to disable.

* Languages: JS, JSX, TS, TSX, HTML, Vue, Angular, Handlebars, CSS, SCSS, Less, Svelte
* Default: Disabled

### sortTailwindcss.attributes

type: `string[]`

List of additional attributes to sort beyond `class` and `className` (exact match).

NOTE: Regex patterns are not yet supported.

* Default: `[]`
* Example: `["myClassProp", ":class"]`

### sortTailwindcss.config

type: `string`

Path to your Tailwind CSS configuration file (v3).

NOTE: Paths are resolved relative to the Oxfmt configuration file.

* Default: Automatically find `"tailwind.config.js"`

### sortTailwindcss.functions

type: `string[]`

List of custom function names whose arguments should be sorted (exact match).

NOTE: Regex patterns are not yet supported.

* Default: `[]`
* Example: `["clsx", "cn", "cva", "tw"]`

### sortTailwindcss.preserveDuplicates

type: `boolean`

Preserve duplicate classes.

* Default: `false`

### sortTailwindcss.preserveWhitespace

type: `boolean`

Preserve whitespace around classes.

* Default: `false`

### sortTailwindcss.stylesheet

type: `string`

Path to your Tailwind CSS stylesheet (v4).

NOTE: Paths are resolved relative to the Oxfmt configuration file.

* Default: Installed Tailwind CSS's `theme.css`

## svelte

type: `object | boolean`

Options for `prettier-plugin-svelte`.

Pass `true` or an object to enable `.svelte` file formatting,
or `false` (handy in overrides) / omit to disable.
Setting `true` resets to defaults — any options inherited from a parent scope are dropped.

NOTE: `prettier-plugin-svelte` requires the `svelte` package (`svelte/compiler`) at runtime,
but Oxfmt does NOT bundle or auto-install it.
You must install `svelte` yourself in your project, formatting will fail at runtime otherwise.

* Languages: Svelte
* Default: Disabled

### svelte.allowShorthand

type: `boolean`

Whether to allow attribute shorthand if attribute name and expression are same.

* Default: `true`

### svelte.indentScriptAndStyle

type: `boolean`

Whether to indent code inside `<script>` and `<style>` tags.

* Default: `true`

### svelte.sortOrder

type: `string`

The order in which Svelte component sections are printed.
Format: join the keywords `options`, `scripts`, `markup`, `styles` with a `-` in the order you want;
or `none` if you don't want to reorder anything.

* Default: `"options-scripts-markup-styles"`

## tabWidth

type: `integer`

Specify the number of spaces per indentation-level.

* Languages: All
* Default: `2`
* Overrides `.editorconfig.indent_size` (falls back to `.editorconfig.tab_width`)

## trailingComma

type: `"all" | "es5" | "none"`

Print trailing commas wherever possible in multi-line comma-separated syntactic structures.

A single-line array, for example, never gets trailing commas.

* Languages: JS, JSX, TS, TSX, JSONC, JSON5, TOML, CSS, Less, SCSS, YAML
* Default: `"all"`

## useTabs

type: `boolean`

Indent lines with tabs instead of spaces.

* Languages: All
* Default: `false`
* Overrides `.editorconfig.indent_style`

## vueIndentScriptAndStyle

type: `boolean`

Whether or not to indent the code inside `<script>` and `<style>` tags in Vue files.

* Languages: Vue
* Default: `false`

---

---
url: /docs/guide/usage/minifier/dead-code-elimination.md
---
# Dead Code Elimination

Oxc minifier supports eliminating dead code. For example, it removes the statements inside a `if (false)` block and the unused private class fields.

This feature is always enabled, but you can remove more code by enabling some options.

::: tip Useful features in the transformer

Other than the options below, you can also use [the `define` feature in the transformer](/docs/guide/usage/transformer/global-variable-replacement#define) to replace global identifiers with constant expressions to remove more dead code.

:::

## Drop Console

You can remove all `console.*` calls by enabling the `dropConsole` option. This option behaves similar to [Terser](https://terser.org/)'s `drop_console` option and [esbuild's `drop: ['console']` option](https://esbuild.github.io/api/#drop).

```js
// input
const bar = window.bar();
console.log("foo", bar, baz());

// output
const bar = window.bar();
```

```js
// Example
import { minify } from "oxc-minify";

const result = await minify("lib.js", code, {
  compress: {
    dropConsole: true,
  },
});
```

::: warning The whole call expression is removed

Note that this option removes the whole call expression including the arguments. This is intentional because removing the evaluation of call arguments is useful for improving the runtime performance if those are expensive to compute. However, if any of those arguments have side effects, this transformation will change the behavior of your code. If you want to keep the arguments, you can use [`compress.treeshake.manualPureFunctions: ['console']`](#define-pure-functions) option.

:::

## Drop Debugger

You can remove all `debugger` statements by enabling the `dropDebugger` option. This option is enabled by default. This option behaves similar to [Terser](https://terser.org/)'s `drop_debugger` option and [esbuild's `drop: ['debugger']` option](https://esbuild.github.io/api/#drop).

```js
// input
debugger;

// output
```

```js
// Example
import { minify } from "oxc-minify";

const result = await minify("lib.js", code, {
  compress: {
    dropDebugger: true,
  },
});
```

## Drop Labels

You can remove all labeled statements with specified labels by enabling the `dropLabels` option. This option behaves similar to [esbuild's `dropLabels` option](https://esbuild.github.io/api/#drop-labels).

```js
// input
DEV: console.log("foo");
console.log("bar");

// output
console.log("bar");
```

```js
// Example
import { minify } from "oxc-minify";

const result = await minify("lib.js", code, {
  compress: {
    dropLabels: ["DEV"],
  },
});
```

## Unused Declarations

All unused function / class / variable declarations are removed by default. You can keep them by using the `unused` option.

```js
// input
{
  function foo() {}
}

// output
```

```js
// Example
import { minify } from "oxc-minify";

const result = await minify("lib.js", code, {
  compress: {
    unused: true, // or "keep_assign"
  },
});
```

## Keep `name` Property Values

By default, Oxc minifier assumes that your code does not rely on the `name` property of functions / classes. This is because the `name` property is inferred from the function / class name or the variable name and keeping the original name would prevent reducing the output size.

To keep the `name` property values, you can use the `keepNames` option.

```js
// input
var bar = function foo() {};

// output
var bar = function foo() {};
```

```js
// Example
import { minify } from "oxc-minify";

const result = await minify("lib.js", code, {
  compress: {
    keepNames: true, // shorthand of { function: true, class: true }
  },
});
```

::: tip `mangle.keepNames` option

If you are using the mangling feature, you may also want to enable [the `mangle.keepNames` option](./mangling#keep-name-property-values).

:::

## Controlling Side Effect Detection

There are multiple options to control the side effect detection.

### Pure Annotations

By default, Oxc minifier respects pure annotations. Pure annotations are annotation comments that marks expressions that can be safely removed if their return values are not used. See [the draft specification proposal](https://github.com/javascript-compiler-hints/compiler-notations-spec) for more information.

This can be disabled by setting `compress.treeshake.annotations` option to `false`.

#### `#__PURE__` / `@__PURE__`

The `#__PURE__` annotation is used to mark function calls that can be safely removed if their return values are not used. Note that it only marks the function call itself and does not cover the arguments of it.

If you want to mark other expressions or the cover the arguments, you can wrap them with a IIFE and put the `#__PURE__` annotation on it.

```js
// input
/* #__PURE__ */ foo();
/* #__PURE__ */ new Foo();
/* #__PURE__ */ foo(bar());
/* #__PURE__ */ (() => {
  foo(bar());
})();
console.log(/* #__PURE__ */ foo());
console.log(/* #__PURE__ */ new Foo());

// output
bar();
console.log(foo());
console.log(new Foo());
```

::: tip The function does not have to be pure

Despite the name, the function does not have to be pure ([Pure function - Wikipedia](https://en.wikipedia.org/wiki/Pure_function)). It does not indicate that the calls can be cached. In other words, the function does not have to be referentially transparent ([Referential transparency - Wikipedia](https://en.wikipedia.org/wiki/Referential_transparency)).

:::

#### `#__NO_SIDE_EFFECTS__` / `@__NO_SIDE_EFFECTS__`

The `#__NO_SIDE_EFFECTS__` annotation is used to mark a function declaration that all calls of it can be safely removed if their return values are not used. This is useful if you have a function call of that function in multiple places.

```js
// input
/* #__NO_SIDE_EFFECTS__ */
export function foo() {}
/* #__NO_SIDE_EFFECTS__ */
export const bar = () => {};
foo();
bar();

// output
export function foo() {}
export const bar = () => {};
```

### Define Pure Functions

Instead of marking functions with pure annotations, you can also mark functions via the `compress.treeshake.manualPureFunctions` option. This option is an array of function names. This feature is similar to [Rollup's `treeshake.manualPureFunctions` option](https://rollupjs.org/configuration-options/#treeshake-manualpurefunctions) and [Terser](https://terser.org/)'s `pure_funcs` option.

```js
// input
foo();
foo.bar();
bar();
bar.baz();
new foo();
foo``;

// output
bar();
```

```js
// Example
import { minify } from "oxc-minify";

const result = await minify("lib.js", code, {
  compress: {
    treeshake: {
      manualPureFunctions: ["foo", "bar.baz"],
    },
  },
});
```

### Ignoring Property Read Side Effects

By default, Oxc minifier assumes that property reads have side effects. This is because the accessing a property of null throws an error. Also there's a case where a property is a getter and the getter might have a side effect. You can tell Oxc minifier to ignore those possibilities by setting `compress.treeshake.propertyReadSideEffects` option to `false`. This feature is similar to [Rollup's `treeshake.propertyReadSideEffects` option](https://rollupjs.org/configuration-options/#treeshake-propertyreadsideeffects) and [Terser](https://terser.org/)'s `pure_getters` option.

```js
// input
const foo = {
  get bar() {
    console.log("effect");
    return "bar";
  },
};
foo.bar;

// output (with `compress.treeshake.propertyReadSideEffects: false`)
```

### Ignoring Global Variable Access Side Effects

By default, Oxc minifier assumes that global variable accesses have side effects. This is because accessing a non-existent global variable throws an error. Also there's a case where a global variable is a getter and the getter might have a side effect. You can tell Oxc minifier to ignore those possibilities by setting `compress.treeshake.unknownGlobalSideEffects` option to `false`. This feature is similar to [Rollup's `treeshake.unknownGlobalSideEffects` option](https://rollupjs.org/configuration-options/#treeshake-unknownglobalsideeffects).

```js
// input
const jQuery = $;

// output (with `compress.treeshake.propertyReadSideEffects: false`)
```

### Ignoring Invalid Import Statement Side Effects

By default, Oxc minifier assumes that import statements don't have side effects. Import statements have side effects in the following cases:

* the import cannot be resolved
* the import name is not exported from the imported module

If these side effects need to be preserved, you can tell Oxc minifier to preserve them by setting `compress.treeshake.invalidImportSideEffects` option to `true`.

```js
// input
import { existing } from "cannot-be-resolved";
import { missing } from "somewhere";

// output (with `compress.treeshake.invalidImportSideEffects: true`)
import { existing } from "cannot-be-resolved";
import { missing } from "somewhere";

// output (with `compress.treeshake.invalidImportSideEffects: false`)
```

---

---
url: /docs/learn/parser_in_rust/errors.md
---

# Dealing with Errors

Quoting from the [Dragon Book](https://www.amazon.com/Compilers-Principles-Techniques-Tools-2nd/dp/0321486811)

> Most programming language specifications do not describe how a compiler should respond to errors; error handling is left to the compiler designer.
> Planning the error handling right from the start can both simplify the structure of a compiler and improve its handling of errors.

A fully recoverable parser can construct an AST no matter what we throw at it.
For tools such as linter or formatter, one would wish for a fully recoverable parser so we can act on part of the program.

A panicking parser will abort if there is any grammar mismatch, and a partially recoverable parser will recover from deterministic grammars.

For example, given a grammatically incorrect while statement `while true {}`, we know it is missing round brackets,
and the only punctuation it can have are round brackets, so we can still return a valid AST and indicate its missing brackets.

Most JavaScript parsers out there are partially recoverable, so we'll do the same and build a partially recoverable parser.

:::info
The Biome parser is a fully recoverable parser.
:::

Rust has the `Result` type for returning and propagating errors.
In conjunction with the `?` syntax, the parse functions will remain simple and clean.

It is common to wrap the Result type so we can replace the error later:

```rust
pub type Result<T> = std::result::Result<T, ()>;
```

Our parse functions will return a Result, for example:

```rust
pub fn parse_binding_pattern(&mut self, ctx: Context) -> Result<BindingPattern<'a>> {
    match self.cur_kind() {
        Kind::LCurly => self.parse_object_binding_pattern(ctx),
        Kind::LBrack => self.parse_array_binding_pattern(ctx),
        kind if kind.is_binding_identifier() => {
          // ... code omitted
        }
        _ => Err(()), // [!code highlight]
    }
}
```

We can add an `expect` function for returning an error if the current token does not match the grammar:

```rust
/// Expect a `Kind` or return error
pub fn expect(&mut self, kind: Kind) -> Result<()> {
    if !self.at(kind) {
        return Err(())
    }
    self.advance();
    Ok(())
}
```

And use it as such:

```rust
pub fn parse_paren_expression(&mut self, ctx: Context) -> Result<Expression> {
    self.expect(Kind::LParen)?;
    let expression = self.parse_expression(ctx)?;
    self.expect(Kind::RParen)?;
    Ok(expression)
}
```

:::info

For completeness, the lexer function `read_next_token` should also return `Result`
when an unexpected `char` is found when lexing.

:::

### The `Error` Trait

To return specific errors, we need to fill in the `Err` part of `Result`:

```rust
pub type Result<T> = std::result::Result<T, SyntaxError>;
                                            ^^^^^^^^^^^
#[derive(Debug)]
pub enum SyntaxError {
    UnexpectedToken(String),
    AutoSemicolonInsertion(String),
    UnterminatedMultiLineComment(String),
}
```

We call it `SyntaxError` because all "early error"s defined in the grammar section of the ECMAScript specification are syntax errors.

To make this a proper `Error`, it needs to implement the [`Error` Trait](https://doc.rust-lang.org/std/error/trait.Error.html). For cleaner code, we can use macros from the [`thiserror`](https://docs.rs/thiserror/latest/thiserror) crate:

```rust
#[derive(Debug, Error)]
pub enum SyntaxError {
    #[error("Unexpected Token")]
    UnexpectedToken,

    #[error("Expected a semicolon or an implicit semicolon after a statement, but found none")]
    AutoSemicolonInsertion,

    #[error("Unterminated multi-line comment")]
    UnterminatedMultiLineComment,
}
```

We can then add an `expect` helper function for throwing an error if the token does not match:

```rust
/// Expect a `Kind` or return error
pub fn expect(&mut self, kind: Kind) -> Result<()> {
    if self.at(kind) {
        return Err(SyntaxError::UnexpectedToken);
    }
    self.advance(kind);
    Ok(())
}
```

The `parse_debugger_statement` can now use the `expect` function for proper error management:

```rust
fn parse_debugger_statement(&mut self) -> Result<Statement> {
    let node = self.start_node();
    self.expect(Kind::Debugger)?;
    Ok(Statement::DebuggerStatement {
        node: self.finish_node(node),
    })
}
```

Notice the `?` after the `expect`,
it is a syntactic sugar called the ["question mark operator"](https://doc.rust-lang.org/book/ch09-02-recoverable-errors-with-result.html#a-shortcut-for-propagating-errors-the--operator) for making the
function return early if the `expect` function returns a `Err`.

### Fancy Error Report

[`miette`](https://docs.rs/miette/latest/miette) is one of the nicest error reporting crate out there,
it provides a fancy colored output

![miette](https://raw.githubusercontent.com/zkat/miette/main/images/serde_json.png)

Add `miette` to your `Cargo.toml`

```toml
[dependencies]
miette = { version = "5", features = ["fancy"] }
```

We can wrap our `Error` with `miette` and not modify the `Result` type defined in our parser:

```rust
pub fn main() -> Result<()> {
    let source_code = "".to_string();
    let file_path = "test.js".to_string();
    let mut parser = Parser::new(&source_code);
    parser.parse().map_err(|error| {
        miette::Error::new(error).with_source_code(miette::NamedSource::new(file_path, source_code))
    })
}
```

---

---
url: /docs/contribute/debugging.md
---

# Debugging

## OXC\_LOG Environment Variable

The `OXC_LOG` environment variable enables runtime tracing in `oxlint` and `oxfmt`. When not set, logging is completely disabled for zero-cost operation.

### Basic Usage

```bash
# Enable debug logging for oxlint
OXC_LOG=debug oxlint

# Enable debug logging for oxfmt
OXC_LOG=debug oxfmt

# Enable resolver tracing when using import plugin
OXC_LOG=oxc_resolver oxlint --import-plugin

# Enable formatter tracing
OXC_LOG=oxc_formatter oxfmt
```

### Filter Syntax

`OXC_LOG` uses [tracing-subscriber](https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html) filter syntax:

| Pattern                      | Description                              |
| ---------------------------- | ---------------------------------------- |
| `debug`                      | Enable debug level for all modules       |
| `trace`                      | Enable trace level for all modules       |
| `oxc_resolver`               | Enable all logs from oxc\_resolver module |
| `oxc_resolver=debug`         | Enable debug level for oxc\_resolver      |
| `oxc_resolver=trace`         | Enable trace level for oxc\_resolver      |
| `oxc_formatter,oxc_resolver` | Enable multiple modules                  |

### Output

Logs are written to **stderr** to avoid interfering with the normal output of linter diagnostics or formatted code on stdout. In `oxfmt`, thread names and span timing information are included for debugging multi-threaded operations.

### Common Use Cases

**List all files being processed:**

```bash
OXC_LOG=debug oxlint
OXC_LOG=debug oxfmt
```

**Debugging module resolution issues:**

```bash
OXC_LOG=oxc_resolver=debug oxlint --import-plugin
```

## rust-lldb

rust-lldb can be used to get panic information from debug builds.

Enable debug symbols:

```toml Cargo.toml
[profile.release]
debug = true
strip = false
panic = "unwind"
```

Build the binary:

```bash
cargo build --release --bin oxlint --features allocator
```

Run the binary:

```bash
rust-lldb -- ./target/release/oxlint
```

Once it launches, press `r` for running the program.

## Debug TypeScript in VSCode

According to their [debugging guide](https://github.com/microsoft/TypeScript/blob/main/CONTRIBUTING.md#debugging-the-tests), in the TypeScript repository:

* rename `.vscode/launch.template.json` to `launch.json`
* add `tests/cases/compiler/foo.ts`
* change `"${fileBasenameNoExtension}"` to `foo.ts`
* set a breakpoint somewhere in TypeScript's source code
* from the menu "Run - Debugging", or press F5
* while debugging, tsc will evaluate global `.d.ts` files before the targeted test file
* `Debug.formatXXX(value)` from `src/compiler/debug.ts` can be used to print out enum values
* use the "WATCH" section to "see" value of interest

## Debug Linter in VSCode

It's easy to debug Linter for a npm project somewhere else with [CodeLLDB](https://marketplace.visualstudio.com/items?itemName=vadimcn.vscode-lldb).

In `.vscode/launch.json`, change config fields to your need:

* `cwd`: absolute path to the npm project
* `args`: arguments passed to linter

```json
{
  "type": "lldb",
  "request": "launch",
  "name": "Debug Oxlint",
  "cargo": {
    "env": {
      "RUSTFLAGS": "-g"
    },
    "args": ["build", "--bin=oxlint", "--package=oxlint"],
    "filter": {
      "name": "oxlint",
      "kind": "bin"
    }
  },
  "cwd": "PATH-TO-TEST-PROJECT", // [!code focus]
  "args": ["--ARGS-TO-OXLINT"] // [!code focus]
}
```

Open VS Code Debugging panel and select `Debug Oxlint`, then start debugging.

The debug process will be launched with specified `cwd`, like running linter in testing project and attaching debugger into it.

---

---
url: /docs/guide/usage/formatter/embedded-formatting.md
---

# Embedded Formatting

Formats code embedded in JS/TS files (CSS in template literals, GraphQL in template literals, JavaScript/TypeScript/CSS/etc in Markdown).

## Configuration

::: code-group

```json [.oxfmtrc.json]
{
  "embeddedLanguageFormatting": "auto"
}
```

```ts [oxfmt.config.ts]
import { defineConfig } from "oxfmt";

export default defineConfig({
  embeddedLanguageFormatting: "auto",
});
```

:::

### Values

* `"auto"` — (default) Format embedded sections
* `"off"` — Skip embedded formatting

## Examples

CSS inside a tagged template literal:

```js
const styles = css`
  .container {
    background: blue;
    color: ${theme.color};
  }
`;
```

Styled-components:

```js
const Button = styled.button`
  background: ${(props) => props.primary};
  color: white;
`;
```

Styled JSX:

```jsx
<style jsx>{`
  .container {
    background: blue;
    color: red;
  }
`}</style>
```

GraphQL inside a tagged template literal:

```js
const query = gql`
  query {
    user {
      id
      name
    }
  }
`;

const query2 = graphql(`
  query {
    user {
      id
      name
    }
  }
  ${fragments.all}
`);
```

HTML inside a tagged template literal:

```js
const template = html`
  <div class="container">
    <h1>Hello</h1>
    <p>${world}</p>
  </div>
`;
```

JavaScript code blocks inside a Markdown file:

````md
This is an example Markdown file with JavaScript code blocks:

```js
const x = 1; // This will be formatted if embedded formatting is enabled.
```

Wow!
````

JavaScript and CSS inside a Vue file:

```vue
<script setup>
import { ref } from "vue";
import MyComponent from "./MyComponent.vue";
</script>

<style>
.container {
  background: blue;
  color: red;
}
</style>
```

---

---
url: /endorsements.md
---

# Endorsements

### [Evan You](https://x.com/youyuxi/status/1734439543280128030), creator of [Vue.js](https://vuejs.org) and [Vite](https://vitejs.dev):

> Ran oxlint on the Vue 3 codebase, ~200 rules + ~590 files finished in 50ms 🤯 (30ms re-runs)
>
> The performance is absolutely nuts

### [Jason Miller](https://github.com/developit), creator of [Preact](https://preactjs.com):

> oxlint has been a massive win for us at Shopify. Our previous linting setup took 75 minutes to run, so we were fanning it out across 40+ workers in CI.
>
> By comparison, oxlint takes around 10 seconds to lint the same codebase on a single worker, and the output is easier to interpret.
>
> We even caught a few bugs that were hidden or skipped by our old setup when we migrated!

### [Luke Edwards](https://x.com/lukeed05/status/1829527267162345651)

> For a while now, @boshen\_c has been crushing it, setting the foundation for the next generation of JS tooling.
>
> There's just so much to learn from the OXC source code. Everything is meticulously measured and benchmarked, then formalized into simple, elegant, non-frightening APIs.
>
> This guy is brilliant, a team player, and is + has been doing thankless, hard work.

### [Yagiz Nizipli](https://github.com/sponsors/anonrig), founder of [Node.js performance team](https://github.com/nodejs/performance):

> I'm impressed by how oxc is actively encouraging JavaScript tools to improve their performance.

### [Eric Simons](https://x.com/ericsimons40/status/1766525300584947999), CEO of [StackBlitz](https://stackblitz.com/):

> Oxc is slept on rn
>
> Most JS/TS toolchains will be using it within the next few yrs imo

### [Miles Johnson](https://x.com/mileswjohnson/status/1734698340791800283), creator of [Moonrepo](https://moonrepo.dev):

> It's crazy how good oxlint (and oxc tools) is. Not just in performance, but ease of use. Banking on Rust was a good choice!

### [Joe Savona](https://x.com/en_JS/status/1676467920334094336), [React](https://react.dev) team member:

> For…reasons I am experimenting w various Rust-based JS compilers. I don’t agree w every design decision but overall oxc is really well done.

### [Sathya Gunasekaran](https://x.com/_gsathya/status/1676453430263701506), [React](https://react.dev) team member:

> oxc is kinda neat

---

---
url: /docs/guide/usage/linter/rules/eslint/accessor-pairs.md
---

### What it does

Enforces getter/setter pairs in objects and classes.

### Why is this bad?

It's a common mistake in JavaScript to create an object with just a setter
for a property but never have a corresponding getter defined for it.
Without a getter, you cannot read the property, so it ends up not being used.

### Examples

Examples of **incorrect** code for this rule:

```js
var o = {
  set a(value) {
    this.val = value;
  },
};

class C {
  set a(value) {
    this.val = value;
  }
}
```

Examples of **correct** code for this rule:

```js
var o = {
  set a(value) {
    this.val = value;
  },
  get a() {
    return this.val;
  },
};

class C {
  set a(value) {
    this.val = value;
  }
  get a() {
    return this.val;
  }
}
```

## Configuration

This rule accepts a configuration object with the following properties:

### enforceForClassMembers

type: `boolean`

default: `true`

Enforce the rule for class members.

### enforceForTSTypes

type: `boolean`

default: `false`

Enforce the rule for TypeScript interfaces and types.

### getWithoutSet

type: `boolean`

default: `false`

Report a getter without a setter.

### setWithoutGet

type: `boolean`

default: `true`

Report a setter without a getter.

## How to use

## Version

This rule was added in v1.33.0.

## References

---

---
url: /docs/guide/usage/linter/rules/eslint/array-callback-return.md
---

### What it does

Enforce return statements in callbacks of array methods.

### Why is this bad?

Array has several methods for filtering, mapping, and folding.
If we forget to write return statement in a callback of those, it’s probably a mistake.
If you don’t want to use a return or don’t need the returned results,
consider using .forEach instead.

### Examples

Examples of **incorrect** code for this rule:

```javascript
let foo = [1, 2, 3, 4];
foo.map((a) => {
  console.log(a);
});
```

Examples of **correct** code for this rule:

```javascript
let foo = [1, 2, 3, 4];
foo.map((a) => {
  console.log(a);
  return a;
});
```

## Configuration

This rule accepts a configuration object with the following properties:

### allowImplicit

type: `boolean`

default: `false`

When set to true, allows callbacks of methods that require a return value to
implicitly return undefined with a return statement containing no expression.

### allowVoid

type: `boolean`

default: `false`

When set to true, rule will not report the return value with a void operator.
Works only if `checkForEach` option is set to true.

### checkForEach

type: `boolean`

default: `false`

When set to true, rule will also report forEach callbacks that return a value.

## How to use

## Version

This rule was added in v0.0.3.

## References

---

---
url: /docs/guide/usage/linter/rules/eslint/arrow-body-style.md
---

### What it does

This rule can enforce or disallow the use of braces around arrow function body.
Arrow functions can use either:

* a block body `() => { ... }`
* or a concise body `() => expression` with an implicit return.

### Why is this bad?

Inconsistent use of block vs. concise bodies makes code harder to read.
Concise bodies are limited to a single expression, whose value is implicitly returned.

### Examples

#### `"never"`

Examples of **incorrect** code for this rule with the `never` option:

```js
/* arrow-body-style: ["error", "never"] */

/* ✘ Bad: */
const foo = () => {
  return 0;
};
```

Examples of **correct** code for this rule with the `never` option:

```js
/* arrow-body-style: ["error", "never"] */

/* ✔ Good: */
const foo = () => 0;
const bar = () => ({ foo: 0 });
```

#### `"always"`

Examples of **incorrect** code for this rule with the `always` option:

```js
/* arrow-body-style: ["error", "always"] */

/* ✘ Bad: */
const foo = () => 0;
```

Examples of **correct** code for this rule with the `always` option:

```js
/* arrow-body-style: ["error", "always"] */

/* ✔ Good: */
const foo = () => {
  return 0;
};
```

#### `"as-needed"` (default)

Examples of **incorrect** code for this rule with the `as-needed` option:

```js
/* arrow-body-style: ["error", "as-needed"] */

/* ✘ Bad: */
const foo = () => {
  return 0;
};
```

Examples of **correct** code for this rule with the `as-needed` option:

```js
/* arrow-body-style: ["error", "as-needed"] */

/* ✔ Good: */
const foo1 = () => 0;

const foo2 = (retv, name) => {
  retv[name] = true;
  return retv;
};

const foo3 = () => {
  bar();
};
```

#### `"as-needed"` with `requireReturnForObjectLiteral`

Examples of **incorrect** code for this rule with the `{ "requireReturnForObjectLiteral": true }` option:

```js
/* arrow-body-style: ["error", "as-needed", { "requireReturnForObjectLiteral": true }] */

/* ✘ Bad: */
const foo = () => ({});
const bar = () => ({ bar: 0 });
```

Examples of **correct** code for this rule with the `{ "requireReturnForObjectLiteral": true }` option:

```js
/* arrow-body-style: ["error", "as-needed", { "requireReturnForObjectLiteral": true }] */

/* ✔ Good: */
const foo = () => {};
const bar = () => {
  return { bar: 0 };
};
```

## Configuration

### The 1st option

type: `"as-needed" | "always" | "never"`

#### `"as-needed"`

Enforces no braces where they can be omitted (default).

#### `"always"`

Enforces braces around the function body.

#### `"never"`

Enforces no braces around the function body (constrains arrow functions to the role of returning an expression).

### The 2nd option

This option is an object with the following properties:

#### requireReturnForObjectLiteral

type: `boolean`

default: `false`

Requires braces and an explicit return for object literals. This option only applies when
the first option is `"as-needed"`.

## How to use

## Version

This rule was added in v1.4.0.

## References

---

---
url: /docs/guide/usage/linter/rules/eslint/block-scoped-var.md
---

### What it does

Enforces that variables are both **declared** and **used** within the same block scope.
This rule prevents accidental use of variables outside their intended block, mimicking C-style block scoping in JavaScript.

### Why is this bad?

JavaScript’s `var` declarations are hoisted to the top of their enclosing function, which can cause variables declared in a block (e.g., inside an `if` or `for`) to be accessible outside of it.
This can lead to hard-to-find bugs.
By enforcing block scoping, this rule helps avoid hoisting issues and aligns more closely with how other languages treat block variables.

### Examples

Examples of **incorrect** code for this rule:

```js
/* block-scoped-var: "error" */

function doIf() {
  if (true) {
    var build = true;
  }
  console.log(build);
}

function doLoop() {
  for (var i = 0; i < 10; i++) {
    // do something
  }
  console.log(i); // i is accessible here
}

function doSomething() {
  if (true) {
    var foo = 1;
  }
  if (false) {
    foo = 2;
  }
}

function doTry() {
  try {
    var foo = 1;
  } catch (e) {
    console.log(foo);
  }
}
```

Examples of **correct** code for this rule:

```js
/* block-scoped-var: "error" */

function doIf() {
  var build;
  if (true) {
    build = true;
  }
  console.log(build);
}

function doLoop() {
  var i;
  for (i = 0; i < 10; i++) {
    // do something
  }
  console.log(i);
}

function doSomething() {
  var foo;
  if (true) {
    foo = 1;
  }
  if (false) {
    foo = 2;
  }
}

function doTry() {
  var foo;
  try {
    foo = 1;
  } catch (e) {
    console.log(foo);
  }
}
```

## How to use

## Version

This rule was added in v0.16.9.

## References

---

---
url: /docs/guide/usage/linter/rules/eslint/capitalized-comments.md
---

### What it does

Enforces or disallows capitalization of the first letter of a comment.

### Why is this bad?

Inconsistent capitalization of comments can make code harder to read.
This rule helps enforce a consistent style across the codebase.

### Examples

Examples of **incorrect** code for this rule with the default `"always"` option:

```js
// lowercase comment
/* lowercase block comment */
```

Examples of **correct** code for this rule with the default `"always"` option:

```js
// Capitalized comment
/* Capitalized block comment */
// 123 - comments starting with non-letters are ignored
```

## Configuration

Configuration for the capitalized-comments rule.

The first element specifies whether comments should `"always"` or `"never"`
begin with a capital letter. The second element is an optional object
containing additional options.

### The 1st option

type: `"always" | "never"`

### The 2nd option

This option is an object with the following properties:

#### ignoreConsecutiveComments

type: `boolean`

If true, consecutive comments will be ignored after the first comment.

#### ignoreInlineComments

type: `boolean`

If true, inline comments (comments in the middle of code) will be ignored.

#### ignorePattern

type: `string`

A regex pattern. Comments that match the pattern will not cause violations.

## How to use

## Version

This rule was added in v1.34.0.

## References

---

---
url: /docs/guide/usage/linter/rules/eslint/class-methods-use-this.md
---

### What it does

Enforce that class methods utilize `this`.

### Why is this bad?

For class methods that do not use `this`, you should consider converting them
to `static` methods. This is not always possible or desirable, but it can
help clarify that the method does not rely on instance state.

If you do convert the method into a `static` function,
instances of the class that call that particular method have to be converted
to a `static` call as well.

### Examples

Examples of **incorrect** code for this rule:

```js
class A {
  foo() {
    console.log("Hello World");
  }
}
```

Examples of **correct** code for this rule:

```js
class A {
  foo() {
    this.bar = "Hello World"; // OK, this is used
  }
}

class B {
  constructor() {
    // OK. constructor is exempt
  }
}

class C {
  static foo() {
    // OK. static methods aren't expected to use this.
  }
}
```

## Configuration

This rule accepts a configuration object with the following properties:

### enforceForClassFields

type: `boolean`

default: `true`

Enforce this rule for class fields that are functions.

### exceptMethods

type: `string[]`

default: `[]`

List of method names to exempt from this rule. Names can include the hash for private methods.
Example: `save`, `#rerender`

### ignoreClassesWithImplements

type: `"all" | "public-fields"`

default: `null`

Whether to ignore classes that implement interfaces.

### ignoreOverrideMethods

type: `boolean`

default: `false`

Whether to ignore methods that are overridden.

## How to use

## Version

This rule was added in v1.16.0.

## References

---

---
url: /docs/guide/usage/linter/rules/eslint/complexity.md
---

### What it does

Enforces a maximum [cyclomatic complexity](https://en.wikipedia.org/wiki/Cyclomatic_complexity) in a program, which is the number
of linearly independent paths in a program.

### Why is this bad?

Having high code complexity reduces code readability. This rule
aims to make the code easier to follow by reducing the number of branches
in the program.

### Examples

Examples of **incorrect** code for this rule with `{ "max": 2 }`

```js
function foo() {
  if (foo1) {
    return x1; // 1st path
  } else if (foo2) {
    return x2; // 2nd path
  } else {
    return x3; // 3rd path
  }
}

function bar() {
  // there are 2 paths - when bar1 is falsy, and when bar1 is truthy, in which bar1 = bar1 && bar2;
  bar1 &&= bar2;
  // there are 2 paths - when bar3 is truthy, and when bar3 is falsy, in which bar3 = 4;
  bar3 ||= 4;
}

// there are 2 paths - when baz1 is defined, and when baz1 is undefined and is assigned 'a'
function baz(baz1 = "a") {
  const { baz2 = "b" } = baz3; // there are 2 additional paths - when baz2 is defined and when baz2 is not
}

function d() {
  d1 = d2?.d3?.(); // optional chaining creates 2 paths each - when object is defined and when it is not
}
```

Examples of **correct** code for this rule with `{ "max": 2 }`

```js
// This example is taken directly from ESLint documentation
function foo() {
  // this function has complexity = 1
  class C {
    x = a + b; // this initializer has complexity = 1
    y = c || d; // this initializer has complexity = 2
    z = e && f; // this initializer has complexity = 2

    static p = g || h; // this initializer has complexity = 2
    static q = i ? j : k; // this initializer has complexity = 2

    static {
      // this static block has complexity = 2
      if (foo) {
        baz = bar;
      }
    }

    static {
      // this static block has complexity = 2
      qux = baz || quux;
    }
  }
}
```

## Configuration

### max

type: `integer`

default: `20`

Maximum amount of cyclomatic complexity

### variant

type: `"classic" | "modified"`

The cyclomatic complexity variant to use

#### `"classic"`

Classic means McCabe cyclomatic complexity

#### `"modified"`

Modified means classic cyclomatic complexity but a switch statement increases
complexity by 1 irrespective of the number of `case` statements

## How to use

## Version

This rule was added in v1.37.0.

## References

---

---
url: /docs/guide/usage/linter/rules/eslint/constructor-super.md
---

### What it does

Requires `super()` calls in constructors of derived classes and disallows `super()` calls
in constructors of non-derived classes.

This rule can be disabled for TypeScript code, as the TypeScript compiler
enforces this check.

### Why is this bad?

In JavaScript, calling `super()` in the constructor of a derived class (a class that extends
another class) is required. Failing to do so will result in a ReferenceError at runtime.
Conversely, calling `super()` in a non-derived class is a syntax error.

### Examples

Examples of **incorrect** code for this rule:

```js
// Missing super() call
class A extends B {
    constructor() { }
}

// super() in non-derived class
class A {
    constructor() {
        super();
    }
}

// super() only in some code paths
class C extends D {
    constructor() {
        if (condition) {
            super();
        }
    }
}
```

Examples of **correct** code for this rule:

```js
// Proper super() call in derived class
class A extends B {
  constructor() {
    super();
  }
}

// No super() in non-derived class
class A {
  constructor() {}
}

// super() in all code paths
class C extends D {
  constructor() {
    if (condition) {
      super();
    } else {
      super();
    }
  }
}
```

## How to use

## Version

This rule was added in v0.0.3.

## References

---

---
url: /docs/guide/usage/linter/rules/eslint/curly.md
---

### What it does

This rule enforces the use of curly braces `{}` for all control statements
(`if`, `else`, `for`, `while`, `do`, `with`).
It ensures that all blocks are enclosed in curly braces to improve code clarity and maintainability.

### Why is this bad?

Omitting curly braces can reduce code readability and increase the likelihood of errors, especially in deeply nested or indented code.
It can also lead to bugs if additional statements are added later without properly enclosing them in braces.
Using curly braces consistently makes the code safer and easier to modify.

### Examples

#### `"all"` (default)

Examples of **incorrect** code for this rule:

```js
/* curly: ["error", "all"] */

if (foo) foo++;
while (bar) bar--;
do foo();
while (bar);
```

Examples of **correct** code for this rule:

```js
/* curly: ["error", "all"] */

if (foo) {
  foo++;
}
while (bar) {
  bar--;
}
do {
  foo();
} while (bar);
```

#### `"multi"`

Examples of **incorrect** code for this rule with the `"multi"` option:

```js
/* curly: ["error", "multi"] */

if (foo) {
  foo();
}

if (foo) bar();
else {
  foo();
}
```

Examples of **correct** code for this rule with the `"multi"` option:

```js
/* curly: ["error", "multi"] */

if (foo) foo();
else bar();
```

#### `"multi-line"`

Examples of **incorrect** code for this rule with the `"multi-line"` option:

```js
/* curly: ["error", "multi-line"] */

if (foo) foo();
else bar();

if (foo) foo(bar, baz);
```

Examples of **correct** code for this rule with the `"multi-line"` option:

```js
/* curly: ["error", "multi-line"] */

if (foo) foo();
else bar();

while (foo) foo();

while (true) {
  doSomething();
  doSomethingElse();
}
```

#### `"multi-or-nest"`

Examples of **incorrect** code for this rule with the `"multi-or-nest"` option:

```js
/* curly: ["error", "multi-or-nest"] */

while (true)
  if (foo) foo();
  else bar();

if (foo) {
  foo++;
}
```

Examples of **correct** code for this rule with the `"multi-or-nest"` option:

```js
/* curly: ["error", "multi-or-nest"] */

if (foo) {
  if (bar) bar();
}

while (foo) {
  while (bar) bar();
}
```

#### `"consistent"`

When enabled, `"consistent"` enforces consistent use of braces within an `if-else` chain.
If one branch of the chain uses braces, then all branches must use braces, even if not strictly required by the first option.

Examples of **incorrect** code with `"multi"` and `"consistent"`:

```js
/* curly: ["error", "multi", "consistent"] */

if (foo) {
  bar();
  baz();
} else qux();

if (foo) bar();
else {
  baz();
  qux();
}
```

Examples of **correct** code with `"multi"` and `"consistent"`:

```js
/* curly: ["error", "multi", "consistent"] */

if (foo) {
  bar();
  baz();
} else {
  qux();
}

if (foo) {
  bar();
} else {
  baz();
  qux();
}
```

Examples of **incorrect** code with `"multi-line"` and `"consistent"`:

```js
/* curly: ["error", "multi-line", "consistent"] */

if (foo) {
  bar();
} else baz();
```

Examples of **correct** code with `"multi-line"` and `"consistent"`:

```js
/* curly: ["error", "multi-line", "consistent"] */

if (foo) {
  bar();
} else {
  baz();
}
```

Examples of **incorrect** code with `"multi-or-nest"` and `"consistent"`:

```js
/* curly: ["error", "multi-or-nest", "consistent"] */

if (foo) {
  if (bar) baz();
} else qux();
```

Examples of **correct** code with `"multi-or-nest"` and `"consistent"`:

```js
/* curly: ["error", "multi-or-nest", "consistent"] */

if (foo) {
  if (bar) baz();
} else {
  qux();
}
```

## Configuration

Configuration for the curly rule, specified as an array of one or two elements.

Examples:

* `["all"]` - Require braces in all cases (default)
* `["multi"]` - Require braces only for multi-statement blocks
* `["multi-line"]` - Require braces for multi-line blocks
* `["multi-or-nest"]` - Require braces for nested or multi-line blocks
* `["multi", "consistent"]` - Multi mode with consistent braces in if-else chains

### The 1st option

type: `"all" | "multi" | "multi-line" | "multi-or-nest"`

The enforcement type for the curly rule.

#### `"all"`

Require braces in all cases (default)

#### `"multi"`

Require braces only when there are multiple statements in the block

#### `"multi-line"`

Require braces when the block spans multiple lines

#### `"multi-or-nest"`

Require braces when the block is nested or spans multiple lines

### The 2nd option

type: `"consistent"`

## How to use

## Version

This rule was added in v0.15.13.

## References

---

---
url: /docs/guide/usage/linter/rules/eslint/default-case.md
---

### What it does

Enforces that all `switch` statements include a `default` case,
unless explicitly marked with a configured comment.

### Why is this bad?

Without a `default` case, it is unclear whether the omission was
intentional or an oversight. Adding a `default` or a special comment
makes the code more explicit and reduces mistakes.

You may optionally include a `// no default` after the last case if there is
no default case. The comment may be in any desired case, such as `// No Default`.

Example configuration:

```json
{
  "default-case": ["error", { "commentPattern": "^skip\\sdefault" }]
}
```

### Examples

Examples of **incorrect** code for this rule:

```js
switch (foo) {
  case 1:
    break;
}
```

Examples of **correct** code for this rule:

```js
switch (a) {
  case 1:
    break;
  default:
    break;
}

switch (a) {
  case 1:
    break;
  // no default
}
```

## Configuration

This rule accepts a configuration object with the following properties:

### commentPattern

type: `string`

A regex pattern used to detect comments that mark the absence
of a `default` case as intentional.

Default value: `no default`.

Examples of **incorrect** code for this rule with the `{ "commentPattern": "^skip\\sdefault" }` option:

```js
switch (a) {
  case 1:
    break;
  // no default
}
```

Examples of **correct** code for this rule with the `{ "commentPattern": "^skip\\sdefault" }` option:

```js
switch (a) {
  case 1:
    break;
  // skip default
}
```

## How to use

## Version

This rule was added in v0.4.0.

## References

---

---
url: /docs/guide/usage/linter/rules/eslint/default-case-last.md
---

### What it does

Requires the `default` clause in `switch` statements to be the last one.

### Why is this bad?

By convention and for readability, the `default` clause should be the last one in a `switch`.
While it is legal to place it before or between `case` clauses, doing so is confusing and may
lead to unexpected "fall-through" behavior.

### Examples

Examples of **incorrect** code for this rule:

```js
/* default-case-last: "error" */

switch (foo) {
  default:
    bar();
    break;
  case "a":
    baz();
    break;
}

switch (foo) {
  case 1:
    bar();
    break;
  default:
    baz();
    break;
  case 2:
    qux();
    break;
}
```

Examples of **correct** code for this rule:

```js
/* default-case-last: "error" */

switch (foo) {
  case 1:
    bar();
    break;
  case 2:
    qux();
    break;
  default:
    baz();
    break;
}

switch (foo) {
  case "x":
    bar();
    break;
  case "y":
  default:
    baz();
    break;
}
```

## How to use

## Version

This rule was added in v0.0.16.

## References

---

---
url: /docs/guide/usage/linter/rules/eslint/default-param-last.md
---

### What it does

Requires default parameters in functions to be the last ones.

### Why is this bad?

Placing default parameters last allows function calls to omit optional trailing arguments,
which improves readability and consistency. This rule applies equally to JavaScript and
TypeScript functions.

### Examples

Examples of **incorrect** code for this rule:

```js
/* default-param-last: "error" */

function f(a = 0, b) {}
function f(a, b = 0, c) {}
function createUser(isAdmin = false, id) {}
createUser(undefined, "tabby");
```

Examples of **correct** code for this rule:

```js
/* default-param-last: "error" */

function f(a, b = 0) {}
function f(a = 0, b = 0) {}
function createUser(id, isAdmin = false) {}
createUser("tabby");
```

Examples of **incorrect** TypeScript code for this rule:

```ts
/* default-param-last: "error" */

function greet(message: string = "Hello", name: string) {}
function combine(a: number = 1, b: number, c: number) {}
function combine(a: number, b: number = 2, c: number) {}
function combine(a: number = 1, b?: number, c: number) {}
```

Examples of **correct** TypeScript code for this rule:

```ts
/* default-param-last: "error" */

function greet(name: string, message: string = "Hello") {}
function combine(a: number, b: number = 2, c: number = 3) {}
function combine(a: number, b?: number, c: number = 3) {}
```

## How to use

## Version

This rule was added in v0.2.15.

## References

---

---
url: /docs/guide/usage/linter/rules/eslint/eqeqeq.md
---

### What it does

Requires the use of the `===` and `!==` operators, disallowing the use of `==` and `!=`.

### Why is this bad?

Using non-strict equality operators leads to unexpected behavior due to type coercion, which can cause hard-to-find bugs.

### Examples

Example JSON configuration:

```json
{
  "eqeqeq": ["error", "always", { "null": "ignore" }]
}
```

#### `"always"` (default)

Examples of **incorrect** code for this rule:

```js
/* eqeqeq: "error" */

if (x == 42) {
}
if ("" == text) {
}
if (obj.getStuff() != undefined) {
}
```

Examples of **correct** code for this rule:

```js
/* eqeqeq: "error" */

if (x === 42) {
}
if ("" === text) {
}
if (obj.getStuff() !== undefined) {
}
```

#### `"smart"`

Examples of **incorrect** code for this rule with the `"smart"` option:

```js
/* eqeqeq: ["error", "smart"] */

if (x == 42) {
}
if ("" == text) {
}
```

Examples of **correct** code for this rule with the `"smart"` option:

```js
/* eqeqeq: ["error", "smart"] */

if (typeof foo == "undefined") {
}
if (foo == null) {
}
if (foo != null) {
}
```

#### `{"null": "ignore"}` (with `"always"` first option)

Examples of **incorrect** code for this rule with the `{ "null": "ignore" }` option:

```js
/* eqeqeq: ["error", "always", { "null": "ignore" }] */
if (x == 42) {
}
if ("" == text) {
}
```

Examples of **correct** code for this rule with the `{ "null": "ignore" }` option:

```js
/* eqeqeq: ["error", "always", { "null": "ignore" }] */
if (foo == null) {
}
if (foo != null) {
}
```

#### `{"null": "always"}` (default - with `"always"` first option)

Examples of **incorrect** code for this rule with the `{ "null": "always" }` option:

```js
/* eqeqeq: ["error", "always", { "null": "always" }] */

if (foo == null) {
}
if (foo != null) {
}
```

Examples of **correct** code for this rule with the `{ "null": "always" }` option:

```js
/* eqeqeq: ["error", "always", { "null": "always" }] */

if (foo === null) {
}
if (foo !== null) {
}
```

#### `{"null": "never"}` (with `"always"` first option)

Examples of **incorrect** code for this rule with the `{ "null": "never" }` option:

```js
/* eqeqeq: ["error", "always", { "null": "never" }] */

if (x == 42) {
}
if ("" == text) {
}
if (foo === null) {
}
if (foo !== null) {
}
```

Examples of **correct** code for this rule with the `{ "null": "never" }` option:

```js
/* eqeqeq: ["error", "always", { "null": "never" }] */

if (x === 42) {
}
if ("" === text) {
}
if (foo == null) {
}
if (foo != null) {
}
```

## Configuration

### The 1st option

type: `"always" | "smart"`

#### `"always"`

Always require triple-equal comparisons, `===`/`!==`.
This is the default.

#### `"smart"`

Allow certain safe comparisons to use `==`/`!=` (`typeof`, literals, nullish).

### The 2nd option

This option is an object with the following properties:

#### null

type: `"always" | "never" | "ignore"`

Configuration for whether to allow/disallow comparisons against `null`,
e.g. `foo == null` or `foo != null`

##### `"always"`

Always require triple-equals when comparing with null, `=== null`/`!== null`.
This is the default.

##### `"never"`

Never require triple-equals when comparing with null, always use `== null`/`!= null`.

##### `"ignore"`

Ignore null comparisons, allow either `== null`/`!= null` or `=== null`/`!== null`.

## How to use

## Version

This rule was added in v0.0.3.

## References

---

---
url: /docs/guide/usage/linter/rules/eslint/for-direction.md
---

### What it does

Disallow `for` loops where the update clause moves the counter in the wrong
direction, preventing the loop from reaching its stop condition.

### Why is this bad?

A `for` loop with a stop condition that can never be reached will run
infinitely. While infinite loops can be intentional, they are usually written
as `while` loops. More often, an infinite `for` loop is a bug.

### Examples

Examples of **incorrect** code for this rule:

```js
/* for-direction: "error" */

for (var i = 0; i < 10; i--) {}

for (var i = 10; i >= 0; i++) {}

for (var i = 0; i > 10; i++) {}

for (var i = 0; 10 > i; i--) {}

const n = -2;
for (let i = 0; i < 10; i += n) {}
```

Examples of **correct** code for this rule:

```js
/* for-direction: "error" */

for (var i = 0; i < 10; i++) {}

for (var i = 0; 10 > i; i++) {
  // with counter "i" on the right
}

for (let i = 10; i >= 0; i += this.step) {
  // direction unknown
}

for (let i = MIN; i <= MAX; i -= 0) {
  // not increasing or decreasing
}
```

## How to use

## Version

This rule was added in v0.0.3.

## References

---

---
url: /docs/guide/usage/linter/rules/eslint/func-name-matching.md
---

### What it does

Requires function expression names to match the variable or property
names they are assigned to, or disallows such matches with `"never"`.

### Why is this bad?

Matching names keep stack traces and source code easier to connect.
If a project prefers distinct names, the `"never"` option enforces that
convention consistently.

### Examples

Examples of **incorrect** code for this rule:

```js
/*eslint func-name-matching: "error"*/

let foo = function bar() {};
foo = function bar() {};
const obj = { foo: function bar() {} };
obj.foo = function bar() {};
obj["foo"] = function bar() {};

class C {
  foo = function bar() {};
}

/*eslint func-name-matching: ["error", "never"] */

let foo = function foo() {};
foo = function foo() {};
const obj = { foo: function foo() {} };
obj.foo = function foo() {};
obj["foo"] = function foo() {};

class C {
  foo = function foo() {};
}
```

Examples of **correct** code for this rule:

```js
/*eslint func-name-matching: "error"*/
// equivalent to /*eslint func-name-matching: ["error", "always"]*/

const foo = function foo() {};
const foo1 = function () {};
const foo2 = () => {};
foo = function foo() {};

const obj = { foo: function foo() {} };
obj.foo = function foo() {};
obj["foo"] = function foo() {};

const obj1 = { [foo]: function bar() {} };
const obj3 = { foo: function () {} };

obj["x" + 2] = function bar() {};
const [bar] = [function bar() {}];

class C {
  foo = function foo() {};
  baz = function () {};
}

// private names are ignored
class D {
  #foo = function foo() {};
  #bar = function foo() {};
  baz() {
    this.#foo = function foo() {};
    this.#foo = function bar() {};
  }
}

module.exports = function foo(name) {};

/*eslint func-name-matching: ["error", "never"] */

let foo = function bar() {};
const foo1 = function () {};
const foo2 = () => {};
foo = function bar() {};

const obj = { foo: function bar() {} };
obj.foo = function bar() {};
obj["foo"] = function bar() {};

const obj1 = { foo: function bar() {} };
const obj2 = { [foo]: function foo() {} };
const obj4 = { foo: function () {} };

obj["x" + 2] = function bar() {};
const [bar] = [function bar() {}];

class C {
  foo = function bar() {};
  baz = function () {};
}

// private names are ignored
class D {
  #foo = function foo() {};
  #bar = function foo() {};
  baz() {
    this.#foo = function foo() {};
    this.#foo = function bar() {};
  }
}

module.exports = function foo(name) {};
```

## Configuration

### \[0]

type: `"always" | "never"`

### \[1]

type: `object`

#### \[1].considerPropertyDescriptor

type: `boolean`

default: `false`

If `considerPropertyDescriptor` is set to `true`, the check will take into account the use of `Object.create`, `Object.defineProperty`, `Object.defineProperties`, and `Reflect.defineProperty`.

#### \[1].includeCommonJSModuleExports

type: `boolean`

default: `false`

If `includeCommonJSModuleExports` is set to `true`, `module.exports` and `module["exports"]` will be checked by this rule.

## How to use

## Version

This rule was added in v1.62.0.

## References

---

---
url: /docs/guide/usage/linter/rules/eslint/func-names.md
---

### What it does

Require or disallow named function expressions.

### Why is this bad?

Leaving the name off a function will cause `<anonymous>` to appear in
stack traces of errors thrown in it or any function called within it.
This makes it more difficult to find where an error is thrown.
Providing an explicit name also improves readability and consistency.

Example configuration:

```json
{
  "func-names": ["error", "as-needed", { "generators": "never" }]
}
```

### Examples

Examples of **incorrect** code for this rule:

```js
/* func-names: ["error", "always"] */

Foo.prototype.bar = function () {};
const cat = { meow: function () {} };
(function () {
  /* ... */
})();
export default function () {}
```

Examples of **correct** code for this rule:

```js
/* func-names: ["error", "always"] */

Foo.prototype.bar = function bar() {};
const cat = { meow() {} };
(function bar() {
  /* ... */
})();
export default function foo() {}
```

#### `as-needed`

Examples of **incorrect** code for this rule with the `"as-needed"` option:

```js
/* func-names: ["error", "as-needed"] */

Foo.prototype.bar = function () {};
(function () {
  /* ... */
})();
export default function () {}
```

Examples of **correct** code for this rule with the `"as-needed"` option:

```js
/* func-names: ["error", "as-needed"] */

const bar = function () {};
const cat = { meow: function () {} };
class C {
  #bar = function () {};
  baz = function () {};
}
quux ??= function () {};
(function bar() {
  /* ... */
})();
export default function foo() {}
```

#### `never`

Examples of **incorrect** code for this rule with the `"never"` option:

```js
/* func-names: ["error", "never"] */

Foo.prototype.bar = function bar() {};
(function bar() {
  /* ... */
})();
```

Examples of **correct** code for this rule with the `"never"` option:

```js
/* func-names: ["error", "never"] */

Foo.prototype.bar = function () {};
(function () {
  /* ... */
})();
```

#### `generators`

Examples of **incorrect** code for this rule with the `"always", { "generators": "as-needed" }` options:

```js
/* func-names: ["error", "always", { "generators": "as-needed" }] */

(function* () {
  /* ... */
})();
```

Examples of **correct** code for this rule with the `"always", { "generators": "as-needed" }` options:

```js
/* func-names: ["error", "always", { "generators": "as-needed" }] */

const foo = function* () {};
```

Examples of **incorrect** code for this rule with the `"always", { "generators": "never" }` options:

```js
/* func-names: ["error", "always", { "generators": "never" }] */

const foo = bar(function* baz() {});
```

Examples of **correct** code for this rule with the `"always", { "generators": "never" }` options:

```js
/* func-names: ["error", "always", { "generators": "never" }] */

const foo = bar(function* () {});
```

Examples of **incorrect** code for this rule with the `"as-needed", { "generators": "never" }` options:

```js
/* func-names: ["error", "as-needed", { "generators": "never" }] */

const foo = bar(function* baz() {});
```

Examples of **correct** code for this rule with the `"as-needed", { "generators": "never" }` options:

```js
/* func-names: ["error", "as-needed", { "generators": "never" }] */

const foo = bar(function* () {});
```

Examples of **incorrect** code for this rule with the `"never", { "generators": "always" }` options:

```js
/* func-names: ["error", "never", { "generators": "always" }] */

const foo = bar(function* () {});
```

Examples of **correct** code for this rule with the `"never", { "generators": "always" }` options:

```js
/* func-names: ["error", "never", { "generators": "always" }] */

const foo = bar(function* baz() {});
```

## Configuration

### The 1st option

type: `"always" | "as-needed" | "never"`

#### `"always"`

Requires all function expressions to have a name.

#### `"as-needed"`

Requires a name only if one is not automatically inferred.

#### `"never"`

Disallows names for function expressions.

### The 2nd option

This option is an object with the following properties:

#### generators

type: `"always" | "as-needed" | "never"`

Configuration for generator function expressions. If not specified, uses the
primary configuration.

Accepts `always`, `as-needed`, or `never`.

Generator functions are those defined using the `function*` syntax.

```js
function* foobar(i) {
  yield i;
  yield i + 10;
}
```

## How to use

## Version

This rule was added in v0.7.0.

## References

---

---
url: /docs/guide/usage/linter/rules/eslint/func-style.md
---

### What it does

Enforce the consistent use of either function declarations or expressions assigned to variables.

### Why is this bad?

This rule enforces a particular type of function style, either function declarations or expressions assigned to variables.
You can specify which you prefer in the configuration.

### Examples

```js
// function declaration
function doSomething() {
  // ...
}

// arrow function expression assigned to a variable
const doSomethingElse = () => {
  // ...
};

// function expression assigned to a variable
const doSomethingAgain = function () {
  // ...
};
```

Examples of **incorrect** code for this rule with the default `"expression"` option:

```js
/* func-style: ["error", "expression"] */

function foo() {
  // ...
}
```

Examples of **incorrect** code for this rule with the `"declaration"` option:

```js
/* func-style: ["error", "declaration"] */
var foo = function () {
  // ...
};

var foo = () => {};
```

Examples of **incorrect** code for this rule with the `"declaration"` and `{"overrides": { "namedExports": "expression" }}` option:

```js
/* func-style: ["error", "declaration", { "overrides": { "namedExports": "expression" } }] */
export function foo() {
  // ...
}
```

Examples of **incorrect** code for this rule with the `"expression"` and `{"overrides": { "namedExports": "declaration" }}` option:

```js
/* func-style: ["error", "expression", { "overrides": { "namedExports": "declaration" } }] */
export var foo = function () {
  // ...
};

export var bar = () => {};
```

Examples of **correct** code for this rule with the default `"expression"` option:

```js
/* func-style: ["error", "expression"] */
var foo = function () {
  // ...
};
```

Examples of **correct** code for this rule with the `"declaration"` option:

```js
/* func-style: ["error", "declaration"] */
function foo() {
  // ...
}
// Methods (functions assigned to objects) are not checked by this rule
SomeObject.foo = function () {
  // ...
};
```

Examples of additional correct code for this rule with the `"declaration"`, `{ "allowArrowFunctions": true }` options:

```js
/* func-style: ["error", "declaration", { "allowArrowFunctions": true }] */
var foo = () => {};
```

Examples of **correct** code for this rule with the `"declaration"` and `{"overrides": { "namedExports": "expression" }}` option:

```js
/* func-style: ["error", "declaration", { "overrides": { "namedExports": "expression" } }] */
export var foo = function () {
  // ...
};
export var bar = () => {};
```

Examples of **correct** code for this rule with the `"expression"` and `{"overrides": { "namedExports": "declaration" }}` option:

```js
/* func-style: ["error", "expression", { "overrides": { "namedExports": "declaration" } }] */
export function foo() {
  // ...
}
```

Examples of **correct** code for this rule with the `{"overrides": { "namedExports": "ignore" }}` option:

```js
/* func-style: ["error", "expression", { "overrides": { "namedExports": "ignore" } }] */
export var foo = function () {
  // ...
};

export var bar = () => {};
export function baz() {
  // ...
}
```

## Configuration

### The 1st option

type: `"expression" | "declaration"`

### The 2nd option

This option is an object with the following properties:

#### allowArrowFunctions

type: `boolean`

default: `false`

When true, arrow functions are allowed regardless of the style setting.

#### allowTypeAnnotation

type: `boolean`

default: `false`

When true, functions with type annotations are allowed regardless of the style setting.

#### overrides

type: `object`

Override the style specifically for named exports. Can be "expression", "declaration", or "ignore" (default).

##### overrides.namedExports

type: `"ignore" | "expression" | "declaration"`

default: `null`

## How to use

## Version

This rule was added in v0.15.11.

## References

---

---
url: /docs/guide/usage/linter/rules/eslint/getter-return.md
---

### What it does

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.

### Examples

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;
  }
}
```

## Configuration

This rule accepts a configuration object with the following properties:

### allowImplicit

type: `boolean`

default: `false`

When set to `true`, allows getters to implicitly return `undefined` with a `return` statement containing no expression.

## How to use

## Version

This rule was added in v0.0.3.

## References

---

---
url: /docs/guide/usage/linter/rules/eslint/grouped-accessor-pairs.md
---

### What it does

Require grouped accessor pairs in object literals and classes.

### Why is this bad?

While it is allowed to define the pair for a getter or a setter anywhere in an object or class definition,
it’s considered a best practice to group accessor functions for the same property.

### Examples

Examples of **incorrect** code for this rule:

```js
const foo = {
  get a() {
    return this.val;
  },
  b: 1,
  set a(value) {
    this.val = value;
  },
};
```

Examples of **correct** code for this rule:

```js
const foo = {
  get a() {
    return this.val;
  },
  set a(value) {
    this.val = value;
  },
  b: 1,
};
```

Examples of **incorrect** code for this rule with the `getBeforeSet` option:

```js
const foo = {
  set a(value) {
    this.val = value;
  },
  get a() {
    return this.val;
  },
};
```

Examples of **correct** code for this rule with the `getBeforeSet` option:

```js
const foo = {
  get a() {
    return this.val;
  },
  set a(value) {
    this.val = value;
  },
};
```

Examples of **incorrect** code for this rule with the `setBeforeGet` option:

```js
const foo = {
  get a() {
    return this.val;
  },
  set a(value) {
    this.val = value;
  },
};
```

Examples of **correct** code for this rule with the `setBeforeGet` option:

```js
const foo = {
  set a(value) {
    this.val = value;
  },
  get a() {
    return this.val;
  },
};
```

## Configuration

### The 1st option

type: `"anyOrder" | "getBeforeSet" | "setBeforeGet"`

#### `"anyOrder"`

Accessors can be in any order. This is the default.

#### `"getBeforeSet"`

Getters must come before setters.

#### `"setBeforeGet"`

Setters must come before getters.

### The 2nd option

This option is an object with the following properties:

#### enforceForTSTypes

type: `boolean`

default: `false`

When `enforceForTSTypes` is enabled, this rule also applies to TypeScript interfaces
and type aliases.

Examples of **incorrect** TypeScript code:

```ts
interface Foo {
  get a(): string;
  someProperty: string;
  set a(value: string);
}

type Bar = {
  get b(): string;
  someProperty: string;
  set b(value: string);
};
```

Examples of **correct** TypeScript code:

```ts
interface Foo {
  get a(): string;
  set a(value: string);
  someProperty: string;
}

type Bar = {
  get b(): string;
  set b(value: string);
  someProperty: string;
};
```

## How to use

## Version

This rule was added in v0.15.12.

## References

---

---
url: /docs/guide/usage/linter/rules/eslint/guard-for-in.md
---

### What it does

Require for-in loops to include an if statement.

### Why is this bad?

Looping over objects with a `for in` loop will include properties that are inherited through
the prototype chain. Using a `for in` loop without filtering the results in the loop can
lead to unexpected items in your for loop which can then lead to unexpected behaviour.

### Examples

Examples of **incorrect** code for this rule:

```javascript
for (key in foo) {
  doSomething(key);
}
```

Examples of **correct** code for this rule:

```javascript
for (key in foo) {
  if (Object.hasOwn(foo, key)) {
    doSomething(key);
  }
}
```

```javascript
for (key in foo) {
  if (Object.prototype.hasOwnProperty.call(foo, key)) {
    doSomething(key);
  }
}
```

```javascript
for (key in foo) {
  if ({}.hasOwnProperty.call(foo, key)) {
    doSomething(key);
  }
}
```

## How to use

## Version

This rule was added in v0.2.14.

## References

---

---
url: /docs/guide/usage/linter/rules/eslint/id-denylist.md
---

### What it does

Disallow specified identifiers

### Why is this bad?

Generic names can lead to hard-to-decipher code. This rule allows you to specify a deny list of disallowed identifier names to avoid this practice.

### Examples

Examples of **incorrect** code for this rule:

```js
/*eslint id-denylist: ["error", "data", "callback"] */

const data = { ...values };
function callback() {
  // ...
}
element.callback = function () {
  // ...
};
const itemSet = {
  data: [...values],
};
class Foo {
  data = [];
}
class Bar {
  #data = [];
}
class Baz {
  callback() {}
}
class Qux {
  #callback() {}
}
```

Examples of **correct** code for this rule:

```js
/*eslint id-denylist: ["error", "data", "callback"] */

const encodingOptions = { ...values };
function processFileResult() {
  // ...
}
element.successHandler = function () {
  // ...
};
const itemSet = {
  entities: [...values],
};
callback(); // all function calls are ignored
foo.callback(); // all function calls are ignored
foo.data; // all property names that are not assignments are ignored
class Foo {
  items = [];
}
class Bar {
  #items = [];
}
class Baz {
  method() {}
}
class Qux {
  #method() {}
}
```

## Configuration

type: `array`

default: `[]`

## How to use

## Version

This rule was added in v1.76.0.

## References

---

---
url: /docs/guide/usage/linter/rules/eslint/id-length.md
---

### What it does

Enforce a minimum and/or maximum identifier length convention by counting the
graphemes for a given identifier.

### Why is this bad?

Very short identifier names like e, x, \_t or very long ones like
hashGeneratorResultOutputContainerObject can make code harder to read and potentially less
maintainable. To prevent this, one may enforce a minimum and/or maximum identifier length.

### Examples

Examples of **incorrect** code for this rule:

```js
/* id-length: "error" */ // default is minimum 2-chars ({ "min": 2 })

const x = 5;
obj.e = document.body;
const foo = function (e) {};
try {
  dangerousStuff();
} catch (e) {
  // ignore as many do
}
const myObj = { a: 1 };
(a) => {
  a * a;
};
class y {}
class Foo {
  x() {}
}
class Bar {
  #x() {}
}
class Baz {
  x = 1;
}
class Qux {
  #x = 1;
}
function bar(...x) {}
function baz([x]) {}
const [z] = arr;
const {
  prop: [i],
} = {};
function qux({ x }) {}
const { j } = {};
const { prop: a } = {};
({ prop: obj.x } = {});
```

Examples of **correct** code for this rule:

```js
/* id-length: "error" */ // default is minimum 2-chars ({ "min": 2 })

const num = 5;
function _f() {
  return 42;
}
function _func() {
  return 42;
}
obj.el = document.body;
const foo = function (evt) {
  /* do stuff */
};
try {
  dangerousStuff();
} catch (error) {
  // ignore as many do
}
const myObj = { apple: 1 };
(num) => {
  num * num;
};
function bar(num = 0) {}
class MyClass {}
class Foo {
  method() {}
}
class Bar {
  #method() {}
}
class Baz {
  field = 1;
}
class Qux {
  #field = 1;
}
function baz(...args) {}
function qux([longName]) {}
const { prop } = {};
const {
  prop: [name],
} = {};
const [longName] = arr;
function foobar({ prop }) {}
function foobaz({ a: prop }) {}
const { a: property } = {};
({ prop: obj.longName } = {});
const data = { x: 1 }; // excused because of quotes
data["y"] = 3; // excused because of calculated property access
```

## Configuration

This rule accepts a configuration object with the following properties:

### checkGeneric

type: `boolean`

default: `true`

Whether to check TypeScript generic type parameter names.
Defaults to `true`.

### exceptionPatterns

type: `string[]`

An array of regex patterns for identifiers to exclude from the rule.
For example, `["^x.*"]` would exclude all identifiers starting with "x".

### exceptions

type: `string[]`

default: `[]`

An array of identifier names that are excluded from the rule.
For example, `["x", "y", "z"]` would allow single-letter identifiers "x", "y", and "z".

### max

type: `integer`

default: `Infinity`

The maximum number of graphemes allowed in an identifier.
Defaults to no maximum (effectively unlimited).

### min

type: `integer`

default: `2`

The minimum number of graphemes required in an identifier.

### properties

type: `"always" | "never"`

default: `"always"`

Whether to check property names for length.

## How to use

## Version

This rule was added in v1.4.0.

## References

---

---
url: /docs/guide/usage/linter/rules/eslint/id-match.md
---

### What it does

Enforces a naming convention for identifiers by requiring each checked
name to match a configured regular expression.

### Why is this bad?

Inconsistent identifier names make code harder to read and maintain.

This rule is most commonly used to enforce a project-wide convention
such as `camelCase`, `snake_case`, or names without underscores.

The configured pattern is compiled with Rust regex syntax. Most common
naming patterns work the same way as JavaScript regular expressions, but
JavaScript-specific features such as lookaround assertions and
backreferences are not supported. Unicode escapes also use Rust syntax,
so `\uXXXX` should be written as `\u{XXXX}`.

### Known differences from ESLint

* Computed destructuring keys are checked in both binding and assignment
  patterns, for example `const { [bad_name]: x } = obj` and
  `({ [bad_name]: x } = obj)`. This still applies when
  `ignoreDestructuring` is enabled because the computed key is a normal
  reference expression, not a binding introduced by destructuring.
* With `properties` enabled, ordinary top-level keys in dynamic import
  options are checked, for example `import("x", { bad_option: true })`.
  Import attributes inside `with { ... }` are still ignored.

These cases are intentionally stricter than ESLint because they still
contain user-controlled identifier names that participate in normal code.

TypeScript syntax is supported on a best-effort basis for identifiers
that flow through the same visited AST node kinds and transparent
wrappers. This rule intentionally does not try to cover the full
TypeScript naming surface.

### Examples

Examples of **incorrect** code for this rule:

```js
/* id-match: ["error", "^[^_]+$"] */
var first_name = "John";

/* id-match: ["error", "^[^_]+$", { "properties": true }] */
obj.first_name = "John";
```

Examples of **correct** code for this rule:

```js
/* id-match: ["error", "^[^_]+$"] */
var firstName = "John";

/* id-match: ["error", "^[^_]+$", { "ignoreDestructuring": true }] */
const { first_name } = user;
```

## Configuration

### The 1st option

type: `string`

### The 2nd option

This option is an object with the following properties:

#### classFields

type: `boolean`

default: `false`

Whether class field names are checked, including public fields,
accessor properties, and private field names.

#### ignoreDestructuring

type: `boolean`

default: `false`

Whether to ignore shorthand and aliased bindings introduced by object
destructuring, such as `foo` in `const { foo } = obj` and `alias` in
`const { foo: alias } = obj`. This does not suppress computed key
references such as `const { [key]: value } = obj`.

#### onlyDeclarations

type: `boolean`

default: `false`

Whether to check only variable and function declaration names.
References, member names, labels, class names, TypeScript declarations,
and function or arrow parameters are skipped.

#### properties

type: `boolean`

default: `false`

Whether object literal property names, class method names, and assigned
member names such as `obj.prop = value` are checked.

## How to use

## Version

This rule was added in v1.66.0.

## References

---

---
url: /docs/guide/usage/linter/rules/eslint/init-declarations.md
---

### What it does

Require or disallow initialization in variable declarations.

### Why is this bad?

In JavaScript, variables can be assigned during declaration, or at any point afterwards using an assignment statement.
For example, in the following code, `foo` is initialized during declaration, while `bar` is initialized later.

```js
var foo = 1;
var bar;
if (foo) {
  bar = 1;
} else {
  bar = 2;
}
```

### Examples

Examples of incorrect code for the default `"always"` option:

```js
/* init-declarations: ["error", "always"] */
function foo() {
  var bar;
  let baz;
}
```

Examples of incorrect code for the `"never"` option:

```js
/* init-declarations: ["error", "never"] */
function foo() {
  var bar = 1;
  let baz = 2;
  for (var i = 0; i < 1; i++) {}
}
```

Examples of correct code for the default `"always"` option:

```js
/* init-declarations: ["error", "always"] */

function foo() {
  var bar = 1;
  let baz = 2;
  const qux = 3;
}
```

Examples of correct code for the `"never"` option:

```js
/* init-declarations: ["error", "never"] */

function foo() {
  var bar;
  let baz;
  const buzz = 1;
}
```

Examples of correct code for the `"never", { "ignoreForLoopInit": true }` options:

```js
/* init-declarations: ["error", "never", { "ignoreForLoopInit": true }] */
for (var i = 0; i < 1; i++) {}
```

## Configuration

### The 1st option

type: `"always" | "never"`

### The 2nd option

This option is an object with the following properties:

#### ignoreForLoopInit

type: `boolean`

default: `false`

When set to `true`, allows uninitialized variables in the init expression of `for`, `for-in`, and `for-of` loops.
Only applies when mode is set to `"never"`.

## How to use

## Version

This rule was added in v0.15.11.

## References

---

---
url: /docs/guide/usage/linter/rules/eslint/logical-assignment-operators.md
---

### What it does

This rule requires or disallows logical assignment operator shorthand.

### Why is this bad?

ES2021 introduces the assignment operator shorthand for the logical operators `||`, `&&` and `??`.
Before, this was only allowed for mathematical operations such as `+` or `*` (see the rule `operator-assignment`).
The shorthand can be used if the assignment target and the left expression of a logical expression are the same.
For example `a = a || b` can be shortened to `a ||= b`.

### Examples

Examples of **incorrect** code for this rule with the default `always` option:

```js
a = a || b;
a = a && b;
a = a ?? b;
a || (a = b);
a && (a = b);
a ?? (a = b);
a = a || b || c;
a = a && b && c;
a = a ?? b ?? c;
```

Examples of **correct** code for this rule with the default `always` option:

```js
a = b;
a += b;
a ||= b;
a = b || c;
a || (b = c);
if (a) a = b;
a = a || b || c;
```

Examples of **incorrect** code for this rule with the `never` option:

```js
a ||= b;
a &&= b;
a ??= b;
```

Examples of **correct** code for this rule with the `never` option:

```js
a = a || b;
a = a && b;
a = a ?? b;
```

## Configuration

### The 1st option

type: `"always" | "never"`

### The 2nd option

This option is an object with the following properties:

#### enforceForIfStatements

type: `boolean`

default: `false`

This option checks for additional patterns with if statements which could be expressed with the logical assignment operator.
Only available if string option is set to `always`.

Examples of **incorrect** code for this rule with the `["always", { enforceForIfStatements: true }]` option:

```js
if (a) a = b; // <=> a &&= b
if (!a) a = b; // <=> a ||= b

if (a == null) a = b; // <=> a ??= b
if (a === null || a === undefined) a = b; // <=> a ??= b
```

Examples of **correct** code for this rule with the `["always", { enforceForIfStatements: true }]` option:

```js
if (a) b = c;
if (a === 0) a = b;
```

## How to use

## Version

This rule was added in v1.63.0.

## References

---

---
url: /docs/guide/usage/linter/rules/eslint/max-classes-per-file.md
---

### What it does

Enforce a maximum number of classes per file.

### Why is this bad?

Files containing multiple classes can often result in a less navigable and poorly
structured codebase. Best practice is to keep each file limited to a single responsibility.

### Examples

Examples of **incorrect** code for this rule:

```javascript
class Foo {}
class Bar {}
```

Examples of **correct** code for this rule:

```js
function foo() {
  var bar = 1;
  let baz = 2;
  const qux = 3;
}
```

## Configuration

### ignoreExpressions

type: `boolean`

default: `false`

Whether to ignore class expressions when counting classes.

### max

type: `integer`

default: `1`

The maximum number of classes allowed per file.

## How to use

## Version

This rule was added in v0.3.4.

## References

---

---
url: /docs/guide/usage/linter/rules/eslint/max-depth.md
---

### What it does

Enforce a maximum depth that blocks can be nested. This rule helps to limit the complexity
of nested blocks, improving readability and maintainability by ensuring that code does not
become too deeply nested.

### Why is this bad?

Many developers consider code difficult to read if blocks are nested beyond a certain depth.
Excessive nesting can make it harder to follow the flow of the code, increasing cognitive load
and making maintenance more error-prone. By enforcing a maximum block depth, this rule encourages
cleaner, more readable code.

### Examples

Examples of **incorrect** code for this rule with the default `{ "max": 3 }` option:

```js
function foo() {
  for (;;) { // Nested 1 deep
    while (true) { // Nested 2 deep
      if (true) { // Nested 3 deep
        if (true) { // Nested 4 deep }
      }
    }
  }
}
```

Examples of **correct** code for this rule with the default `{ "max": 3 }` option:

```js
function foo() {
  for (;;) { // Nested 1 deep
    while (true) { // Nested 2 deep
      if (true) { // Nested 3 deep }
    }
  }
}
```

Note that class static blocks do not count as nested blocks, and that the depth in
them is calculated separately from the enclosing context.

Example:

```js
function foo() {
  if (true) { // Nested 1 deep
    class C {
      static {
        if (true) { // Nested 1 deep
          if (true) { // Nested 2 deep }
        }
      }
    }
  }
}
```

## Configuration

### max

type: `integer`

default: `4`

The `max` enforces a maximum depth that blocks can be nested

## How to use

## Version

This rule was added in v0.15.12.

## References

---

---
url: /docs/guide/usage/linter/rules/eslint/max-lines.md
---

### What it does

Enforce a maximum number of lines per file.

### Why is this bad?

Some people consider large files a code smell. Large files tend to do a
lot of things and can make it hard following what’s going. While there
is not an objective maximum number of lines considered acceptable in a
file, most people would agree it should not be in the thousands.
Recommendations usually range from 100 to 500 lines.

## Configuration

### max

type: `integer`

default: `300`

Maximum number of lines allowed per file.

### skipBlankLines

type: `boolean`

default: `false`

Whether to ignore blank lines when counting.

### skipComments

type: `boolean`

default: `false`

Whether to ignore comments when counting.

## How to use

## Version

This rule was added in v0.2.14.

## References

---

---
url: /docs/guide/usage/linter/rules/eslint/max-lines-per-function.md
---

### What it does

Enforce a maximum number of lines of code in a function. This rule ensures
that functions do not exceed a specified line count, promoting smaller,
more focused functions that are easier to maintain and understand.

### Why is this bad?

Some people consider large functions a code smell. Large functions tend to
do a lot of things and can make it hard to follow what’s going on. Many coding
style guides dictate a limit to the number of lines that a function can
comprise of. This rule can help enforce that style.

### Examples

Examples of **incorrect** code for this rule with a particular max value:

```js
/* { "eslint/max-lines-per-function": ["error", 2] } */
function foo() {
  const x = 0;
}

/* { "eslint/max-lines-per-function": ["error", 4] } */
function foo() {
  // a comment followed by a blank line

  const x = 0;
}
```

Examples of **correct** code for this rule with a particular max value:

```js
/* { "eslint/max-lines-per-function": ["error", 3] } */
function foo() {
  const x = 0;
}

/* { "eslint/max-lines-per-function": ["error", 5] } */
function foo() {
  // a comment followed by a blank line

  const x = 0;
}
```

## Configuration

### IIFEs

type: `boolean`

default: `false`

The `IIFEs` option controls whether IIFEs are included in the line count.
By default, IIFEs are not considered, but when set to `true`, they will
be included in the line count for the function.

### max

type: `integer`

default: `50`

Maximum number of lines allowed in a function.

### skipBlankLines

type: `boolean`

default: `false`

Skip lines made up purely of whitespace.

### skipComments

type: `boolean`

default: `false`

Skip lines containing just comments.

## How to use

## Version

This rule was added in v0.15.12.

## References

---

---
url: /docs/guide/usage/linter/rules/eslint/max-nested-callbacks.md
---

### What it does

Enforce a maximum depth that callbacks can be nested. This rule helps to limit
the complexity of callback nesting, ensuring that callbacks do not become too
deeply nested, improving code readability and maintainability.

### Why is this bad?

Many JavaScript libraries use the callback pattern to manage asynchronous
operations. A program of any complexity will most likely need to manage several
asynchronous operations at various levels of concurrency. A common pitfall is
nesting callbacks excessively, making code harder to read and understand.

### Examples

Examples of **incorrect** code for this rule with the `{ "max": 3 }` option:

```js
foo1(function () {
  foo2(function () {
    foo3(function () {
      foo4(function () {
        // ...
      });
    });
  });
});
```

Examples of **correct** code for this rule with the `{ "max": 3 }` option:

```js
foo1(handleFoo1);

function handleFoo1() {
  foo2(handleFoo2);
}

function handleFoo2() {
  foo3(handleFoo3);
}

function handleFoo3() {
  foo4(handleFoo4);
}

function handleFoo4() {
  foo5();
}
```

## Configuration

### max

type: `integer`

default: `10`

The `max` enforces a maximum depth that callbacks can be nested.

## How to use

## Version

This rule was added in v0.15.12.

## References

---

---
url: /docs/guide/usage/linter/rules/eslint/max-params.md
---

### What it does

Enforce a maximum number of parameters in function definitions which by
default is three.

### Why is this bad?

Functions that take numerous parameters can be difficult to read and
write because it requires the memorization of what each parameter is,
its type, and the order they should appear in. As a result, many coders
adhere to a convention that caps the number of parameters a function
can take.

### Examples

Examples of **incorrect** code for this rule:

```javascript
function foo(bar, baz, qux, qxx) {
  doSomething();
}
```

```javascript
let foo = (bar, baz, qux, qxx) => {
  doSomething();
};
```

Examples of **correct** code for this rule:

```javascript
function foo(bar, baz, qux) {
  doSomething();
}
```

```javascript
let foo = (bar, baz, qux) => {
  doSomething();
};
```

## Configuration

### countThis

type: `"always" | "never" | "except-void"`

This option controls when to count a `this` parameter.

* "always": always count `this`
* "never": never count `this`
* "except-void": count `this` only when it is not type `void`

### countVoidThis

type: `boolean`

default: `false`

Deprecated alias for `countThis`.

For example `{ "countVoidThis": true }` would mean that having a function
take a `this` parameter of type `void` is counted towards the maximum number of parameters.

### max

type: `integer`

default: `3`

Maximum number of parameters allowed in function definitions.

## How to use

## Version

This rule was added in v0.2.14.

## References

---

---
url: /docs/guide/usage/linter/rules/eslint/max-statements.md
---

### What it does

Enforce a maximum number of statements in a function. This rule ensures
that functions do not exceed a specified statements count, promoting smaller,
more focused functions that are easier to maintain and understand.

### Why is this bad?

Some people consider large functions a code smell. Large functions tend to
do a lot of things and can make it hard to follow what's going on.
This rule can help avoid large functions.

### Examples

Examples of **incorrect** code for this rule with the default `{ "max": 10 }` option:

```js
function foo() {
  const foo1 = 1;
  const foo2 = 2;
  const foo3 = 3;
  const foo4 = 4;
  const foo5 = 5;
  const foo6 = 6;
  const foo7 = 7;
  const foo8 = 8;
  const foo9 = 9;
  const foo10 = 10;

  const foo11 = 11; // Too many.
}

const bar = () => {
  const foo1 = 1;
  const foo2 = 2;
  const foo3 = 3;
  const foo4 = 4;
  const foo5 = 5;
  const foo6 = 6;
  const foo7 = 7;
  const foo8 = 8;
  const foo9 = 9;
  const foo10 = 10;

  const foo11 = 11; // Too many.
};
```

Examples of **correct** code for this rule with the default `{ "max": 10 }` option:

```js
function foo() {
  const foo1 = 1;
  const foo2 = 2;
  const foo3 = 3;
  const foo4 = 4;
  const foo5 = 5;
  const foo6 = 6;
  const foo7 = 7;
  const foo8 = 8;
  const foo9 = 9;
  return function () {
    // 10

    // The number of statements in the inner function does not count toward the
    // statement maximum.

    let bar;
    let baz;
    return 42;
  };
}

const bar = () => {
  const foo1 = 1;
  const foo2 = 2;
  const foo3 = 3;
  const foo4 = 4;
  const foo5 = 5;
  const foo6 = 6;
  const foo7 = 7;
  const foo8 = 8;
  const foo9 = 9;
  return function () {
    // 10

    // The number of statements in the inner function does not count toward the
    // statement maximum.

    let bar;
    let baz;
    return 42;
  };
};
```

Note that this rule does not apply to class static blocks, and that statements in
class static blocks do not count as statements in the enclosing function.

Examples of **correct** code for this rule with `{ "max": 2 }` option:

```js
function foo() {
  let one;
  let two = class {
    static {
      let three;
      let four;
      let five;
      if (six) {
        let seven;
        let eight;
        let nine;
      }
    }
  };
}
```

Examples of additional **correct** code for this rule with the
`{ "max": 10 }, { "ignoreTopLevelFunctions": true }` options:

```js
function foo() {
  const foo1 = 1;
  const foo2 = 2;
  const foo3 = 3;
  const foo4 = 4;
  const foo5 = 5;
  const foo6 = 6;
  const foo7 = 7;
  const foo8 = 8;
  const foo9 = 9;
  const foo10 = 10;
  const foo11 = 11;
}
```

## Configuration

### ignoreTopLevelFunctions

type: `boolean`

default: `false`

Whether to ignore top-level functions.

### max

type: `integer`

default: `10`

Maximum number of statements allowed per function.

## How to use

## Version

This rule was added in v1.35.0.

## References

---

---
url: /docs/guide/usage/linter/rules/eslint/new-cap.md
---

### What it does

This rule requires constructor names to begin with a capital letter.

### Why is this bad?

The new operator in JavaScript creates a new instance of a particular type of object.
That type of object is represented by a constructor function.
Since constructor functions are just regular functions, the only defining characteristic
is that new is being used as part of the call.
Native JavaScript functions begin with an uppercase letter to distinguish those functions
that are to be used as constructors from functions that are not.
Many style guides recommend following this pattern
to more easily determine which functions are to be used as constructors.

**Warning**:
The option `newIsCapExceptionPattern` and `capIsNewExceptionPattern` are implemented with
the [rust regex syntax](https://docs.rs/regex/latest/regex/). Many JavaScript features
are not supported (Lookahead, Lookbehinds, ...).

### Examples

Examples of **incorrect** code for this rule:

```js
function foo(arg) {
  return Boolean(arg);
}
```

Examples of **incorrect** code for this rule with the default `{ "newIsCap": true }` option:

```js
/* new-cap: ["error", { "newIsCap": true }] */

var friend = new person();
```

Examples of **correct** code for this rule with the default `{ "newIsCap": true }` option:

```js
/* new-cap: ["error", { "newIsCap": true }] */

var friend = new Person();
```

Examples of **correct** code for this rule with the `{ "newIsCap": false }` option:

```js
/* new-cap: ["error", { "newIsCap": false }] */

var friend = new person();
```

Examples of **incorrect** code for this rule with the default `{ "capIsNew": true }` option:

```js
/* new-cap: ["error", { "capIsNew": true }] */

var colleague = Person();
```

Examples of **correct** code for this rule with the default `{ "capIsNew": true }` option:

```js
/* new-cap: ["error", { "capIsNew": true }] */

var colleague = new Person();
```

Examples of **correct** code for this rule with the `{ "capIsNew": false }` option:

```js
/* new-cap: ["error", { "capIsNew": false }] */

var colleague = Person();
```

Examples of additional **correct** code for this rule with the `{ "newIsCapExceptions": ["events"] }` option:

```js
/* new-cap: ["error", { "newIsCapExceptions": ["events"] }] */

var events = require("events");

var emitter = new events();
```

Examples of additional **correct** code for this rule with the `{ "newIsCapExceptionPattern": "^person\\.." }` option:

```js
/* new-cap: ["error", { "newIsCapExceptionPattern": "^person\\.." }] */

var friend = new person.acquaintance();

var bestFriend = new person.friend();
```

Examples of additional **correct** code for this rule with the `{ "newIsCapExceptionPattern": "\\.bar$" }` option:

```js
/* new-cap: ["error", { "newIsCapExceptionPattern": "\\.bar$" }] */

var friend = new person.bar();
```

Examples of additional **correct** code for this rule with the `{ "capIsNewExceptions": ["Person"] }` option:

```js
/* new-cap: ["error", { "capIsNewExceptions": ["Person"] }] */

function foo(arg) {
  return Person(arg);
}
```

Examples of additional **correct** code for this rule with the `{ "capIsNewExceptionPattern": "^person\\.." }` option:

```js
/* new-cap: ["error", { "capIsNewExceptionPattern": "^person\\.." }] */

var friend = person.Acquaintance();
var bestFriend = person.Friend();
```

Examples of additional **correct** code for this rule with the `{ "capIsNewExceptionPattern": "\\.Bar$" }` option:

```js
/* new-cap: ["error", { "capIsNewExceptionPattern": "\\.Bar$" }] */

foo.Bar();
```

Examples of additional **correct** code for this rule with the `{ "capIsNewExceptionPattern": "^Foo" }` option:

```js
/* new-cap: ["error", { "capIsNewExceptionPattern": "^Foo" }] */

var x = Foo(42);

var y = Foobar(42);

var z = Foo.Bar(42);
```

### properties

Examples of **incorrect** code for this rule with the default `{ "properties": true }` option:

```js
/* new-cap: ["error", { "properties": true }] */

var friend = new person.acquaintance();
```

Examples of **correct** code for this rule with the default `{ "properties": true }` option:

```js
/* new-cap: ["error", { "properties": true }] */

var friend = new person.Acquaintance();
```

Examples of **correct** code for this rule with the `{ "properties": false }` option:

```js
/* new-cap: ["error", { "properties": false }] */

var friend = new person.acquaintance();
```

Examples of **incorrect** code for this rule with the default `{ "newIsCap": true }` option:

```js
/* new-cap: ["error", { "newIsCap": true }] */

var friend = new person();
```

Examples of **correct** code for this rule with the default `{ "newIsCap": true }` option:

```js
/* new-cap: ["error", { "newIsCap": true }] */

var friend = new Person();
```

Examples of **correct** code for this rule with the `{ "newIsCap": false }` option:

```js
/* new-cap: ["error", { "newIsCap": false }] */

var friend = new person();
```

Examples of **incorrect** code for this rule with the default `{ "capIsNew": true }` option:

```js
/* new-cap: ["error", { "capIsNew": true }] */

var colleague = Person();
```

Examples of **correct** code for this rule with the default `{ "capIsNew": true }` option:

```js
/* new-cap: ["error", { "capIsNew": true }] */

var colleague = new Person();
```

Examples of **correct** code for this rule with the `{ "capIsNew": false }` option:

```js
/* new-cap: ["error", { "capIsNew": false }] */

var colleague = Person();
```

Examples of additional **correct** code for this rule with the `{ "newIsCapExceptions": ["events"] }` option:

```js
/* new-cap: ["error", { "newIsCapExceptions": ["events"] }] */

var events = require("events");

var emitter = new events();
```

Examples of additional **correct** code for this rule with the `{ "newIsCapExceptionPattern": "^person\\.." }` option:

```js
/* new-cap: ["error", { "newIsCapExceptionPattern": "^person\\.." }] */

var friend = new person.acquaintance();

var bestFriend = new person.friend();
```

Examples of additional **correct** code for this rule with the `{ "newIsCapExceptionPattern": "\\.bar$" }` option:

```js
/* new-cap: ["error", { "newIsCapExceptionPattern": "\\.bar$" }] */

var friend = new person.bar();
```

Examples of additional **correct** code for this rule with the `{ "capIsNewExceptions": ["Person"] }` option:

::: correct

```js
/* new-cap: ["error", { "capIsNewExceptions": ["Person"] }] */

function foo(arg) {
  return Person(arg);
}
```

Examples of additional **correct** code for this rule with the `{ "capIsNewExceptionPattern": "^person\\.." }` option:

```js
/* new-cap: ["error", { "capIsNewExceptionPattern": "^person\\.." }] */

var friend = person.Acquaintance();
var bestFriend = person.Friend();
```

Examples of additional **correct** code for this rule with the `{ "capIsNewExceptionPattern": "\\.Bar$" }` option:

```js
/* new-cap: ["error", { "capIsNewExceptionPattern": "\\.Bar$" }] */

foo.Bar();
```

Examples of additional **correct** code for this rule with the `{ "capIsNewExceptionPattern": "^Foo" }` option:

```js
/* new-cap: ["error", { "capIsNewExceptionPattern": "^Foo" }] */

var x = Foo(42);

var y = Foobar(42);

var z = Foo.Bar(42);
```

Examples of **incorrect** code for this rule with the default `{ "properties": true }` option:

```js
/* new-cap: ["error", { "properties": true }] */

var friend = new person.acquaintance();
```

Examples of **correct** code for this rule with the default `{ "properties": true }` option:

```js
/* new-cap: ["error", { "properties": true }] */

var friend = new person.Acquaintance();
```

Examples of **correct** code for this rule with the `{ "properties": false }` option:

```js
/* new-cap: ["error", { "properties": false }] */

var friend = new person.acquaintance();
```

## Configuration

This rule accepts a configuration object with the following properties:

### capIsNew

type: `boolean`

default: `true`

`true` to require that all functions with names starting with an uppercase letter to be called with `new`.

### capIsNewExceptionPattern

type: `string`

A regex pattern to match exceptions for functions with names starting with an uppercase letter.

### capIsNewExceptions

type: `string[]`

default: `[]`

Exceptions to ignore for functions with names starting with an uppercase letter.

### newIsCap

type: `boolean`

default: `true`

`true` to require that all constructor names start with an uppercase letter, e.g. `new Person()`.

### newIsCapExceptionPattern

type: `string`

A regex pattern to match exceptions for constructor names starting with an uppercase letter.

### newIsCapExceptions

type: `string[]`

default: `["Array", "Boolean", "Date", "Error", "Function", "Number", "Object", "RegExp", "String", "Symbol", "BigInt"]`

Exceptions to ignore for constructor names starting with an uppercase letter.

### properties

type: `boolean`

default: `true`

`true` to require capitalization for object properties (e.g., `new obj.Method()`).

## How to use

## Version

This rule was added in v0.15.5.

## References

---

---
url: /docs/guide/usage/linter/rules/eslint/no-alert.md
---

### What it does

Disallow the use of `alert`, `confirm`, and `prompt`.

### Why is this bad?

JavaScript’s `alert`, `confirm`, and `prompt` functions are widely considered to be obtrusive as UI elements and should be replaced by a more appropriate custom UI implementation.
Furthermore, `alert` is often used while debugging code, which should be removed before deployment to production.

### Examples

Examples of **incorrect** code for this rule:

```js
alert("here!");

confirm("Are you sure?");

prompt("What's your name?", "John Doe");
```

Examples of **correct** code for this rule:

```js
customAlert("Something happened!");

customConfirm("Are you sure?");

customPrompt("Who are you?");

function foo() {
  var alert = myCustomLib.customAlert;
  alert();
}
```

## How to use

## Version

This rule was added in v0.9.3.

## References

---

---
url: /docs/guide/usage/linter/rules/eslint/no-array-constructor.md
---

### What it does

Disallows creating arrays with the `Array` constructor.

### Why is this bad?

Use of the `Array` constructor to construct a new array is generally
discouraged in favor of array literal notation because of the
single-argument pitfall and because the `Array` global may be redefined.
The exception is when the `Array` constructor is used to intentionally
create sparse arrays of a specified size by giving the constructor a
single numeric argument.

### Examples

Examples of **incorrect** code for this rule:

```javascript
let arr = new Array();
```

Examples of **correct** code for this rule:

```javascript
let arr = [];
let arr2 = Array.from(iterable);
let arr3 = new Array(9);
```

## How to use

## Version

This rule was added in v0.0.3.

## References

---

---
url: /docs/guide/usage/linter/rules/eslint/no-async-promise-executor.md
---

### What it does

Disallow using an async function as a Promise executor.

### Why is this bad?

The `new Promise` constructor accepts an executor function as an argument,
which has `resolve` and `reject` parameters that can be used to control the state of the
created Promise. For example:

```javascript
const result = new Promise(function executor(resolve, reject) {
  readFile("foo.txt", function (err, result) {
    if (err) {
      reject(err);
    } else {
      resolve(result);
    }
  });
});
```

The executor function can also be an `async function`. However, this is usually a mistake, for a few reasons:

* If an async executor function throws an error, the error will be lost and won’t cause
  the newly-constructed `Promise` to reject.This could make it difficult to debug and handle some errors.
* If a `Promise` executor function is using `await`, this is usually a sign that it is not
  actually necessary to use the new `Promise` constructor, or the scope of the new
  `Promise` constructor can be reduced.

### Examples

Examples of **incorrect** code for this rule:

```javascript
const foo = new Promise(async (resolve, reject) => {
  readFile("foo.txt", function (err, result) {
    if (err) {
      reject(err);
    } else {
      resolve(result);
    }
  });
});

const result = new Promise(async (resolve, reject) => {
  resolve(await foo);
});
```

Examples of **correct** code for this rule:

```javascript
const foo = new Promise((resolve, reject) => {
  readFile("foo.txt", function (err, result) {
    if (err) {
      reject(err);
    } else {
      resolve(result);
    }
  });
});

const result = Promise.resolve(foo);
```

## How to use

## Version

This rule was added in v0.0.3.

## References

---

---
url: /docs/guide/usage/linter/rules/eslint/no-await-in-loop.md
---

### What it does

This rule disallows the use of `await` within loop bodies. (for, for-in, for-of, while, do-while).

### Why is this bad?

It potentially indicates that the async operations are not being effectively parallelized.
Instead, they are being run in series, which can lead to poorer performance.

### Examples

Examples of **incorrect** code for this rule:

```javascript
async function bad() {
  for (const user of users) {
    const userRecord = await getUserRecord(user);
  }
}
```

Examples of **correct** code for this rule:

```javascript
async function good() {
  await Promise.all(users.map((user) => getUserRecord(user)));
}
```

## How to use

## Version

This rule was added in v0.3.2.

## References

---

---
url: /docs/guide/usage/linter/rules/eslint/no-bitwise.md
---

### What it does

Disallow bitwise operators.

### Why is this bad?

The use of bitwise operators in JavaScript is very rare and often `&` or `|` is simply a mistyped `&&` or `||`,
which will lead to unexpected behavior.

### Examples

Examples of **incorrect** code for this rule:

```javascript
var x = y | z;
```

```javascript
var x = y ^ z;
```

```javascript
var x = y >> z;
```

Examples of **correct** code for this rule:

```javascript
var x = y || z;
```

```javascript
var x = y && z;
```

```javascript
var x = y > z;
```

## Configuration

This rule accepts a configuration object with the following properties:

### allow

type: `string[]`

default: `[]`

The `allow` option permits the given list of bitwise operators to be used
as exceptions to this rule.

For example `{ "allow": ["~"] }` would allow the use of the bitwise operator
`~` without restriction. Such as in the following:

```javascript
~[1, 2, 3].indexOf(1) === -1;
```

### int32Hint

type: `boolean`

default: `false`

When set to `true` the `int32Hint` option allows the use of bitwise OR in |0
pattern for type casting.

For example with `{ "int32Hint": true }` the following is permitted:

```javascript
const b = a | 0;
```

## How to use

## Version

This rule was added in v0.0.3.

## References

---

---
url: /docs/guide/usage/linter/rules/eslint/no-caller.md
---

### What it does

Disallow the use of `arguments.caller` or `arguments.callee`.

### Why is this bad?

The use of `arguments.caller` and `arguments.callee` make several code
optimizations impossible. They have been deprecated in JavaScript, and
their use is forbidden while in strict mode.

```js
function foo() {
  var callee = arguments.callee;
}
```

This rule is aimed at discouraging the use of deprecated and sub-optimal
code by disallowing the use of `arguments.caller` and `arguments.callee`. As
such, it will warn when `arguments.caller` and `arguments.callee` are used.

See [the MDN docs](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Functions/arguments/callee)
for more information.

### Examples

Examples of **incorrect** code for this rule:

```js
function foo(n) {
  if (n <= 0) {
    return;
  }

  arguments.callee(n - 1);
}

[1, 2, 3, 4, 5].map(function (n) {
  return !(n > 1) ? 1 : arguments.callee(n - 1) * n;
});
```

Examples of **correct** code for this rule:

```js
function foo(n) {
  if (n <= 0) {
    return;
  }

  foo(n - 1);
}

[1, 2, 3, 4, 5].map(function factorial(n) {
  return !(n > 1) ? 1 : factorial(n - 1) * n;
});
```

## How to use

## Version

This rule was added in v0.0.3.

## References

---

---
url: /docs/guide/usage/linter/rules/eslint/no-case-declarations.md
---

### What it does

Disallow lexical declarations in case clauses.

### Why is this bad?

The reason is that the lexical declaration is visible
in the entire switch block but it only gets initialized when it is assigned,
which will only happen if the case where it is defined is reached.

### Examples

Examples of **incorrect** code for this rule:

```javascript
switch (foo) {
  case 1:
    let x = 1;
    break;
  case 2:
    const y = 2;
    break;
  case 3:
    function f() {}
    break;
  default:
    class C {}
}
```

Examples of **correct** code for this rule:

```javascript
switch (foo) {
  case 1: {
    let x = 1;
    break;
  }
  case 2: {
    const y = 2;
    break;
  }
  case 3: {
    function f() {}
    break;
  }
  default: {
    class C {}
  }
}
```

## How to use

## Version

This rule was added in v0.0.4.

## References

---

---
url: /docs/guide/usage/linter/rules/eslint/no-class-assign.md
---

### What it does

Disallow reassigning class variables.

This rule can be disabled for TypeScript code, as the TypeScript compiler
enforces this check.

### Why is this bad?

`ClassDeclaration` creates a variable that can be re-assigned, but the re-assignment is a
mistake in most cases.

### Examples

Examples of **incorrect** code for this rule:

```javascript
class A {}
A = 0;
```

```javascript
A = 0;
class A {}
```

```javascript
class A {
  b() {
    A = 0;
  }
}
```

```javascript
let A = class A {
  b() {
    A = 0;
    // `let A` is shadowed by the class name.
  }
};
```

Examples of **correct** code for this rule:

```javascript
let A = class A {};
A = 0; // A is a variable.
```

```javascript
let A = class {
  b() {
    A = 0; // A is a variable.
  }
};
```

```javascript
class A {
  b(A) {
    A = 0; // A is a parameter.
  }
}
```

## How to use

## Version

This rule was added in v0.0.3.

## References

---

---
url: /docs/guide/usage/linter/rules/eslint/no-compare-neg-zero.md
---

### What it does

Disallow comparing against `-0`

### Why is this bad?

The rule should warn against code that tries to compare against `-0`,
since that will not work as intended. That is, code like `x === -0` will
pass for both `+0` and `-0`. The author probably intended `Object.is(x, -0)`.

### Examples

Examples of **incorrect** code for this rule:

```javascript
if (x === -0) {
  // doSomething()...
}
```

```javascript
if (-0 > x) {
  // doSomething()...
}
```

Examples of **correct** code for this rule:

```javascript
if (x === 0) {
  // doSomething()...
}
```

```javascript
if (Object.is(x, -0)) {
  // doSomething()...
}
```

```javascript
if (0 > x) {
  // doSomething()...
}
```

## How to use

## Version

This rule was added in v0.0.3.

## References

---

---
url: /docs/guide/usage/linter/rules/eslint/no-cond-assign.md
---

### What it does

Disallow assignment operators in conditional expressions.

### Why is this bad?

In conditional statements, it is very easy to mistype a comparison
operator (such as `==`) as an assignment operator (such as `=`).

There are valid reasons to use assignment operators in conditional
statements. However, it can be difficult to tell whether a specific
assignment was intentional.

### Examples

Examples of **incorrect** code for this rule:

```js
// Check the user's job title
if ((user.jobTitle = "manager")) {
  // user.jobTitle is now incorrect
}
```

Examples of **correct** code for this rule:

```js
// Check the user's job title
if (user.jobTitle === "manager") {
  // correctly compared `jobTitle`
}
```

## Configuration

This rule accepts one of the following string values:

### `"except-parens"`

Allow assignments in conditional expressions only if they are
enclosed in parentheses.

### `"always"`

Disallow all assignments in conditional expressions.

## How to use

## Version

This rule was added in v0.0.5.

## References

---

---
url: /docs/guide/usage/linter/rules/eslint/no-console.md
---

### What it does

Disallow the use of console.

### Why is this bad?

In JavaScript that is designed to be executed in the browser, it’s considered a best
practice to avoid using methods on console. Such messages are considered to be for
debugging purposes and therefore not suitable to ship to the client. In general, calls
using console should be stripped before being pushed to production.

### Examples

Examples of **incorrect** code for this rule:

```javascript
console.log("Log a debug level message.");
console.warn("Log a warn level message.");
console.error("Log an error level message.");
console.log = foo();
```

Examples of **correct** code for this rule:

```javascript
// custom console
Console.log("Hello world!");
```

## Configuration

This rule accepts a configuration object with the following properties:

### allow

type: `string[]`

default: `[]`

The `allow` option permits the given list of console methods to be used as exceptions to
this rule.

Say the option was configured as `{ "allow": ["info"] }` then the rule would behave as
follows:

Example of **incorrect** code for this option:

```javascript
console.log("foo");
```

Example of **correct** code for this option:

```javascript
console.info("foo");
```

## How to use

## Version

This rule was added in v0.0.13.

## References

---

---
url: /docs/guide/usage/linter/rules/eslint/no-const-assign.md
---

### What it does

Disallow reassigning `const` variables.

### Why is this bad?

We cannot modify variables that are declared using the `const` keyword,
as it will raise a runtime error.

Note that this rule is not necessary for TypeScript
code, as TypeScript will already catch this as an error.

### Examples

Examples of **incorrect** code for this rule:

```js
const a = 0;
a = 1;

const b = 0;
b += 1;
```

Examples of **correct** code for this rule:

```js
const a = 0;
console.log(a);

var b = 0;
b += 1;
```

## How to use

## Version

This rule was added in v0.0.3.

## References

---

---
url: /docs/guide/usage/linter/rules/eslint/no-constant-binary-expression.md
---

### What it does

Disallow expressions where the operation doesn't affect the value.

### Why is this bad?

Comparisons which will always evaluate to true or false and logical expressions (`||`, `&&`, `??`) which either always
short-circuit or never short-circuit are both likely indications of programmer error.
By default, this rule also reports relational comparisons
(`<`, `<=`, `>`, `>=`) where both sides are literal values.

These errors are especially common in complex expressions where operator precedence is easy to misjudge.

Additionally, this rule detects comparisons to newly constructed objects/arrays/functions/etc.
In JavaScript, where objects are compared by reference, a newly constructed object can never `===` any other value.
This can be surprising for programmers coming from languages where objects are compared by value.

### Examples

Examples of **incorrect** code for this rule:

```javascript
// One might think this would evaluate as `a + (b ?? c)`:
const x = a + b ?? c;

// But it actually evaluates as `(a + b) ?? c`. Since `a + b` can never be null,
// the `?? c` has no effect.

// Programmers coming from a language where objects are compared by value might expect this to work:
const isEmpty = x === [];

// However, this will always result in `isEmpty` being `false`.
```

Examples of **correct** code for this rule:

```javascript
const x = a + (b ?? c);

const isEmpty = x.length === 0;
```

## Configuration

This rule accepts a configuration object with the following properties:

### checkRelationalComparisons

type: `boolean`

default: `true`

## How to use

## Version

This rule was added in v0.0.3.

## References

---

---
url: /docs/guide/usage/linter/rules/eslint/no-constant-condition.md
---

### What it does

Disallow constant expressions in conditions.

### Why is this bad?

A constant expression (for example, a literal) as a test condition might
be a typo or development trigger for a specific behavior.

This rule disallows constant expressions in the test condition of:

* `if`, `for`, `while`, or `do...while` statement
* `?`: ternary expression

### Examples

Examples of **incorrect** code for this rule:

```js
if (false) {
  doSomethingUnfinished();
}

if (new Boolean(x)) {
  doSomethingAlways();
}
if ((x ||= true)) {
  doSomethingAlways();
}

do {
  doSomethingForever();
} while ((x = -1));
```

Examples of **correct** code for this rule:

```js
if (x === 0) {
  doSomething();
}

while (typeof x === "undefined") {
  doSomething();
}
```

## Configuration

This rule accepts a configuration object with the following properties:

### checkLoops

type: `boolean | "all" | "allExceptWhileTrue" | "none"`

## How to use

## Version

This rule was added in v0.0.3.

## References

---

---
url: /docs/guide/usage/linter/rules/eslint/no-constructor-return.md
---

### What it does

Disallow returning a value from a constructor.

### Why is this bad?

In JavaScript, returning a value in the constructor of a class may be a mistake.
Forbidding this pattern prevents mistakes resulting from unfamiliarity with the language or a copy-paste error.

### Examples

Examples of **incorrect** code for this rule:

```js
class C {
  constructor() {
    return 42;
  }
}
```

Examples of **correct** code for this rule:

```js
class C {
  constructor() {
    this.value = 42;
  }
}
```

## How to use

## Version

This rule was added in v0.4.3.

## References

---

---
url: /docs/guide/usage/linter/rules/eslint/no-continue.md
---

### What it does

Disallow `continue` statements.

### Why is this bad?

The continue statement terminates execution of the statements in the current iteration of the current or labeled loop, and continues execution of the loop with the next iteration. When used incorrectly it makes code less testable, less readable and less maintainable. Structured control flow statements such as if should be used instead.

### Examples

Examples of **incorrect** code for this rule:

```javascript
var sum = 0,
  i;

for (i = 0; i < 10; i++) {
  if (i >= 5) {
    continue;
  }

  sum += i;
}
```

Examples of **correct** code for this rule:

```javascript
var sum = 0,
  i;
for (i = 0; i < 10; i++) {
  if (i < 5) {
    sum += i;
  }
}
```

## How to use

## Version

This rule was added in v0.2.14.

## References

---

---
url: /docs/guide/usage/linter/rules/eslint/no-control-regex.md
---

### What it does

Disallows control characters and some escape sequences that match
control characters in regular expressions.

### Why is this bad?

Control characters are special, invisible characters in the ASCII range
0-31. These characters are rarely used in JavaScript strings so a
regular expression containing elements that explicitly match these
characters is most likely a mistake.

### Examples

Examples of **incorrect** code for this rule:

```javascript
var pattern1 = /\x00/;
var pattern2 = /\x0C/;
var pattern3 = /\x1F/;
var pattern4 = /\u000C/;
var pattern5 = /\u{C}/u;
var pattern6 = new RegExp("\x0C"); // raw U+000C character in the pattern
var pattern7 = new RegExp("\\x0C"); // \x0C pattern
```

Examples of **correct** code for this rule:

```javascript
var pattern1 = /\x20/;
var pattern2 = /\u0020/;
var pattern3 = /\u{20}/u;
var pattern4 = /\t/;
var pattern5 = /\n/;
var pattern6 = new RegExp("\x20");
var pattern7 = new RegExp("\\t");
var pattern8 = new RegExp("\\n");
var pattern9 = /\0/;
```

## How to use

## Version

This rule was added in v0.0.7.

## References

---

---
url: /docs/guide/usage/linter/rules/eslint/no-debugger.md
---

### What it does

Checks for usage of the `debugger` statement.

### Why is this bad?

`debugger` statements do not affect functionality when a debugger isn't attached.
They're most commonly an accidental debugging leftover.

### Examples

Examples of **incorrect** code for this rule:

```javascript
async function main() {
  const data = await getData();
  const result = complexCalculation(data);
  debugger;
}
```

Examples of **correct** code for this rule:

```javascript
async function main() {
  const data = await getData();
  const result = complexCalculation(data);
}
```

## How to use

## Version

This rule was added in v0.0.3.

## References

---

---
url: /docs/guide/usage/linter/rules/eslint/no-delete-var.md
---

### What it does

The purpose of the `delete` operator is to remove a property from an
object.

### Why is this bad?

Using the `delete` operator on a variable might lead to unexpected
behavior.

### Examples

Examples of **incorrect** code for this rule:

```javascript
var x;
delete x;
```

Examples of **correct** code for this rule:

```javascript
var x;

var y;
delete y.prop;
```

## How to use

## Version

This rule was added in v0.0.4.

## References

---

---
url: /docs/guide/usage/linter/rules/eslint/no-div-regex.md
---

### What it does

Disallow equal signs explicitly at the beginning of regular expressions.

### Why is this bad?

Characters /= at the beginning of a regular expression literal can be confused with a
division assignment operator.

### Examples

Examples of **incorrect** code for this rule:

```javascript
function bar() {
  return /=foo/;
}
```

Examples of **correct** code for this rule:

```javascript
function bar() {
  return /[=]foo/;
}
```

## How to use

## Version

This rule was added in v0.4.2.

## References

---

---
url: /docs/guide/usage/linter/rules/eslint/no-dupe-class-members.md
---

### What it does

Disallow duplicate class members.

This rule can be disabled for TypeScript code, as the TypeScript compiler
enforces this check.

### Why is this bad?

If there are declarations of the same name in class members,
the last declaration overwrites other declarations silently. It can cause unexpected behaviors.

### Examples

Examples of **incorrect** code for this rule:

```javascript
class A {
  foo() {
    console.log("foo");
  }
  foo = 123;
}
let a = new A();
a.foo(); // Uncaught TypeError: a.foo is not a function
```

Examples of **correct** code for this rule:

```javascript
class A {
  foo() {
    console.log("foo");
  }
}
let a = new A();
a.foo();
```

## How to use

## Version

This rule was added in v0.0.3.

## References

---

---
url: /docs/guide/usage/linter/rules/eslint/no-dupe-else-if.md
---

### What it does

Disallow duplicate conditions in if-else-if chains.

### Why is this bad?

if-else-if chains are commonly used when there is a need to execute only one branch (or at most one branch) out of several possible branches, based on certain conditions.
Two identical test conditions in the same chain are almost always a mistake in the code. Unless there are side effects in the expressions,
a duplicate will evaluate to the same true or false value as the identical expression earlier in the chain, meaning that its branch can never execute.

### Examples

Examples of **incorrect** code for this rule:

```javascript
if (a) {
  foo();
} else if (b) {
  bar();
} else if (b) {
  baz();
}
```

```javascript
if (a || b) {
  foo();
} else if (a) {
  bar();
}
```

```javascript
if (n === 1) {
  foo();
} else if (n === 2) {
  bar();
} else if (n === 3) {
  baz();
} else if (n === 2) {
  quux();
} else if (n === 5) {
  quuux();
}
```

Examples of **correct** code for this rule:

```javascript
if (a) {
  foo();
} else if (b) {
  bar();
} else if (c) {
  baz();
}
```

```javascript
if (a || b) {
  foo();
} else if (c) {
  bar();
}
```

```javascript
if (n === 1) {
  foo();
} else if (n === 2) {
  bar();
} else if (n === 3) {
  baz();
} else if (n === 4) {
  quux();
} else if (n === 5) {
  quuux();
}
```

## How to use

## Version

This rule was added in v0.0.5.

## References

---

---
url: /docs/guide/usage/linter/rules/eslint/no-dupe-keys.md
---

### What it does

Disallow duplicate keys in object literals.

This rule can be disabled for TypeScript code, as the TypeScript compiler
enforces this check.

### Why is this bad?

Multiple properties with the same key in object literals can cause
unexpected behavior in your application.

### Examples

Examples of **incorrect** code for this rule:

```js
var foo = {
  bar: "baz",
  bar: "qux",
};

var foo = {
  bar: "baz",
  bar: "qux",
};

var foo = {
  0x1: "baz",
  1: "qux",
};
```

Examples of **correct** code for this rule:

```js
var foo = {
  bar: "baz",
  qux: "qux",
};
```

## How to use

## Version

This rule was added in v0.0.3.

## References

---

---
url: /docs/guide/usage/linter/rules/eslint/no-duplicate-case.md
---

### What it does

Disallow duplicate case labels.

### Why is this bad?

If a switch statement has duplicate test expressions in case clauses,
it is likely that a programmer copied a case clause but forgot to change the test expression.

### Examples

Examples of **incorrect** code for this rule:

```js
var a = 1,
  one = 1;
switch (a) {
  case 1:
    break;
  case 2:
    break;
  case 1: // duplicate test expression
    break;
  default:
    break;
}

switch (a) {
  case one:
    break;
  case 2:
    break;
  case one: // duplicate test expression
    break;
  default:
    break;
}
```

Examples of **correct** code for this rule:

```js
var a = 1,
  one = 1;
switch (a) {
  case 1:
    break;
  case 2:
    break;
  default:
    break;
}

switch (a) {
  case "1":
    break;
  case "2":
    break;
  default:
    break;
}
```

## How to use

## Version

This rule was added in v0.0.3.

## References

---

---
url: /docs/guide/usage/linter/rules/eslint/no-duplicate-imports.md
---

### What it does

Disallow duplicate module imports.

### Why is this bad?

Using a single import statement per module will make the code clearer because you can see
everything being imported from that module on one line.

### Examples

Examples of **incorrect** code for this rule:

In the following example the module import on line 1 is repeated on line 3. These can be
combined to make the list of imports more succinct.

```js
import { merge } from "module";
import something from "another-module";
import { find } from "module";
```

Examples of **correct** code for this rule:

```js
import { merge, find } from "module";
import something from "another-module";
```

## Configuration

This rule accepts a configuration object with the following properties:

### allowSeparateTypeImports

type: `boolean`

default: `false`

When `true`, imports with only type specifiers (inline types or type imports) are
considered separate from imports with value specifiers, so they can be imported from the
same module on separate import statements.

Examples of **correct** code when `allowSeparateTypeImports` is set to `true`:

```js
import { foo } from "module";
import type { Bar } from "module";
```

```js
import { type Foo } from "module";
import type { Bar } from "module";
```

### includeExports

type: `boolean`

default: `false`

When `true` this rule will also look at exports to see if there is both a re-export of a
module as in `export ... from 'module'` and also a standard import statement for the same
module. This would count as a rule violation because there are in a sense two statements
importing from the same module.

Examples of **incorrect** code when `includeExports` is set to `true`:

```js
import { merge } from "module";

export { find } from "module"; // re-export which is an import and an export.
```

Examples of **correct** code when `includeExports` is set to `true`:

If re-exporting from an imported module, you should add the imports to the
`import` statement, and export that directly, not use `export ... from`.

```js
import { merge } from "lodash-es";
export { merge as lodashMerge };
```

```js
import { merge, find } from "module";

// cannot be merged with the above import
export * as something from "module";

// cannot be written differently
export * from "module";
```

## How to use

## Version

This rule was added in v0.13.2.

## References

---

---
url: /docs/guide/usage/linter/rules/eslint/no-else-return.md
---

### 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.

### 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";
  }
}
```

## Configuration

This rule accepts a configuration object with the following properties:

### allowElseIf

type: `boolean`

default: `true`

Whether to allow `else if` blocks after a return statement.

Examples of **incorrect** code for this rule with `allowElseIf: false`:

```javascript
function foo() {
  if (error) {
    return "It failed";
  } else if (loading) {
    return "It's still loading";
  }
}
```

Examples of **correct** code for this rule with `allowElseIf: false`:

```javascript
function foo() {
  if (error) {
    return "It failed";
  }

  if (loading) {
    return "It's still loading";
  }
}
```

## How to use

## Version

This rule was added in v0.9.10.

## References

---

---
url: /docs/guide/usage/linter/rules/eslint/no-empty.md
---

### What it does

Disallows empty block statements.

### Why is this bad?

Empty block statements, while not technically errors, usually occur due to refactoring that wasn’t completed.
They can cause confusion when reading code.

### Examples

Examples of **incorrect** code for this rule:

```javascript
if (condition) {
}
```

Examples of **correct** code for this rule:

```javascript
if (condition) {
  throw new Error("condition should be false");
}
```

## Configuration

This rule accepts a configuration object with the following properties:

### allowEmptyCatch

type: `boolean`

default: `false`

If set to `true`, allows an empty `catch` block without triggering the linter.

## How to use

## Version

This rule was added in v0.0.3.

## References

---

---
url: /docs/guide/usage/linter/rules/eslint/no-empty-character-class.md
---

### What it does

Disallow empty character classes in regular expressions.

### Why is this bad?

Because empty character classes in regular expressions do not match anything, they might be typing mistakes.

### Examples

Examples of **incorrect** code for this rule:

```javascript
var foo = /^abc[]/;
```

Examples of **correct** code for this rule:

```javascript
var foo = /^abc/;
var foo2 = /^abc[123]/;
```

## How to use

## Version

This rule was added in v0.0.7.

## References

---

---
url: /docs/guide/usage/linter/rules/eslint/no-empty-function.md
---

### What it does

Disallows the usage of empty functions.

### Why is this bad?

Empty functions can reduce readability because readers need to guess whether it's
intentional or not. So writing a clear comment for empty functions is a good practice.

### Examples

Examples of **incorrect** code for this rule:

```typescript
function foo() {}

const bar = () => {};

class Foo {
  constructor();
  someMethod() {}
  set bar(value) {}
}
```

Examples of **correct** code for this rule:

```typescript
function foo() {
  // do nothing
}

function foo() {
  return;
}
const add = (a, b) => a + b;

class Foo {
  // constructor body is empty, but it declares a private property named
  // `_name`
  constructor(private _name: string) {}

  public get name() {
    return this._name;
  }
}
```

## Configuration

This rule accepts a configuration object with the following properties:

### allow

type: `array`

Types of functions that are allowed to be empty.

By default, no function kinds are allowed to be empty, but this option can be used to
permit specific kinds of functions.

Example:

```json
{
  "no-empty-function": [
    "error",
    {
      "allow": ["constructors"]
    }
  ]
}
```

#### allow\[n]

type: `"functions" | "arrowFunctions" | "generatorFunctions" | "methods" | "generatorMethods" | "getters" | "setters" | "constructors" | "asyncFunctions" | "asyncMethods" | "privateConstructors" | "protectedConstructors" | "decoratedFunctions" | "overrideMethods"`

Kinds of functions that can be allowed to be empty.

##### `"functions"`

Allow empty regular functions.

```js
function foo() {}
```

##### `"arrowFunctions"`

Allow empty arrow functions.

```js
const foo = () => {};
```

##### `"generatorFunctions"`

Allow empty generator functions.

```js
function* foo() {}
```

##### `"methods"`

Allow empty methods.

```js
class Foo {
  bar() {}
}
```

##### `"generatorMethods"`

Allow empty generator methods.

```js
class Foo {
  *bar() {}
}
```

##### `"getters"`

Allow empty getters.

```js
class Foo {
  get bar() {}
}
```

##### `"setters"`

Allow empty setters.

```js
class Foo {
  set bar(value) {}
}
```

##### `"constructors"`

Allow empty constructors.

```js
class Foo {
  constructor() {}
}
```

##### `"asyncFunctions"`

Allow empty async functions.

```js
async function foo() {}
```

##### `"asyncMethods"`

Allow empty async methods.

```js
class Foo {
  async bar() {}
}
```

##### `"privateConstructors"`

Allow empty private constructors.

```ts
class Foo {
  private constructor() {}
}
```

##### `"protectedConstructors"`

Allow empty protected constructors.

```ts
class Foo {
  protected constructor() {}
}
```

##### `"decoratedFunctions"`

Allow empty decorated functions.

```js
class Foo {
  @decorator()
  bar() {}
}
```

##### `"overrideMethods"`

Allow empty override methods.

```ts
class Foo extends Base {
  override bar() {}
}
```

## How to use

## Version

This rule was added in v0.3.3.

## References

---

---
url: /docs/guide/usage/linter/rules/eslint/no-empty-pattern.md
---

### What it does

Disallow empty destructuring patterns.

### Why is this bad?

When using destructuring, it’s possible to create a pattern that has no effect.
This happens when empty curly braces are used to the right of
an embedded object destructuring pattern, such as:

```JavaScript
// doesn't create any variables
var {a: {}} = foo;
```

In this code, no new variables are created because a is just a location helper
while the `{}` is expected to contain the variables to create, such as:

```JavaScript
// creates variable b
var {a: { b }} = foo;
```

In many cases, the empty object pattern is a mistake
where the author intended to use a default value instead, such as:

```JavaScript
// creates variable a
var {a = {}} = foo;
```

The difference between these two patterns is subtle,
especially because the problematic empty pattern looks just like an object literal.

### Examples of **incorrect** code for this rule:

```JavaScript
var {} = foo;
var [] = foo;
var {a: {}} = foo;
var {a: []} = foo;
function foo({}) {}
function foo([]) {}
function foo({a: {}}) {}
function foo({a: []}) {}
```

### Examples of **correct** code for this rule:

```JavaScript
var {a = {}} = foo;
var {a = []} = foo;
function foo({a = {}}) {}
function foo({a = []}) {}
```

## Configuration

This rule accepts a configuration object with the following properties:

### allowObjectPatternsAsParameters

type: `boolean`

default: `false`

When set to `true`, this rule allows empty object patterns used directly as function
parameters, including parameters defaulted to an empty object literal.

## How to use

## Version

This rule was added in v0.0.3.

## References

---

---
url: /docs/guide/usage/linter/rules/eslint/no-empty-static-block.md
---

### What it does

Disallow empty static blocks.

### Why is this bad?

Empty block statements, while not technically errors, usually occur due
to refactoring that wasn’t completed. They can cause confusion when
reading code.

### Examples

Examples of **incorrect** code for this rule:

```js
class Foo {
  static {}
}
```

Examples of **correct** code for this rule:

```js
class Foo {
  static {
    // blocks with comments are allowed
  }
}
class Bar {
  static {
    doSomething();
  }
}
```

## How to use

## Version

This rule was added in v0.0.19.

## References

---

---
url: /docs/guide/usage/linter/rules/eslint/no-eq-null.md
---

### What it does

Disallow `null` comparisons without type-checking operators.

### Why is this bad?

Comparing to `null` without a type-checking operator (`==` or `!=`), can
have unintended results as the comparison will evaluate to `true` when
comparing to not just a `null`, but also an `undefined` value.

### Examples

Examples of **incorrect** code for this rule:

```js
if (foo == null) {
  bar();
}
if (baz != null) {
  bar();
}
```

Examples of **correct** code for this rule:

```js
if (foo === null) {
  bar();
}

if (baz !== null) {
  bar();
}

if (bang === undefined) {
  bar();
}
```

## How to use

## Version

This rule was added in v0.2.14.

## References

---

---
url: /docs/guide/usage/linter/rules/eslint/no-eval.md
---

### What it does

Disallows referencing the `eval` function. This rule is aimed at preventing
potentially dangerous, unnecessary, and slow code by disallowing the use of
the `eval()` function.

### Why is this bad?

JavaScript’s `eval()` function is potentially dangerous and is often misused.
Using `eval()` on untrusted code can open a program up to several different
injection attacks. The use of `eval()` in most contexts can be substituted for
a better, safer alternative approach to solving the problem, such as using
`JSON.parse()` or `Function` constructors in safer ways.

### Examples

Examples of **incorrect** code for this rule:

```js
const obj = { x: "foo" },
  key = "x",
  value = eval("obj." + key);

(0, eval)("const a = 0");

const foo = eval;
foo("const a = 0");

this.eval("const a = 0");
```

Examples of **correct** code for this rule:

```js
const obj = { x: "foo" },
  key = "x",
  value = obj[key];

class A {
  foo() {
    this.eval("const a = 0");
  }

  eval() {}

  static {
    this.eval("const a = 0");
  }

  static eval() {}
}
```

## Configuration

This rule accepts a configuration object with the following properties:

### allowIndirect

type: `boolean`

default: `true`

This `allowIndirect` option allows indirect `eval()` calls.

Indirect calls to `eval`(e.g., `window['eval']`) are less dangerous
than direct calls because they cannot dynamically change the scope.
Indirect `eval()` calls also typically have less impact on performance
compared to direct calls, as they do not invoke JavaScript's scope chain.

## How to use

## Version

This rule was added in v0.0.3.

## References

---

---
url: /docs/guide/usage/linter/rules/eslint/no-ex-assign.md
---

### What it does

Disallow reassigning exceptions in catch clauses.

### Why is this bad?

If a catch clause in a try statement accidentally
(or purposely) assigns another value to the exception parameter,
it is impossible to refer to the error from that point on.
Since there is no arguments object to offer alternative access to this data,
assignment of the parameter is absolutely destructive.

### Examples

Examples of **incorrect** code for this rule:

```javascript
try {
  // code
} catch (e) {
  e = 10;
}
```

Examples of **correct** code for this rule:

```javascript
try {
  // code
} catch (e) {
  let val = 10;
}
```

## How to use

## Version

This rule was added in v0.0.4.

## References

---

---
url: /docs/guide/usage/linter/rules/eslint/no-extend-native.md
---

### What it does

Prevents extending native global objects such as `Object`, `String`, or `Array` with new
properties.

### Why is this bad?

Extending native objects can cause unexpected behavior and conflicts with other code.

For example:

```js
// Adding a new property, which might seem okay
Object.prototype.extra = 55;

// Defining a user object
const users = {
  1: "user1",
  2: "user2",
};

for (const id in users) {
  // This will print "extra" as well as "1" and "2":
  console.log(id);
}
```

### Examples

Examples of **incorrect** code for this rule:

```js
Object.prototype.p = 0;
Object.defineProperty(Array.prototype, "p", { value: 0 });
```

Examples of **correct** code for this rule:

```js
x.prototype.p = 0;
Object.defineProperty(x.prototype, "p", { value: 0 });
```

## Configuration

This rule accepts a configuration object with the following properties:

### exceptions

type: `string[]`

default: `[]`

A list of objects which are allowed to be exceptions to the rule.

## How to use

## Version

This rule was added in v0.9.7.

## References

---

---
url: /docs/guide/usage/linter/rules/eslint/no-extra-bind.md
---

### What it does

Disallow unnecessary calls to `.bind()`.

### Why is this bad?

This rule is aimed at avoiding the unnecessary use of `bind()`
and as such will warn whenever an immediately-invoked function expression (IIFE) is using `bind()`
and doesn’t have an appropriate `this` value.
This rule won’t flag usage of `bind()` that includes function argument binding.

### Examples

Examples of **incorrect** code for this rule:

```js
const x = function () {
  foo();
}.bind(bar);

const z = (() => {
  this.foo();
}).bind(this);
```

Examples of **correct** code for this rule:

```js
const x = function () {
  this.foo();
}.bind(bar);
const y = function (a) {
  return a + 1;
}.bind(foo, bar);
```

## How to use

## Version

This rule was added in v1.1.0.

## References

---

---
url: /docs/guide/usage/linter/rules/eslint/no-extra-boolean-cast.md
---

### What it does

This rule disallows unnecessary boolean casts.

### Why is this bad?

In contexts such as an if statement's test where the result of the expression will already be coerced to a Boolean,
casting to a Boolean via double negation (`!!`) or a `Boolean` call is unnecessary.

### Examples

Examples of **incorrect** code for this rule:

```javascript
var foo = !!!bar;
var foo = Boolean(!!bar);

if (!!foo) {
}
if (Boolean(foo)) {
}

// with "enforceForInnerExpressions" option enabled
if (!!foo || bar) {
}
```

Examples of **correct** code for this rule:

```javascript
var foo = !bar;
var foo = Boolean(bar);

if (foo) {
}
if (foo) {
}

// with "enforceForInnerExpressions" option enabled
if (foo || bar) {
}
```

## Configuration

This rule accepts a configuration object with the following properties:

### enforceForInnerExpressions

type: `boolean`

default: `false`

when set to `true`, in addition to checking default contexts, checks
whether extra boolean casts are present in expressions whose result is
used in a boolean context. See examples below. Default is `false`,
meaning that this rule by default does not warn about extra booleans
cast inside inner expressions.

## How to use

## Version

This rule was added in v0.0.8.

## References

---

---
url: /docs/guide/usage/linter/rules/eslint/no-extra-label.md
---

### What it does

Disallow unnecessary labels.

### Why is this bad?

If a loop contains no nested loops or switches, labeling the loop is unnecessary.

```js
A: while (a) {
  break A;
}
```

You can achieve the same result by removing the label and using `break` or `continue` without a label.
Probably those labels would confuse developers because they expect labels to jump to further.

### Examples

Examples of **incorrect** code for this rule:

```js
A: while (a) {
  break A;
}

B: for (let i = 0; i < 10; ++i) {
  break B;
}

C: switch (a) {
  case 0:
    break C;
}
```

Examples of **correct** code for this rule:

```js
while (a) {
  break;
}

for (let i = 0; i < 10; ++i) {
  break;
}

switch (a) {
  case 0:
    break;
}

A: {
  break A;
}

B: while (a) {
  while (b) {
    break B;
  }
}

C: switch (a) {
  case 0:
    while (b) {
      break C;
    }
    break;
}
```

## How to use

## Version

This rule was added in v0.15.4.

## References

---

---
url: /docs/guide/usage/linter/rules/eslint/no-fallthrough.md
---

### What it does

Disallow fallthrough of `case` statements

This rule is aimed at eliminating unintentional fallthrough of one case
to the other. As such, it flags any fallthrough scenarios that are not
marked by a comment.

### Why is this bad?

The switch statement in JavaScript is one of the more error-prone
constructs of the language thanks in part to the ability to “fall
through” from one case to the next. For example:

```js
switch (foo) {
  case 1:
    doSomething();

  case 2:
    doSomethingElse();
}
```

In this example, if `foo` is `1`, then execution will flow through both
cases, as the first falls through to the second. You can prevent this by
using `break`, as in this example:

```js
switch (foo) {
  case 1:
    doSomething();
    break;

  case 2:
    doSomethingElse();
}
```

That works fine when you don’t want a fallthrough, but what if the
fallthrough is intentional, there is no way to indicate that in the
language. It’s considered a best practice to always indicate when a
fallthrough is intentional using a comment which matches the
\`/falls?\s?through/i\`\` regular expression but isn’t a directive:

```js
switch (foo) {
  case 1:
    doSomething();
  // falls through

  case 2:
    doSomethingElse();
}

switch (foo) {
  case 1:
    doSomething();
  // fall through

  case 2:
    doSomethingElse();
}

switch (foo) {
  case 1:
    doSomething();
  // fallsthrough

  case 2:
    doSomethingElse();
}

switch (foo) {
  case 1: {
    doSomething();
    // falls through
  }

  case 2: {
    doSomethingElse();
  }
}
```

In this example, there is no confusion as to the expected behavior. It
is clear that the first case is meant to fall through to the second
case.

### Examples

Examples of **incorrect** code for this rule:

```js
switch (foo) {
  case 1:
    doSomething();

  case 2:
    doSomething();
}
```

Examples of **correct** code for this rule:

```js
switch (foo) {
  case 1:
    doSomething();
    break;

  case 2:
    doSomething();
}

function bar(foo) {
  switch (foo) {
    case 1:
      doSomething();
      return;

    case 2:
      doSomething();
  }
}

switch (foo) {
  case 1:
    doSomething();
    throw new Error("Boo!");

  case 2:
    doSomething();
}

switch (foo) {
  case 1:
  case 2:
    doSomething();
}

switch (foo) {
  case 1:
  case 2:
    doSomething();
}

switch (foo) {
  case 1:
    doSomething();
  // falls through

  case 2:
    doSomething();
}

switch (foo) {
  case 1: {
    doSomething();
    // falls through
  }

  case 2: {
    doSomethingElse();
  }
}
```

Note that the last case statement in these examples does not cause a
warning because there is nothing to fall through into.

## Configuration

This rule accepts a configuration object with the following properties:

### allowEmptyCase

type: `boolean`

default: `false`

Whether to allow empty case clauses to fall through.

### commentPattern

type: `string`

Custom regex pattern to match fallthrough comments.

### reportUnusedFallthroughComment

type: `boolean`

default: `false`

Whether to report unused fallthrough comments.

## How to use

## Version

This rule was added in v0.0.14.

## References

---

---
url: /docs/guide/usage/linter/rules/eslint/no-func-assign.md
---

### What it does

Disallow reassigning `function` declarations.

This rule can be disabled for TypeScript code, as the TypeScript compiler
enforces this check.

### Why is this bad?

Overwriting/reassigning a function written as a FunctionDeclaration is often indicative of
a mistake or issue.

### Examples

Examples of **incorrect** code for this rule:

```javascript
function foo() {}
foo = bar;
```

```javascript
function foo() {
  foo = bar;
}
```

```javascript
let a = function hello() {
  hello = 123;
};
```

Examples of **correct** code for this rule:

```javascript
let foo = function () {};
foo = bar;
```

```javascript
function baz(baz) {
  // `baz` is shadowed.
  baz = bar;
}
```

```
function qux() {
  const qux = bar;  // `qux` is shadowed.
}
```

## How to use

## Version

This rule was added in v0.0.3.

## References

---

---
url: /docs/guide/usage/linter/rules/eslint/no-global-assign.md
---

### What it does

Disallow modifications to read-only global variables.

### Why is this bad?

In almost all cases, you don't want to assign a value to these global variables as doing so could result in losing access to important functionality.

### Examples

Examples of **incorrect** code for this rule:

```javascript
Object = null;
```

## Configuration

This rule accepts a configuration object with the following properties:

### exceptions

type: `string[]`

default: `[]`

List of global variable names to exclude from this rule.
Globals listed here can be assigned to without triggering warnings.

## How to use

## Version

This rule was added in v0.0.7.

## References

---

---
url: /docs/guide/usage/linter/rules/eslint/no-implicit-coercion.md
---

### What it does

Disallow shorthand type conversions using operators like `!!`, unary `+`, and `"" +`.

### Why is this bad?

Implicit type coercions using operators can be less clear than using explicit
type conversion functions like `Boolean()`, `Number()`, and `String()`.
Using explicit conversions makes the intent clearer and the code more readable.

### Examples

Examples of **incorrect** code for this rule:

```javascript
var b = !!foo;
var n = +foo;
var s = "" + foo;
```

Examples of **correct** code for this rule:

```javascript
var b = Boolean(foo);
var n = Number(foo);
var s = String(foo);
```

## Configuration

This rule accepts a configuration object with the following properties:

### allow

type: `string[]`

List of operators to allow. Valid values: `"!!"`, `"~"`, `"+"`, `"-"`, `"- -"`, `"*"`

### boolean

type: `boolean`

default: `true`

When `true`, warns on implicit boolean coercion (e.g., `!!foo`).

### disallowTemplateShorthand

type: `boolean`

default: `false`

When `true`, disallows using template literals for string coercion (e.g., `` `${foo}` ``).

### number

type: `boolean`

default: `true`

When `true`, warns on implicit number coercion (e.g., `+foo`).

### string

type: `boolean`

default: `true`

When `true`, warns on implicit string coercion (e.g., `"" + foo`).

## How to use

## Version

This rule was added in v1.33.0.

## References

---

---
url: /docs/guide/usage/linter/rules/eslint/no-implicit-globals.md
---

### What it does

Disallows declarations in the global scope, global variable leaks, and
writes or redeclarations of read-only globals.

### Why is this bad?

Browser scripts share a global scope. Top-level `var` and `function`
declarations, and assignments to undeclared variables in sloppy mode,
create globals that can collide with other scripts.

### Examples

Examples of **incorrect** code for this rule:

```js
var foo = 1;
function bar() {}
baz = 1;
```

Examples of **correct** code for this rule:

```js
window.foo = 1;
(function () {
  var bar = 1;
})();
```

## Configuration

### lexicalBindings

type: `boolean`

default: `false`

## How to use

## Version

This rule was added in v1.65.0.

## References

---

---
url: /docs/guide/usage/linter/rules/eslint/no-implied-eval.md
---

### What it does

Disallows passing strings to `setTimeout()`, `setInterval()`, and
`execScript()`.

### Why is this bad?

Passing a string to these APIs evaluates the string as JavaScript source
text at runtime. This has many of the same security, readability, and
performance problems as `eval()`. Pass a function instead.

### Examples

Examples of **incorrect** code for this rule:

```js
setTimeout("alert('Hi!')", 100);
setInterval("doWork()", 1000);
window.setTimeout("doWork()", 100);
```

Examples of **correct** code for this rule:

```js
setTimeout(() => alert("Hi!"), 100);
setInterval(doWork, 1000);
window.setTimeout(doWork, 100);
```

## How to use

## Version

This rule was added in v1.66.0.

## References

---

---
url: /docs/guide/usage/linter/rules/eslint/no-import-assign.md
---

### What it does

Disallow assigning to imported bindings.

### Why is this bad?

The updates of imported bindings by ES Modules cause runtime errors.

The TypeScript compiler generally enforces this check already. Although
it should be noted that there are some cases TypeScript does not catch, such
as assignments via `Object.assign`. So this rule is still useful for
TypeScript code in those cases.

### Examples

Examples of **incorrect** code for this rule:

```javascript
import mod, { named } from "./mod.mjs";
import * as mod_ns from "./mod.mjs";

mod = 1; // ERROR: 'mod' is readonly.
named = 2; // ERROR: 'named' is readonly.
mod_ns.named = 3; // ERROR: The members of 'mod_ns' are readonly.
mod_ns = {}; // ERROR: 'mod_ns' is readonly.
// Can't extend 'mod_ns'
Object.assign(mod_ns, { foo: "foo" }); // ERROR: The members of 'mod_ns' are readonly.
```

## How to use

## Version

This rule was added in v0.0.5.

## References

---

---
url: /docs/guide/usage/linter/rules/eslint/no-inline-comments.md
---

### What it does

Disallows comments on the same line as code.

### Why is this bad?

Comments placed at the end of a line of code can make code harder to read.
They can easily be missed when scanning vertically, and they make lines longer.
Moving comments to their own lines makes them more prominent and reduces line length.

### Examples

Examples of **incorrect** code for this rule:

```js
var a = 1; // inline comment
var b = 2; /* another inline comment */
```

Examples of **correct** code for this rule:

```js
// comment on its own line
var a = 1;

/* block comment on its own line */
var b = 2;
```

## Configuration

This rule accepts a configuration object with the following properties:

### ignorePattern

type: `string`

A regex pattern to ignore certain inline comments.

Comments matching this pattern will not be reported.

Example configuration:

```json
{
  "no-inline-comments": [
    "error",
    {
      "ignorePattern": "webpackChunkName"
    }
  ]
}
```

## How to use

## Version

This rule was added in v1.34.0.

## References

---

---
url: /docs/guide/usage/linter/rules/eslint/no-inner-declarations.md
---

### What it does

Disallow variable or function declarations in nested blocks.

### Why is this bad?

A variable declaration is permitted anywhere a statement can go, even nested deeply inside other blocks.
This is often undesirable due to variable hoisting, and moving declarations to the root of the program or function body can increase clarity.
Note that block bindings (let, const) are not hoisted and therefore they are not affected by this rule.

### Examples

Examples of **incorrect** code for this rule:

```javascript
if (test) {
  function doSomethingElse() {}
}
```

Examples of **correct** code for this rule:

```javascript
function doSomethingElse() {}
if (test) {
  // your code here
}
```

## Configuration

### The 1st option

type: `"functions" | "both"`

Determines what type of declarations to check.

#### `"functions"`

Disallows function declarations in nested blocks.

#### `"both"`

Disallows function and var declarations in nested blocks.

### The 2nd option

This option is an object with the following properties:

#### blockScopedFunctions

type: `"allow" | "disallow"`

Controls whether function declarations in nested blocks are allowed in strict mode (ES6+ behavior).

##### `"allow"`

Allow function declarations in nested blocks in strict mode (ES6+ behavior).

##### `"disallow"`

Disallow function declarations in nested blocks regardless of strict mode.

#### namespaces

type: `"allow" | "disallow"`

Controls whether declarations directly inside TypeScript namespace or module bodies are allowed.

##### `"allow"`

Allow declarations directly inside TypeScript namespace or module bodies.

##### `"disallow"`

Disallow declarations directly inside TypeScript namespace or module bodies.

## How to use

## Version

This rule was added in v0.0.5.

## References

---

---
url: /docs/guide/usage/linter/rules/eslint/no-invalid-regexp.md
---

### What it does

Disallow invalid regular expression strings in RegExp constructors.

### Why is this bad?

An invalid pattern in a regular expression literal is a SyntaxError when the code is parsed,
but an invalid string in RegExp constructors throws a SyntaxError only when the code is executed.

### Examples

Examples of **incorrect** code for this rule:

```js
RegExp("[");
RegExp(".", "z");
new RegExp("\\");
```

Examples of **correct** code for this rule:

```js
RegExp(".");
new RegExp();
this.RegExp("[");
```

## Configuration

This rule accepts a configuration object with the following properties:

### allowConstructorFlags

type: `string[]`

default: `[]`

Case-sensitive array of flags that will be allowed.

## How to use

## Version

This rule was added in v0.9.4.

## References

---

---
url: /docs/guide/usage/linter/rules/eslint/no-irregular-whitespace.md
---

### What it does

Disallows the use of irregular whitespace characters in the code.

### Why is this bad?

Irregular whitespace characters are invisible to most editors and can
cause unexpected behavior, making code harder to debug and maintain.
They can also cause issues with code formatting and parsing.

### Examples

Examples of **incorrect** code for this rule:

```javascript
// Contains irregular whitespace characters (invisible)
function example() {
  var foo = "bar"; // irregular whitespace before 'bar'
}
```

Examples of **correct** code for this rule:

```javascript
function example() {
  var foo = "bar"; // regular spaces only
}
```

## Configuration

This rule accepts a configuration object with the following properties:

### skipComments

type: `boolean`

default: `true`

Whether to skip irregular whitespace in comments.

### skipJSXText

type: `boolean`

default: `true`

Whether to skip irregular whitespace in JSX text.

### skipRegExps

type: `boolean`

default: `true`

Whether to skip irregular whitespace in regular expression literals.

### skipStrings

type: `boolean`

default: `true`

Whether to skip irregular whitespace in string literals.

### skipTemplates

type: `boolean`

default: `true`

Whether to skip irregular whitespace in template literals.

## How to use

## Version

This rule was added in v0.1.1.

## References

---

---
url: /docs/guide/usage/linter/rules/eslint/no-iterator.md
---

### What it does

Disallow the use of the `__iterator__` property.

### Why is this bad?

The `__iterator__` property was a SpiderMonkey extension to JavaScript
that could be used to create custom iterators that are compatible with
JavaScript’s for in and for each constructs. However, this property is
now obsolete, so it should not be used. Here’s an example of how this
used to work:

```js
Foo.prototype.__iterator__ = function () {
  return new FooIterator(this);
};
```

### Examples

Examples of **incorrect** code for this rule:

```javascript
Foo.prototype.__iterator__ = function () {
  return new FooIterator(this);
};

foo.__iterator__ = function () {};

foo["__iterator__"] = function () {};
```

Examples of **correct** code for this rule:

```js
const __iterator__ = 42; // not using the __iterator__ property

Foo.prototype[Symbol.iterator] = function () {
  return new FooIterator(this);
};
```

## How to use

## Version

This rule was added in v0.2.15.

## References

---

---
url: /docs/guide/usage/linter/rules/eslint/no-label-var.md
---

### What it does

Disallow labels that share a name with a variable.

### Why is this bad?

This rule aims to create clearer code by disallowing the bad practice of creating a label
that shares a name with a variable that is in scope.

### Examples

Examples of **incorrect** code for this rule:

```js
var x = foo;
function bar() {
  x: for (;;) {
    break x;
  }
}
```

Examples of **correct** code for this rule:

```js
// The variable that has the same name as the label is not in scope.

function foo() {
  var q = t;
}

function bar() {
  q: for (;;) {
    break q;
  }
}
```

## How to use

## Version

This rule was added in v0.6.0.

## References

---

---
url: /docs/guide/usage/linter/rules/eslint/no-labels.md
---

### What it does

Disallow labeled statements.

### Why is this bad?

Labeled statements in JavaScript are used in conjunction with `break` and `continue` to control flow around multiple loops. For example:

```js
outer: while (true) {
  while (true) {
    break outer;
  }
}
```

The `break outer` statement ensures that this code will not result in an infinite loop because control is returned to the next statement after the `outer` label was applied. If this statement was changed to be just `break`, control would flow back to the outer `while` statement and an infinite loop would result.
While convenient in some cases, labels tend to be used only rarely and are frowned upon by some as a remedial form of flow control that is more error prone and harder to understand.

### Examples

Examples of **incorrect** code for this rule:

```js
label: while (true) {
  // ...
}

label: while (true) {
  break label;
}

label: while (true) {
  continue label;
}

label: switch (a) {
  case 0:
    break label;
}

label: {
  break label;
}

label: if (a) {
  break label;
}
```

Examples of **correct** code for this rule:

```js
var f = {
  label: "foo",
};

while (true) {
  break;
}

while (true) {
  continue;
}
```

## Configuration

This rule accepts a configuration object with the following properties:

### allowLoop

type: `boolean`

default: `false`

If set to `true`, this rule ignores labels which are sticking to loop statements.
Examples of **correct** code with this option set to `true`:

```js
label: while (true) {
  break label;
}
```

### allowSwitch

type: `boolean`

default: `false`

If set to `true`, this rule ignores labels which are sticking to switch statements.
Examples of **correct** code with this option set to `true`:

```js
label: switch (a) {
  case 0:
    break label;
}
```

## How to use

## Version

This rule was added in v0.15.4.

## References

---

---
url: /docs/guide/usage/linter/rules/eslint/no-lone-blocks.md
---

### What it does

Disallows unnecessary standalone block statements.

### Why is this bad?

Standalone blocks can be confusing as they do not provide any meaningful purpose when used unnecessarily.
They may introduce extra nesting, reducing code readability, and can mislead readers about scope or intent.

### Examples

Examples of **incorrect** code for this rule:

```js
{
  var x = 1;
}
```

Examples of **correct** code for this rule:

```js
if (condition) {
  var x = 1;
}

{
  let x = 1; // Used to create a valid block scope.
}
```

## How to use

## Version

This rule was added in v0.15.6.

## References

---

---
url: /docs/guide/usage/linter/rules/eslint/no-lonely-if.md
---

### What it does

Disallow `if` statements as the only statement in `else` blocks.

### Why is this bad?

When an `if` statement is the only statement in an `else` block, it is often clearer to use
an `else if` instead.

### Examples

Examples of **incorrect** code for this rule:

```js
if (condition) {
  // ...
} else {
  if (anotherCondition) {
    // ...
  }
}
```

```js
if (condition) {
  // ...
} else {
  if (anotherCondition) {
    // ...
  } else {
    // ...
  }
}
```

Examples of **correct** code for this rule:

```js
if (condition) {
  // ...
} else if (anotherCondition) {
  // ...
}
```

```js
if (condition) {
  // ...
} else if (anotherCondition) {
  // ...
} else {
  // ...
}
```

```js
if (condition) {
  // ...
} else {
  if (anotherCondition) {
    // ...
  }
  doSomething();
}
```

## How to use

## Version

This rule was added in v0.16.0.

## References

---

---
url: /docs/guide/usage/linter/rules/eslint/no-loop-func.md
---

### What it does

Disallows function declarations and expressions inside loop statements
when they reference variables declared in the outer scope that may change
across iterations.

### Why is this bad?

Writing functions within loops tends to result in errors due to the way
closures work in JavaScript. Functions capture variables by reference,
not by value. When using `var`, which is function-scoped, all iterations
share the same variable binding, leading to unexpected behavior.

### Examples

Examples of **incorrect** code for this rule:

```js
for (var i = 0; i < 10; i++) {
  funcs[i] = function () {
    return i;
  };
}
```

Examples of **correct** code for this rule:

```js
for (let i = 0; i < 10; i++) {
  funcs[i] = function () {
    return i;
  };
}
```

## How to use

## Version

This rule was added in v1.33.0.

## References

---

---
url: /docs/guide/usage/linter/rules/eslint/no-loss-of-precision.md
---

### What it does

Disallow precision loss in numeric literals.

### Why is this bad?

It can lead to unexpected results in certain situations.
For example, when performing mathematical operations.

In JavaScript, Numbers are stored as double-precision floating-point numbers
according to the IEEE 754 standard. Because of this, numbers can only
retain accuracy up to a certain amount of digits. If the programmer
enters additional digits, those digits will be lost in the conversion
to the Number type and will result in unexpected/incorrect behavior.

### Examples

Examples of **incorrect** code for this rule:

```javascript
var x = 2e999;
```

```javascript
var x = 9007199254740993;
```

```javascript
var x = 5123000000000000000000000000001;
```

```javascript
var x = 1230000000000000000000000.0;
```

```javascript
var x = 0x200000_0000000_1;
```

Examples of **correct** code for this rule:

```javascript
var x = 12345;
```

```javascript
var x = 123.456;
```

```javascript
var x = 123.0;
```

```javascript
var x = 123e34;
```

```javascript
var x = 0x1fff_ffff_fff_fff;
```

## How to use

## Version

This rule was added in v0.0.7.

## References

---

---
url: /docs/guide/usage/linter/rules/eslint/no-magic-numbers.md
---

### What it does

This rule aims to make code more readable and refactoring easier by ensuring that special numbers are declared as constants to make their meaning explicit.
The current implementation does not support BigInt numbers inside array indexes.

### Why is this bad?

‘Magic numbers’ are numbers that occur multiple times in code without an explicit meaning. They should preferably be replaced by named constants.

### Examples

Examples of **incorrect** code for this rule:

```javascript
var dutyFreePrice = 100;
var finalPrice = dutyFreePrice + dutyFreePrice * 0.25;
```

Examples of **correct** code for this rule with option "ignore":

```javascript
/*typescript no-magic-numbers: ["error", { "ignore": [1] }]*/
var data = ["foo", "bar", "baz"];
var dataLast = data.length && data[data.length - 1];
```

Examples of **correct** code for this rule with option "ignoreArrayIndexes":

```javascript
/*typescript no-magic-numbers: ["error", { "ignoreArrayIndexes": true }]*/
var item = data[2];
data[100] = a;
f(data[0]);
a = data[-0]; // same as data[0], -0 will be coerced to "0"
a = data[0xab];
a = data[5.6e1];
a = data[4294967294]; // max array index
```

Examples of **correct** code for this rule with option "ignoreDefaultValues":

```javascript
/*typescript no-magic-numbers: ["error", { "ignoreDefaultValues": true }]*/
const { tax = 0.25 } = accountancy;
function mapParallel(concurrency = 3) {
  /***/
}
```

Examples of **correct** code for this rule with option "ignoreClassFieldInitialValues":

```javascript
/*typescript no-magic-numbers: ["error", { "ignoreClassFieldInitialValues": true }]*/
class C {
  foo = 2;
  bar = -3;
  #baz = 4;
  static qux = 5;
}
```

Examples of **incorrect** code for this rule with option "enforceConst":

```javascript
/*typescript no-magic-numbers: ["error", { "enforceConst": true }]*/
var TAX = 0.25;
```

Examples of **incorrect** code for this rule with option "detectObjects":

```javascript
/*typescript no-magic-numbers: ["error", { "detectObjects": true }]*/
var magic = {
  tax: 0.25,
};
```

Examples of **correct** code for this rule with option "detectObjects":

```javascript
/*typescript no-magic-numbers: ["error", { "detectObjects": true }]*/
var TAX = 0.25;

var magic = {
  tax: TAX,
};
```

Examples of **correct** code for this rule with option "ignoreEnums":

```typescript
/*typescript no-magic-numbers: ["error", { "ignoreEnums": true }]*/
enum foo {
  SECOND = 1000,
}
```

Examples of **correct** code for this rule with option "ignoreNumericLiteralTypes":

```typescript
/*typescript no-magic-numbers: ["error", { "ignoreNumericLiteralTypes": true }]*/
type SmallPrimes = 2 | 3 | 5 | 7 | 11;
```

Examples of **correct** code for this rule with option "ignoreReadonlyClassProperties":

```typescript
/*typescript no-magic-numbers: ["error", { "ignoreReadonlyClassProperties": true }]*/
class Foo {
  readonly A = 1;
  readonly B = 2;
  public static readonly C = 1;
  static readonly D = 1;
}
```

Examples of **correct** code for this rule with option "ignoreTypeIndexes":

```typescript
/*typescript no-magic-numbers: ["error", { "ignoreTypeIndexes": true }]*/
type Foo = Bar[0];
type Baz = Parameters<Foo>[2];
```

## Configuration

This rule accepts a configuration object with the following properties:

### detectObjects

type: `boolean`

default: `false`

When true, numeric literals used in object properties are considered magic numbers.

### enforceConst

type: `boolean`

default: `false`

When true, enforces that number constants must be declared using `const` instead of `let` or `var`.

### ignore

type: `array`

default: `[]`

An array of numbers to ignore if used as magic numbers. Can include floats or BigInt strings.

#### ignore\[n]

type: `number | string`

### ignoreArrayIndexes

type: `boolean`

default: `false`

When true, numeric literals used as array indexes are ignored.

### ignoreClassFieldInitialValues

type: `boolean`

default: `false`

When true, numeric literals used as initial values in class fields are ignored.

### ignoreDefaultValues

type: `boolean`

default: `false`

When true, numeric literals used as default values in function parameters and destructuring are ignored.

### ignoreEnums

type: `boolean`

default: `false`

When true, numeric literals in TypeScript enums are ignored.

### ignoreNumericLiteralTypes

type: `boolean`

default: `false`

When true, numeric literals used as TypeScript numeric literal types are ignored.

### ignoreReadonlyClassProperties

type: `boolean`

default: `false`

When true, numeric literals in readonly class properties are ignored.

### ignoreTypeIndexes

type: `boolean`

default: `false`

When true, numeric literals used to index TypeScript types are ignored.

## How to use

## Version

This rule was added in v0.9.3.

## References

---

---
url: /docs/guide/usage/linter/rules/eslint/no-misleading-character-class.md
---

### What it does

This rule reports regular expressions which include multiple code point characters in character class syntax. This includes:

* Characters with combining marks (e.g., `Á` where `A` is followed by a combining acute accent)
* Characters with emoji modifiers (e.g., `👶🏻`)
* Pairs of regional indicator symbols (e.g., `🇯🇵`)
* Characters joined by zero-width joiner (ZWJ) (e.g., `👨‍👩‍👦`)
* Surrogate pairs without the Unicode flag (e.g., `/^[👍]$/`)

### Why is this bad?

Unicode includes characters which are made by multiple code points.
RegExp character class syntax (`/[abc]/`) cannot handle characters
which are made by multiple code points as a character;
those characters will be dissolved to each code point.
For example, `❇️` is made by `❇` (`U+2747`) and VARIATION SELECTOR-16 (`U+FE0F`).
If this character is in a RegExp character class,
it will match either `❇` (`U+2747`) or VARIATION SELECTOR-16 (`U+FE0F`) rather than `❇️`.

This can lead to regular expressions that do not match what the author intended,
especially for emoji, regional indicators, and characters with combining marks.

#### Examples

Examples of **incorrect** code for this rule:

```javascript
/^[Á]$/u;
/^[❇️]$/u;
/^[👶🏻]$/u;
/^[🇯🇵]$/u;
/^[👨‍👩‍👦]$/u;
/^[👍]$/;
new RegExp("[🎵]");
```

Examples of **correct** code for this rule:

```javascript
/^[abc]$/;
/^[👍]$/u;
/[\u00B7\u0300-\u036F]/u;
new RegExp("^[\u{1F1EF}\u{1F1F5}]", "u");
```

## Configuration

This rule accepts a configuration object with the following properties:

### allowEscape

type: `boolean`

default: `false`

When set to `true`, the rule allows any grouping of code points
inside a character class as long as they are written using escape sequences.

Examples of **incorrect** code for this rule with `{ "allowEscape": true }`:

```javascript
/[\uD83D]/; // backslash can be omitted
new RegExp("[\ud83d" + "\udc4d]");
```

Examples of **correct** code for this rule with `{ "allowEscape": true }`:

```javascript
/[\ud83d\udc4d]/;
/[\u00B7\u0300-\u036F]/u;
/[👨\u200d👩]/u;
new RegExp("[\x41\u0301]");
new RegExp(`[\u{1F1EF}\u{1F1F5}]`, "u");
new RegExp("[\\u{1F1EF}\\u{1F1F5}]", "u");
```

## How to use

## Version

This rule was added in v1.17.0.

## References

---

---
url: /docs/guide/usage/linter/rules/eslint/no-multi-assign.md
---

### What it does

Disallow use of chained assignment expressions.

### Why is this bad?

Chaining the assignment of variables can lead to unexpected results and be difficult to read.

```js
(function () {
  const foo = (bar = 0); // Did you mean `foo = bar == 0`?
  bar = 1; // This will not fail since `bar` is not constant.
})();
console.log(bar); // This will output 1 since `bar` is not scoped.
```

### Examples

Examples of **incorrect** code for this rule:

```js
var a = (b = c = 5);

const foo = (bar = "baz");

let d = (e = f);

class Foo {
  a = (b = 10);
}

a = b = "quux";
```

Examples of **correct** code for this rule:

```js
var a = 5;
var b = 5;
var c = 5;

const foo = "baz";
const bar = "baz";

let d = c;
let e = c;

class Foo {
  a = 10;
  b = 10;
}

a = "quux";
b = "quux";
```

## Configuration

This rule accepts a configuration object with the following properties:

### ignoreNonDeclaration

type: `boolean`

default: `false`

When set to `true`, the rule allows chains that don't include initializing a variable in a declaration or initializing a class field.

Examples of **correct** code for this option set to `true`:

```js
let a;
let b;
a = b = "baz";

const x = {};
const y = {};
x.one = y.one = 1;
```

Examples of **incorrect** code for this option set to `true`:

```js
let a = (b = "baz");

const foo = (bar = 1);

class Foo {
  a = (b = 10);
}
```

## How to use

## Version

This rule was added in v0.15.4.

## References

---

---
url: /docs/guide/usage/linter/rules/eslint/no-multi-str.md
---

### What it does

Disallow multiline strings.

### Why is this bad?

Some consider this to be a bad practice as it was an undocumented feature of JavaScript
that was only formalized later.

### Examples

Examples of **incorrect** code for this rule:

```javascript
var x =
  "Line 1 \
 Line 2";
```

## How to use

## Version

This rule was added in v0.5.3.

## References

---

---
url: /docs/guide/usage/linter/rules/eslint/no-negated-condition.md
---

### What it does

Disallow negated conditions.

### Why is this bad?

Negated conditions are more difficult to understand. Code can be made more readable by inverting the condition.

### Examples

Examples of **incorrect** code for this rule:

```javascript
if (!a) {
  doSomethingC();
} else {
  doSomethingB();
}

!a ? doSomethingC() : doSomethingB();
```

Examples of **correct** code for this rule:

```javascript
if (a) {
  doSomethingB();
} else {
  doSomethingC();
}

a ? doSomethingB() : doSomethingC();
```

## How to use

## Version

This rule was added in v0.0.18.

## References

---

---
url: /docs/guide/usage/linter/rules/eslint/no-nested-ternary.md
---

### What it does

Disallow nested ternary expressions.

### Why is this bad?

Nested ternary expressions make code harder to read and understand. Nesting of these expressions can lead
to complex logic that is difficult to understand.

### Examples

Examples of **incorrect** code for this rule:

```js
const result = condition1 ? (condition2 ? "a" : "b") : "c";
```

Examples of **correct** code for this rule:

```js
let result;
if (condition1) {
  result = condition2 ? "a" : "b";
} else {
  result = "c";
}
```

## How to use

## Version

This rule was added in v0.15.4.

## References

---

---
url: /docs/guide/usage/linter/rules/eslint/no-new.md
---

### What it does

Disallow new operators outside of assignments or comparisons.

### Why is this bad?

Calling new without assigning or comparing it the reference is thrown away and in many
cases the constructor can be replaced with a function.

### Examples

Examples of **incorrect** code for this rule:

```javascript
new Person();

() => {
  new Date();
};
```

Examples of **correct** code for this rule:

```javascript
var a = new Date()(() => new Date());
```

## How to use

## Version

This rule was added in v0.4.0.

## References

---

---
url: /docs/guide/usage/linter/rules/eslint/no-new-func.md
---

### What it does

Disallow `new` operators with the `Function` object.

### Why is this bad?

Using `new Function` or `Function` can lead to code that is difficult to understand and maintain. It can introduce security risks similar to those associated with `eval` because it generates a new function from a string of code, which can be a vector for injection attacks. Additionally, it impacts performance negatively as these functions are not optimized by the JavaScript engine.

### Examples

Examples of **incorrect** code for this rule:

```js
var x = new Function("a", "b", "return a + b");
var x = Function("a", "b", "return a + b");
var x = Function.call(null, "a", "b", "return a + b");
var x = Function.apply(null, ["a", "b", "return a + b"]);
var x = Function.bind(null, "a", "b", "return a + b")();
var f = Function.bind(null, "a", "b", "return a + b");
```

Examples of **correct** code for this rule:

```js
let x = function (a, b) {
  return a + b;
};
```

## How to use

## Version

This rule was added in v0.9.2.

## References

---

---
url: /docs/guide/usage/linter/rules/eslint/no-new-native-nonconstructor.md
---

### What it does

Disallow `new` operators with global non-constructor functions (`Symbol`, `BigInt`).

This rule can be disabled for TypeScript code, as the TypeScript compiler
enforces this check.

### Why is this bad?

Both `new Symbol` and `new BigInt` throw a type error because they are
functions and not classes. It is easy to make this mistake by assuming
the uppercase letters indicate classes.

### Examples

Examples of **incorrect** code for this rule:

```js
// throws a TypeError
let foo = new Symbol("foo");

// throws a TypeError
let result = new BigInt(9007199254740991);
```

Examples of **correct** code for this rule:

```js
let foo = Symbol("foo");

let result = BigInt(9007199254740991);
```

## How to use

## Version

This rule was added in v0.3.3.

## References

---

---
url: /docs/guide/usage/linter/rules/eslint/no-new-wrappers.md
---

### What it does

Disallow `new` operators with the `String`, `Number`, and `Boolean` objects.

### Why is this bad?

The first problem is that primitive wrapper objects are, in fact,
objects. That means `typeof` will return `"object"` instead of `"string"`,
`"number"`, or `"boolean"`. The second problem comes with boolean
objects. Every object is truthy, that means an instance of `Boolean`
always resolves to `true` even when its actual value is `false`.

https://eslint.org/docs/latest/rules/no-new-wrappers

### Examples

Examples of **incorrect** code for this rule:

```js
var stringObject = new String("Hello world");
var numberObject = new Number(33);
var booleanObject = new Boolean(false);
var symbolObject = new Symbol("foo"); // symbol is not a constructor
```

Examples of **correct** code for this rule:

```js
var stringObject = "Hello world";
var stringObject2 = String(value);
var numberObject = Number(value);
var booleanObject = Boolean(value);
var symbolObject = Symbol("foo");
```

## How to use

## Version

This rule was added in v0.2.10.

## References

---

---
url: /docs/guide/usage/linter/rules/eslint/no-nonoctal-decimal-escape.md
---

### What it does

Disallow `\8` and `\9` escape sequences in string literals.

### Why is this bad?

ECMAScript specification treats `\8` and `\9` in string literals as a legacy feature

### Examples

Examples of **incorrect** code for this rule:

```javascript
let x = "\8";
let y = "\9";
```

Examples of **correct** code for this rule:

```javascript
let x = "8";
let y = "\\9";
```

## How to use

## Version

This rule was added in v0.2.10.

## References

---

---
url: /docs/guide/usage/linter/rules/eslint/no-obj-calls.md
---

### What it does

Disallow calling some global objects as functions.

This rule can be disabled for TypeScript code, as the TypeScript compiler
enforces this check.

### Why is this bad?

Some global objects are not intended to be called as functions.
Calling them as functions will usually result in a TypeError being thrown.

### Examples

Examples of **incorrect** code for this rule:

```javascript
let math = Math();
let newMath = new Math();

let json = JSON();
let newJson = new JSON();

let atomics = Atomics();
let newAtomics = new Atomics();

let intl = Intl();
let newIntl = new Intl();

let reflect = Reflect();
let newReflect = new Reflect();
```

Examples of **correct** code for this rule:

```javascript
let area = (r) => 2 * Math.PI * r * r;
let object = JSON.parse("{}");
let first = Atomics.load(sharedArray, 0);
let segmenterFrom = Intl.Segmenter("fr", { granularity: "word" });
```

## How to use

## Version

This rule was added in v0.0.7.

## References

---

---
url: /docs/guide/usage/linter/rules/eslint/no-object-constructor.md
---

### What it does

Disallow calls to the Object constructor without an argument.

### Why is this bad?

Use of the Object constructor to construct a new empty object is generally discouraged in favor of object literal notation because of conciseness and because the Object global may be redefined. The exception is when the Object constructor is used to intentionally wrap a specified value which is passed as an argument.

### Examples

Examples of **incorrect** code for this rule:

```js
Object();
new Object();
```

Examples of **correct** code for this rule:

```js
Object("foo");
const obj = { a: 1, b: 2 };
const isObject = (value) => value === Object(value);
const createObject = (Object) => new Object();
```

## How to use

## Version

This rule was added in v0.13.2.

## References

---

---
url: /docs/guide/usage/linter/rules/eslint/no-param-reassign.md
---

### What it does

Disallow reassigning function parameters or, optionally, their properties.

### Why is this bad?

Reassigning parameters can lead to unexpected behavior, especially when relying on the
original arguments passed into the function. Mutating parameter properties can be similarly
surprising and harder to reason about.

### Examples

```javascript
function foo(bar) {
  bar = 1;
}

function baz(qux) {
  qux.prop = 2; // when `props` option is enabled
}
```

## Configuration

This rule accepts a configuration object with the following properties:

### ignorePropertyModificationsFor

type: `string[]`

default: `[]`

An array of parameter names whose property modifications should be ignored.

### ignorePropertyModificationsForRegex

type: `string[]`

An array of regex patterns (as strings) for parameter names whose property modifications should be ignored.
Note that this uses [Rust regex syntax](https://docs.rs/regex/latest/regex/) and so may not have all features
available to JavaScript regexes.

### props

type: `boolean`

default: `false`

When true, also check for modifications to properties of parameters.

## How to use

## Version

This rule was added in v1.20.0.

## References

---

---
url: /docs/guide/usage/linter/rules/eslint/no-plusplus.md
---

### What it does

Disallow the unary operators `++` and `--`.

### Why is this bad?

Because the unary `++` and `--` operators are subject to automatic semicolon insertion, differences in whitespace
can change the semantics of source code. For example, these two code blocks are not equivalent:

```js
var i = 10;
var j = 20;

i++;
j;
// => i = 11, j = 20
```

```js
var i = 10;
var j = 20;

i;
++j;
// => i = 10, j = 21
```

### Examples

Examples of **incorrect** code for this rule:

```js
var x = 0;
x++;
var y = 0;
y--;
for (let i = 0; i < l; i++) {
  doSomething(i);
}
```

Examples of **correct** code for this rule:

```js
var x = 0;
x += 1;
var y = 0;
y -= 1;
for (let i = 0; i < l; i += 1) {
  doSomething(i);
}
```

## Configuration

This rule accepts a configuration object with the following properties:

### allowForLoopAfterthoughts

type: `boolean`

default: `false`

Whether to allow `++` and `--` in for loop afterthoughts.

## How to use

## Version

This rule was added in v0.9.5.

## References

---

---
url: /docs/guide/usage/linter/rules/eslint/no-promise-executor-return.md
---

### What it does

Disallow returning values from Promise executor functions.

### Why is this bad?

The `new Promise` constructor accepts an executor function as an argument,
which has `resolve` and `reject` parameters that can be used to control the
state of the created Promise.

The return value of the executor is ignored. Returning a value from an executor
function is a possible error because the returned value cannot be used and it
doesn't affect the promise in any way.

### Examples

Examples of **incorrect** code for this rule:

```javascript
new Promise((resolve, reject) => {
  if (someCondition) {
    return defaultResult;
  }
  getSomething((err, result) => {
    if (err) {
      reject(err);
    } else {
      resolve(result);
    }
  });
});

new Promise((resolve, reject) =>
  getSomething((err, data) => {
    if (err) {
      reject(err);
    } else {
      resolve(data);
    }
  }),
);

new Promise(() => {
  return 1;
});
```

Examples of **correct** code for this rule:

```javascript
new Promise((resolve, reject) => {
  if (someCondition) {
    resolve(defaultResult);
    return;
  }
  getSomething((err, result) => {
    if (err) {
      reject(err);
    } else {
      resolve(result);
    }
  });
});

new Promise((resolve, reject) => {
  getSomething((err, data) => {
    if (err) {
      reject(err);
    } else {
      resolve(data);
    }
  });
});

new Promise((r) => {
  r(1);
});
```

## Configuration

This rule accepts a configuration object with the following properties:

### allowVoid

type: `boolean`

default: `false`

If `true`, allows returning `void` expressions (e.g., `return void resolve()`).

## How to use

## Version

This rule was added in v1.33.0.

## References

---

---
url: /docs/guide/usage/linter/rules/eslint/no-proto.md
---

### What it does

Disallow the use of the `__proto__` property.

### Why is this bad?

The `__proto__` property has been deprecated as of ECMAScript 3.1 and
shouldn’t be used in new code. Use `Object.getPrototypeOf` and
`Object.setPrototypeOf` instead.

For more information, see
[the MDN documentation](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/proto).

### Examples

Examples of **incorrect** code for this rule:

```javascript
var a = obj.__proto__;

var a = obj["__proto__"];

obj.__proto__ = b;

obj["__proto__"] = b;
```

## How to use

## Version

This rule was added in v0.2.14.

## References

---

---
url: /docs/guide/usage/linter/rules/eslint/no-prototype-builtins.md
---

### What it does

Disallow calling some `Object.prototype` methods directly on objects.

### Why is this bad?

In ECMAScript 5.1, `Object.create` was added, which enables the creation of objects with a specified \[\[Prototype]].
`Object.create(null)` is a common pattern used to create objects that will be used as a Map.
This can lead to errors when it is assumed that objects will have properties from `Object.prototype`. This rule prevents calling some `Object.prototype` methods directly from an object.
Additionally, objects can have properties that shadow the builtins on `Object.prototype`, potentially causing unintended behavior or denial-of-service security vulnerabilities.
For example, it would be unsafe for a webserver to parse JSON input from a client and call `hasOwnProperty` directly on the resulting object, because a malicious client could send a JSON value like {"hasOwnProperty": 1} and cause the server to crash.

To avoid subtle bugs like this, it’s better to always call these methods from `Object.prototype`. For example, `foo.hasOwnProperty("bar")` should be replaced with `Object.prototype.hasOwnProperty.call(foo, "bar")`.

### Examples

Examples of **incorrect** code for this rule:

```javascript
var hasBarProperty = foo.hasOwnProperty("bar");
var isPrototypeOfBar = foo.isPrototypeOf(bar);
var barIsEnumerable = foo.propertyIsEnumerable("bar");
```

## How to use

## Version

This rule was added in v0.0.5.

## References

---

---
url: /docs/guide/usage/linter/rules/eslint/no-redeclare.md
---

### What it does

This rule disallows redeclaring variables within the same scope, ensuring that each variable
is declared only once. It helps avoid confusion and unintended behavior in code.

### Why is this bad?

Redeclaring variables in the same scope can lead to unexpected behavior, overwriting existing values,
and making the code harder to understand and maintain.

### Examples

Examples of **incorrect** code for this rule:

```javascript
var a = 3;
var a = 10;
```

Examples of **correct** code for this rule:

```javascript
var a = 3;
a = 10;
```

## Configuration

This rule accepts a configuration object with the following properties:

### builtinGlobals

type: `boolean`

default: `true`

When set `true`, it flags redeclaring built-in globals (e.g., `let Object = 1;`).

## How to use

## Version

This rule was added in v0.0.13.

## References

---

---
url: /docs/guide/usage/linter/rules/eslint/no-regex-spaces.md
---

### What it does

Disallow 2+ consecutive spaces in regular expressions.

### Why is this bad?

In a regular expression, it is hard to tell how many spaces are
intended to be matched. It is better to use only one space and
then specify how many spaces are expected using a quantifier.

```javascript
var re = /foo {3}bar/;
```

### Examples

Examples of **incorrect** code for this rule:

```javascript
var re = /foo   bar/;
```

## How to use

## Version

This rule was added in v0.0.18.

## References

---

---
url: /docs/guide/usage/linter/rules/eslint/no-restricted-exports.md
---

### What it does

This rule disallows specified names from being used as exported names.

By default, this rule doesn’t disallow any names. Only the names you specify in the configuration will be disallowed.

### Why is this bad?

In a project, certain names may be disallowed from being used as exported names for various reasons.

## Configuration

This rule accepts a configuration object with the following properties:

### restrictDefaultExports

type: `object`

An object with boolean properties to restrict certain default export
declarations. This option works only if the `restrictedNamedExports`
option does not contain the `"default"` value.

#### restrictDefaultExports.defaultFrom

type: `boolean`

default: `false`

Whether to restrict `export { default } from` declarations.

Example of **incorrect** code for `"restrictDefaultExports": { "defaultFrom": true }`:

```js
export { default } from "foo";
```

#### restrictDefaultExports.direct

type: `boolean`

default: `false`

Whether to restrict `export default` declarations.

Example of **incorrect** code for `"restrictDefaultExports": { "direct": true }`:

```js
const foo = 123;
export default foo;
```

#### restrictDefaultExports.named

type: `boolean`

default: `false`

Whether to restrict `export { foo as default }` declarations.

Example of **incorrect** code for `"restrictDefaultExports": { "named": true }`:

```js
const foo = 123;
export { foo as default };
```

#### restrictDefaultExports.namedFrom

type: `boolean`

default: `false`

Whether to restrict `export { foo as default } from` declarations.

Example of **incorrect** code for `"restrictDefaultExports": { "namedFrom": true }`:

```js
export { foo as default } from "foo";
```

#### restrictDefaultExports.namespaceFrom

type: `boolean`

default: `false`

Whether to restrict `export * as default from` declarations.

Example of **incorrect** code for `"restrictDefaultExports": { "namespaceFrom": true }`:

```js
export * as default from "foo";
```

### restrictedNamedExports

type: `string[]`

default: `[]`

An array of strings, where each string is a name to be restricted.

Example of **incorrect** code for `"restrictedNamedExports": ["foo"]`:

```ts
export const foo = 1;
```

Example of **correct** code for `"restrictedNamedExports": ["foo"]`:

```ts
export const bar = 1;
```

By design, this option doesn't disallow export default declarations. If
you configure `default` as a restricted name, that restriction will apply
only to named export declarations.

Example of **incorrect** code for `"restrictedNamedExports": ["default"]`:

```ts
function foo() {}
export { foo as default };

export { default } from "some_module";
```

### restrictedNamedExportsPattern

type: `string`

A string representing a regular expression pattern. Named exports
matching this pattern will be restricted. This option does not apply to
default named exports.

Example of **incorrect** code for \`"restrictedNamedExportsPattern": "bar$":

```ts
export const foobar = 1;
```

Example of **correct** code for \`"restrictedNamedExportsPattern": "bar$":

```ts
export const foo = 1;
```

## How to use

## Version

This rule was added in v1.59.0.

## References

---

---
url: /docs/guide/usage/linter/rules/eslint/no-restricted-globals.md
---

### What it does

Specify global variable names that should not be used in your application.

### Why is this bad?

Disallowing usage of specific global variables can be useful if you want to allow a set of global
variables by enabling an environment, but still want to disallow some of those.

For instance, early Internet Explorer versions exposed the current DOM event as a global variable
`event`, but using this variable has been considered as a bad practice for a long time. Restricting
this will make sure this variable isn't used in browser code.

### Examples

If we have options:

```json
"no-restricted-globals": ["error", "event"]
```

The following patterns are considered problems:

```javascript
function onClick() {
  console.log(event); // Unexpected global variable 'event'. Use local parameter instead.
}
```

## How to use

## Version

This rule was added in v0.4.0.

## References

---

---
url: /docs/guide/usage/linter/rules/eslint/no-restricted-imports.md
---

### What it does

This rule allows you to specify imports that you don’t want to use in your application.
It applies to static imports and to dynamic `import()` with a string-literal source;
computed sources like `import(bar)` are ignored.

### Why is this bad?

Some imports might not make sense in a particular environment.
For example, Node.js’ fs module would not make sense in an environment that didn’t have a file system.

Some modules provide similar or identical functionality, think lodash and underscore. Your project may have standardized on a module.
You want to make sure that the other alternatives are not being used as this would unnecessarily bloat the project
and provide a higher maintenance cost of two dependencies when one would suffice.

### Examples

Examples of **incorrect** code for this rule:

```js
/* no-restricted-imports: ["error", "disallowed-import"] */

import foo from "disallowed-import";
export * from "disallowed-import";
```

Examples of **correct** code for this rule:

```js
/* no-restricted-imports: ["error", "fs"] */

import crypto from "crypto";
export * from "bar";
```

### Options

You may also specify a custom message for a particular module using the `name` and `message` properties inside an object,
where the value of the name is the `name` of the module and message property contains the custom message.
The custom message will be displayed as a help text for the user.

Examples of **incorrect** code for this rule:

```js
/* no-restricted-imports: ["error", {
  "name": "disallowed-import",
  "message": "Please use 'allowed-import' instead"
}] */

import foo from "disallowed-import";
```

#### paths

This is an object option whose value is an array containing the names of the modules you want to restrict.

```json
{"rules: {"no-restricted-imports": ["error", { "paths": ["import1", "import2"] }]}}
```

Examples of **incorrect** code for `paths`:

```js
/* no-restricted-imports: ["error", { "paths": ["cluster"] }] */

import cluster from "cluster";
```

Custom messages for a particular module can also be specified in `paths` array using objects with `name` and `message`.

```json
"no-restricted-imports": ["error", {
  "paths": [{
    "name": "import-foo",
    "message": "Please use import-bar instead."
  }, {
    "name": "import-baz",
    "message": "Please use import-quux instead."
  }]
}]
```

##### importNames

This option in `paths` is an array and can be used to specify the names of certain bindings exported from a module.
Import names specified inside `paths` array affect the module specified in the `name` property of corresponding object,
so it is required to specify the `name` property first when you are using `importNames` or `message` option.

Specifying `"default"` string inside the `importNames` array will restrict the default export from being imported.

Examples of **incorrect** code for this rule:

```js
/* no-restricted-imports: ["error", { paths: [{
  "name": "foo",
  "importNames": ["default"]
}, {
  "name": "bar",
  "importNames": ["Baz"]
}]}] */

import DisallowedObject from "foo";
import { Baz } from "far";
```

##### allowImportNames

This option is an array. Inverse of `importNames`, `allowImportNames` allows the imports that are specified inside this array.
So it restricts all imports from a module, except specified allowed ones.

Note: `allowImportNames` cannot be used in combination with `importNames`.

Examples of **incorrect** code for this rule:

```js
/* no-restricted-imports: ["error", { paths: [{
  "name": "foo",
  "allowImportNames": ["AllowedObject"],
  "message": "Please use only 'AllowedObject' from 'foo'."
}]}] */

import { DisallowedObject } from "foo";
```

#### allowTypeImports

Whether to allow type-only imports for a path. Default: `false`.

Examples of **incorrect** code for this rule:

```typescript
/* no-restricted-imports: ["error", { paths: [{
  "name": "foo",
  "allowTypeImports": true
}]}] */

import foo from "import-foo";
export { Foo } from "import-foo";
```

Examples of **correct** code for this rule:

```typescript
/* no-restricted-imports: ["error", { paths: [{
  "name": "foo",
  "allowTypeImports": true
}]}] */

import type foo from "import-foo";
export type { Foo } from "import-foo";
```

#### patterns

This is also an object option whose value is an array.
This option allows you to specify multiple modules to restrict using `gitignore`-style patterns or regular expressions.

Where `paths` option takes exact import paths, `patterns` option can be used to specify the import paths with more flexibility,
allowing for the restriction of multiple modules within the same directory. For example:

```json
"no-restricted-imports": ["error", {
  "paths": [{
    "name": "import-foo",
  }]
}]
```

This configuration restricts import of the `import-foo` module
but wouldn’t restrict the import of `import-foo/bar` or `import-foo/baz`. You can use `patterns` to restrict both:

```json
"no-restricted-imports": ["error", {
  "paths": [{
    "name": "import-foo",
  }],
  "patterns": [{
    "group": ["import-foo/ba*"],
  }]
}]
```

This configuration restricts imports not just from `import-foo` using path,
but also `import-foo/bar` and `import-foo/baz` using `patterns`.

You can also use regular expressions to restrict modules (see the `regex` option).

Examples of **incorrect** code for `patterns` option:

```js
/* no-restricted-imports: ["error", { "patterns": ["lodash/*"] }] */

import pick from "lodash/pick";
```

Examples of **correct** code for `patterns` option:

```js
/* no-restricted-imports: ["error", { "patterns": ["crypto/*"] }] */

import crypto from "crypto";
```

##### group

The `patterns` array can also include objects. The `group` property is used to specify the `gitignore`-style patterns
for restricting modules and the `message` property is used to specify a custom message.

Either of the `group` or `regex` properties is required when using the `patterns` option.

Examples of **incorrect** code for `group` option:

```js
/* no-restricted-imports: ["error", { patterns: [{
  group: ["lodash/*"],
  message: "Please use the default import from 'lodash' instead."
}]}] */

import pick from "lodash/pick";
```

##### regex

The `regex` property is used to specify the regex patterns for restricting modules.

Note: `regex` cannot be used in combination with `group`.

**Warning**: This rule uses the [Rust-Regex](https://docs.rs/regex/latest/regex/), which supports not all features of JS-Regex,
like Lookahead and Lookbehinds.

Examples of **incorrect** code for `regex` option:

```js
/* no-restricted-imports: ["error", { patterns: [{
  regex: "@app/(api|enums).*",
}]}] */

import Foo from "@app/api";
import Bar from "@app/api/bar";
import Baz from "@app/api/baz";
import Bux from "@app/api/enums/foo";
```

##### caseSensitive

This is a boolean option and sets the patterns specified in the `group` property to be case-sensitive when `true`. Default is `false`.

**Warning**: It will not apply case-sensitive checks to `regex`. `regex` uses Rust-RegEx which has its own implementation of case-sensitive.

##### importNames

You can also specify `importNames` within objects inside the `patterns` array.
In this case, the specified names apply only to the associated `group` or `regex` property.

Examples of **incorrect** code for `importNames` in `patterns`:

```js
/* no-restricted-imports: ["error", { patterns: [{
  group: ["utils/*"],
  importNames: ['isEmpty'],
  message: "Use 'isEmpty' from lodash instead."
}]}] */

import { isEmpty } from "utils/collection-utils";
```

##### allowImportNames

You can also specify `allowImportNames` within objects inside the `patterns` array.
In this case, the specified names apply only to the associated `group` or `regex` property.

Note: `allowImportNames` cannot be used in combination with `importNames`, `importNamePattern` or `allowImportNamePattern`.

##### importNamePattern

This option allows you to use regex patterns to restrict import names.

Examples of **incorrect** code for `importNamePattern` option:

```js
/* no-restricted-imports: ["error", { patterns: [{
  group: ["foo/*"],
  importNamePattern: '^(is|has)',
  message: "Use 'is*' and 'has*' functions from baz/bar instead"
}]}] */

import { isSomething, hasSomething } from "foo/bar";
```

##### allowImportNamePattern

This is a string option. Inverse of `importNamePattern`, this option allows imports that matches the specified regex pattern.
So it restricts all imports from a module, except specified allowed patterns.

Note: `allowImportNamePattern` cannot be used in combination with `importNames`, `importNamePattern` or `allowImportNames`.

```json
"no-restricted-imports": ["error", {
  "patterns": [{
    "group": ["import-foo/*"],
    "allowImportNamePattern": "^foo",
  }]
}]
```

Examples of **incorrect** code for `allowImportNamePattern` option:

```js
/* no-restricted-imports: ["error", { patterns: [{
  group: ["utils/*"],
  allowImportNamePattern: '^has'
}]}] */

import { isEmpty } from "utils/collection-utils";
```

Examples of **correct** code for `allowImportNamePattern` option:

```js
/* no-restricted-imports: ["error", { patterns: [{
  group: ["utils/*"],
  allowImportNamePattern: '^is'
}]}] */

import { isEmpty } from "utils/collection-utils";
```

## How to use

## Version

This rule was added in v0.15.0.

## References

---

---
url: /docs/guide/usage/linter/rules/eslint/no-restricted-properties.md
---

### What it does

This rule allows you to disallow access to certain properties on certain objects.

### Why is this bad?

Certain properties on objects may be disallowed in a codebase. This is useful for
deprecating an API or restricting usage of a module’s methods. For example, you may want
to disallow using describe.only when using Mocha or telling people to use Object.assign
instead of \_.extend.

If you want to disallow APIs marked with `@deprecated`, consider using the type-aware
`typescript/no-deprecated` rule instead.

### Examples

**With options:**

```json
"no-restricted-properties": ["error", {
  "object": "JSON",
  "property": "parse"
}]
```

Examples of **incorrect** code for this rule:

```js
/* no-restricted-properties: ["error", { "object": "JSON", "property": "parse" }] */

JSON.parse('{ "json": "here" }'); // 'JSON.parse' is restricted from being used.
```

Examples of **correct** code for this rule:

```js
/* no-restricted-properties: ["error", { "object": "JSON", "property": "parse" }] */

JSON.stringify({ json: "here" });
```

**With options:**

```json
"no-restricted-properties": ["error", {
  "property": "extend",
  "allowObjects": ["safeUtils"]
}]
```

Examples of **incorrect** code for this rule:

```js
/* no-restricted-properties: ["error", { "property": "extend", "allowObjects": ["safeUtils"] }] */

unsafeUtils.extend(value); // 'extend' is restricted from being used. Property 'extend' is only allowed on these objects: safeUtils.
```

Examples of **correct** code for this rule:

```js
/* no-restricted-properties: ["error", { "property": "extend", "allowObjects": ["safeUtils"] }] */

safeUtils.extend(value);
```

**With options:**

```json
"no-restricted-properties": ["error", {
  "object": "legacyApi",
  "allowProperties": ["stableMethod"]
}]
```

Examples of **incorrect** code for this rule:

```js
/* no-restricted-properties: ["error", { "object": "legacyApi", "allowProperties": ["stableMethod"] }] */

legacyApi.unstableMethod(); // 'legacyApi' is restricted from being used. Only these properties are allowed: stableMethod.
```

Examples of **correct** code for this rule:

```js
/* no-restricted-properties: ["error", { "object": "legacyApi", "allowProperties": ["stableMethod"] }] */

legacyApi.stableMethod();
```

## How to use

## Version

This rule was added in v1.63.0.

## References

---

---
url: /docs/guide/usage/linter/rules/eslint/no-return-assign.md
---

### 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;
}
```

## Configuration

This rule accepts one of the following string values:

### `"always"`

Disallow all assignments in return statements.

### `"except-parens"`

Allow assignments in return statements only if they are enclosed in parentheses.
This is the default mode.

## How to use

## Version

This rule was added in v0.9.10.

## References

---

---
url: /docs/guide/usage/linter/rules/eslint/no-script-url.md
---

### What it does

Disallow `javascript:` URLs.

### Why is this bad?

Using `javascript:` URLs is considered by some as a form of `eval`. Code
passed in `javascript:` URLs must be parsed and evaluated by the browser
in the same way that `eval` is processed. This can lead to security and
performance issues.

### Examples

Examples of **incorrect** code for this rule:

```javascript
location.href = "javascript:void(0)";

location.href = `javascript:void(0)`;
```

## How to use

## Version

This rule was added in v0.2.15.

## References

---

---
url: /docs/guide/usage/linter/rules/eslint/no-self-assign.md
---

### What it does

Disallow assignments where both sides are exactly the same.

### Why is this bad?

Self assignments have no effect, so probably those are an error due to incomplete
refactoring. Those indicate that what you should do is still remaining.

### Examples

Examples of **incorrect** code for this rule:

```javascript
foo = foo;

[a, b] = [a, b];
[a, ...b] = [x, ...b];

({ a, b } = { a, x });

foo &&= foo;
foo ||= foo;
foo ??= foo;
```

```javascript
obj.a = obj.a;
obj.a.b = obj.a.b;
obj["a"] = obj["a"];
obj[a] = obj[a];
```

Examples of **correct** code for this rule:

```javascript
foo = bar;
[a, b] = [b, a];

// This pattern is warned by the `no-use-before-define` rule.
let foo = foo;

// The default values have an effect.
[foo = 1] = [foo];

// This ignores if there is a function call.
obj.a().b = obj.a().b;
a().b = a().b;

// `&=` and `|=` have an effect on non-integers.
foo &= foo;
foo |= foo;
```

## Configuration

This rule accepts a configuration object with the following properties:

### props

type: `boolean`

default: `true`

The `props` option when set to `false`, disables the checking of properties.

With `props` set to `false` the following are examples of correct code:

```javascript
obj.a = obj.a;
obj.a.b = obj.a.b;
obj["a"] = obj["a"];
obj[a] = obj[a];
```

## How to use

## Version

This rule was added in v0.0.5.

## References

---

---
url: /docs/guide/usage/linter/rules/eslint/no-self-compare.md
---

### What it does

Disallow comparisons where both sides are exactly the same.

### Why is this bad?

Comparing a variable against itself is usually an error, either a typo or refactoring error.
It is confusing to the reader and may potentially introduce a runtime error.

### Examples

Examples of **incorrect** code for this rule:

```javascript
var x = 10;
if (x === x) {
  x = 20;
}
```

## How to use

## Version

This rule was added in v0.0.3.

## References

---

---
url: /docs/guide/usage/linter/rules/eslint/no-sequences.md
---

### What it does

Disallows the use of the comma operator.

### Why is this bad?

The comma operator evaluates each of its operands (from left to right)
and returns the value of the last operand. However, this frequently
obscures side effects, and its use is often an accident.

### Examples

Examples of **incorrect** code for this rule:

```javascript
((foo = doSomething()), val);

(0, eval("doSomething();"));

// Arrow function body needs double parentheses
const fn = () => (doSomething(), val);

// with allowInParentheses: false
foo = (doSomething(), val);
```

Examples of **correct** code for this rule:

```javascript
foo = (doSomething(), val);

(0, eval)("doSomething();");

// Single extra parentheses is enough for conditions
do {} while ((doSomething(), !!test));

for (i = 0, j = 10; i < j; i++, j--) {}

// Arrow function body needs double parentheses
const fn = () => (doSomething(), val);
```

## Configuration

This rule accepts a configuration object with the following properties:

### allowInParentheses

type: `boolean`

default: `true`

If this option is set to `false`, this rule disallows the comma operator
even when the expression sequence is explicitly wrapped in parentheses.

## How to use

## Version

This rule was added in v1.33.0.

## References

---

---
url: /docs/guide/usage/linter/rules/eslint/no-setter-return.md
---

### What it does

Setters cannot return values.

This rule can be disabled for TypeScript code, as the TypeScript compiler
enforces this check.

### Why is this bad?

While returning a value from a setter does not produce an error, the returned value is
being ignored. Therefore, returning a value from a setter is either unnecessary or a
possible error, since the returned value cannot be used.

### Examples

Examples of **incorrect** code for this rule:

```javascript
class URL {
  set origin() {
    return true;
  }
}
```

## How to use

## Version

This rule was added in v0.0.3.

## References

---

---
url: /docs/guide/usage/linter/rules/eslint/no-shadow.md
---

### What it does

Disallows variable declarations from shadowing variables declared in the outer scope.

### Why is this bad?

Shadowing is the process by which a local variable shares the same name as a variable
in its containing scope. This can cause confusion, as it may be unclear which variable
is being referenced, and can lead to bugs that are difficult to diagnose.

### Examples

Examples of **incorrect** code for this rule:

```js
var x = 1;
function foo() {
  var x = 2; // x shadows the outer x
}
```

Examples of **correct** code for this rule:

```js
var x = 1;
function foo() {
  var y = 2; // different name, no shadowing
}
```

## Configuration

This rule accepts a configuration object with the following properties:

### allow

type: `string[]`

default: `[]`

List of variable names that are allowed to shadow.

### builtinGlobals

type: `boolean`

default: `false`

Whether to report shadowing of built-in global variables.

### hoist

type: `"all" | "functions" | "functions-and-types" | "never" | "types"`

default: `"functions-and-types"`

Controls how hoisting is handled when checking for shadowing.

#### `"all"`

Report shadowing even before the outer variable is declared (due to hoisting).

#### `"functions"`

Only report shadowing for function declarations that are hoisted.

#### `"functions-and-types"`

Report shadowing for both function and type declarations that are hoisted.

#### `"never"`

Never report shadowing before the outer variable is declared.

#### `"types"`

Only report shadowing for type declarations that are hoisted.

### ignoreFunctionTypeParameterNameValueShadow

type: `boolean`

default: `true`

If `true`, ignore when a function type parameter shadows a value.
Example: `const T = 1; function foo<T>() {}`

### ignoreOnInitialization

type: `boolean`

default: `false`

Whether to ignore the variable initializers when the shadowed variable is presumably still uninitialized.

### ignoreTypeValueShadow

type: `boolean`

default: `true`

If `true`, ignore when a type and a value have the same name.
This is common in TypeScript: `type Foo = ...; const Foo = ...;`

## How to use

## Version

This rule was added in v1.48.0.

## References

---

---
url: /docs/guide/usage/linter/rules/eslint/no-shadow-restricted-names.md
---

### What it does

Disallows the redefining of global variables such as `undefined`, `NaN`, `Infinity`,
`eval`, `globalThis` and `arguments`.

### Why is this bad?

Value properties of the Global Object `NaN`, `Infinity`, `undefined`, `globalThis` as well as the strict
mode restricted identifiers `eval` and `arguments` are considered to be restricted names in
JavaScript. Defining them to mean something else can have unintended consequences and
confuse others reading the code. For example, there’s nothing preventing you from
writing:

```javascript
var undefined = "foo";
```

Then any code used within the same scope would not get the global `undefined`, but rather the
local version with a very different meaning.

### Examples

Examples of **incorrect** code for this rule:

```javascript
function NaN() {}

!function (Infinity) {};

var undefined = 5;

try {
} catch (eval) {}

const globalThis = "foo";
```

```javascript
import NaN from "foo";

import { undefined } from "bar";

class Infinity {}
```

Examples of **correct** code for this rule:

```javascript
var Object;

function f(a, b) {}

// Exception: `undefined` may be shadowed if the variable is never assigned a value.
var undefined;
```

```javascript
import { undefined as undef } from "bar";
```

## Configuration

This rule accepts a configuration object with the following properties:

### reportGlobalThis

type: `boolean`

default: `true`

If true, also report shadowing of `globalThis`.

## How to use

## Version

This rule was added in v0.0.3.

## References

---

---
url: /docs/guide/usage/linter/rules/eslint/no-sparse-arrays.md
---

### What it does

Disallow sparse arrays.

### Why is this bad?

Take the following example:

```javascript
const items = [, ,];
```

While the items array in this example has a length of 2, there are actually
no values in items\[0] or items\[1]. The fact that the array literal is
valid with only commas inside, coupled with the length being set and
actual item values not being set, make sparse arrays confusing for many
developers.

The confusion around sparse arrays is enough that it’s recommended to
avoid using them unless you are certain that they are useful in your
code.

### Examples

Examples of **incorrect** code for this rule:

```javascript
var items = [, ,];
```

```javascript
var colors = ["red", , "blue"];
```

Examples of **correct** code for this rule:

```javascript
var items = [];
```

// trailing comma (after the last element) is not a problem

```javascript
var colors = ["red", "blue"];
```

## How to use

## Version

This rule was added in v0.0.4.

## References

---

---
url: /docs/guide/usage/linter/rules/eslint/no-template-curly-in-string.md
---

### What it does

Disallow template literal placeholder syntax in regular strings. This rule ensures that
expressions like `${variable}` are only used within template literals, avoiding incorrect
usage in regular strings.

### Why is this bad?

ECMAScript 6 allows programmers to create strings containing variables or expressions using
template literals. This is done by embedding expressions like `${variable}` between backticks.
If regular quotes (`'` or `"`) are used with template literal syntax, it results in the literal
string `"${variable}"` instead of evaluating the expression. This rule helps to avoid this mistake,
ensuring that expressions are correctly evaluated inside template literals.

### Examples

Examples of **incorrect** code for this rule:

```javascript
"Hello ${name}!";
"Hello ${name}!";
"Time: ${12 * 60 * 60 * 1000}";
```

Examples of **correct** code for this rule:

```javascript
`Hello ${name}!`;
`Time: ${12 * 60 * 60 * 1000}`;
templateFunction`Hello ${name}`;
```

## How to use

## Version

This rule was added in v0.2.14.

## References

---

---
url: /docs/guide/usage/linter/rules/eslint/no-ternary.md
---

### What it does

Disallow ternary operators.

### Why is this bad?

The ternary operator is used to conditionally assign a value to a
variable. Some believe that the use of ternary operators leads to
unclear code.

### Examples

Examples of **incorrect** code for this rule:

```javascript
var foo = isBar ? baz : qux;
```

```javascript
function quux() {
  return foo ? bar() : baz();
}
```

Examples of **correct** code for this rule:

```javascript
let foo;

if (isBar) {
  foo = baz;
} else {
  foo = qux;
}
```

```javascript
function quux() {
  if (foo) {
    return bar();
  } else {
    return baz();
  }
}
```

## How to use

## Version

This rule was added in v0.2.14.

## References

---

---
url: /docs/guide/usage/linter/rules/eslint/no-this-before-super.md
---

### What it does

Requires calling `super()` before using `this` or `super`.

This rule can be disabled for TypeScript code, as the TypeScript compiler
enforces this check.

### Why is this bad?

In the constructor of derived classes, if `this`/`super` are used before `super()` calls,
it raises a `ReferenceError`.

### Examples

Examples of **incorrect** code for this rule:

```javascript
class A1 extends B {
  constructor() {
    // super() needs to be called first
    this.a = 0;
    super();
  }
}
```

## How to use

## Version

This rule was added in v0.2.6.

## References

---

---
url: /docs/guide/usage/linter/rules/eslint/no-throw-literal.md
---

### What it does

Disallows throwing literals or non-Error objects as exceptions.

::: warning
This rule has been deprecated, please instead use [typescript/only-throw-error](https://oxc.rs/docs/guide/usage/linter/rules/typescript/only-throw-error.html).
The typescript rule is more reliable than the Javascript version, as it has less false positive, and can catch more cases.
:::

### 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;
}
```

## How to use

## Version

This rule was added in v0.9.10.

## References

---

---
url: /docs/guide/usage/linter/rules/eslint/no-unassigned-vars.md
---

### What it does

Disallow let or var variables that are read but never assigned.

### Why is this bad?

This rule flags let or var declarations that are never assigned a value but are still read or used in the code.
Since these variables will always be `undefined`, their usage is likely a programming mistake.

### Examples

Examples of **incorrect** code for this rule:

```js
let status;
if (status === "ready") {
  console.log("Ready!");
}
```

Examples of **correct** code for this rule:

```js
let message = "hello";
console.log(message);

let user;
user = getUser();
console.log(user.name);
```

## How to use

## Version

This rule was added in v1.10.0.

## References

---

---
url: /docs/guide/usage/linter/rules/eslint/no-undef.md
---

### What it does

Disallow the use of undeclared variables.

This rule can be disabled for TypeScript code, as the TypeScript compiler
enforces this check.

### Why is this bad?

It is most likely a potential ReferenceError caused by a misspelling
of a variable or parameter name.

### Examples

Examples of **incorrect** code for this rule:

```javascript
var foo = someFunction();
var bar = a + 1;
```

## Configuration

This rule accepts a configuration object with the following properties:

### typeof

type: `boolean`

default: `false`

When set to `true`, warns on undefined variables used in a `typeof` expression.

## How to use

## Version

This rule was added in v0.0.8.

## References

---

---
url: /docs/guide/usage/linter/rules/eslint/no-undefined.md
---

### What it does

Disallow the use of `undefined` as an identifier.

### Why is this bad?

Using `undefined` directly can lead to bugs, since it can be shadowed or overwritten in JavaScript.
It's safer and more intentional to use `null` or rely on implicit `undefined` (e.g., missing return) to avoid accidental issues.

### Examples

Examples of **incorrect** code for this rule:

```javascript
var foo = undefined;

var undefined = "foo";

if (foo === undefined) {
  // ...
}

function baz(undefined) {
  // ...
}

bar(undefined, "lorem");
```

Examples of **correct** code for this rule:

```javascript
var foo = void 0;

var Undefined = "foo";

if (typeof foo === "undefined") {
  // ...
}

global.undefined = "foo";

bar(void 0, "lorem");
```

## How to use

## Version

This rule was added in v0.5.3.

## References

---

---
url: /docs/guide/usage/linter/rules/eslint/no-underscore-dangle.md
---

### What it does

Disallows dangling underscores in identifiers.

### Why is this bad?

There is a long history of using `_` as a prefix or suffix for private members in JavaScript.
It is however recommended to use the formal private class feature introduced in ES2022.
See <https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Classes/Private_elements> for more information.

### Examples

Examples of **incorrect** code for this rule:

```js
let foo_;
const __proto__ = {};
foo._bar();
```

Examples of **correct** code for this rule:

```js
const _ = require("underscore");
const obj = _.contains(items, item);
obj.__proto__ = {};
const file = __filename;
function foo(_bar) {}
const bar = { onClick(_bar) {} };
const baz = (_bar) => {};
```

## Configuration

### allow

type: `string[]`

default: `[]`

An array of variable names that are allowed to have dangling underscores.

### allowAfterSuper

type: `boolean`

default: `false`

Whether to allow dangling underscores in members of the `super` object.

### allowAfterThis

type: `boolean`

default: `false`

Whether to allow dangling underscores in members of the `this` object.

### allowAfterThisConstructor

type: `boolean`

default: `false`

Whether to allow dangling underscores in members of the `this.constructor` object.

### allowFunctionParams

type: `boolean`

default: `true`

Whether to allow dangling underscores in function parameter names.

### allowInArrayDestructuring

type: `boolean`

default: `true`

Whether to allow dangling underscores in variable names assigned by array destructuring.

### allowInObjectDestructuring

type: `boolean`

default: `true`

Whether to allow dangling underscores in variable names assigned by object destructuring.

### allowInUsingDeclarations

type: `boolean`

default: `false`

Whether to allow dangling underscores in `using` and `await using` declarations.

### enforceInClassFields

type: `boolean`

default: `false`

Whether to enforce dangling underscores in class field names.

### enforceInMethodNames

type: `boolean`

default: `false`

Whether to enforce dangling underscores in method names.

## How to use

## Version

This rule was added in v1.62.0.

## References

---

---
url: /docs/guide/usage/linter/rules/eslint/no-unexpected-multiline.md
---

### What it does

In most cases, semicolons are not required in JavaScript in order for code to be parsed
and executed as expected. Typically this occurs because semicolons are automatically
inserted based on a fixed set of rules. This rule exists to detect those cases where a semicolon
is NOT inserted automatically, and may be parsed differently than expected.

### Why is this bad?

Code that has unexpected newlines may be parsed and executed differently than what the
developer intended. This can lead to bugs that are difficult to track down.

### Examples

Examples of **incorrect** code for this rule:

```js
var a = b(x || y).doSomething();

var a = b[(a, b, c)].forEach(doSomething);

let x = (function () {})`hello`;

foo / bar / g.test(baz);
```

Examples of **correct** code for this rule:

```js
var a = b;
(x || y).doSomething();

var a = b;
[a, b, c].forEach(doSomething);

let x = function () {};
`hello`;

foo;
/bar/g.test(baz);
```

## How to use

## Version

This rule was added in v0.9.7.

## References

---

---
url: /docs/guide/usage/linter/rules/eslint/no-unmodified-loop-condition.md
---

### What it does

Disallow references in loop conditions that are never modified within the loop.

### Why is this bad?

A loop condition that depends on values that never change within the loop body
can cause infinite loops or logic bugs.

### Examples

Examples of **incorrect** code for this rule:

```js
let done = false;
while (!done) {
  work();
}
```

Examples of **correct** code for this rule:

```js
let done = false;
while (!done) {
  done = checkDone();
}
```

## How to use

## Version

This rule was added in v1.48.0.

## References

---

---
url: /docs/guide/usage/linter/rules/eslint/no-unneeded-ternary.md
---

### What it does

Disallow ternary operators when simpler alternatives exist.

### Why is this bad?

It’s a common mistake in JavaScript to use a conditional expression to select between two
Boolean values instead of using ! to convert the test to a Boolean.

Another common mistake is using a single variable as both the conditional test and the
consequent. In such cases, the logical OR can be used to provide the same functionality.

### Examples

Examples of **incorrect** code for this rule:

```js
const isYes = answer === 1 ? true : false;
const isNo = answer === 1 ? false : true;

foo(bar ? bar : 1);
```

Examples of **correct** code for this rule:

```js
const isYes = answer === 1;
const isNo = answer !== 1;

foo(bar || 1);
```

## Configuration

This rule accepts a configuration object with the following properties:

### defaultAssignment

type: `boolean`

default: `true`

Whether to allow the default assignment pattern `x ? x : y`.

When set to `false`, the rule also flags cases like `x ? x : y` and suggests using
the logical OR form `x || y` instead. When `true` (default), such default assignments
are allowed and not reported.

## How to use

## Version

This rule was added in v0.15.12.

## References

---

---
url: /docs/guide/usage/linter/rules/eslint/no-unreachable.md
---

### What it does

Disallow unreachable code after `return`, `throw`, `continue`, and `break` statements.

This rule can be disabled for TypeScript code if `allowUnreachableCode: false` is configured
in the `tsconfig.json`, as the TypeScript compiler enforces this check.

### Why is this bad?

Unreachable code after a `return`, `throw`, `continue`, or `break` statement can never be run.

### Examples

Examples of **incorrect** code for this rule:

```ts
function foo() {
  return 2;
  console.log("this will never be executed");
}
```

Examples of **correct** code for this rule:

```ts
function foo() {
  console.log("this will be executed");
  return 2;
}
```

## How to use

## Version

This rule was added in v0.4.4.

## References

---

---
url: /docs/guide/usage/linter/rules/eslint/no-unreachable-loop.md
---

### What it does

Disallow loops whose body allows only one iteration.

### Why is this bad?

A loop that always exits before a second iteration is usually accidental
and can be replaced with simpler control flow.

### Examples

Examples of **incorrect** code for this rule:

```js
for (const item of items) {
  console.log(item);
  break;
}
```

Examples of **correct** code for this rule:

```js
for (const item of items) {
  console.log(item);
}
```

## Configuration

### ignore

type: `array`

#### ignore\[n]

type: `"WhileStatement" | "DoWhileStatement" | "ForStatement" | "ForInStatement" | "ForOfStatement"`

## How to use

## Version

This rule was added in vnext.

## References

---

---
url: /docs/guide/usage/linter/rules/eslint/no-unsafe-finally.md
---

### What it does

Disallow control flow statements in `finally` blocks.

### Why is this bad?

JavaScript suspends the control flow statements of `try` and `catch`
blocks until the execution of a `finally` block finishes.

So, when `return`, `throw`, `break`, or `continue` is used in `finally`,
control flow statements inside `try` and `catch` are overwritten.
This is possibly unexpected behavior for the developer.

### Examples

Examples of **incorrect** code for this rule:

```javascript
// We expect this function to return 1;
(() => {
  try {
    return 1; // 1 is returned but suspended until finally block ends
  } catch (err) {
    return 2;
  } finally {
    return 3; // 3 is returned before 1, which we did not expect
  }
})();

// > 3
```

## How to use

## Version

This rule was added in v0.0.5.

## References

---

---
url: /docs/guide/usage/linter/rules/eslint/no-unsafe-negation.md
---

### What it does

Disallows negating the left operand of relational operators to prevent logical errors
caused by misunderstanding operator precedence or accidental use of negation.

This rule can be disabled for TypeScript code, as the TypeScript compiler
enforces this check.

### Why is this bad?

Negating the left operand of relational operators can result in unexpected behavior due to
operator precedence, leading to logical errors. For instance, `!a in b` may be interpreted
as `(!a) in b` instead of `!(a in b)`, which is not the intended logic.

### Examples

Examples of **incorrect** code for this rule:

```javascript
if (!key in object) {}

if (!obj instanceof Ctor) {}
```

Examples of **correct** code for this rule:

```javascript
if (!(key in object)) {}

if (!(obj instanceof Ctor)) {}
```

## Configuration

This rule accepts a configuration object with the following properties:

### enforceForOrderingRelations

type: `boolean`

default: `false`

The `enforceForOrderingRelations` option determines whether negation is allowed
on the left-hand side of ordering relational operators (<, >, <=, >=).

The purpose is to avoid expressions such as `!a < b` (which is equivalent to `(a ? 0 : 1) < b`)
when what is really intended is `!(a < b)`.

## How to use

## Version

This rule was added in v0.0.3.

## References

---

---
url: /docs/guide/usage/linter/rules/eslint/no-unsafe-optional-chaining.md
---

### What it does

Disallow use of optional chaining in contexts where the `undefined` value is not allowed.

### Why is this bad?

The optional chaining (`?.`) expression can short-circuit with a return value of `undefined`.
Therefore, treating an evaluated optional chaining expression as a function, object, number, etc.,
can cause TypeError or unexpected results. For example:

### Examples

Examples of **incorrect** code for this rule:

```javascript
var obj = undefined;
1 in obj?.foo; // TypeError
with (obj?.foo); // TypeError
for (bar of obj?.foo); // TypeError
bar instanceof obj?.foo; // TypeError
const { bar } = obj?.foo; // TypeError
```

## Configuration

This rule accepts a configuration object with the following properties:

### disallowArithmeticOperators

type: `boolean`

default: `false`

Disallow arithmetic operations on optional chaining expressions.
If this is true, this rule warns arithmetic operations on optional chaining expressions, which possibly result in NaN.

## How to use

## Version

This rule was added in v0.0.5.

## References

---

---
url: /docs/guide/usage/linter/rules/eslint/no-unused-expressions.md
---

### What it does

This rule disallows unused expressions.

### Why is this bad?

Unused expressions are usually a mistake. They can be a symptom of a bug or a misunderstanding of the code.

### Examples

Examples of **incorrect** code for this rule:

```ts
Set<number>;
1 as number;
window!;
```

Examples of **correct** code for this rule:

```ts
const foo = new Set<number>();
```

## Configuration

This rule accepts a configuration object with the following properties:

### allowShortCircuit

type: `boolean`

default: `false`

When set to `true`, allows short circuit evaluations in expressions.

### allowTaggedTemplates

type: `boolean`

default: `false`

When set to `true`, allows tagged template literals in expressions.

### allowTernary

type: `boolean`

default: `false`

When set to `true`, allows ternary operators in expressions.

### enforceForJSX

type: `boolean`

default: `false`

When set to `true`, enforces the rule for unused JSX expressions also.

### ignoreDirectives

type: `boolean`

default: `false`

When set to `true`, allows directive prologues.

## How to use

## Version

This rule was added in v0.14.0.

## References

---

---
url: /docs/guide/usage/linter/rules/eslint/no-unused-labels.md
---

### What it does

Disallow unused labels.

### Why is this bad?

Labels that are declared and not used anywhere in the code are most likely an error due to incomplete refactoring.

### Examples

Examples of **incorrect** code for this rule:

```javascript
OUTER_LOOP: for (const student of students) {
  if (checkScores(student.scores)) {
    continue;
  }
  doSomething(student);
}
```

Examples of **correct** code for this rule:

```javascript
for (const student of students) {
  if (checkScores(student.scores)) {
    continue;
  }
  doSomething(student);
}
```

## How to use

## Version

This rule was added in v0.0.3.

## References

---

---
url: /docs/guide/usage/linter/rules/eslint/no-unused-private-class-members.md
---

### What it does

Disallow unused private class members.

### Why is this bad?

Private class members that are declared and not used anywhere in the code are most likely an error due to incomplete refactoring. Such class members take up space in the code and can lead to confusion by readers.

### Examples

Examples of **incorrect** code for this rule:

```javascript
class A {
  #unusedMember = 5;
}

class B {
  #usedOnlyInWrite = 5;
  method() {
    this.#usedOnlyInWrite = 42;
  }
}

class C {
  #usedOnlyToUpdateItself = 5;
  method() {
    this.#usedOnlyToUpdateItself++;
  }
}

class D {
  #unusedMethod() {}
}

class E {
  get #unusedAccessor() {}
  set #unusedAccessor(value) {}
}
```

Examples of **correct** code for this rule:

```javascript
class A {
  #usedMember = 42;
  method() {
    return this.#usedMember;
  }
}

class B {
  #usedMethod() {
    return 42;
  }
  anotherMethod() {
    return this.#usedMethod();
  }
}

class C {
  get #usedAccessor() {}
  set #usedAccessor(value) {}

  method() {
    this.#usedAccessor = 42;
  }
}
```

## How to use

## Version

This rule was added in v0.1.1.

## References

---

---
url: /docs/guide/usage/linter/rules/eslint/no-unused-vars.md
---

### What it does

Disallows variable declarations, imports, or type declarations that are
not used in code.

### Why is this bad?

Variables that are declared and not used anywhere in the code are most
likely an error due to incomplete refactoring. Such variables take up
space in the code and can lead to confusion by readers.

```ts
// `b` is unused; this indicates a bug.
function add(a: number, b: number) {
  return a;
}
console.log(add(1, 2));
```

A variable `foo` is considered to be used if any of the following are
true:

* It is called (`foo()`) or constructed (`new foo()`)
* It is read (`var bar = foo`)
* It is passed into a function or constructor as an argument (`doSomething(foo)`)
* It is read inside of a function that is passed to another function
  (`doSomething(function() { foo(); })`)
* It is exported (`export const foo = 42`)
* It is used as an operand to TypeScript's `typeof` operator (`const bar:
  typeof foo = 4`)

A variable is *not* considered to be used if it is only ever declared
(`var foo = 5`) or assigned to (`foo = 7`).

#### Types

This rule has full support for TypeScript types, interfaces, enums, and
namespaces.

A type or interface `Foo` is considered to be used if it is used in any
of the following ways:

* It is used in the definition of another type or interface.
* It is used as a type annotation or as part of a function signature.
* It is used in a cast or `satisfies` expression.

A type or interface is *not* considered to be used if it is only ever
used in its own definition, e.g. `type Foo = Array<Foo>`.

Enums and namespaces are treated the same as variables, classes,
functions, etc.

#### Ignored Files

This rule ignores `.d.ts`, `.astro`, `.svelte` and `.vue` files entirely. Variables,
classes, interfaces, and types declared in `.d.ts` files are generally
used by other files, which are not checked by Oxlint. Since Oxlint does
not support parsing template syntax, this rule cannot tell if a variable
is used or unused in a Vue / Svelte / Astro file.

#### Exported

The original ESLint rule recognizes `/* exported variableName */`
comments as a way to indicate that a variable is used in another script
and should not be considered unused. Since ES modules are now a TC39
standard, Oxlint does not support this feature.

### Examples

Examples of **incorrect** code for this rule:

```javascript
/* no-unused-vars: "error" */
/* if you have `some_unused_var` defined as a global in .oxlintrc.json */

// It checks variables you have defined as global
some_unused_var = 42;

var x;

// Write-only variables are not considered as used.
var y = 10;
y = 5;

// A read for a modification of itself is not considered as used.
var z = 0;
z = z + 1;

// By default, unused arguments cause warnings.
(function (foo) {
  return 5;
})();

// Unused recursive functions also cause warnings.
function fact(n) {
  if (n < 2) return 1;
  return n * fact(n - 1);
}

// When a function definition destructures an array, unused entries from
// the array also cause warnings.
function getY([x, y]) {
  return y;
}
```

```ts
type A = Array<A>;

enum Color {
  Red,
  Green,
  Blue,
}
```

Examples of **correct** code for this rule:

```js
/* no-unused-vars: "error" */

var x = 10;
alert(x);

// foo is considered used here
myFunc(
  function foo() {
    // ...
  }.bind(this),
);

(function (foo) {
  return foo;
})();

var myFunc;
myFunc = setTimeout(function () {
  // myFunc is considered used
  myFunc();
}, 50);

// Only the second argument from the destructured array is used.
function getY([, y]) {
  return y;
}
```

```ts
export const x = 1;
const y = 1;
export { y };

type A = Record<string, unknown>;
type B<T> = T extends Record<infer K, any> ? K : never;
const x = "foo" as B<A>;
console.log(x);
```

Examples of **incorrect** code for `/* exported variableName */` operation:

```js
/* exported global_var */

// Not respected, use ES modules instead.
var global_var = 42;
```

## Configuration

### args

type: `"after-used" | "all" | "none"`

Controls how unused arguments are checked.

#### `"after-used"`

Unused positional arguments that occur before the last used argument
will not be checked, but all named arguments and all positional
arguments after the last used argument will be checked.

#### `"all"`

All named arguments must be used

#### `"none"`

Do not check arguments

### argsIgnorePattern

type: `string`

Specifies exceptions to this rule for unused arguments. Arguments whose
names match this pattern will be ignored.

By default, this pattern is `^_` unless options are configured with an
object. In this case it will default to \[`None`]. Note that this
behavior deviates from both ESLint and TypeScript-ESLint, which never
provide a default pattern.

#### Example

Examples of **correct** code for this option when the pattern is `^_`:

```javascript
function foo(_a, b) {
  console.log(b);
}
foo(1, 2);
```

### caughtErrors

type: `"all" | "none"`

Used for `catch` block validation.

#### `"all"`

All named arguments must be used.

#### `"none"`

Do not check error objects.

### caughtErrorsIgnorePattern

type: `string`

Specifies exceptions to this rule for errors caught within a `catch` block.
Variables declared within a `catch` block whose names match this pattern
will be ignored.

#### Example

Examples of **correct** code when the pattern is `^ignore`:

```javascript
try {
  // ...
} catch (ignoreErr) {
  console.error("Error caught in catch block");
}
```

### destructuredArrayIgnorePattern

type: `string`

This option specifies exceptions within destructuring patterns that will
not be checked for usage. Variables declared within array destructuring
whose names match this pattern will be ignored.

By default this pattern is unset.

#### Example

Examples of **correct** code for this option, when the pattern is `^_`:

```javascript
const [a, _b, c] = ["a", "b", "c"];
console.log(a + c);

const {
  x: [_a, foo],
} = bar;
console.log(foo);

let _m, n;
foo.forEach((item) => {
  [_m, n] = item;
  console.log(n);
});
```

### fix

type: `object`

Controls which `no-unused-vars` auto-fixes are emitted.

When omitted, both `imports` and `variables` default to `"suggestion"`,
preserving the current behavior.

NOTE: This option is experimental and may change based on feedback.

Fine-grained auto-fix controls for `no-unused-vars`.

#### fix.imports

type: `"off" | "suggestion" | "fix" | "safe-fix"`

Controls auto-fixes for unused imports.

##### `"off"`

Disable auto-fixes for this symbol kind.

##### `"suggestion"`

Emit suggestion-style fixes (current behavior).

##### `"fix"`

Emit fix-style fixes.

##### `"safe-fix"`

Like `Fix`, but does not mark them as dangerous.
Only applicable for imports, unavailable for variables.

#### fix.variables

type: `"off" | "suggestion" | "fix" | "safe-fix"`

Controls auto-fixes for unused variables (including catch bindings).

##### `"off"`

Disable auto-fixes for this symbol kind.

##### `"suggestion"`

Emit suggestion-style fixes (current behavior).

##### `"fix"`

Emit fix-style fixes.

##### `"safe-fix"`

Like `Fix`, but does not mark them as dangerous.
Only applicable for imports, unavailable for variables.

### ignoreClassWithStaticInitBlock

type: `boolean`

default: `false`

The `ignoreClassWithStaticInitBlock` option is a boolean. Static
initialization blocks allow you to initialize static variables and
execute code during the evaluation of a class definition, meaning
the static block code is executed without creating a new instance
of the class. When set to `true`, this option ignores classes
containing static initialization blocks.

#### Example

Examples of **incorrect** code for the `{ "ignoreClassWithStaticInitBlock": true }` option

```javascript
/* no-unused-vars: ["error", { "ignoreClassWithStaticInitBlock": true }]*/

class Foo {
  static myProperty = "some string";
  static mymethod() {
    return "some string";
  }
}

class Bar {
  static {
    let baz; // unused variable
  }
}
```

Examples of **correct** code for the `{ "ignoreClassWithStaticInitBlock": true }` option

```javascript
/* no-unused-vars: ["error", { "ignoreClassWithStaticInitBlock": true }]*/

class Foo {
  static {
    let bar = "some string";

    console.log(bar);
  }
}
```

### ignoreRestSiblings

type: `boolean`

default: `false`

Using a Rest property it is possible to "omit" properties from an
object, but by default the sibling properties are marked as "unused".
With this option enabled the rest property's siblings are ignored.

#### Example

Examples of **correct** code when this option is set to `true`:

```js
// 'foo' and 'bar' were ignored because they have a rest property sibling.
var { foo, ...coords } = data;

var bar;
({ bar, ...coords } = data);
```

### ignoreUsingDeclarations

type: `boolean`

default: `false`

When set to `true`, the rule will ignore variables declared with
`using` or `await using` declarations, even if they are unused.

This is useful when working with resources that need to be disposed
via the explicit resource management proposal, where the primary
purpose is the disposal side effect rather than using the resource.

#### Example

Examples of **correct** code for the `{ "ignoreUsingDeclarations": true }` option:

```javascript
/* no-unused-vars: ["error", { "ignoreUsingDeclarations": true }]*/

using resource = getResource();
await using anotherResource = getAnotherResource();
```

### reportUsedIgnorePattern

type: `boolean`

default: `false`

The `reportUsedIgnorePattern` option is a boolean.
Using this option will report variables that match any of the valid
ignore pattern options (`varsIgnorePattern`, `argsIgnorePattern`,
`caughtErrorsIgnorePattern`, or `destructuredArrayIgnorePattern`) if
they have been used.

#### Example

Examples of **incorrect** code for the `{ "reportUsedIgnorePattern": true }` option:

```javascript
/* no-unused-vars: ["error", { "reportUsedIgnorePattern": true, "varsIgnorePattern": "[iI]gnored" }]*/

var firstVarIgnored = 1;
var secondVar = 2;
console.log(firstVarIgnored, secondVar);
```

Examples of **correct** code for the `{ "reportUsedIgnorePattern": true }` option:

```javascript
/* no-unused-vars: ["error", { "reportUsedIgnorePattern": true, "varsIgnorePattern": "[iI]gnored" }]*/

var firstVar = 1;
var secondVar = 2;
console.log(firstVar, secondVar);
```

### reportVarsOnlyUsedAsTypes

type: `boolean`

default: `false`

The `reportVarsOnlyUsedAsTypes` option is a boolean.

If `true`, the rule will also report variables that are only used as types.

#### Examples

Examples of **incorrect** code for the `{ "reportVarsOnlyUsedAsTypes": true }` option:

```javascript
/*  no-unused-vars: ["error", { "reportVarsOnlyUsedAsTypes": true }] */

const myNumber: number = 4;
export type MyNumber = typeof myNumber
```

Examples of **correct** code for the `{ "reportVarsOnlyUsedAsTypes": true }` option:

```javascript
export type MyNumber = number;
```

Note: even with `{ "reportVarsOnlyUsedAsTypes": false }`, cases where the value is
only used a type within itself will still be reported:

```javascript
function foo(): typeof foo {}
```

### vars

type: `"all" | "local"`

Controls how usage of a variable in the global scope is checked.

#### `"all"`

All variables are checked for usage, including those in the global scope.

#### `"local"`

Checks only that locally-declared variables are used but will allow
global variables to be unused.

### varsIgnorePattern

type: `string`

Specifies exceptions to this rule for unused variables. Variables whose
names match this pattern will be ignored.

By default, this pattern is `^_` unless options are configured with an
object. In this case it will default to \[`None`]. Note that this
behavior deviates from both ESLint and TypeScript-ESLint, which never
provide a default pattern.

#### Example

Examples of **correct** code for this option when the pattern is `^_`:

```javascript
var _a = 10;
var b = 10;
console.log(b);
```

## How to use

## Version

This rule was added in v0.7.0.

## References

---

---
url: /docs/guide/usage/linter/rules/eslint/no-use-before-define.md
---

### What it does

Disallows using variables before they are defined.

### Why is this bad?

Referencing identifiers before their declarations can hide bugs and
make code order-dependent and difficult to reason about.

### Examples

Examples of **incorrect** code for this rule:

```ts
new A();
var A = class {};
```

Examples of **correct** code for this rule:

```ts
var A = class {};
new A();
```

## Configuration

### allowNamedExports

type: `boolean`

default: `false`

Allow named exports that appear before declaration.

### classes

type: `boolean`

default: `true`

Check class declarations.

### enums

type: `boolean`

default: `true`

Check enum declarations.

### functions

type: `boolean`

default: `true`

Check function declarations.

### ignoreTypeReferences

type: `boolean`

default: `true`

Ignore usages that are type-only references.

### typedefs

type: `boolean`

default: `true`

Check type aliases, interfaces, and type parameters.

### variables

type: `boolean`

default: `true`

Check variable declarations.

## How to use

## Version

This rule was added in v1.49.0.

## References

---

---
url: /docs/guide/usage/linter/rules/eslint/no-useless-assignment.md
---

### What it does

Flags assignments where the newly assigned value is never read afterward (a "dead store"). This helps catch wasted work or accidental mistakes.

### Why is this bad?

Dead stores add noise and can hide real bugs (e.g., you meant to use that value or wrote to the wrong variable). Removing them improves clarity and performance.

### Examples

Examples of **incorrect** code for this rule:

```js
function fn1() {
  let v = "used";
  doSomething(v);
  v = "unused"; // assigned but never read
}

function fn2() {
  let v = "used";
  if (condition) {
    v = "unused"; // early return; this write is never observed
    return;
  }
  doSomething(v);
}

function fn3() {
  let v = "used";
  if (condition) {
    doSomething(v);
  } else {
    v = "unused"; // value not used later in this branch
  }
}
```

Examples of **correct** code for this rule:

```js
function fn1() {
  let v = "used";
  doSomething(v);
  v = "used-2";
  doSomething(v); // the reassigned value is read
}

function fn2() {
  let v = "used";
  if (condition) {
    v = "used-2";
    doSomething(v); // reassignment is observed before returning
    return;
  }
  doSomething(v);
}

function fn3() {
  let v = "used";
  for (let i = 0; i < 10; i++) {
    doSomething(v);
    v = "used in next iteration"; // used on the next loop pass
  }
}
```

## How to use

## Version

This rule was added in v1.59.0.

## References

---

---
url: /docs/guide/usage/linter/rules/eslint/no-useless-backreference.md
---

### What it does

Disallows backreferences in regular expressions that will always be ignored
because the capture group they refer to has not matched and cannot match
at the time the backreference is evaluated.

### Why is this bad?

Useless backreferences can lead to confusing or misleading regular expressions.
They may give the impression that a group’s value is being reused, but due to
the structure of the pattern (e.g., order of evaluation, disjunctions, or negative
lookarounds), the group has not matched anything — so the reference always
resolves to an empty string. This is almost always a mistake and makes patterns
harder to understand and maintain.

### Examples

Examples of **incorrect** code for this rule:

```js
/\1(a)/; // backreference appears before group
/(a|\1b)/; // group and reference are in different alternatives
/(?<=\1(a))b/; // backreference used before group in lookbehind
/\1(?!(a))/; // group is inside negative lookahead
/(a\1)/; // backreference is inside its own group
```

Examples of **correct** code for this rule:

```js
/(a)\1/; // valid — backreference follows completed group
/(?<name>a)\k<name>/; // named group used properly
/(?:a|(b))\1/; // backreference only used when group matches
```

## How to use

## Version

This rule was added in v0.16.10.

## References

---

---
url: /docs/guide/usage/linter/rules/eslint/no-useless-call.md
---

### What it does

Disallow unnecessary calls to `.call()` and `.apply()`

### Why is this bad?

`Function.prototype.call()` and `Function.prototype.apply()` are slower than the normal function invocation.

This rule compares code statically to check whether or not thisArg is changed.
So if the code about thisArg is a dynamic expression, this rule cannot judge correctly.

### Examples

Examples of **incorrect** code for this rule:

```js
// These are the same as `foo(1, 2, 3);`
foo.call(undefined, 1, 2, 3);
foo.apply(undefined, [1, 2, 3]);
foo.call(null, 1, 2, 3);
foo.apply(null, [1, 2, 3]);

// These are the same as `obj.foo(1, 2, 3);`
obj.foo.call(obj, 1, 2, 3);
obj.foo.apply(obj, [1, 2, 3]);
```

Examples of **correct** code for this rule:

```js
// The `this` binding is different.
foo.call(obj, 1, 2, 3);
foo.apply(obj, [1, 2, 3]);
obj.foo.call(null, 1, 2, 3);
obj.foo.apply(null, [1, 2, 3]);
obj.foo.call(otherObj, 1, 2, 3);
obj.foo.apply(otherObj, [1, 2, 3]);

// The argument list is variadic.
// Those are warned by the `prefer-spread` rule.
foo.apply(undefined, args);
foo.apply(null, args);
obj.foo.apply(obj, args);
```

## How to use

## Version

This rule was added in v0.15.9.

## References

---

---
url: /docs/guide/usage/linter/rules/eslint/no-useless-catch.md
---

### What it does

Disallow unnecessary catch clauses.

### Why is this bad?

A catch clause that only rethrows the original error is redundant,
and has no effect on the runtime behavior of the program.
These redundant clauses can be a source of confusion and code bloat,
so it’s better to disallow these unnecessary catch clauses.

### Examples

Examples of **incorrect** code for this rule:

```javascript
try {
  doSomethingThatMightThrow();
} catch (e) {
  throw e;
}
```

Examples of **correct** code for this rule:

```javascript
doSomethingThatMightThrow();
```

## How to use

## Version

This rule was added in v0.0.5.

## References

---

---
url: /docs/guide/usage/linter/rules/eslint/no-useless-computed-key.md
---

### What it does

Disallow unnecessary computed property keys in objects and classes.

### Why is this bad?

It’s unnecessary to use computed properties with literals such as:

```js
const foo = { ["a"]: "b" };
```

The code can be rewritten as:

```js
const foo = { a: "b" };
```

### Examples

Examples of **incorrect** code for this rule:

```js
const a = { ["0"]: 0 };
const b = { ["0+1,234"]: 0 };
const c = { [0]: 0 };
const e = { ["x"]() {} };

class Foo {
  ["foo"] = "bar";
  [0]() {}
  static ["foo"] = "bar";
  get ["b"]() {}
  set ["c"](value) {}
}
```

Examples of **correct** code for this rule:

```js
const a = { a: 0 };
const b = { 0: 0 };
const c = { x() {} };
const e = { "0+1,234": 0 };

class Foo {
  foo = "bar";
  0() {}
  a() {}
  static foo = "bar";
}
```

Examples of additional **correct** code for this rule:

```js
const c = {
  __proto__: foo, // defines object's prototype
  ["__proto__"]: bar, // defines a property named "__proto__"
};
class Foo {
  ["constructor"]; // instance field named "constructor"
  constructor() {} // the constructor of this class
  static ["constructor"]; // static field named "constructor"
  static ["prototype"]; // runtime error, it would be a parsing error without `[]`
}
```

## Configuration

This rule accepts a configuration object with the following properties:

### enforceForClassMembers

type: `boolean`

default: `true`

The `enforceForClassMembers` option controls whether the rule applies to
class members (methods and properties).

Examples of **correct** code for this rule with the `{ "enforceForClassMembers": false }` option:

```js
class SomeClass {
  ["foo"] = "bar";
  [42] = "baz";
  get ["b"]() {}
  set ["c"](value) {}
  static ["foo"] = "bar";
}
```

## How to use

## Version

This rule was added in v1.16.0.

## References

---

---
url: /docs/guide/usage/linter/rules/eslint/no-useless-concat.md
---

### What it does

Disallow unnecessary concatenation of literals or template literals.

### Why is this bad?

It’s unnecessary to concatenate two strings together when they could
be combined into a single literal.

### Examples

Examples of **incorrect** code for this rule:

```javascript
var foo = "a" + "b";
```

```javascript
var foo = "a" + "b" + "c";
```

Examples of **correct** code for this rule:

```javascript
var foo = "a" + bar;

// When the string concatenation is multiline
var foo = "a" + "b" + "c";
```

## How to use

## Version

This rule was added in v0.4.2.

## References

---

---
url: /docs/guide/usage/linter/rules/eslint/no-useless-constructor.md
---

### What it does

Disallow constructors that can be safely removed without changing how the class works.

### Why is this bad?

ES2015 provides a default class constructor if one is not specified. As
such, it is unnecessary to provide an empty constructor or one that
simply delegates into its parent class.

::: warning
Caveat: This lint rule will report on constructors whose sole purpose
is to change the visibility of a parent constructor, or to expose parameter
properties with modifiers. This is because the rule does not have type
information to determine if the parent constructor is `public`, `protected`,
or `private`.
:::

### Examples

Examples of **incorrect** code for this rule:

```javascript
class A {
  constructor() {}
}

class B extends A {
  constructor(...args) {
    super(...args);
  }
}
```

Examples of **correct** code for this rule:

```javascript
class A {}

class B {
  constructor() {
    doSomething();
  }
}

class C extends A {
  constructor() {
    super("foo");
  }
}

class D extends A {
  constructor() {
    super();
    doSomething();
  }
}
```

## How to use

## Version

This rule was added in v0.4.4.

## References

---

---
url: /docs/guide/usage/linter/rules/eslint/no-useless-escape.md
---

### What it does

Disallow unnecessary escape characters.

### Why is this bad?

Escaping characters unnecessarily has no effect on the behavior of strings or regexes,
and can make code harder to read and understand by adding unnecessary complexity.
This applies to string literals, template literals, and regular expressions.

### Examples

Examples of **incorrect** code for this rule:

```javascript
"\'";
'\"';
"\#";
"\e";
`\"`;
`\"${foo}\"`;
`\#{foo}`;
/\!/;
/\@/;
/[\[]/;
/[a-z\-]/;
```

Examples of **correct** code for this rule:

```javascript
"\"";
'\'';
"\x12";
"\u00a9";
"\371";
"xs\u2111";
`\``;
`\${${foo}}`;
`$\{${foo}}`;
/\\/g;
/\t/g;
/\w\$\*\^\./;
/[[]/;
/[\]]/;
/[a-z-]/;
```

## Configuration

This rule accepts a configuration object with the following properties:

### allowRegexCharacters

type: `string[]`

default: `[]`

An array of characters that are allowed to be escaped unnecessarily in regexes.
For example, setting this to `["#"]` allows `\#` in regexes.

Each string in this array must be a single character.

## How to use

## Version

This rule was added in v0.0.5.

## References

---

---
url: /docs/guide/usage/linter/rules/eslint/no-useless-rename.md
---

### What it does

Disallow renaming import, export, and destructured assignments to the same name.

### Why is this bad?

It is unnecessary to rename a variable to the same name.

### Examples

Examples of **incorrect** code for this rule:

```javascript
import { foo as foo } from "foo";
const { bar: bar } = obj;
export { baz as baz };
```

Examples of **correct** code for this rule:

```javascript
import { foo } from "foo";
const { bar: renamed } = obj;
export { baz };
```

## Configuration

This rule accepts a configuration object with the following properties:

### ignoreDestructuring

type: `boolean`

default: `false`

When set to `true`, allows using the same name in destructurings.

### ignoreExport

type: `boolean`

default: `false`

When set to `true`, allows renaming exports to the same name.

### ignoreImport

type: `boolean`

default: `false`

When set to `true`, allows renaming imports to the same name.

## How to use

## Version

This rule was added in v0.2.14.

## References

---

---
url: /docs/guide/usage/linter/rules/eslint/no-useless-return.md
---

### What it does

Disallows redundant return statements.

### Why is this bad?

A `return;` statement with nothing after it is redundant, and has no effect
on the runtime behavior of a function. This can be confusing, so it's better
to disallow these redundant statements.

### Examples

Examples of **incorrect** code for this rule:

```js
function foo() {
  return;
}

function bar() {
  doSomething();
  return;
}

function baz() {
  if (condition) {
    doSomething();
    return;
  }
}
```

Examples of **correct** code for this rule:

```js
function foo() {
  return 5;
}

function bar() {
  if (condition) {
    return;
  }
  doSomething();
}

function baz() {
  return doSomething();
}
```

## How to use

## Version

This rule was added in v1.32.0.

## References

---

---
url: /docs/guide/usage/linter/rules/eslint/no-var.md
---

### What it does

ECMAScript 2015 allows programmers to create variables with block scope
instead of function scope using the `let` and `const` keywords. Block
scope is common in many other programming languages and helps
programmers avoid mistakes.

### Why is this bad?

Using `var` in an ES2015 environment triggers this error

### Examples

Examples of **incorrect** code for this rule:

```javascript
var x = "y";
var CONFIG = {};
```

Examples of **correct** code for this rule:

```javascript
let x = "y";
const CONFIG = {};
```

## How to use

## Version

This rule was added in v0.1.1.

## References

---

---
url: /docs/guide/usage/linter/rules/eslint/no-void.md
---

### What it does

Disallows the use of the `void` operator.

### Why is this bad?

The `void` operator is often used to get `undefined`, but this is
unnecessary because `undefined` can be used directly instead.

### Examples

Examples of **incorrect** code for this rule:

```ts
void 0;
var foo = void 0;
```

Examples of **correct** code for this rule:

```ts
"var foo = bar()";
"foo.void()";
"foo.void = bar";
```

## Configuration

This rule accepts a configuration object with the following properties:

### allowAsStatement

type: `boolean`

default: `false`

If set to `true`, using `void` as a standalone statement is allowed.

## How to use

## Version

This rule was added in v0.2.5.

## References

---

---
url: /docs/guide/usage/linter/rules/eslint/no-warning-comments.md
---

### What it does

Disallows warning comments such as TODO, FIXME, XXX in code.

### Why is this bad?

Developers often add comments like TODO or FIXME to mark incomplete work or areas
that need attention. While useful during development, these comments can indicate
unfinished code that shouldn't be shipped to production. This rule helps catch
such comments before they make it into production code.

### Examples

Examples of **incorrect** code for this rule:

```javascript
// TODO: implement this feature
function doSomething() {}

// FIXME: this is broken
const x = 1;

/* XXX: hack */
let y = 2;
```

Examples of **correct** code for this rule:

```javascript
// This is a regular comment
function doSomething() {}

// Note: This explains something
const x = 1;
```

## Configuration

This rule accepts a configuration object with the following properties:

### decoration

type: `string[]`

default: `[]`

An array of characters to ignore at the start of comments when `location` is `"start"`.

Useful for ignoring common comment decorations like `*` in JSDoc-style comments.

### location

type: `"start" | "anywhere"`

default: `"start"`

Where to check for the terms.

#### `"start"`

Terms must appear at the start of the comment, after any decoration.

#### `"anywhere"`

Terms can appear anywhere in the comment.

### terms

type: `string[]`

default: `["todo", "fixme", "xxx"]`

An array of terms to match. The matching is case-insensitive.

## How to use

## Version

This rule was added in v1.24.0.

## References

---

---
url: /docs/guide/usage/linter/rules/eslint/no-with.md
---

### What it does

Disallow [`with`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/with) statements.

### Why is this bad?

The with statement is potentially problematic because it adds members
of an object to the current scope, making it impossible to tell what a
variable inside the block actually refers to.

It is generally considered a bad practice and is forbidden in strict mode.

This rule is not necessary in TypeScript code if `alwaysStrict` is enabled.

### Examples

Examples of **incorrect** code for this rule:

```javascript
with (point) {
  r = Math.sqrt(x * x + y * y); // is r a member of point?
}
```

## How to use

## Version

This rule was added in v0.2.14.

## References

---

---
url: /docs/guide/usage/linter/rules/eslint/object-shorthand.md
---

### What it does

Require or disallow method and property shorthand syntax for object literals

### Why is this bad?

Stylistic preference

### Example

Here are a few common examples using the ES5 syntax:

```javascript
var properties = { x: x, y: y, z: z };
var methods = { a: function () {}, b: function () {} };
```

Now here are ES6 equivalents:

```javascript
var properties = { x, y, z };
var methods = { a() {}, b() {} };
```

## Configuration

### The 1st option

type: `"always" | "methods" | "properties" | "consistent" | "consistent-as-needed" | "never"`

### The 2nd option

This option is an object with the following properties:

#### avoidExplicitReturnArrows

type: `boolean`

default: `false`

#### avoidQuotes

type: `boolean`

default: `false`

#### ignoreConstructors

type: `boolean`

default: `false`

#### methodsIgnorePattern

type: `string`

## How to use

## Version

This rule was added in v1.59.0.

## References

---

---
url: /docs/guide/usage/linter/rules/eslint/one-var.md
---

### What it does

Enforces variables to be declared either together or separately.

### Why is this bad?

Consistent declaration grouping makes variable lifetimes and initialization patterns easier
to scan. This rule can require one declaration per scope, one declarator per statement, or
grouping only consecutive declarations.

### Examples

Examples of **incorrect** code for this rule:

```js
var foo = 1;
var bar = 2;
```

Examples of **correct** code for this rule:

```js
var foo = 1,
  bar = 2;
```

## Configuration

Enforces consistent grouping of variable declarations.

type: `object`

## How to use

## Version

This rule was added in vnext.

## References

---

---
url: /docs/guide/usage/linter/rules/eslint/operator-assignment.md
---

### What it does

This rule requires or disallows assignment operator shorthand where possible.
It encourages the use of shorthand assignment operators like `+=`, `-=`, `*=`, `/=`, etc.
to make the code more concise and readable.

### Why is this bad?

JavaScript provides shorthand operators that combine variable assignment and simple
mathematical operations. Failing to use these shorthand operators can lead to unnecessarily
verbose code and can be seen as a missed opportunity for clarity and simplicity.

### Examples

Examples of **incorrect** code for this rule with the default `always` option:

```js
x = x + y;
x = y * x;
x[0] = x[0] / y;
x.y = x.y << z;
```

Examples of **correct** code for this rule with the default `always` option:

```js
x = y;
x += y;
x = y * z;
x = x * y * z;
x[0] /= y;
x[foo()] = x[foo()] % 2;
x = y + x; // `+` is not always commutative (e.g. x = "abc")
```

Examples of **incorrect** code for this rule with the `never` option:

```js
x *= y;
x ^= (y + z) / foo();
```

Examples of **correct** code for this rule with the `never` option:

```js
x = x + y;
x.y = x.y / a.b;
```

## Configuration

This rule accepts one of the following string values:

type: `"always" | "never"`

## How to use

## Version

This rule was added in v0.15.13.

## References

---

---
url: /docs/guide/usage/linter/rules/eslint/prefer-arrow-callback.md
---

### What it does

Requires using arrow functions for callbacks.

### Why is this bad?

Arrow functions are generally better suited for callbacks because they:

* inherit `this` from the surrounding scope, avoiding a common source of bugs;
* are shorter and easier to read;
* cannot be used as constructors, which is desirable for callbacks.

### Examples

Examples of **incorrect** code for this rule:

```js
foo(function (a) {
  return a;
});
foo(
  function () {
    return this.a;
  }.bind(this),
);
```

Examples of **correct** code for this rule:

```js
foo((a) => a);
foo(function* () {
  yield;
});
foo(function () {
  this;
});
foo(function bar() {
  bar();
});
```

## Configuration

### allowNamedFunctions

type: `boolean`

default: `false`

If this option is set to `true`, named function expressions are allowed.

### allowUnboundThis

type: `boolean`

default: `true`

If this option is set to `false`, function expressions that reference `this` are reported even when they are not bound to a `this` value.

## How to use

## Version

This rule was added in v1.65.0.

## References

---

---
url: /docs/guide/usage/linter/rules/eslint/prefer-const.md
---

### What it does

Requires `const` declarations for variables that are never
reassigned after their initial declaration.

#### Ignored Files

This rule ignores `.svelte` and `.vue` files entirely. Oxlint only parses the
`<script>` blocks of these files, so a binding that the template reassigns looks
like it is never reassigned, and turning it into a `const` makes the framework
compiler fail. In Svelte the template writes through `bind:this={el}` and
`bind:value={x}`; in Vue a `<script setup>` `let` is a `setup-let` binding that
`v-model="x"` and inline handlers such as `@click="x = 1"` assign to directly.

### Why is this bad?

If a variable is never reassigned, using the `const` declaration is better.
`const` declaration tells readers, "this variable is never reassigned," reducing cognitive load and improving maintainability.

### Examples

Examples of **incorrect** code for this rule:

```js
let a = 3;
console.log(a);

let b;
b = 0;
console.log(b);

for (let i in [1, 2, 3]) {
  console.log(i);
}
```

Examples of **correct** code for this rule:

```js
const a = 0;

let a;
a = 0;
a = 1;

let a;
if (true) {
  a = 0;
}

for (const i in [1, 2, 3]) {
  console.log(i);
}
```

## Configuration

### destructuring

type: `"any" | "all"`

Configures how destructuring assignments are handled.

#### `"any"`

Warn if any of the variables in a destructuring assignment should be `const`.

#### `"all"`

Only warn if all variables in a destructuring assignment should be `const`. Otherwise, ignore them.

### ignoreReadBeforeAssign

type: `boolean`

default: `false`

If `true`, the rule will not report variables that are read before their initial assignment.
This is mainly useful for preventing conflicts with the `typescript/no-use-before-define` rule.

## How to use

## Version

This rule was added in v1.43.0.

## References

---

---
url: /docs/guide/usage/linter/rules/eslint/prefer-destructuring.md
---

### What it does

Require destructuring from arrays and/or objects.

### Why is this bad?

With JavaScript ES2015, a new syntax was added for creating variables from an array index or object property,
called destructuring. This rule enforces usage of destructuring
instead of accessing a property through a member expression.

### Examples

Examples of **incorrect** code for this rule:

```js
// With `array` enabled
const foo = array[0];
bar.baz = array[0];
// With `object` enabled
const qux = object.qux;
const quux = object["quux"];
```

Examples of **correct** code for this rule:

```js
// With `array` enabled
const [foo] = array;
const arr = array[someIndex];
[bar.baz] = array;

// With `object` enabled
const { baz } = object;
const obj = object.bar;
```

## Configuration

### The 1st option

This option is an object with the following properties:

#### array

type: `boolean`

#### object

type: `boolean`

### The 2nd option

This option is an object with the following properties:

#### enforceForDeclarationWithTypeAnnotation

type: `boolean`

default: `false`

#### enforceForRenamedProperties

type: `boolean`

default: `false`

## How to use

## Version

This rule was added in v1.10.0.

## References

---

---
url: /docs/guide/usage/linter/rules/eslint/prefer-exponentiation-operator.md
---

### What it does

Disallow the use of `Math.pow` in favor of the `**` operator.

### Why is this bad?

Introduced in ES2016, the infix exponentiation operator `**` is an alternative for the
standard `Math.pow` function. Infix notation is considered to be more readable and thus more
preferable than the function notation.

### Examples

Examples of **incorrect** code for this rule:

```javascript
Math.pow(a, b);
```

Examples of **correct** code for this rule:

```javascript
a ** b;
```

## How to use

## Version

This rule was added in v0.4.0.

## References

---

---
url: /docs/guide/usage/linter/rules/eslint/prefer-named-capture-group.md
---

### What it does

Enforces the use of named capture groups in regular expressions.

### Why is this bad?

Unnamed capturing groups (`(...)`) are referenced only by position, which
makes the regex harder to read and maintain. When the pattern changes, index-based
references silently break. Named groups (`(?<name>...)`) make the intent explicit
and allow references by name (e.g. `match.groups.year`), which is more robust.

### Examples

Examples of **incorrect** code for this rule:

```js
const re = /([0-9]{4})-([0-9]{2})/;
const match = re.exec(str);
const year = match[1]; // fragile index
```

Examples of **correct** code for this rule:

```js
const re = /(?<year>[0-9]{4})-(?<month>[0-9]{2})/;
const match = re.exec(str);
const year = match.groups.year; // explicit name

// Non-capturing groups are always fine
const parts = /(?:[0-9]{4})/;
```

## How to use

## Version

This rule was added in v1.68.0.

## References

---

---
url: /docs/guide/usage/linter/rules/eslint/prefer-numeric-literals.md
---

### What it does

Disallow `parseInt()` and `Number.parseInt()` in favor of binary, octal, and hexadecimal
literals.

### Why is this bad?

The `parseInt()` and `Number.parseInt()` functions can be used to turn binary, octal, and
hexadecimal strings into integers. As binary, octal, and hexadecimal literals are supported
in ES2015, this rule encourages use of those numeric literals instead of `parseInt()` or
`Number.parseInt()`.

### Examples

Examples of **incorrect** code for this rule:

```javascript
parseInt("111110111", 2) === 503;
parseInt(`111110111`, 2) === 503;
parseInt("767", 8) === 503;
parseInt("1F7", 16) === 503;
Number.parseInt("111110111", 2) === 503;
Number.parseInt("767", 8) === 503;
Number.parseInt("1F7", 16) === 503;
```

## How to use

## Version

This rule was added in v0.7.0.

## References

---

---
url: /docs/guide/usage/linter/rules/eslint/prefer-object-has-own.md
---

### What it does

Disallow use of `Object.prototype.hasOwnProperty.call()` and prefer use of `Object.hasOwn()`

### Why is this bad?

It is very common to write code like:

```javascript
if (Object.prototype.hasOwnProperty.call(object, "foo")) {
  console.log("has property foo");
}
```

This is a common practice because methods on `Object.prototype` can sometimes be unavailable or redefined (see the no-prototype-builtins rule).
Introduced in ES2022, `Object.hasOwn()` is a shorter alternative to `Object.prototype.hasOwnProperty.call()`:

```javascript
if (Object.hasOwn(object, "foo")) {
  console.log("has property foo");
}
```

### Examples

Examples of **incorrect** code for this rule:

```js
Object.prototype.hasOwnProperty.call(obj, "a");
Object.hasOwnProperty.call(obj, "a");
({}).hasOwnProperty.call(obj, "a");
const hasProperty = Object.prototype.hasOwnProperty.call(object, property);
```

Examples of **correct** code for this rule:

```js
Object.hasOwn(obj, "a");
const hasProperty = Object.hasOwn(object, property);
```

## How to use

## Version

This rule was added in v0.11.0.

## References

---

---
url: /docs/guide/usage/linter/rules/eslint/prefer-object-spread.md
---

### What it does

Disallow using `Object.assign` with an object literal as the first argument and prefer the use of object spread instead.

### Why is this bad?

When `Object.assign` is called using an object literal as the first argument, this rule requires using the object spread syntax instead. This rule also warns on cases where an `Object.assign` call is made using a single argument that is an object literal, in this case, the `Object.assign` call is not needed.

### Examples

Examples of **incorrect** code for this rule:

```js
Object.assign({}, foo);

Object.assign({}, { foo: "bar" });

Object.assign({ foo: "bar" }, baz);

Object.assign({}, baz, { foo: "bar" });

Object.assign({}, { ...baz });

// Object.assign with a single argument that is an object literal
Object.assign({});

Object.assign({ foo: bar });
```

Examples of **correct** code for this rule:

```js
({ ...foo });

({ ...baz, foo: "bar" });

// Any Object.assign call without an object literal as the first argument
Object.assign(foo, { bar: baz });

Object.assign(foo, bar);

Object.assign(foo, { bar, baz });

Object.assign(foo, { ...baz });
```

## How to use

## Version

This rule was added in v0.15.9.

## References

---

---
url: /docs/guide/usage/linter/rules/eslint/prefer-promise-reject-errors.md
---

### What it does

Require using Error objects as Promise rejection reasons.

::: warning
This rule is not as accurate as the type-aware
[typescript/prefer-promise-reject-errors](https://oxc.rs/docs/guide/usage/linter/rules/typescript/prefer-promise-reject-errors.html)
rule. We recommend using the TypeScript rule when type information is available.
:::

### Why is this bad?

It is considered good practice to only pass instances of the built-in `Error` object to the
`reject()` function for user-defined errors in Promises. `Error` objects automatically
store a stack trace, which can be used to debug an error by determining where it came
from. If a Promise is rejected with a non-`Error` value, it can be difficult to
determine where the rejection occurred.

### Examples

Examples of **incorrect** code for this rule:

```js
Promise.reject("something bad happened");

Promise.reject(5);

Promise.reject();

new Promise(function (resolve, reject) {
  reject("something bad happened");
});

new Promise(function (resolve, reject) {
  reject();
});
```

Examples of **correct** code for this rule:

```js
Promise.reject(new Error("something bad happened"));

Promise.reject(new TypeError("something bad happened"));

new Promise(function (resolve, reject) {
  reject(new Error("something bad happened"));
});

var foo = getUnknownValue();
Promise.reject(foo);
```

## Configuration

This rule accepts a configuration object with the following properties:

### allowEmptyReject

type: `boolean`

default: `false`

Whether to allow calls to `Promise.reject()` with no arguments.

## How to use

## Version

This rule was added in v0.15.7.

## References

---

---
url: /docs/guide/usage/linter/rules/eslint/prefer-regex-literals.md
---

### What it does

Disallow use of the RegExp constructor in favor of regular expression literals.

### Why is this bad?

There are two ways to create a regular expression:

* Regular expression literals, e.g., `/abc/u`.
* The `RegExp` constructor function, e.g., `new RegExp("abc", "u")` or `RegExp("abc", "u")`.

The constructor function is particularly useful when you want to dynamically generate the pattern,
because it takes string arguments.

When using the constructor function with string literals, don't forget that the string escaping rules still apply.
If you want to put a backslash in the pattern, you need to escape it in the string literal.
Thus, the following are equivalent:

```js
new RegExp("^\\d\\.$");

/^\d\.$/;

// matches "0.", "1.", "2." ... "9."
```

In the above example, the regular expression literal is easier to read and reason about.
Also, it's a common mistake to omit the extra `\` in the string literal, which would produce a completely different regular expression:

```js
new RegExp("^\d\.$");

// equivalent to /^d.$/, matches "d1", "d2", "da", "db" ...
```

When a regular expression is known in advance, it is considered a best practice to avoid the string literal notation on top
of the regular expression notation, and use regular expression literals instead of the constructor function.

### Examples

Examples of **incorrect** code for this rule:

```js
new RegExp("abc");
new RegExp("abc", "u");
RegExp("abc");
RegExp("abc", "u");
new RegExp("\\d\\d\\.\\d\\d\\.\\d\\d\\d\\d");
RegExp(`^\\d\\.$`);
new RegExp(String.raw`^\d\.$`);
```

Examples of **correct** code for this rule:

```js
/abc/;
/abc/u;
/\d\d\.\d\d\.\d\d\d\d/;
/^\d\.$/;
// RegExp constructor is allowed for dynamically generated regular expressions
new RegExp(pattern);
RegExp("abc", flags);
new RegExp(prefix + "abc");
RegExp(`${prefix}abc`);
new RegExp(String.raw`^\d\. ${suffix}`);
```

## Configuration

### disallowRedundantWrapping

type: `boolean`

default: `false`

By default, this rule doesn’t check when a regex literal is unnecessarily wrapped in a `RegExp` constructor call.
When the option `disallowRedundantWrapping` is set to `true`, the rule will also disallow such unnecessary patterns.

Examples of **incorrect** code for `{ "disallowRedundantWrapping": true }`:

```js
new RegExp(/abc/);
new RegExp(/abc/, "u");
```

Examples of **correct** code for `{ "disallowRedundantWrapping": true }`:

```js
/abc/;
/abc/u;
new RegExp(/abc/, flags);
```

## How to use

## Version

This rule was added in v1.64.0.

## References

---

---
url: /docs/guide/usage/linter/rules/eslint/prefer-rest-params.md
---

### What it does

Disallows the use of the `arguments` object and instead enforces the use of rest parameters.

### Why is this bad?

The `arguments` object does not have methods from `Array.prototype`, making it inconvenient for array-like operations.
Using rest parameters provides a more intuitive and efficient way to handle variadic arguments.

### Examples

Examples of **incorrect** code for this rule:

```javascript
function foo() {
  console.log(arguments);
}

function foo(action) {
  var args = Array.prototype.slice.call(arguments, 1);
  action.apply(null, args);
}

function foo(action) {
  var args = [].slice.call(arguments, 1);
  action.apply(null, args);
}
```

Examples of **correct** code for this rule:

```javascript
function foo(...args) {
  console.log(args);
}

function foo(action, ...args) {
  action.apply(null, args); // Or use `action(...args)` (related to `prefer-spread` rule).
}

// Note: Implicit `arguments` can be shadowed.
function foo(arguments) {
  console.log(arguments); // This refers to the first argument.
}
function foo() {
  var arguments = 0;
  console.log(arguments); // This is a local variable.
}
```

## How to use

## Version

This rule was added in v0.15.4.

## References

---

---
url: /docs/guide/usage/linter/rules/eslint/prefer-spread.md
---

### What it does

Require spread operators instead of `.apply()`

### Why is this bad?

Before ES2015, one must use `Function.prototype.apply()` to call variadic functions.

```javascript
var args = [1, 2, 3, 4];
Math.max.apply(Math, args);
```

In ES2015, one can use spread syntax to call variadic functions.

```javascript
var args = [1, 2, 3, 4];
Math.max(...args);
```

### Examples

Examples of **incorrect** code for this rule:

```javascript
foo.apply(undefined, args);
foo.apply(null, args);
obj.foo.apply(obj, args);
```

Examples of **correct** code for this rule:

```javascript
// Using spread syntax
foo(...args);
obj.foo(...args);

// The `this` binding is different.
foo.apply(obj, args);
obj.foo.apply(null, args);
obj.foo.apply(otherObj, args);

// The argument list is not variadic.
// Those are warned by the `no-useless-call` rule.
foo.apply(undefined, [1, 2, 3]);
foo.apply(null, [1, 2, 3]);
obj.foo.apply(obj, [1, 2, 3]);
```

## How to use

## Version

This rule was added in v0.0.17.

## References

---

---
url: /docs/guide/usage/linter/rules/eslint/prefer-template.md
---

### What it does

Require template literals instead of string concatenation.

### Why is this bad?

In ES2015 (ES6), we can use template literals instead of string concatenation.

### Examples

Examples of **incorrect** code for this rule:

```js
const str = "Hello, " + name + "!";
const str1 = "Time: " + 12 * 60 * 60 * 1000;
```

Examples of **correct** code for this rule:

```js
const str = "Hello World!";
const str2 = `Time: ${12 * 60 * 60 * 1000}`;
const str4 = "Hello, " + "World!";
```

## How to use

## Version

This rule was added in v1.12.0.

## References

---

---
url: /docs/guide/usage/linter/rules/eslint/preserve-caught-error.md
---

### What it does

Enforces that when re-throwing an error in a catch block, the original error
is preserved using the 'cause' property.

### Why is this bad?

Re-throwing an error without preserving the original error loses important
debugging information and makes it harder to trace the root cause of issues.

### Examples

Examples of **incorrect** code for this rule:

```js
try {
  doSomething();
} catch (err) {
  throw new Error("Something failed");
}
```

Examples of **correct** code for this rule:

```js
try {
  doSomething();
} catch (err) {
  throw new Error("Something failed", { cause: err });
}
```

## Configuration

This rule accepts a configuration object with the following properties:

### requireCatchParameter

type: `boolean`

default: `false`

When set to `true`, requires that catch clauses always have a parameter.

## How to use

## Version

This rule was added in v1.16.0.

## References

---

---
url: /docs/guide/usage/linter/rules/eslint/radix.md
---

### What it does

Enforce the consistent use of the radix argument when using `parseInt()`,
which specifies what base to use for parsing the number.

### Why is this bad?

Using the `parseInt()` function without specifying
the radix can lead to unexpected results.

See the
[MDN documentation](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/parseInt#radix)
for more information on how `parseInt()` handles certain edge-cases.

### Configuration

Note that passing an option to this rule has no effect on its behavior.
In v1.49.0, the config option for this rule was removed and made a no-op.
This matches the behavior change made in ESLint v10, and the rule now
always enforces that a radix parameter is provided to `parseInt()`.

If you receive new violations due to this change, you may either opt
to disable this rule, or add the radix parameter to all usages of
`parseInt()` in your codebase.

### Examples

Examples of **incorrect** code for this rule:

```javascript
let num = parseInt("071"); // 57
```

Examples of **correct** code for this rule:

```javascript
let num = parseInt("071", 10); // 71
```

## Configuration

This rule accepts one of the following string values:

### `"always"`

Always require the radix parameter when using `parseInt()`.

### `"as-needed"`

Only require the radix parameter when necessary.

## How to use

## Version

This rule was added in v0.3.3.

## References

---

---
url: /docs/guide/usage/linter/rules/eslint/require-await.md
---

### What it does

Disallow async functions which have no `await` expression.

::: warning NOTE
This rule is inferior to the accuracy of the type-aware
`typescript/require-await` rule. If using type-aware
rules, always prefer that rule over this one.
:::

### Why is this bad?

Asynchronous functions in JavaScript behave differently than other
functions in two important ways:

1. The return value is always a `Promise`.
2. You can use the `await` operator inside of them.

The primary reason to use asynchronous functions is typically to use the
await operator, such as this:

```js
async function fetchData(processDataItem) {
  const response = await fetch(DATA_URL);
  const data = await response.json();

  return data.map(processDataItem);
}
```

Asynchronous functions that don’t use `await` might not need to be
asynchronous functions and could be the unintentional result of
refactoring.

Note: this rule ignores async generator functions. This is because
generators yield rather than return a value and async generators might
yield all the values of another async generator without ever actually
needing to use `await`.

### Examples

Examples of **incorrect** code for this rule:

```js
async function foo() {
  doSomething();
}
```

Examples of **correct** code for this rule:

```js
async function foo() {
  await doSomething();
}
```

## How to use

## Version

This rule was added in v0.4.2.

## References

---

---
url: /docs/guide/usage/linter/rules/eslint/require-unicode-regexp.md
---

### What it does

Enforce the use of `u` or `v` flag on regular expressions.

### Why is this bad?

RegExp `u` flag has two effects:

1. Make the regular expression handling UTF-16 surrogate pairs correctly.

```js
/^[👍]$/.test("👍") //→ false
/^[👍]$/u.test("👍") //→ true
```

2. Make the regular expression throwing syntax errors early as disabling [Annex B extensions](https://262.ecma-international.org/6.0/#sec-regular-expressions-patterns).
   Because of historical reason, JavaScript regular expressions are tolerant of syntax errors.
   For example, `/\w{1, 2/` is a syntax error, but JavaScript doesn’t throw the error. It matches strings such as `"a{1, 2"` instead. Such a recovering logic is defined in Annex B.

The RegExp `v` flag, introduced in ECMAScript 2024, is a superset of the `u` flag, and offers two more features:

1. Unicode properties of strings

```js
const re = /^\p{RGI_Emoji}$/v;

// Match an emoji that consists of just 1 code point:
re.test("⚽"); // '\u26BD'
// → true ✅

// Match an emoji that consists of multiple code points:
re.test("👨🏾‍⚕️"); // '\u{1F468}\u{1F3FE}\u200D\u2695\uFE0F'
// → true ✅
```

2. Set notation
   It allows for set operations between character classes:

```js
const re = /[\p{White_Space}&&\p{ASCII}]/v;
re.test("\n"); // → true
re.test("\u2028"); // → false
```

### Examples

Examples of **incorrect** code for this rule:

```js
const a = /aaa/;
const b = /bbb/gi;
const c = new RegExp("ccc");
const d = new RegExp("ddd", "gi");
```

Examples of **correct** code for this rule:

```js
const a = /aaa/u;
const b = /bbb/giu;
const c = new RegExp("ccc", "u");
const d = new RegExp("ddd", "giu");

const e = /aaa/v;
const f = /bbb/giv;
const g = new RegExp("ccc", "v");
const h = new RegExp("ddd", "gv");

// This rule ignores RegExp calls if the flags could not be evaluated to a static value.
function i(flags) {
  return new RegExp("eee", flags);
}
```

## Configuration

### requireFlag

type: `"u" | "v"`

default: `null`

The `u` flag may be preferred in environments that do not support the `v` flag.

Examples of **incorrect** code for this rule with the `{ "requireFlag": "u" }` option:

```js
const fooEmpty = /foo/;
const fooEmptyRegexp = new RegExp("foo");
const foo = /foo/v;
const fooRegexp = new RegExp("foo", "v");
```

Examples of **correct** code for this rule with the `{ "requireFlag": "u" }` option:

```js
const foo = /foo/u;
const fooRegexp = new RegExp("foo", "u");
```

The `v` flag may be a better choice when it is supported because it has more features than the `u` flag (e.g., the ability to test Unicode properties of strings).
It does have a stricter syntax, however (e.g., the need to escape certain characters within character classes).

Examples of **incorrect** code for this rule with the `{ "requireFlag": "v" }` option:

```js
const fooEmpty = /foo/;
const fooEmptyRegexp = new RegExp("foo");
const foo = /foo/u;
const fooRegexp = new RegExp("foo", "u");
```

Examples of **correct** code for this rule with the `{ "requireFlag": "v" }` option:

```js
const foo = /foo/v;
const fooRegexp = new RegExp("foo", "v");
```

## How to use

## Version

This rule was added in v1.63.0.

## References

---

---
url: /docs/guide/usage/linter/rules/eslint/require-yield.md
---

### What it does

This rule generates warnings for generator functions that do not have the yield keyword.

### Why is this bad?

Probably a mistake.

### Examples

Examples of **incorrect** code for this rule:

```javascript
function* foo() {
  return 10;
}
```

## How to use

## Version

This rule was added in v0.0.4.

## References

---

---
url: /docs/guide/usage/linter/rules/eslint/sort-imports.md
---

### What it does

This rule checks all import declarations and verifies that all imports are first sorted
by the used member syntax and then alphabetically by the first member or alias name.

When declaring multiple imports, a sorted list of import declarations make it easier for developers to read
the code and find necessary imports later.

### Why is this bad?

Consistent import sorting can be useful for readability and maintainability of code.

### Examples

Examples of **incorrect** code for this rule:

```javascript
import { b, a, c } from "foo.js";

import d from "foo.js";
import e from "bar.js";
```

## Configuration

This rule accepts a configuration object with the following properties:

### allowSeparatedGroups

type: `boolean`

default: `false`

When `true`, the rule allows import groups separated by blank lines to be treated independently.

### ignoreCase

type: `boolean`

default: `false`

When `true`, the rule ignores case-sensitivity when sorting import names.

### ignoreDeclarationSort

type: `boolean`

default: `false`

When `true`, the rule ignores the sorting of import declarations (the order of `import` statements).

### ignoreMemberSort

type: `boolean`

default: `false`

When `true`, the rule ignores the sorting of import members within a single import declaration.

### memberSyntaxSortOrder

type: `array`

default: `["none", "all", "multiple", "single"]`

Specifies the sort order of different import syntaxes.
Must include all 4 kinds!

#### memberSyntaxSortOrder\[n]

type: `"none" | "all" | "multiple" | "single"`

## How to use

## Version

This rule was added in v0.4.4.

## References

---

---
url: /docs/guide/usage/linter/rules/eslint/sort-keys.md
---

### What it does

When declaring multiple properties, sorting property names alphabetically makes it easier
to find and/or diff necessary properties at a later time.

### Why is this bad?

Unsorted property keys can make the code harder to read and maintain.

### Examples

Examples of **incorrect** code for this rule:

```js
let myObj = {
  c: 1,
  a: 2,
};
```

Examples of **correct** code for this rule:

```js
let myObj = {
  a: 2,
  c: 1,
};
```

## Configuration

### The 1st option

type: `"desc" | "asc"`

Sorting order for keys. Accepts "asc" for ascending or "desc" for descending.

### The 2nd option

This option is an object with the following properties:

#### allowLineSeparatedGroups

type: `boolean`

default: `false`

When true, groups of properties separated by a blank line are sorted independently.

#### caseSensitive

type: `boolean`

default: `true`

Whether the sort comparison is case-sensitive (A < a when true).

#### minKeys

type: `integer`

default: `2`

Minimum number of properties required in an object before sorting is enforced.

#### natural

type: `boolean`

default: `false`

Use natural sort order so that, for example, "a2" comes before "a10".

## How to use

## Version

This rule was added in v0.9.4.

## References

---

---
url: /docs/guide/usage/linter/rules/eslint/sort-vars.md
---

### What it does

Enforce sorting of variable declarations within the same block.

### Why is this bad?

When declaring multiple variables within the same block, sorting variable names can make it
easier to find necessary variables at a later time.

Unsorted variable declarations can make the code harder to read and maintain.

### Examples

Examples of **incorrect** code for this rule:

```js
var b, a;
var a, B, c;
```

Examples of **correct** code for this rule:

```js
var a, b, c, d;
var B, a, c;
```

## Configuration

This rule accepts a configuration object with the following properties:

### ignoreCase

type: `boolean`

default: `false`

When `true`, the rule ignores case-sensitivity when sorting variables.

## How to use

## Version

This rule was added in v0.9.3.

## References

---

---
url: /docs/guide/usage/linter/rules/eslint/symbol-description.md
---

### What it does

Require symbol descriptions.

### Why is this bad?

The Symbol function may have an optional description.

```js
var foo = Symbol("some description");

var someString = "some description";
var bar = Symbol(someString);
```

Using `description` promotes easier debugging: when a symbol is logged the description is used:

```js
var foo = Symbol("some description");

console.log(foo);
// prints - Symbol(some description)
```

### Examples

Examples of **incorrect** code for this rule:

```javascript
var foo = Symbol();
```

Examples of **correct** code for this rule:

```javascript
var foo = Symbol("some description");
```

## How to use

## Version

This rule was added in v0.4.0.

## References

---

---
url: /docs/guide/usage/linter/rules/eslint/unicode-bom.md
---

### What it does

Require or disallow Unicode byte order mark (BOM)

### Why is this bad?

The Unicode Byte Order Mark (BOM) is used to specify whether code units are big endian or
little endian. That is, whether the most significant or least significant bytes come first.
UTF-8 does not require a BOM because byte ordering does not matter when characters are a
single byte. Since UTF-8 is the dominant encoding of the web, we make "never" the default
option.

### Examples

Examples of **incorrect** code for this rule:

```javascript
var a = 123;
```

## Configuration

This rule accepts one of the following string values:

### `"always"`

Always require a Unicode BOM (Byte Order Mark) at the beginning of the file.

### `"never"`

Never allow a Unicode BOM (Byte Order Mark) at the beginning of the file.
This is the default option.

## How to use

## Version

This rule was added in v0.3.3.

## References

---

---
url: /docs/guide/usage/linter/rules/eslint/use-isnan.md
---

### What it does

Disallows checking against `NaN` without using `isNaN()` call.

### Why is this bad?

In JavaScript, `NaN` is a special value of the Number type.
It’s used to represent any of the “not-a-number” values represented
by the double-precision 64-bit format as specified by the IEEE Standard
for Binary Floating-Point Arithmetic.

Because `NaN` is unique in JavaScript by not being equal to anything, including itself,
the results of comparisons to `NaN` are confusing:

* `NaN === NaN` or `NaN == NaN` evaluate to false
* `NaN !== NaN` or `NaN != NaN` evaluate to true

Therefore, use `Number.isNaN()` or global `isNaN()` functions to test whether a value is `NaN`.

### Examples

Examples of **incorrect** code for this rule:

```javascript
foo == NaN;
foo === NaN;
foo <= NaN;
foo > NaN;
```

## Configuration

This rule accepts a configuration object with the following properties:

### enforceForIndexOf

type: `boolean`

default: `false`

Whether to disallow NaN as arguments of `indexOf` and `lastIndexOf`

### enforceForSwitchCase

type: `boolean`

default: `true`

Whether to disallow NaN in switch cases and discriminants

## How to use

## Version

This rule was added in v0.0.3.

## References

---

---
url: /docs/guide/usage/linter/rules/eslint/valid-typeof.md
---

### What it does

Enforce comparing `typeof` expressions against valid strings.

### Why is this bad?

For a vast majority of use cases, the result of the `typeof` operator is one of the
following string literals: `"undefined"`, `"object"`, `"boolean"`, `"number"`, `"string"`,
`"function"`, `"symbol"`, and `"bigint"`. It is usually a typing mistake to compare the
result of a `typeof` operator to other string literals.

### Examples

Examples of **incorrect** code for this rule:

```js
typeof foo === "strnig";
typeof foo == "undefimed";
typeof bar != "nunber"; // spellchecker:disable-line
typeof bar !== "fucntion"; // spellchecker:disable-line
```

Examples of **correct** code for this rule:

```js
typeof foo === "string";
typeof bar == "undefined";
typeof foo === baz;
typeof bar === typeof qux;
```

## Configuration

This rule accepts a configuration object with the following properties:

### requireStringLiterals

type: `boolean`

default: `false`

The `requireStringLiterals` option when set to `true`, allows the comparison of `typeof`
expressions with only string literals or other `typeof` expressions, and disallows
comparisons to any other value. Default is `false`.

With `requireStringLiterals` set to `true`, the following are examples of **incorrect** code:

```js
typeof foo === undefined;
typeof bar == Object;
typeof baz === "strnig";
typeof qux === "some invalid type";
typeof baz === anotherVariable;
typeof foo == 5;
```

With `requireStringLiterals` set to `true`, the following are examples of **correct** code:

```js
typeof foo === "undefined";
typeof bar == "object";
typeof baz === "string";
typeof bar === typeof qux;
```

## How to use

## Version

This rule was added in v0.0.3.

## References

---

---
url: /docs/guide/usage/linter/rules/eslint/vars-on-top.md
---

### What it does

Enforces that all `var` declarations are placed at the top of their containing scope.

### Why is this bad?

In JavaScript, `var` declarations are hoisted to the top of their containing scope. Placing `var` declarations at the top explicitly improves code readability and maintainability by making the scope of variables clear.

### Examples

Examples of **incorrect** code for this rule:

```js
function doSomething() {
  if (true) {
    var first = true;
  }
  var second;
}

function doSomethingElse() {
  for (var i = 0; i < 10; i++) {}
}

f();
var a;

class C {
  static {
    if (something) {
      var a = true;
    }
  }
  static {
    f();
    var a;
  }
}
```

Examples of **correct** code for this rule:

```js
function doSomething() {
  var first;
  var second;
  if (true) {
    first = true;
  }
}

function doSomethingElse() {
  var i;
  for (i = 0; i < 10; i++) {}
}

var a;
f();

class C {
  static {
    var a;
    if (something) {
      a = true;
    }
  }
  static {
    var a;
    f();
  }
}
```

## How to use

## Version

This rule was added in v0.15.4.

## References

---

---
url: /docs/guide/usage/linter/rules/eslint/yoda.md
---

### What it does

Require or disallow "Yoda" conditions. This rule aims to enforce consistent style of conditions which compare a variable to a literal value.

### Why is this bad?

Yoda conditions are so named because the literal value of the condition comes first while the variable comes second. For example, the following is a Yoda condition:

```js
if ("red" === color) {
}
```

This is called a Yoda condition because it reads as, "if red equals the color", similar to the way the Star Wars character Yoda speaks. Compare to the other way of arranging the operands:

```js
if (color === "red") {
  // ...
}
```

This typically reads, "if the color equals red", which is arguably a more natural way to describe the comparison.
Proponents of Yoda conditions highlight that it is impossible to mistakenly use `=` instead of `==` because you cannot assign to a literal value. Doing so will cause a syntax error and you will be informed of the mistake early on. This practice was therefore very common in early programming where tools were not yet available.
Opponents of Yoda conditions point out that tooling has made us better programmers because tools will catch the mistaken use of `=` instead of `==` (ESLint will catch this for you). Therefore, they argue, the utility of the pattern doesn't outweigh the readability hit the code takes while using Yoda conditions.

### Examples

#### never

Examples of **incorrect** code for the default `"never"` option:

```js
if ("red" === color) {
  // ...
}
if (`red` === color) {
  // ...
}
if (`red` === `${color}`) {
  // ...
}

if (true == flag) {
  // ...
}

if (0 <= x && x < 1) {
  // ...
}
```

Examples of **correct** code for the default `"never"` option:

```js
if (5 & value) {
  // ...
}

if (value === "red") {
  // ...
}

if (value === `red`) {
  // ...
}

if (`${value}` === `red`) {
}
```

#### exceptRange

Examples of **correct** code for the `"never", { "exceptRange": true }` options:

```js
function isReddish(color) {
  return color.hue < 60 || 300 < color.hue;
}

if (x < -1 || 1 < x) {
  // ...
}

if (count < 10 && 0 <= rand && rand < 1) {
  // ...
}

if (`blue` < x && x < `green`) {
  // ...
}

function howLong(arr) {
  return 0 <= arr.length && arr.length < 10 ? "short" : "long";
}
```

#### onlyEquality

Examples of **correct** code for the `"never", { "onlyEquality": true }` options:

```js
if (x < -1 || 9 < x) {
}

if (x !== "foo" && "bar" != x) {
}

if (x !== `foo` && `bar` != x) {
}
```

#### always

Examples of **incorrect** code for the `"always"` option:

```js
if (color == "blue") {
  // ...
}

if (color == `blue`) {
  // ...
}
```

Examples of **correct** code for the `"always"` option:

```js
if ("blue" == value) {
  // ...
}

if (`blue` == value) {
  // ...
}

if (`blue` == `${value}`) {
  // ...
}

if (-1 < str.indexOf(substr)) {
  // ...
}
```

## Configuration

### The 1st option

type: `"never" | "always"`

#### `"never"`

The default `"never"` option can have exception options in an object literal, via `exceptRange` and `onlyEquality`.

#### `"always"`

The `"always"` option requires that literal values must always come first in comparisons.

### The 2nd option

This option is an object with the following properties:

#### exceptRange

type: `boolean`

default: `false`

If the `"exceptRange"` property is `true`, the rule *allows* yoda conditions
in range comparisons which are wrapped directly in parentheses, including the
parentheses of an `if` or `while` condition.
A *range* comparison tests whether a variable is inside or outside the range
between two literal values.

#### onlyEquality

type: `boolean`

default: `false`

If the `"onlyEquality"` property is `true`, the rule reports yoda
conditions *only* for the equality operators `==` and `===`. The `onlyEquality`
option allows a superset of the exceptions which `exceptRange` allows, thus
both options are not useful together.

## How to use

## Version

This rule was added in v0.14.1.

## References

---

---
url: /docs/guide/usage/minifier/faq.md
---
# FAQ

## Top level variables are removed

Top level variables are removed when the source type is `module`. This is because top level variables in module code are not accessible from other modules. Contrary to that, top level variables in script code are treated as global variables and are accessible from other scripts. If you expect the top level variables to be kept, you should not use a `.mjs` filename nor enable the `module` option.

## New lines in strings are not removed

It may be surprising that new lines in strings are not removed and replaced with `\n` in minified code. This behavior is because the character escape sequences `\n` is two bytes long while the new line character is one byte long.

```js
// this code is 16 bytes
const foo="a\nb"

// this code is 15 bytes
const foo=`a
b`
```

---

---
url: /docs/contribute/formatter.md
---

# Formatter (oxfmt)

We are currently porting Prettier and Biome Formatter to Oxc to create a high-performance, Prettier-compatible formatter.

## Architecture Overview

The Oxc formatter is built around the same core concepts as Prettier but with significant performance optimizations:

* **Document Model**: Uses Prettier and Biome's document IR (Intermediate Representation)
* **Pretty Printing**: Implements Wadler's pretty printing algorithm
* **AST Integration**: Leverages Oxc's fast parser for optimal performance

## Performance Considerations

### Optimization Strategies

* **Memory Arena**: AST allocated in bump allocator
* **String Interning**: Reuse common strings
* **Lazy Evaluation**: Defer expensive computations

## Current Challenges

### Technical Challenges

1. **Comment Handling**: Preserving comment placement and formatting
2. **JavaScript Quirks**: Handling edge cases in JavaScript syntax
3. **Performance vs Compatibility**: Balancing speed with exact Prettier output
4. **Memory Management**: Efficient handling of large files

### Missing Features

* \[ ] Plugin system compatibility
* \[x] Configuration file support
* \[ ] Editor integrations
* \[x] CLI tool
* \[x] Language server protocol

---

---
url: /docs/contribute/development.md
---

# Getting Started

## Clone Repository

```bash
git clone -c core.longpaths=true git@github.com:oxc-project/oxc.git
```

## Set Up Project

### Install Rust

If you have not yet installed Rust, follow [the official instruction](https://www.rust-lang.org/tools/install) and install Rust.

After installing Rust, run the following command on the project root:

```bash
rustup show
```

`rustup show` reads the `./rust-toolchain.toml` file and installs the correct Rust toolchain and components for this project.

### `cargo binstall`

Some Cargo tools are required to develop OXC, and it is recommended to use [cargo binstall](https://github.com/cargo-bins/cargo-binstall), which provides a low-complexity mechanism to install rust binaries and is faster way than building them from source by running `cargo install`.

```bash
cargo install cargo-binstall
```

You can also download [the pre-compiled binary](https://github.com/cargo-bins/cargo-binstall#installation) and save it in `~/.cargo/bin`.

### `just`

OXC utilizes [`just`](https://github.com/casey/just), which is a handy way to save and run project-specific commands:

```bash
cargo binstall just -y
```

### Install CMake

Install CMake by downloading from the official [website](https://cmake.org/download/).

[Homebrew](https://brew.sh/) users can alternatively install with:

```bash
brew install cmake
```

### Install pnpm

Install `pnpm` (a package manager for node.js, similar to `npm`) by following instructions from the official [website](https://pnpm.io/installation).

#### Dependencies

Run the following command in `justfile` at the project root to install dependencies:

```bash
just init
```

You can see the list of available commands by running `just`.

You can run `just ready` (or, `just r` in short) to make sure the whole project builds and runs correctly.

## macOS: Faster Compilation

macOS has an antivirus feature called XProtect that scans executables for malware on first run. This can significantly slow down Rust builds, especially build scripts and test executables. You can speed up compilation by adding Terminal as a "developer tool" in System Settings:

1. Open System Settings > Privacy & Security > Developer Tools
2. Add your terminal app (Terminal, iTerm, etc.)
3. Restart the terminal app

**Note:** This disables an OS security feature. Only do this if you're comfortable with the trade-off.

More details: https://nnethercote.github.io/2025/09/04/faster-rust-builds-on-mac.html

---

---
url: /docs/guide/introduction.md
---

# Getting Started

[What is Oxc?](/docs/guide/what-is-oxc)

## Lint or format a codebase

* Lint: [Oxlint](/docs/guide/usage/linter)
* Format: [Oxfmt](/docs/guide/usage/formatter)

## Build tooling on top of Oxc

* Parse JavaScript and TypeScript: [Parser](/docs/guide/usage/parser)
* Transform TypeScript, JSX, and modern JavaScript: [Transformer](/docs/guide/usage/transformer)
* Minify JavaScript for production builds: [Minifier](/docs/guide/usage/minifier)
* Resolve modules for JavaScript and TypeScript: [Resolver](/docs/guide/usage/resolver)
* Run TypeScript and JSX directly in Node.js: [TypeScript Runner](/docs/guide/usage/oxc-node)

## Contribute or learn

* [Contribute](/docs/contribute/introduction)
* [Learn](/docs/learn/parser_in_rust/intro)

## Other resources

* [Troubleshooting](/docs/guide/troubleshooting)
* [Benchmarks](/docs/guide/benchmarks)
* [Projects using Oxc](/docs/guide/projects)
* [Talks and media](/docs/guide/media)
* [Team](/team)
* [Endorsements](/endorsements)
* [Release Blog](/blog/)
* [Releases](https://github.com/oxc-project/oxc/releases)

---

---
url: /docs/guide/usage/transformer/global-variable-replacement.md
---
# Global Variable Replacement

Oxc transformer supports replacing global variables.

::: tip Evaluation order
`inject` runs before `define`, and both run after all other transforms. See the [transformer overview](../transformer#features) for the full order.
:::

## Define

"Define" feature provides a way to replace global variables with constant expressions. This feature is similar to [Terser](https://terser.org/)'s `global_defs` option and [esbuild's `define` option](https://esbuild.github.io/api/#define).

```js
// input
const foo = __DEV__ ? 1 : 2;

// output
const foo = 1;
```

```js
// Example
import { transform } from "oxc-transform";

const result = await transform("lib.js", sourceCode, {
  define: {
    __DEV__: "true",
  },
});
```

Each `define` entry maps an expression to a string of code containing an expression. The keys of it must be an identifier (e.g. `__DEV__`), or a dotted sequence of identifiers (e.g. `process.env.NODE_ENV`, `import.meta.env.MODE`). The values of it must be a valid expression.

::: tip Always quote the values

The values of `define` are the string of expressions. This means the value should always a string. If you mean a string literal, you should quote it (e.g. `__MODE__: '"development"'`, `__MODE__: JSON.stringify("development")`).

:::

::: tip The object reference are not shared

Differently from esbuild, when passing an object to the value of the `define` option, the object reference is not shared. This means that if you change the object, the changes will not be reflected in the other places.

```js
const foo = __OBJECT__;
foo.bar = 1;
console.log(foo.bar); // 1

const bar = __OBJECT__;
console.log(foo.bar); // undefined
```

```js
// Example
import { transform } from "oxc-transform";

const result = await transform("lib.js", sourceCode, {
  define: {
    __OBJECT__: "{}",
  },
});
```

:::

## Inject

"Inject" feature provides a way to replace global variables with an import from a module. This feature is similar to [esbuild's `inject` option](https://esbuild.github.io/api/#inject) and [`@rollup/plugin-inject`](https://github.com/rollup/plugins/tree/master/packages/inject).

```js
// input
const foo = new Promise((resolve) => resolve(1));

// output
import { Promise as P } from "es6-promise";
const foo = new P((resolve) => resolve(1));
```

```js
// Example
import { transform } from "oxc-transform";

const result = await transform("lib.js", sourceCode, {
  inject: {
    P: ["es6-promise", "Promise"],
  },
});
```

Each `inject` entry maps an expression to an imported identifier. The keys of it must be an identifier (e.g. `__DEV__`), or a dotted sequence of identifiers (e.g. `process.env.NODE_ENV`). The values of it must be a string of the import source, or a tuple of strings of the import source and the import name (`*` is namespace import).

```js
const examples = {
  // import { Promise } from 'es6-promise'
  Promise: ["es6-promise", "Promise"],
  // import { Promise as P } from 'es6-promise'
  P: ["es6-promise", "Promise"],
  // import $ from 'jquery'
  $: "jquery",
  // import * as fs from 'fs'
  fs: ["fs", "*"],
  // use a local module instead of a third-party one
  "Object.assign": path.resolve("src/helpers/object-assign.js"),
};
```

---

---
url: /docs/learn/ecmascript/grammar.md
---

# Grammar

JavaScript has one of the most challenging grammar to parse,
this tutorial details all the sweat and tears I had while learning it.

## LL(1) Grammar

According to [Wikipedia](https://en.wikipedia.org/wiki/LL_grammar),

> an LL grammar is a context-free grammar that can be parsed by an LL parser, which parses the input from Left to right

The first **L** means the scanning the source from **L**eft to right,
and the second **L** means the construction of a **L**eftmost derivation tree.

Context-free and the (1) in LL(1) means a tree can be constructed by just peeking at the next token and nothing else.

LL Grammars are of particular interest in academia because we are lazy human beings and we want to write programs that generate parsers automatically so we don't need to write parsers by hand.

Unfortunately, most industrial programming languages do not have a nice LL(1) grammar,
and this applies to JavaScript too.

:::info
Mozilla started the [jsparagus](https://github.com/mozilla-spidermonkey/jsparagus) project a few years ago
and wrote a [LALR parser generator in Python](https://github.com/mozilla-spidermonkey/jsparagus/tree/master/jsparagus).
They haven't updated it much in the past two years and they sent a strong message at the end of [js-quirks.md](https://github.com/mozilla-spidermonkey/jsparagus/blob/master/js-quirks.md)

> What have we learned today?
>
> * Do not write a JS parser.
> * JavaScript has some syntactic horrors in it. But hey, you don't make the world's most widely used programming language by avoiding all mistakes. You do it by shipping a serviceable tool, in the right circumstances, for the right users.

:::

***

The only practical way to parse JavaScript is to write a recursive descent parser by hand because of the nature of its grammar,
so let's learn all the quirks in the grammar before we shoot ourselves in the foot.

The list below starts simple and will become difficult to grasp,
so please take grab a coffee and take your time.

## Identifiers

There are three types of identifiers defined in `#sec-identifiers`,

```
IdentifierReference[Yield, Await] :
BindingIdentifier[Yield, Await] :
LabelIdentifier[Yield, Await] :
```

`estree` and some ASTs do not distinguish the above identifiers,
and the specification does not explain them in plain text.

`BindingIdentifier`s are declarations and `IdentifierReference`s are references to binding identifiers.
For example in `var foo = bar`, `foo` is a `BindingIdentifier` and `bar` is a `IdentifierReference` in the grammar:

```
VariableDeclaration[In, Yield, Await] :
    BindingIdentifier[?Yield, ?Await] Initializer[?In, ?Yield, ?Await] opt

Initializer[In, Yield, Await] :
    = AssignmentExpression[?In, ?Yield, ?Await]
```

follow `AssignmentExpression` into `PrimaryExpression` we get

```
PrimaryExpression[Yield, Await] :
    IdentifierReference[?Yield, ?Await]
```

Declaring these identifiers differently in the AST will greatly simply downstream tools, especially for semantic analysis.

```rust
pub struct BindingIdentifier {
    pub node: Node,
    pub name: Atom,
}

pub struct IdentifierReference {
    pub node: Node,
    pub name: Atom,
}
```

***

## Class and Strict Mode

ECMAScript Class is born after strict mode, so they decided that everything inside a class must be strict mode for simplicity.
It is stated as such in `#sec-class-definitions` with just a `Node: A class definition is always strict mode code.`

It is easy to declare strict mode by associating it with function scopes, but a `class` declaration does not have a scope,
we need to keep an extra state just for parsing classes.

```rust
// https://github.com/swc-project/swc/blob/f9c4eff94a133fa497778328fa0734aa22d5697c/crates/swc_ecma_parser/src/parser/class_and_fn.rs#L85
fn parse_class_inner(
    &mut self,
    _start: BytePos,
    class_start: BytePos,
    decorators: Vec<Decorator>,
    is_ident_required: bool,
) -> PResult<(Option<Ident>, Class)> {
    self.strict_mode().parse_with(|p| {
        expect!(p, "class");
```

***

## Legacy Octal and Use Strict

`#sec-string-literals-early-errors` disallows escaped legacy octal inside strings `"\01"`:

```
EscapeSequence ::
    LegacyOctalEscapeSequence
    NonOctalDecimalEscapeSequence

It is a Syntax Error if the source text matched by this production is strict mode code.
```

The best place to detect this is inside the lexer, it can ask the parser for strict mode state and throw errors accordingly.

But, this becomes impossible when mixed with directives:

```javascript reference
https://github.com/tc39/test262/blob/747bed2e8aaafe8fdf2c65e8a10dd7ae64f66c47/test/language/literals/string/legacy-octal-escape-sequence-prologue-strict.js#L16-L19
```

`use strict` is declared after the escaped legacy octal, yet the syntax error needs to be thrown.
Fortunately, no real code uses directives with legacy octals ... unless you want to pass the test262 case from above.

***

## Non-simple Parameter and Strict Mode

Identical function parameters is allowed in non-strict mode `function foo(a, a) { }`,
and we can forbid this by adding `use strict`: `function foo(a, a) { "use strict" }`.
Later on in es6, other grammars were added to function parameters, for example `function foo({ a }, b = c) {}`.

Now, what happens if we write the following where "01" is a strict mode error?

```javaScript
function foo(
  value = (function() {
    return "\01";
  }()),
) {
  "use strict";
  return value;
}
```

More specifically, what should we do if there is a strict mode syntax error inside the parameters thinking from the parser perspective?
So in `#sec-function-definitions-static-semantics-early-errors`, it just bans this by stating

```
FunctionDeclaration :
FunctionExpression :

It is a Syntax Error if FunctionBodyContainsUseStrict of FunctionBody is true and IsSimpleParameterList of FormalParameters is false.
```

Chrome throws this error with a mysterious message "Uncaught SyntaxError: Illegal 'use strict' directive in function with non-simple parameter list".

A more in-depth explanation is described in [this blog post](https://humanwhocodes.com/blog/2016/10/the-ecmascript-2016-change-you-probably-dont-know/) by the author of ESLint.

:::info

Fun fact, the above rule does not apply if we are targeting `es5` in TypeScript, it transpiles to

```javaScript
function foo(a, b) {
  "use strict";
  if (b === void 0) b = "\01";
}
```

:::

***

## Parenthesized Expression

Parenthesized expressions are supposed to not have any semantic meanings?
For instance the AST for `((x))` can just be a single `IdentifierReference`, not `ParenthesizedExpression` -> `ParenthesizedExpression` -> `IdentifierReference`.
And this is the case for JavaScript grammar.

But ... who would have thought it can have runtime meanings.
Found in [this estree issue](https://github.com/estree/estree/issues/194), it shows that

```javascript
> fn = function () {};
> fn.name
< "fn"

> (fn) = function () {};
> fn.name
< ''
```

So eventually acorn and babel added the `preserveParens` option for compatibility.

***

## Function Declaration in If Statement

If we follow the grammar precisely in `#sec-ecmascript-language-statements-and-declarations`:

```
Statement[Yield, Await, Return] :
    ... lots of statements

Declaration[Yield, Await] :
    ... declarations
```

The `Statement` node we define for our AST would obviously not contain `Declaration`,

but in Annex B `#sec-functiondeclarations-in-ifstatement-statement-clauses`,
it allows declaration inside the statement position of `if` statements in non-strict mode:

```javascript
if (x) {
  function foo() {}
} else function bar() {}
```

***

## Label statement is legit

We probably have never written a single line of labelled statement, but it is legit in modern JavaScript and not banned by strict mode.

The following syntax is correct, it returns a labelled statement (not object literal).

```javascript
<Foo
  bar={() => {
    baz: "quaz";
  }}
/>
//   ^^^^^^^^^^^ `LabelledStatement`
```

***

## `let` is not a keyword

`let` is not a keyword so it is allowed to appear anywhere unless the grammar explicitly states `let` is not allowed in such positions.
Parsers need to peek at the token after the `let` token and decide what it needs to be parsed into, e.g.:

```javascript
let a;
let = foo;
let instanceof x;
let + 1;
while (true) let;
a = let[0];
```

***

## For-in / For-of and the \[In] context

If we look at the grammar for `for-in` and `for-of` in `#prod-ForInOfStatement`,
it is immediately confusing to understand how to parse these.

There are two major obstacles for us to understand: the `[lookahead ≠ let]` part and the `[+In]` part.

If we have parsed to `for (let`, we need to check the peeking token is:

* not `in` to disallow `for (let in)`
* is `{`, `[` or an identifier to allow `for (let {} = foo)`, `for (let [] = foo)` and `for (let bar = foo)`

Once reached the `of` or `in` keyword, the right-hand side expression needs to be passed with the correct \[+In] context to disallow
the two `in` expressions in `#prod-RelationalExpression`:

```
RelationalExpression[In, Yield, Await] :
    [+In] RelationalExpression[+In, ?Yield, ?Await] in ShiftExpression[?Yield, ?Await]
    [+In] PrivateIdentifier in ShiftExpression[?Yield, ?Await]

Note 2: The [In] grammar parameter is needed to avoid confusing the in operator in a relational expression with the in operator in a for statement.
```

And this is the only application for the `[In]` context in the entire specification.

Also to note, the grammar `[lookahead ∉ { let, async of }]` forbids `for (async of ...)`,
and it needs to be explicitly guarded against.

***

## Block-Level Function Declarations

In Annex B.3.2 `#sec-block-level-function-declarations-web-legacy-compatibility-semantics`,
an entire page is dedicated to explain how `FunctionDeclaration` is supposed to behave in `Block` statements.
It boils down to

```javascript reference
https://github.com/acornjs/acorn/blob/11735729c4ebe590e406f952059813f250a4cbd1/acorn/src/scope.js#L30-L35
```

The name of a `FunctionDeclaration` needs to be treated the same as a `var` declaration if its inside a function declaration.
This code snippet errors with a re-declaration error since `bar` is inside a block scope:

```javascript
function foo() {
  if (true) {
    var bar;
    function bar() {} // redeclaration error
  }
}
```

meanwhile, the following does not error because it is inside a function scope, function `bar` is treated as a var declaration:

```javascript
function foo() {
  var bar;
  function bar() {}
}
```

***

## Grammar Context

The syntactic grammar has 5 context parameters for allowing and disallowing certain constructs,
namely `[In]`, `[Return]`, `[Yield]`, `[Await]` and `[Default]`.

It is best to keep a context during parsing, for example in Biome:

```rust
// https://github.com/rome/tools/blob/5a059c0413baf1d54436ac0c149a829f0dfd1f4d/crates/rome_js_parser/src/state.rs#L404-L425

pub(crate) struct ParsingContextFlags: u8 {
    /// Whether the parser is in a generator function like `function* a() {}`
    /// Matches the `Yield` parameter in the ECMA spec
    const IN_GENERATOR = 1 << 0;
    /// Whether the parser is inside a function
    const IN_FUNCTION = 1 << 1;
    /// Whatever the parser is inside a constructor
    const IN_CONSTRUCTOR = 1 << 2;

    /// Is async allowed in this context. Either because it's an async function or top level await is supported.
    /// Equivalent to the `Async` generator in the ECMA spec
    const IN_ASYNC = 1 << 3;

    /// Whether the parser is parsing a top-level statement (not inside a class, function, parameter) or not
    const TOP_LEVEL = 1 << 4;

    /// Whether the parser is in an iteration or switch statement and
    /// `break` is allowed.
    const BREAK_ALLOWED = 1 << 5;

    /// Whether the parser is in an iteration statement and `continue` is allowed.
    const CONTINUE_ALLOWED = 1 << 6;
```

And toggle and check these flags accordingly by following the grammar.

## AssignmentPattern vs BindingPattern

In `estree`, the left-hand side of an `AssignmentExpression` is a `Pattern`:

```
extend interface AssignmentExpression {
    left: Pattern;
}
```

and the left-hand side of a `VariableDeclarator` is a `Pattern`:

```
interface VariableDeclarator <: Node {
    type: "VariableDeclarator";
    id: Pattern;
    init: Expression | null;
}
```

A `Pattern` can be a `Identifier`, `ObjectPattern`, `ArrayPattern`:

```
interface Identifier <: Expression, Pattern {
    type: "Identifier";
    name: string;
}

interface ObjectPattern <: Pattern {
    type: "ObjectPattern";
    properties: [ AssignmentProperty ];
}

interface ArrayPattern <: Pattern {
    type: "ArrayPattern";
    elements: [ Pattern | null ];
}
```

But from the specification perspective, we have the following JavaScript:

```javascript
// AssignmentExpression:
{ foo } = bar;
  ^^^ IdentifierReference
[ foo ] = bar;
  ^^^ IdentifierReference

// VariableDeclarator
var { foo } = bar;
      ^^^ BindingIdentifier
var [ foo ] = bar;
      ^^^ BindingIdentifier
```

This starts to become confusing because we now have a situation where we cannot directly distinguish whether the `Identifier` is a `BindingIdentifier` or a `IdentifierReference`
inside a `Pattern`:

```rust
enum Pattern {
    Identifier, // Is this a `BindingIdentifier` or a `IdentifierReference`?
    ArrayPattern,
    ObjectPattern,
}
```

This will lead to all sorts of unnecessary code further down the parser pipeline.
For example, when setting up the scope for semantic analysis, we need to inspect the parents of this `Identifier`
to determine whether we should bind it to the scope or not.

A better solution is to fully understand the specification and decide what to do.

The grammar for `AssignmentExpression` and `VariableDeclaration` are defined as:

```
13.15 Assignment Operators

AssignmentExpression[In, Yield, Await] :
    LeftHandSideExpression[?Yield, ?Await] = AssignmentExpression[?In, ?Yield, ?Await]

13.15.5 Destructuring Assignment

In certain circumstances when processing an instance of the production
AssignmentExpression : LeftHandSideExpression = AssignmentExpression
the interpretation of LeftHandSideExpression is refined using the following grammar:

AssignmentPattern[Yield, Await] :
    ObjectAssignmentPattern[?Yield, ?Await]
    ArrayAssignmentPattern[?Yield, ?Await]
```

```
14.3.2 Variable Statement

VariableDeclaration[In, Yield, Await] :
    BindingIdentifier[?Yield, ?Await] Initializer[?In, ?Yield, ?Await]opt
    BindingPattern[?Yield, ?Await] Initializer[?In, ?Yield, ?Await]
```

The specification distinguishes this two grammar by defining them separately with an `AssignmentPattern` and a `BindingPattern`.

So in situations like this, do not be afraid to deviate from `estree` and define extra AST nodes for our parser:

```rust
enum BindingPattern {
    BindingIdentifier,
    ObjectBindingPattern,
    ArrayBindingPattern,
}

enum AssignmentPattern {
    IdentifierReference,
    ObjectAssignmentPattern,
    ArrayAssignmentPattern,
}
```

I was in a super confusing state for a whole week until I finally reached enlightenment:
we need to define an `AssignmentPattern` node and a `BindingPattern` node instead of a single `Pattern` node.

* `estree` must be correct because people have been using it for years so it cannot be wrong?
* how are we going to cleanly distinguish the `Identifier`s inside the patterns without defining two separate nodes? I just cannot find where the grammar is?
* After a whole day of navigating the specification ... the grammar for `AssignmentPattern` is in the 5th subsection of the main section "13.15 Assignment Operators" with the subtitle "Supplemental Syntax" 🤯 - this is really out of place because all grammar is defined in the main section, not like this one defined after the "Runtime Semantics" section

***

:::tip
The following cases are really difficult to grasp. Here be dragons.
:::

## Ambiguous Grammar

Let's first think like a parser and solve the problem - given the `/` token, is it a division operator or the start of a regex expression?

```javascript
a / b;
a / / regex /;
a /= / regex /;
/ regex / / b;
/=/ / /=/;
```

It is almost impossible, isn't it? Let's break these down and follow the grammar.

The first thing we need to understand is that the syntactic grammar drives the lexical grammar as stated in `#sec-ecmascript-language-lexical-grammar`

> There are several situations where the identification of lexical input elements is sensitive to the syntactic grammar context that is consuming the input elements.

This means that the parser is responsible for telling the lexer which token to return next.
The above example indicates that the lexer needs to return either a `/` token or a `RegExp` token.
For getting the correct `/` or `RegExp` token, the specification says:

> The InputElementRegExp goal symbol is used in all syntactic grammar contexts where a RegularExpressionLiteral is permitted ...
> In all other contexts, InputElementDiv is used as the lexical goal symbol.

And the syntax for `InputElementDiv` and `InputElementRegExp` are

```
InputElementDiv ::
    WhiteSpace
    LineTerminator
    Comment
    CommonToken
    DivPunctuator <---------- the `/` and `/=` token
    RightBracePunctuator

InputElementRegExp ::
    WhiteSpace
    LineTerminator
    Comment
    CommonToken
    RightBracePunctuator
    RegularExpressionLiteral <-------- the `RegExp` token
```

This means whenever the grammar reaches `RegularExpressionLiteral`, `/` need to be tokenized as a `RegExp` token (and throw an error if it does not have a matching `/`).
All other cases we'll tokenize `/` as a slash token.

Let's walk through an example:

```
a / / regex /
^ ------------ PrimaryExpression:: IdentifierReference
  ^ ---------- MultiplicativeExpression: MultiplicativeExpression MultiplicativeOperator ExponentiationExpression
    ^^^^^^^^ - PrimaryExpression: RegularExpressionLiteral
```

This statement does not match any other start of `Statement`,
so it'll go down the `ExpressionStatement` route:

`ExpressionStatement` --> `Expression` --> `AssignmentExpression` --> ... -->
`MultiplicativeExpression` --> ... -->
`MemberExpression` --> `PrimaryExpression` --> `IdentifierReference`.

We stopped at `IdentifierReference` and not `RegularExpressionLiteral`,
the statement "In all other contexts, InputElementDiv is used as the lexical goal symbol" applies.
The first slash is a `DivPunctuator` token.

Since this is a `DivPunctuator` token,
the grammar `MultiplicativeExpression: MultiplicativeExpression MultiplicativeOperator ExponentiationExpression` is matched,
the right-hand side is expected to be an `ExponentiationExpression`.

Now we are at the second slash in `a / /`.
By following `ExponentiationExpression`,
we reach `PrimaryExpression: RegularExpressionLiteral` because `RegularExpressionLiteral` is the only matching grammar with a `/`:

```
RegularExpressionLiteral ::
    / RegularExpressionBody / RegularExpressionFlags
```

This second `/` will be tokenized as `RegExp` because
the specification states "The InputElementRegExp goal symbol is used in all syntactic grammar contexts where a RegularExpressionLiteral is permitted".

:::info
As an exercise, try and follow the grammar for `/=/ / /=/`.
:::

***

## Cover Grammar

Read the [V8 blog post](https://v8.dev/blog/understanding-ecmascript-part-4) on this topic first.

To summarize, the specification states the following three cover grammars:

#### CoverParenthesizedExpressionAndArrowParameterList

```
PrimaryExpression[Yield, Await] :
    CoverParenthesizedExpressionAndArrowParameterList[?Yield, ?Await]

When processing an instance of the production
PrimaryExpression[Yield, Await] : CoverParenthesizedExpressionAndArrowParameterList[?Yield, ?Await]
    the interpretation of CoverParenthesizedExpressionAndArrowParameterList is refined using the following grammar:

ParenthesizedExpression[Yield, Await] :
    ( Expression[+In, ?Yield, ?Await] )
```

```
ArrowFunction[In, Yield, Await] :
    ArrowParameters[?Yield, ?Await] [no LineTerminator here] => ConciseBody[?In]

ArrowParameters[Yield, Await] :
    BindingIdentifier[?Yield, ?Await]
    CoverParenthesizedExpressionAndArrowParameterList[?Yield, ?Await]
```

These definitions defines:

```javascript
let foo = (a, b, c); // SequenceExpression
let bar = (a, b, c) => {}; // ArrowExpression
          ^^^^^^^^^ CoverParenthesizedExpressionAndArrowParameterList
```

A simple but cumbersome approach to solving this problem is to parse it as a `Vec<Expression>` first,
then write a converter function to convert it to `ArrowParameters` node, i.e. each individual `Expression` need to be converted to a `BindingPattern`.

It should be noted that, if we are building the scope tree within the parser,
i.e. create the scope for arrow expression during parsing,
but do not create one for a sequence expression,
it is not obvious how to do this. [esbuild](https://github.com/evanw/esbuild) solved this problem by creating a temporary scope first,
and then dropping it if it is not an `ArrowExpression`.

This is stated in its [architecture document](https://github.com/evanw/esbuild/blob/master/docs/architecture.md#symbols-and-scopes):

> This is mostly pretty straightforward except for a few places where the parser has pushed a scope and is in the middle of parsing a declaration only to discover that it's not a declaration after all. This happens in TypeScript when a function is forward-declared without a body, and in JavaScript when it's ambiguous whether a parenthesized expression is an arrow function or not until we reach the => token afterwards. This would be solved by doing three passes instead of two so we finish parsing before starting to set up scopes and declare symbols, but we're trying to do this in just two passes. So instead we call popAndDiscardScope() or popAndFlattenScope() instead of popScope() to modify the scope tree later if our assumptions turn out to be incorrect.

***

#### CoverCallExpressionAndAsyncArrowHead

```
CallExpression :
    CoverCallExpressionAndAsyncArrowHead

When processing an instance of the production
CallExpression : CoverCallExpressionAndAsyncArrowHead
the interpretation of CoverCallExpressionAndAsyncArrowHead is refined using the following grammar:

CallMemberExpression[Yield, Await] :
    MemberExpression[?Yield, ?Await] Arguments[?Yield, ?Await]
```

```
AsyncArrowFunction[In, Yield, Await] :
    CoverCallExpressionAndAsyncArrowHead[?Yield, ?Await] [no LineTerminator here] => AsyncConciseBody[?In]

CoverCallExpressionAndAsyncArrowHead[Yield, Await] :
    MemberExpression[?Yield, ?Await] Arguments[?Yield, ?Await]

When processing an instance of the production
AsyncArrowFunction : CoverCallExpressionAndAsyncArrowHead => AsyncConciseBody
the interpretation of CoverCallExpressionAndAsyncArrowHead is refined using the following grammar:

AsyncArrowHead :
    async [no LineTerminator here] ArrowFormalParameters[~Yield, +Await]
```

These definitions define:

```javascript
async (a, b, c); // CallExpression
async (a, b, c) => {} // AsyncArrowFunction
^^^^^^^^^^^^^^^ CoverCallExpressionAndAsyncArrowHead
```

This looks strange because `async` is not a keyword. The first `async` is a function name.

***

#### CoverInitializedName

```
13.2.5 Object Initializer

ObjectLiteral[Yield, Await] :
    ...

PropertyDefinition[Yield, Await] :
    CoverInitializedName[?Yield, ?Await]

Note 3: In certain contexts, ObjectLiteral is used as a cover grammar for a more restricted secondary grammar.
The CoverInitializedName production is necessary to fully cover these secondary grammars. However, use of this production results in an early Syntax Error in normal contexts where an actual ObjectLiteral is expected.

13.2.5.1 Static Semantics: Early Errors

In addition to describing an actual object initializer the ObjectLiteral productions are also used as a cover grammar for ObjectAssignmentPattern and may be recognized as part of a CoverParenthesizedExpressionAndArrowParameterList. When ObjectLiteral appears in a context where ObjectAssignmentPattern is required the following Early Error rules are not applied. In addition, they are not applied when initially parsing a CoverParenthesizedExpressionAndArrowParameterList or CoverCallExpressionAndAsyncArrowHead.

PropertyDefinition : CoverInitializedName
    I* t is a Syntax Error if any source text is matched by this production.
```

```
13.15.1 Static Semantics: Early Errors

AssignmentExpression : LeftHandSideExpression = AssignmentExpression
If LeftHandSideExpression is an ObjectLiteral or an ArrayLiteral, the following Early Error rules are applied:
    * LeftHandSideExpression must cover an AssignmentPattern.
```

These definitions define:

```javascript
({ prop = value } = {}); // ObjectAssignmentPattern
({ prop: value }); // ObjectLiteral with SyntaxError
```

Parsers need to parse `ObjectLiteral` with `CoverInitializedName`,
and throw the syntax error if it does not reach `=` for `ObjectAssignmentPattern`.

As an exercise, which one of the following `=` should throw a syntax error?

```javascript
let { x = 1 } = ({ x = 1 } = { x: 1 });
```

---

---
url: /docs/guide/usage/formatter/ignore-files.md
---

# Ignore files

Oxfmt provides several ways to exclude files from formatting.

Some ignore mechanisms apply globally, while others are scoped to the config file they belong to:

| Mechanism                           | Scope                 |
| ----------------------------------- | --------------------- |
| CLI paths with `!` prefix           | Global                |
| `.prettierignore` / `--ignore-path` | Global                |
| `ignorePatterns` in config          | Scoped to that config |

When using [nested config](./config#create-a-config-file), `ignorePatterns` only applies to files that are resolved by that particular config file. Global mechanisms always apply regardless of which config file is in effect.

## `ignorePatterns`

The recommended way to ignore files. Add to your Oxfmt config:

::: code-group

```json [.oxfmtrc.json]
{
  "ignorePatterns": ["dist/**", "*.min.js"]
}
```

```ts [oxfmt.config.ts]
import { defineConfig } from "oxfmt";

export default defineConfig({
  ignorePatterns: ["dist/**", "*.min.js"],
});
```

:::

* Uses `.gitignore` syntax
* Paths are resolved relative to the directory containing the Oxfmt config file
* Formatter-specific and independent of Git

Files matching `ignorePatterns` **cannot be formatted**, even if explicitly specified.

## `.gitignore`

Oxfmt respects the same Git ignore rules as Git itself:

* `.gitignore` files in the current directory tree
* `.gitignore` files in parent directories (up to the repository boundary)
* `.git/info/exclude`

However, global gitignore (`core.excludesFile`) is not read.

Files ignored by `.gitignore` **can still be formatted** if explicitly specified.

## VCS directories and `node_modules`

Ignored by default: `.git`, `.svn`, `.jj`, `node_modules`

Use `--with-node-modules` to include `node_modules`.

## Lock files

`package-lock.json`, `pnpm-lock.yaml`, etc. are always ignored.

## `.prettierignore`

Supported for Prettier compatibility. Uses `.gitignore` syntax.

Files in `.prettierignore` cannot be formatted, even when explicitly specified.

For new projects, prefer `ignorePatterns`.

---

---
url: /docs/guide/usage/linter/ignore-files.md
description: Control which files Oxlint lints.
---

# Ignore files

Large repositories contain files that should not be linted, such as build output, vendored code, snapshots, or generated artifacts. Oxlint provides a predictable ignore model that works well in monorepos and CI.

> \[!TIP]
> It is strongly recommended to use `"ignorePatterns"` in your Oxlint config file (`.oxlintrc.json` or `oxlint.config.ts`) for ignoring files rather than a separate ignore file. This ensures that every developer will have the same ignores across all tools and commands running Oxlint, especially IDE/editor integrations. It also keeps your configuration centralized to one file.

## Default ignores

Oxlint automatically ignores:

* `.git` directories
* Minified files containing `.min.`, `-min.`, or `_min.` in the file name
* Files matched by `.gitignore` (global gitignore files are not respected)

Hidden files are not automatically ignored.

## `ignorePatterns`

The recommended approach is to define ignores in your config file using `ignorePatterns`. This keeps ignores close to the configuration they belong to and works naturally with nested configs.

Patterns are resolved relative to the configuration file.

::: code-group

```json [.oxlintrc.json]
{
  "$schema": "./node_modules/oxlint/configuration_schema.json",
  "ignorePatterns": ["dist/**", "coverage/**", "vendor/**", "test/snapshots/**"]
}
```

```ts [oxlint.config.ts]
import { defineConfig } from "oxlint";

export default defineConfig({
  ignorePatterns: ["dist/**", "coverage/**", "vendor/**", "test/snapshots/**"],
});
```

:::

In monorepos, nested configs can ignore package specific output without affecting the rest of the repository.

## `.eslintignore`

Oxlint also supports `.eslintignore` for compatibility with existing ESLint setups. Existing `.eslintignore` files can remain in place during migration. The syntax is compatible with `.gitignore`, including comments and negation patterns.

New projects should prefer `"ignorePatterns"` in their config file, and we strongly recommend moving over to `"ignorePatterns"` soon after migrating, if not during migration.

## Ignore from the command line

CLI flags are useful for one-off changes in CI or local debugging.

Use a custom ignore file:

```bash
oxlint --ignore-path path/to/ignorefile
```

Add additional ignore patterns:

```bash
oxlint --ignore-pattern 'dist/**' --ignore-pattern 'coverage/**'
```

Quote patterns to avoid shell glob expansion.

## Unignoring files

Ignore files support negation patterns, which allow a directory to be ignored while keeping specific files.

To ignore everything under `build/` except one file, ignore the contents rather than the directory itself:

::: code-group

```json [.oxlintrc.json]
{
  "$schema": "./node_modules/oxlint/configuration_schema.json",
  "ignorePatterns": ["build/**/*", "!build/keep.js"]
}
```

```ts [oxlint.config.ts]
import { defineConfig } from "oxlint";

export default defineConfig({
  ignorePatterns: ["build/**/*", "!build/keep.js"],
});
```

:::

This keeps traversal possible while still ignoring almost everything.

## Disable ignoring

To disable all ignore behavior, including ignore files and CLI ignore options, use `--no-ignore`:

```bash
oxlint --no-ignore
```

---

---
url: /docs/guide/usage/linter/rules/import/consistent-type-specifier-style.md
---

### What it does

Enforces or bans the use of inline type-only markers for named imports.

### Why is this bad?

Mixing top-level `import type { Foo } from 'foo'` with inline `{ type Bar }`
forces readers to mentally switch contexts when scanning your imports.
Enforcing one style makes it immediately obvious which imports are types and which are value imports.

### Examples

Examples of incorrect code for the default `prefer-top-level` option:

```typescript
import { type Foo } from "Foo";
import Foo, { type Bar } from "Foo";
```

Examples of correct code for the default option:

```typescript
import type { Foo } from 'Foo';
import type Foo, { Bar } from 'Foo';
```

Examples of incorrect code for the `prefer-top-level-if-only-type-imports` option:

```typescript
import { type Foo } from "Foo";
import { type Foo, type Bar } from "Foo";
```

Examples of correct code for the `prefer-top-level-if-only-type-imports` option:

```typescript
import type { Foo } from 'Foo';
import { type Foo, someValue } from 'Foo';
import type Foo, { Bar } from 'Foo';
```

Examples of incorrect code for the `prefer-inline` option:

```typescript
import type { Foo } from 'Foo';
import type Foo, { Bar } from 'Foo';
```

Examples of correct code for the `prefer-inline` option:

```typescript
import { type Foo } from "Foo";
import Foo, { type Bar } from "Foo";
```

## Configuration

This rule accepts one of the following string values:

### `"prefer-top-level"`

Prefer `import type { Foo } from 'foo'` for type imports.

### `"prefer-inline"`

Prefer `import { type Foo } from 'foo'` for type imports.

### `"prefer-top-level-if-only-type-imports"`

Prefer `import type { Foo } from 'foo'` when all named imports are types, but allow
`import { type Foo, bar } from 'foo'` when value imports are present.

## How to use

## Version

This rule was added in v0.16.11.

## References

---

---
url: /docs/guide/usage/linter/rules/import/default.md
---

### What it does

If a default import is requested, this rule will report if there is no
default export in the imported module.

### 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
export function bar() {
  return null;
}

// ./foo.js
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
```

## How to use

## Version

This rule was added in v0.0.13.

## References

---

---
url: /docs/guide/usage/linter/rules/import/export.md
---

### What it does

Reports funny business with exports, like repeated exports of names or defaults.

### 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"; // 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
```

## How to use

## Version

This rule was added in v0.0.21.

## References

---

---
url: /docs/guide/usage/linter/rules/import/exports-last.md
---

### What it does

This rule enforces that all exports are declared at the bottom of the file.
This rule will report any export declarations that comes before any non-export statements.

### Why is this bad?

Exports scattered throughout the file can lead to poor code readability
and increase the cost of locating the export quickly

### Examples

Examples of **incorrect** code for this rule:

```js
const bool = true;
export const foo = "bar";
const str = "foo";
```

Examples of **correct** code for this rule:

```js
const arr = ["bar"];
export const bool = true;
export const str = "foo";
export function func() {
  console.log("Hello World");
}
```

## How to use

## Version

This rule was added in v0.15.14.

## References

---

---
url: /docs/guide/usage/linter/rules/import/extensions.md
---

### What it does

Some file resolve algorithms allow you to omit the file extension within the import source path.
For example the node resolver (which does not yet support ESM/import) can resolve ./foo/bar to the absolute path /User/someone/foo/bar.js because the .js extension is resolved automatically by default in CJS.
Depending on the resolver you can configure more extensions to get resolved automatically.
In order to provide a consistent use of file extensions across your code base, this rule can enforce or disallow the use of certain file extensions.

### Why is this bad?

ESM-based file resolve algorithms (e.g., the one that Vite provides) recommend
specifying the file extension to improve performance. Without extensions, the
bundler must check for various possible file extensions, which can slow down
the build process on large projects. In addition, common ESM environments
(such as browsers and Node.js) typically require fully specified relative imports,
which means extensionless imports are not supported there.

For personal preference and compatibility reasons, the rule also allows configuration
to *disallow* extensions in imports. This is generally not recommended, but it can be
done if preferred.

### Examples

Examples of **incorrect** code for this rule:

The following patterns are considered problems when configuration set to "always":

```js
import foo from "./foo";
import bar from "./bar";
import Component from "./Component";
import foo from "@/foo";
```

The following patterns are considered problems when configuration set to "never":

```js
import foo from "./foo.js";
import bar from "./bar.json";
import Component from "./Component.jsx";
import express from "express/index.js";
```

Examples of **correct** code for this rule:

The following patterns are not considered problems when configuration set to "always":

```js
import foo from "./foo.js";
import bar from "./bar.json";
import Component from "./Component.jsx";
import * as path from "path";
import foo from "@/foo.js";
```

The following patterns are not considered problems when configuration set to "never":

```js
import foo from "./foo";
import bar from "./bar";
import Component from "./Component";
import express from "express/index";
import * as path from "path";
```

**Per-extension configuration examples**:

```js
// Configuration: { "vue": "always", "ts": "never" }
import Component from "./Component.vue"; // ✓ OK - .vue configured as "always"
import utils from "./utils"; // ✓ OK - .ts configured as "never"
import styles from "./styles.css"; // ✓ OK - .css not configured, ignored

// Configuration: ["ignorePackages", { "js": "never", "ts": "never" }]
import foo from "./foo"; // ✓ OK - no extension
import bar from "lodash/fp"; // ✓ OK - package import, ignored (ignorePackages sets this to true)
```

### Differences compared to `eslint-plugin-import`

If you see differences between this rule implementation and the original `eslint-plugin-import`
rule, please note that there are some intentional, inherent differences in the behavior of this
rule and the original.

Oxlint understands and can resolve TypeScript paths out-of-the-box. If your ESLint
configuration did not include `eslint-import-resolver-typescript` or similar, then the original
rule will not have been able to resolve TypeScript paths correctly, and so the behavior
between ESLint and Oxlint may differ. Generally, this means that Oxlint will catch *more*
valid violations than the original rule, though this depends on the specific configuration.

Oxlint is also able to resolve multiple `tsconfig.json` files in a single repo, and so in a
monorepo setup will be more capable with regards to resolving file paths.

## Configuration

### \[0]

type: `"always" | "never" | "ignorePackages"`

Extension rule configuration; Copy to avoid extra indirection.

### \[1]

type: `object`

#### \[1].checkTypeImports

type: `boolean`

default: `false`

Whether to check type imports when enforcing extension rules.

#### \[1].ignorePackages

type: `boolean`

default: `false`

Whether to ignore package imports when enforcing extension rules.

#### \[1].pathGroupOverrides

type: `array`

Path group overrides for bespoke import specifiers.

##### \[1].pathGroupOverrides\[n]

type: `object`

###### \[1].pathGroupOverrides\[n].action

type: `"enforce" | "ignore"`

Action to take when pattern matches.

Action to take for path group overrides.

Determines how import extensions are validated for matching bespoke import specifiers.

\####### `"enforce"`

Enforce extension validation for matching imports (require extensions based on config).

\####### `"ignore"`

Ignore matching imports entirely (skip all extension validation).

###### \[1].pathGroupOverrides\[n].pattern

type: `string`

Glob pattern to match import specifiers.

#### \[1].pattern

type: `Record<string, string>`

Per-extension rules.

## How to use

## Version

This rule was added in v1.2.0.

## References

---

---
url: /docs/guide/usage/linter/rules/import/first.md
---

### What it does

Forbids any non-import statements before imports except directives.

### Why is this bad?

Notably, imports are hoisted, which means the imported modules will be evaluated
before any of the statements interspersed between them.
Keeping all imports together at the top of the file may prevent surprises
resulting from this part of the spec

### Examples

Examples of **incorrect** code for this rule:

```js
import { x } from "./foo";
export { x };
import { y } from "./bar";
```

Examples of **correct** code for this rule:

```js
import { x } from "./foo";
import { y } from "./bar";
export { x, y };
```

## Configuration

This rule accepts one of the following string values:

### `"absolute-first"`

Forces absolute imports to be listed before relative imports.

Examples of **incorrect** code for this rule with `"absolute-first"`:

```js
import { x } from "./foo";
import { y } from "bar";
```

Examples of **correct** code for this rule with `"absolute-first"`:

```js
import { y } from "bar";
import { x } from "./foo";
```

### `"disable-absolute-first"`

Disables the absolute-first behavior.
This is the default behavior.

## How to use

## Version

This rule was added in v0.11.1.

## References

---

---
url: /docs/guide/usage/linter/rules/import/group-exports.md
---

### What it does

Reports when named exports are not grouped together in a single export declaration
or when multiple assignments to CommonJS module.exports
or exports object are present in a single file.

### Why is this bad?

An export declaration or module.exports assignment can appear anywhere in the code.
By requiring a single export declaration all your exports will remain at one place,
making it easier to see what exports a module provides.

### Examples

Examples of **incorrect** code for this rule:

```js
export const first = true;
export const second = true;
```

Examples of **correct** code for this rule:

```js
const first = true;
const second = true;
export { first, second };
```

## How to use

## Version

This rule was added in v0.16.6.

## References

---

---
url: /docs/guide/usage/linter/rules/import/max-dependencies.md
---

### What it does

Forbid modules to have too many dependencies (`import` statements only).

### 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.

**NOTE**: This rule only counts `import` statements, and does not count dependencies from
CommonJS `require()` statements. This is a difference from the original
eslint-import-plugin rule.

### Examples

Given `{ "max": 2 }`

Examples of **incorrect** code for this rule:

```javascript
import a from "./a";
import b from "./b";
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)
```

## Configuration

### ignoreTypeImports

type: `boolean`

default: `false`

Whether to ignore type imports when counting dependencies.

```ts
// Neither of these count as dependencies if `ignoreTypeImports` is true:
import type { Foo } from "./foo";
import { type Foo } from "./foo";
```

### max

type: `integer`

default: `10`

Maximum number of dependencies allowed in a file.

## How to use

## Version

This rule was added in v0.5.0.

## References

---

---
url: /docs/guide/usage/linter/rules/import/named.md
---

### What it does

Verifies that all named imports are part of the set of named exports in
the referenced module.

For `export`, verifies that all named exports exist in the referenced
module.

Note: for packages, the plugin will find exported names from
`jsnext:main` (deprecated) or `module`, if present in `package.json`.
Redux's npm module includes this key, and thereby is lintable, for
example.

A module path that is ignored or not unambiguously an ES module will not
be reported when imported. Note that type imports and exports, as used
by Flow, are always ignored.

### Why is this bad?

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

```js
// ./foo.js
export const foo = "I'm so foo";
```

Examples of **incorrect** code for this rule:

```js
// ./baz.js
import { notFoo } from "./foo";

// re-export
export { notFoo as defNotBar } from "./foo";

// will follow 'jsnext:main', if available
import { dontCreateStore } from "redux";
```

Examples of **correct** code for this rule:

```js
// ./bar.js
import { foo } from "./foo";

// re-export
export { foo as bar } from "./foo";

// node_modules without jsnext:main are not analyzed by default
// (import/ignore setting)
import { SomeNonsenseThatDoesntExist } from "react";
```

## How to use

## Version

This rule was added in v0.0.13.

## References

---

---
url: /docs/guide/usage/linter/rules/import/namespace.md
---

### What it does

Enforces names exist at the time they are dereferenced, when imported as
a full namespace (i.e. `import * as foo from './foo'; foo.bar();` will
report if bar is not exported by `./foo.`). Will report at the import
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
```

## Configuration

This rule accepts a configuration object with the following properties:

### allowComputed

type: `boolean`

default: `false`

Whether to allow computed references to an imported namespace.

## How to use

## Version

This rule was added in v0.2.11.

## References

---

---
url: /docs/guide/usage/linter/rules/import/newline-after-import.md
---

### What it does

Enforces having one or more empty lines after the last top-level import statement or require call.

### Why is this bad?

Without a blank line, import/require declarations blend into the following logic,
which hurts readability and makes changes harder to scan. A blank line clearly
separates dependencies from implementation.

### Examples

Examples of **incorrect** code for this rule:

```js
import * as foo from "foo";
const FOO = "BAR";
```

```js
import * as foo from "foo";
const FOO = "BAR";

import { bar } from "bar-lib";
```

```js
const FOO = require("./foo");
const BAZ = 1;
const BAR = require("./bar");
```

Examples of **correct** code for this rule:

```js
import defaultExport from "./foo";

const FOO = "BAR";
```

```js
import defaultExport from "./foo";
import { bar } from "bar-lib";

const FOO = "BAR";
```

```js
const FOO = require("./foo");
const BAR = require("./bar");

const BAZ = 1;
```

With count set to 2 this will be considered valid:

```js
import defaultExport from "./foo";

const FOO = "BAR";
```

```js
import defaultExport from "./foo";

const FOO = "BAR";
```

With count set to 2 these will be considered invalid:

```js
import defaultExport from "./foo";
const FOO = "BAR";
```

```js
import defaultExport from "./foo";

const FOO = "BAR";
```

With count set to 2 and exactCount set to true this will be considered valid:

```js
import defaultExport from "./foo";

const FOO = "BAR";
```

With count set to 2 and exactCount set to true these will be considered invalid:

```js
import defaultExport from "./foo";
const FOO = "BAR";
```

```js
import defaultExport from "./foo";

const FOO = "BAR";
```

```js
import defaultExport from "./foo";

const FOO = "BAR";
```

```js
import defaultExport from "./foo";

const FOO = "BAR";
```

With considerComments set to false this will be considered valid:

```js
import defaultExport from "./foo";
// some comment here.
const FOO = "BAR";
```

With considerComments set to true this will be considered valid:

```js
import defaultExport from "./foo";

// some comment here.
const FOO = "BAR";
```

With considerComments set to true this will be considered invalid:

```js
import defaultExport from "./foo";
// some comment here.
const FOO = "BAR";
```

### Example options usage

```json
{
  "rules": {
    "import/newline-after-import": ["error", { "count": 1 }]
  }
}
```

## Configuration

This rule accepts a configuration object with the following properties:

### considerComments

type: `boolean`

default: `false`

### count

type: `integer`

default: `1`

### exactCount

type: `boolean`

default: `false`

## How to use

## Version

This rule was added in v1.66.0.

## References

---

---
url: /docs/guide/usage/linter/rules/import/no-absolute-path.md
---

### What it does

Forbid the import of modules using absolute paths.

### Why is this bad?

Node.js allows the import of modules using an absolute path such as `/home/xyz/file.js`.
That is a bad practice as it ties the code using it to your computer,
and therefore makes it unusable in packages distributed on npm for instance.

### Examples

Examples of **incorrect** code for this rule:

```js
import f from "/foo";
import f from "/some/path";
var f = require("/foo");
var f = require("/some/path");
```

Examples of **correct** code for this rule:

```js
import _ from "lodash";
import foo from "foo";
import foo from "./foo";

var _ = require("lodash");
var foo = require("foo");
var foo = require("./foo");
```

Examples of **incorrect** code for the `{ amd: true }` option:

```js
define("/foo", function (foo) {});
require("/foo", function (foo) {});
```

Examples of **correct** code for the `{ amd: true }` option:

```js
define("./foo", function (foo) {});
require("./foo", function (foo) {});
```

## Configuration

This rule accepts a configuration object with the following properties:

### amd

type: `boolean`

default: `false`

If set to `true`, dependency paths for AMD-style define and require calls will be resolved:

```js
/* import/no-absolute-path: ["error", { "commonjs": false, "amd": true }] */
define(["/foo"], function (foo) {
  /*...*/
}); // reported
require(["/foo"], function (foo) {
  /*...*/
}); // reported

const foo = require("/foo"); // ignored because of explicit `commonjs: false`
```

### commonjs

type: `boolean`

default: `true`

If set to `true`, dependency paths for CommonJS-style require calls will be resolved:

```js
var foo = require("/foo"); // reported
```

### esmodule

type: `boolean`

default: `true`

If set to `true`, dependency paths for ES module import statements will be resolved:

```js
import foo from "/foo"; // reported
```

## How to use

## Version

This rule was added in v0.15.13.

## References

---

---
url: /docs/guide/usage/linter/rules/import/no-amd.md
---

### What it does

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 ES 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:

```javascript
require([a, b], function () {});
```

Examples of **correct** code for this rule:

```javascript
require("../name");
require(`../name`);
```

## How to use

## Version

This rule was added in v0.0.16.

## References

---

---
url: /docs/guide/usage/linter/rules/import/no-anonymous-default-export.md
---

### What it does

Reports if a module's default export is unnamed.
This includes several types of unnamed data types;
literals, object expressions, arrays, anonymous functions, arrow functions,
and anonymous class declarations.

### Why is this bad?

Ensuring that default exports are named helps improve the grepability of
the codebase by encouraging the re-use of the same identifier for
the module's default export at its declaration site and at its import sites.

### Examples

Examples of **incorrect** code for this rule:

```js
export default [];
export default () => {};
export default class {};
export default function() {};
export default foo(bar);
export default 123;
export default {};
export default new Foo();
export default `foo`;
export default /^123/;
```

Examples of **correct** code for this rule:

```js
const foo = 123;
export default foo;
export default function foo() {};
export default class MyClass {};
export default function foo() {};
export default foo(bar);
/* import/no-anonymous-default-export: ["error", { "allowLiteral": true }] */
export default 123;
/* import/no-anonymous-default-export: ["error", { "allowArray": true }] */
export default []
/* import/no-anonymous-default-export: ["error", { "allowArrowFunction": true }] */
export default () => {};
/* import/no-anonymous-default-export: ["error", { "allowAnonymousClass": true }] */
export default class {};
/* import/no-anonymous-default-export: ["error", { "allowAnonymousFunction": true }] */
export default function() {};
/* import/no-anonymous-default-export: ["error", { "allowObject": true }] */
export default {};
/* import/no-anonymous-default-export: ["error", { "allowNew": true }] */
export default new Foo();
/* import/no-anonymous-default-export: ["error", { "allowCallExpression": true }] */
export default foo(bar);
```

By default, all types of anonymous default exports are forbidden,
but any types can be selectively allowed by toggling them on in the options.

## Configuration

This rule accepts a configuration object with the following properties:

### allowAnonymousClass

type: `boolean`

default: `false`

Allow anonymous class as default export.

### allowAnonymousFunction

type: `boolean`

default: `false`

Allow anonymous function as default export.

### allowArray

type: `boolean`

default: `false`

Allow anonymous array as default export.

### allowArrowFunction

type: `boolean`

default: `false`

Allow anonymous arrow function as default export.

### allowCallExpression

type: `boolean`

default: `true`

Allow anonymous call expression as default export.

### allowLiteral

type: `boolean`

default: `false`

Allow anonymous literal as default export.

### allowNew

type: `boolean`

default: `false`

Allow anonymous new expression as default export.

### allowObject

type: `boolean`

default: `false`

Allow anonymous object as default export.

## How to use

## Version

This rule was added in v0.15.14.

## References

---

---
url: /docs/guide/usage/linter/rules/import/no-commonjs.md
---

### What it does

Forbids the use of CommonJS `require` calls. Also forbids `module.exports` and `exports.*`.

### Why is this bad?

ESM modules or Typescript uses `import` and `export` syntax instead of CommonJS syntax.
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:

```js
var mod = require("fs");

var exports = (module.exports = {});

exports.sayHello = function () {
  return "Hello";
};

module.exports = "Hola";
```

Examples of **correct** code for this rule:

```js
var a = b && require("c");

if (typeof window !== "undefined") {
  require("somelib");
}

var fs = null;
try {
  fs = require("fs");
} catch (error) {}
```

## Configuration

This rule accepts a configuration object with the following properties:

### allowConditionalRequire

type: `boolean`

default: `true`

When set to `true`, allows conditional `require()` calls (e.g., inside `if` statements or try-catch blocks).
This is useful for places where you need to conditionally load via commonjs requires if ESM imports are not supported.

### allowPrimitiveModules

type: `boolean`

default: `false`

If `allowPrimitiveModules` option is set to true, the following is valid:

```js
module.exports = "foo";
module.exports = function rule(context) {
  return {/* ... */};
};
```

but this is still reported:

```js
module.exports = { x: "y" };
exports.z = function bark() {
  /* ... */
};
```

### allowRequire

type: `boolean`

default: `false`

If set to `true`, `require` calls are valid:

```js
var mod = require("./mod");
```

but `module.exports` is reported as usual.

## How to use

## Version

This rule was added in v0.11.0.

## References

---

---
url: /docs/guide/usage/linter/rules/import/no-cycle.md
---

### What it does

Disallow cyclic dependencies. The rule ensures that there is no resolvable path back
to this module via its dependencies.

This includes cycles of depth 1 (imported module imports me), up to an effectively
infinite value when 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.

### Examples

Examples of **incorrect** code for this rule:

```javascript
// dep-b.js
import "./dep-a.js";
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.

## Configuration

This rule accepts a configuration object with the following properties:

### allowUnsafeDynamicCyclicDependency

type: `boolean`

default: `false`

Allow cyclic dependency if there is at least one dynamic import in the chain

### ignoreExternal

type: `boolean`

default: `false`

Ignore external modules

### ignoreTypes

type: `boolean`

default: `true`

Ignore type-only imports

### maxDepth

type: `integer`

default: `Infinity`

Maximum dependency depth to traverse

## How to use

## Version

This rule was added in v0.0.13.

## References

---

---
url: /docs/guide/usage/linter/rules/import/no-default-export.md
---

### What it does

Disallow modules from having default exports.

This can help 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

Examples of **incorrect** code for this rule:

```javascript
export default 'bar';

const foo = 'foo';
export { foo as default }
```

Examples of **correct** code for this rule:

```javascript
export const foo = "foo";
export const bar = "bar";
```

## How to use

## Version

This rule was added in v0.2.14.

## References

---

---
url: /docs/guide/usage/linter/rules/import/no-duplicates.md
---

### What it does

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";

import a from "./module";
import { b } from "./module";
```

Examples of **correct** code for this rule:

```typescript
import { foo, bar } from "./module";

import * as a from "foo"; // separate statements for namespace imports
import { b } from "foo";

import { c } from "foo"; // separate type imports, unless
import type { d } from "foo"; // `prefer-inline` is true
```

## Configuration

This rule accepts a configuration object with the following properties:

### considerQueryString

type: `boolean`

default: `false`

When set to `true`, the rule will consider the query string part of the import path
when determining if imports are duplicates. This is useful when using loaders like
webpack that use query strings to configure how a module should be loaded.

Examples of **correct** code with this option set to `true`:

```javascript
import x from "./bar?optionX";
import y from "./bar?optionY";
```

### preferInline

type: `boolean`

default: `false`

When set to `true`, prefer inline type imports instead of separate type import
statements for TypeScript code.

Examples of **correct** code with this option set to `true`:

```typescript
import { Foo, type Bar } from "./module";
```

## How to use

## Version

This rule was added in v0.2.11.

## References

---

---
url: /docs/guide/usage/linter/rules/import/no-dynamic-require.md
---

### What it does

Forbids imports that use an expression for the module argument. This includes
dynamically resolved paths in `require` or `import` statements.

### Why is this bad?

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

Examples of **incorrect** code for this rule:

```javascript
require(name);
require(`../${name}`);
```

Examples of **correct** code for this rule:

```javascript
require("../name");
require(`../name`);
```

## Configuration

This rule accepts a configuration object with the following properties:

### esmodule

type: `boolean`

default: `false`

When `true`, also check `import()` expressions for dynamic module specifiers.

## How to use

## Version

This rule was added in v0.9.3.

## References

---

---
url: /docs/guide/usage/linter/rules/import/no-empty-named-blocks.md
---

### What it does

Enforces that named import blocks are not empty.

### Why is this bad?

Empty named imports serve no practical purpose and often
result from accidental deletions or tool-generated code.

### Examples

Examples of **incorrect** code for this rule:

```js
import {} from "mod";
import Default from "mod";
```

Examples of **correct** code for this rule:

```js
import { mod } from "mod";
import Default, { mod } from "mod";
```

## How to use

## Version

This rule was added in v0.16.1.

## References

---

---
url: /docs/guide/usage/linter/rules/import/no-mutable-exports.md
---

### What it does

Forbids the use of mutable exports with var or let.

### Why is this bad?

In general, we should always export constants

### Examples

Examples of **incorrect** code for this rule:

```js
export let count = 2;
export var count = 3;

let count = 4;
export { count };
```

Examples of **correct** code for this rule:

```js
export const count = 1;
export function getCount() {}
export class Counter {}
```

### Functions/Classes

Note that exported function/class declaration identifiers may be reassigned,
but are not flagged by this rule at this time. They may be in the future.

## How to use

## Version

This rule was added in v0.15.13.

## References

---

---
url: /docs/guide/usage/linter/rules/import/no-named-as-default.md
---

### 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.

### 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
export default "foo";
export const bar = true;
```

Examples of **incorrect** code for this rule:

```javascript
// Invalid: using exported name 'bar' as the identifier for default export.
import bar from "./foo.js";
```

Examples of **correct** code for this rule:

```javascript
// Valid: correctly importing default export with a non-conflicting name.
import foo from "./foo.js";
```

### Differences compared to `eslint-plugin-import`

If you see differences between this rule implementation and the original `eslint-plugin-import`
rule, please note that the behavior may differ in certain cases due to differences in how
module resolution is implemented and configured.

For example, the original rule may require additional resolver configuration to handle certain
imports, especially when TypeScript paths are used or in monorepo setups with multiple
`tsconfig.json` files.

## How to use

## Version

This rule was added in v0.2.3.

## References

---

---
url: /docs/guide/usage/linter/rules/import/no-named-as-default-member.md
---

### What it does

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.

### 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
export function bar() {
  return null;
}
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"; // Correct: accessing named export directly
```

## How to use

## Version

This rule was added in v0.2.1.

## References

---

---
url: /docs/guide/usage/linter/rules/import/no-named-default.md
---

### What it does

Reports use of a default export as a locally named import.

### Why is this bad?

Rationale: the syntax exists to import default exports expressively, let's use it.

### Examples

Examples of **incorrect** code for this rule:

```js
// message: Using exported name 'bar' as identifier for default export.
import { default as foo } from "./foo.js";
import { default as foo, bar } from "./foo.js";
```

Examples of **correct** code for this rule:

```js
import foo from "./foo.js";
import foo, { bar } from "./foo.js";
```

## How to use

## Version

This rule was added in v0.15.3.

## References

---

---
url: /docs/guide/usage/linter/rules/import/no-named-export.md
---

### What it does

Prohibit named exports.

### Why is this bad?

Named exports require strict identifier matching and can lead to fragile imports,
while default exports enforce a single, consistent module entry point.

### Examples

Examples of **incorrect** code for this rule:

```js
export const foo = "foo";

const bar = "bar";
export { bar };
```

Examples of **correct** code for this rule:

```js
export default 'bar';

const foo = 'foo';
export { foo as default }
```

## How to use

## Version

This rule was added in v1.19.0.

## References

---

---
url: /docs/guide/usage/linter/rules/import/no-namespace.md
---

### What it does

Enforce a convention of not using namespaced (a.k.a. "wildcard" \*) imports.

### Why is this bad?

Namespaced imports, while sometimes used, are generally considered less ideal in modern JavaScript development for several reasons:

1. **Specificity and Namespace Pollution**:

* **Specificity**: Namespaced imports import the entire module, bringing in everything, even if you only need a few specific functions or classes. This can lead to potential naming conflicts if different modules have the same names for different functions.
* **Pollution**: Importing an entire namespace pollutes your current scope with potentially unnecessary functions and variables. It increases the chance of accidental use of an unintended function or variable, leading to harder-to-debug errors.

2. **Maintainability**:

* **Clarity**: Namespaced imports can make it harder to understand which specific functions or classes are being used in your code. This is especially true in larger projects with numerous imports.
* **Refactoring**: If a function or class name changes within the imported module, you might need to update several parts of your code if you are using namespaced imports. This becomes even more challenging when dealing with multiple namespaces.

3. **Modern Practice**:

* **Explicit Imports**: Modern JavaScript practices encourage explicit imports for specific components. This enhances code readability and maintainability.
* **Tree-Shaking**: Tools like Webpack and Rollup use tree-shaking to remove unused code from your bundles. Namespaced imports can prevent efficient tree-shaking, leading to larger bundle sizes.

### Examples

Examples of **incorrect** code for this rule:

```js
import * as user from "user-lib";

import some, * as user from "./user";
```

Examples of **correct** code for this rule:

```js
import { getUserName, isUser } from "user-lib";

import user from "user-lib";
import defaultExport, { isUser } from "./user";
```

## Configuration

This rule accepts a configuration object with the following properties:

### ignore

type: `string[]`

default: `[]`

An array of glob strings for modules that should be ignored by the rule.
For example, `["*.json"]` will ignore all JSON imports.

## How to use

## Version

This rule was added in v0.12.0.

## References

---

---
url: /docs/guide/usage/linter/rules/import/no-nodejs-modules.md
---

### What it does

Forbid the use of Node.js builtin modules. Can be useful for client-side web projects that do not have access to those modules.

### Why is this bad?

Node.js builtins (e.g. `fs`, `path`, `crypto`) are not available in browsers, so importing them in client bundles causes runtime failures or forces bundlers to inject heavy polyfills/shims.
This increases bundle size, can leak server-only logic to the client, and may hide environment mismatches until production.

### Examples

Examples of **incorrect** code for this rule:

```js
import fs from "fs";
import path from "path";

var fs = require("fs");
var path = require("path");
```

Examples of **correct** code for this rule:

```js
import _ from "lodash";
import foo from "foo";
import foo from "./foo";

var _ = require("lodash");
var foo = require("foo");
var foo = require("./foo");

/* import/no-nodejs-modules: ["error", {"allow": ["path"]}] */
import path from "path";
```

## Configuration

This rule accepts a configuration object with the following properties:

### allow

type: `string[]`

Array of names of allowed modules. Defaults to an empty array.

## How to use

## Version

This rule was added in v1.43.0.

## References

---

---
url: /docs/guide/usage/linter/rules/import/no-relative-parent-imports.md
---

### What it does

Forbids importing modules from parent directories using relative paths.

### Why is this bad?

This restriction enforces tree-like folder structures instead of complex
graph-like structures, making large codebases easier to maintain.
Dependencies flow in one direction (parent to child), which clarifies
module relationships.

### Examples

Examples of **incorrect** code for this rule:

```javascript
import foo from "../bar";
import foo from "../../utils/helper";
const baz = require("../config");
export { qux } from "../shared";
```

Examples of **correct** code for this rule:

```javascript
import foo from "lodash";
import a from "./lib/a";
import b from "./b";
```

## How to use

## Version

This rule was added in v1.43.0.

## References

---

---
url: /docs/guide/usage/linter/rules/import/no-self-import.md
---

### What it does

Forbids a module from importing itself. This can sometimes happen accidentally,
especially during refactoring.

### 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 bar from "./bar.js"; // Correct: module imports another module
```

## How to use

## Version

This rule was added in v0.0.13.

## References

---

---
url: /docs/guide/usage/linter/rules/import/no-unassigned-import.md
---

### What it does

This rule aims to remove modules with side-effects by reporting when a module is imported but not assigned.

### Why is this bad?

With both CommonJS' require and the ES modules' import syntax,
it is possible to import a module but not to use its result.
This can be done explicitly by not assigning the module to a variable.
Doing so can mean either of the following things:

* The module is imported but not used
* The module has side-effects. Having side-effects,
  makes it hard to know whether the module is actually used or can be removed.
  It can also make it harder to test or mock parts of your application.

### Examples

Examples of **incorrect** code for this rule:

```js
import "should";
require("should");
```

Examples of **correct** code for this rule:

```js
import _ from "foo";
import _, { foo } from "foo";
import _, { foo as bar } from "foo";
const _ = require("foo");
const { foo } = require("foo");
const { foo: bar } = require("foo");
bar(require("foo"));
```

## Configuration

This rule accepts a configuration object with the following properties:

### allow

type: `string[]`

default: `[]`

A list of glob patterns to allow unassigned imports for specific modules.
For example:
`{ "allow": ["**/*.css"] }` will allow unassigned imports for any module ending with `.css`.

## How to use

## Version

This rule was added in v0.16.11.

## References

---

---
url: /docs/guide/usage/linter/rules/import/no-webpack-loader-syntax.md
---

### What it does

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).

### Examples

Examples of **incorrect** code for this rule:

```javascript
import myModule from "my-loader!my-module";
import theme from "style!css!./theme.css";

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");
```

## How to use

## Version

This rule was added in v0.7.0.

## References

---

---
url: /docs/guide/usage/linter/rules/import/prefer-default-export.md
---

### What it does

Checks whether there is a default export.

### Why is this bad?

This rule exists to standardize module exports by preferring default exports
when a module only has one export, enhancing readability, maintainability.

### Examples

Examples of **incorrect** code for the `{ target: "single" }` option:

```js
export const foo = "foo";
```

Examples of **correct** code for the `{ target: "single" }` option:

```js
export const foo = "foo";
const bar = "bar";
export default bar;
```

Examples of **incorrect** code for the `{ target: "any" }` option:

```js
export const foo = "foo";
export const baz = "baz";
```

Examples of **correct** code for the `{ target: "any" }` option:

```js
export default function bar() {}
```

## Configuration

This rule accepts a configuration object with the following properties:

### target

type: `"single" | "any"`

default: `"single"`

Configuration option to specify the target type for preferring default exports.

#### `"single"`

Prefer default export when there is only one export in the module.

#### `"any"`

Prefer default export in any module that has exports.

## How to use

## Version

This rule was added in v1.4.0.

## References

---

---
url: /docs/guide/usage/linter/rules/import/unambiguous.md
---

### What it does

Warn if a `module` could be mistakenly parsed as a `script` instead of
as a pure [ES module](https://nodejs.org/api/esm.html#modules-ecmascript-modules).

### Why is this bad?

For ESM-only environments, ambiguous files may lead to unexpected results and problems.

### Examples

Examples of **incorrect** code for this rule:

```js
function x() {}

(function x() {
  return 42;
})();
```

Examples of **correct** code for this rule:

```js
import "foo";
function x() {
  return 42;
}

export function x() {
  return 42;
}

(function x() {
  return 42;
})();
export {}; // simple way to mark side-effects-only file as 'module' without any imports/exports
```

## How to use

## Version

This rule was added in v0.11.1.

## References

---

---
url: /docs/guide/usage/formatter/ignore-comments.md
---

# Inline ignore comments

For JS/TS files, use `oxfmt-ignore` to skip formatting the next statement:

```js
// oxfmt-ignore
const a    = 42;

/* oxfmt-ignore */
const x = () => { return 2; };

<>
  {/* oxfmt-ignore */}
  <span   ugly   format=""   />
</>;
```

For JS-in-Vue, use `oxfmt-ignore` inside the `<script>` tag:

```vue
<script>
// oxfmt-ignore
const a    = 42;
</script>
```

Trailing ignore comments are also supported:

```js
const a    = 42; // oxfmt-ignore
```

For other files and non-JS parts of Vue files (e.g., `<template>`, `<style>`), use `prettier-ignore` comment. See also Prettier's [ignore documentation](https://prettier.io/docs/ignore#html).

Currently, TOML files do not support ignore comments.

## Prettier compatibility

* `prettier-ignore` comment is also supported

---

---
url: /docs/guide/usage/linter/ignore-comments.md
description: Disable specific rules inline using Oxlint ignore comments
---

# Inline ignore comments

Ignore comments provide an escape hatch for exceptional cases where a rule is correct in general but needs to be suppressed in a small, well scoped section of code. Inline comments override configuration files.

Oxlint supports line comments (`//`) and block comments (`/* */`). Comments must start with one of the keywords below.

## oxlint-disable

Disable one or more rules until the end of the file, or until they are re-enabled.

```js
// Disable all Oxlint rules for the rest of the file
/* oxlint-disable */

// Disable a single rule in this file
/* oxlint-disable no-console */

// Disable multiple rules in this file
/* oxlint-disable no-console, typescript/no-floating-promises */
```

## oxlint-enable

Enable one or more rules until the end of the file, or until they are disabled again.

```js
/* oxlint-enable no-console */

/* oxlint-enable no-console, no-alert */
```

## oxlint-disable-line

Disable one or more rules on the current line.

```js
console.log("Hello, world!"); // oxlint-disable-line no-console

console.log(x++); // oxlint-disable-line no-console, no-plusplus
```

## oxlint-disable-next-line

Disable one or more rules on the line following the comment, then re-enables them for subsequent lines.

```js
// oxlint-disable-next-line no-console
console.log("Hello, world!"); // allowed because of the previous comment
console.log(x++); // not allowed because the previous comment only applied to the previous line

// oxlint-disable-next-line no-console, no-plusplus
console.log("Hello, world!"); // allowed
```

## ESLint compatibility

For compatibility with existing ESLint codebases, the same keywords are supported with `oxlint` replaced by `eslint`, such as `/* eslint-disable */` and `// eslint-disable-next-line`.

The `oxlint-*` form is recommended. The `eslint-*` form is useful during migration for rules that Oxlint does not support yet.

## Rule options cannot be changed inline

Ignore comments can enable or disable rules, but they cannot change rule options. Rule options belong in configuration files.

## Report unused ignore comments

Reporting unused ignore comments is disabled by default. When enabled, Oxlint reports comments such as `// oxlint-disable-line` when no diagnostics would have been reported on that line.

Enable reporting:

```bash
oxlint --report-unused-disable-directives
```

Specify the severity:

```bash
oxlint --report-unused-disable-directives-severity error
```

Only one of these options can be used at a time.

This can also be set in the Oxlint configuration file:

::: code-group

```jsonc [.oxlintrc.json]
{
  "$schema": "./node_modules/oxlint/configuration_schema.json",
  "options": {
    "reportUnusedDisableDirectives": "error", // or "off" or "warn"
  },
}
```

```ts [oxlint.config.ts]
import { defineConfig } from "oxlint";

export default defineConfig({
  options: {
    reportUnusedDisableDirectives: "error", // or "off" or "warn"
  },
});
```

:::

---

---
url: /docs/contribute/introduction.md
---

# Contributing to Oxc

Thank you for your interest in contributing to Oxc! We're building the next generation of JavaScript tooling, and we'd love your help.

## Quick Start

The fastest way to get started is through our [good first issues](https://github.com/oxc-project/oxc/contribute). These are carefully selected tasks that are perfect for new contributors.

Need guidance? Join our [Discord community](https://discord.gg/9uXCAwqQZW) where our team and community members are happy to help.

## Ways to Contribute

We welcome and appreciate any form of contributions:

### 🐛 Bug Reports

* Report parsing errors or incorrect linting behavior
* Share performance issues or regressions
* Document edge cases we haven't considered

### 🚀 Feature Development

* Add new linting rules
* Improve parser conformance
* Enhance transformer capabilities
* Build new tools in the Oxc ecosystem

### 📚 Documentation

* Improve getting started guides
* Add examples and tutorials
* Document architecture decisions
* Translate content to other languages

### 🧪 Testing

* Add test cases from real-world codebases
* Improve test coverage
* Create performance benchmarks
* Test against ecosystem projects

### 🔧 Infrastructure

* Improve build and CI systems
* Enhance development tooling
* Optimize performance critical paths
* Maintain compatibility with other tools

### Understanding the Codebase

Oxc is organized into several crates:

* **`oxc_parser`**: High-performance JavaScript/TypeScript parser
* **`oxc_linter`**: Fast linting engine with 650+ rules
* **`oxc_transformer`**: TypeScript and JSX transformation
* **`oxc_minifier`**: JavaScript minification (in development)
* **`oxc_formatter`**: Code formatting, compatible with Prettier

### Your First Contribution

1. **Browse Issues**: Look for issues labeled [`good first issue`](https://github.com/oxc-project/oxc/labels/good%20first%20issue)
2. **Ask Questions**: Don't hesitate to ask for clarification on Discord or GitHub
3. **Start Small**: Begin with documentation improvements or small bug fixes
4. **Learn the Patterns**: Study existing code to understand our conventions

## Community

### Communication Channels

* **GitHub Discussions**: For design discussions and questions
* **Discord**: Real-time chat with the team and community
* **GitHub Issues**: Bug reports and feature requests
* **Twitter**: Follow [@boshen\_c](https://twitter.com/boshen_c) for updates

### Code of Conduct

We are committed to providing a welcoming and inclusive experience for everyone. Please read our [Code of Conduct](https://github.com/oxc-project/oxc?tab=coc-ov-file#readme) before participating.

### AI Usage Policy

When using AI tools (including LLMs like ChatGPT, Claude, Copilot, etc.) to contribute to Oxc:

* **Please disclose AI usage** to reduce maintainer fatigue
* **You are responsible** for all AI-generated issues or PRs you submit
* **Low-quality or unreviewed AI content will be closed immediately**
* **Contributors who submit repeated low-quality ("slop") PRs will be banned without prior warning.** Bans may be lifted if you commit to contributing to Oxc in accordance with this policy. You may request an unban via our [Discord](https://discord.gg/9uXCAwqQZW).

We encourage the use of AI tools to assist with development, but all contributions must be thoroughly reviewed and tested by the contributor before submission. AI-generated code should be understood, validated, and adapted to meet Oxc's standards.

## Next Steps

Ready to contribute? Here are some great places to start:

* 📖 **Learn More**: Check out our [development guide](./development.md)
* 🔍 **Find an Issue**: Browse our [good first issues](https://github.com/oxc-project/oxc/contribute)
* 💬 **Join the Community**: Connect with us on [Discord](https://discord.gg/9uXCAwqQZW)
* 🛠️ **Pick a Tool**: Dive into [parser](./parser.md), [linter](./linter.md), [transformer](./transformer.md), or [other tools](./formatter.md)
* ⚡️ **Open a Pull Request**: Review our [PR Rules and Policies](./rules.md) to get started.

We can't wait to see what you'll build with us! 🚀

---

---
url: /docs/learn/parser_in_rust/intro.md
---

# Introduction

We are in [The Third Age of JavaScript](https://www.swyx.io/js-third-age/),
the common trend right now is to author JavaScript tools in Rust or Go for their performance gains.

But authoring JavaScript tools are challenging, let alone writing them in Rust.
I have struggled a lot when learning these technologies,
and I wish fewer people to take the same struggling journey.

I want to make my own contribution to the community by writing this guide,
so you don't have to take the same journey as I had.

There are only a handful of developers on the Rust side, and I would like to see you here and join us,
so we can build better and faster tools for everyone to enjoy.

## Overview

For this guide, the standard compiler frontend phases will be applied:

```
Source Text --> Lexer --> Token --> Parser --> AST
```

Writing a JavaScript parser is fairly easy,
it is 10% architectural decisions and 90% hard work on the fine-grained details.

The architectural decisions will mostly affect two categories:

* the performance of our parser
* how nice it is to consume our AST

Knowing all the options and trade-offs before building a parser in Rust will make our whole journey much smoother.

## Performance

The key to a performant Rust program is to **allocate less memory** and **use fewer CPU cycles**.

It is mostly transparent where memory allocations are made just by looking for heap-allocated objects such as a `Vec`, `Box` or `String`.
Reasoning about their usage will give us a sense of how fast our program will be - the more we allocate, the slower our program will be.

Rust gives us the power of zero-cost abstractions, we don't need to worry too much about abstractions causing slower performance.
Be careful with our algorithmic complexities and we will be all good to go.

:::info
You should also read [The Rust Performance Book](https://nnethercote.github.io/perf-book/introduction.html).
:::

## Rust Source Code

Whenever the performance of a function call cannot be deduced,
do not be afraid to click the "source" button on the Rust documentation and read the source code,
they are easy to understand most of the time.

:::info
When navigating the Rust source code, searching for a definition is simply looking for
`fn function_name`, `struct struct_name`, `enum enum_name`, etc.
This is one advantage of having constant grammar in Rust (compared to JavaScript 😉).
:::

---

---
url: /docs/guide/usage/transformer/isolated-declarations.md
---
# Isolated Declarations Emit

Oxc transformer supports emitting TypeScript declarations without using the TypeScript compiler for projects with [isolated declarations](https://www.typescriptlang.org/tsconfig/#isolatedDeclarations) enabled.

## Example

**Input**:

```ts
export function foo(a: number, b: string): number {
  return a + Number(b);
}

export enum Bar {
  a,
  b,
}
```

**Output**:

```ts
export declare function foo(a: number, b: string): number;
export declare enum Bar {
  a = 0,
  b = 1,
}
```

## Usage

```ts
import { isolatedDeclaration } from "oxc-transform";

const result = await isolatedDeclaration("lib.ts", sourceCode, {
  sourcemap: false,
  stripInternal: false,
});

console.log(result.code); // the .d.ts content
console.log(result.map); // the source map (if sourcemap is enabled)
console.log(result.errors); // parse and transformation errors
```

A synchronous `isolatedDeclarationSync` variant is also available with the same signature.

---

---
url: /docs/guide/usage/linter/rules/jest/consistent-test-it.md
---

### What it does

Jest allows you to choose how you want to define your tests, using the `it` or
the `test` keywords, with multiple permutations for each:

* **it:** `it`, `xit`, `fit`, `it.only`, `it.skip`.
* **test:** `test`, `xtest`, `test.only`, `test.skip`.

### Why is this bad?

It's a good practice to be consistent in your test suite, so that all tests are written in the same way.

## Configuration

This rule accepts a configuration object with the following properties:

### fn

type: `"it" | "test"`

default: `"test"`

Decides whether to use `test` or `it`.

Examples of **incorrect** code for `{ "fn": "test" }`:

```javascript
it("foo");
it.only("foo");
```

Examples of **correct** code for `{ "fn": "test" }`:

```javascript
test("foo");
test.only("foo");
```

Examples of **incorrect** code for `{ "fn": "it" }`:

```javascript
test("foo");
test.only("foo");
```

Examples of **correct** code for `{ "fn": "it" }`:

```javascript
it("foo");
it.only("foo");
```

### withinDescribe

type: `"it" | "test"`

default: `"it"`

Decides whether to use `test` or `it` within a `describe` scope.
If only `fn` is provided, this will default to the value of `fn`.

Examples of **incorrect** code for `{ "withinDescribe": "test" }`:

```javascript
describe("foo", function () {
  it("bar");
});
```

Examples of **correct** code for `{ "withinDescribe": "test" }`:

```javascript
describe("foo", function () {
  test("bar");
});
```

## How to use

## Version

This rule was added in v0.5.3.

## References

---

---
url: /docs/guide/usage/linter/rules/jest/expect-expect.md
---

### What it does

This rule triggers when there is no call made to `expect` in a test, ensure that there is at least one `expect` call made in a test.

### Why is this bad?

People may forget to add assertions.

### Examples

Examples of **incorrect** code for this rule:

```javascript
it("should be a test", () => {
  console.log("no assertion");
});
test("should assert something", () => {});
```

## Configuration

This rule accepts a configuration object with the following properties:

### additionalTestBlockFunctions

type: `string[]`

default: `[]`

An array of function names that should also be treated as test blocks.

### assertFunctionNames

type: `string[]`

default: `["expect"]`

A list of function names that should be treated as assertion functions.

NOTE: The default value is `["expect"]` for Jest and
`["expect", "expectTypeOf", "assert", "assertType"]` for Vitest.

## How to use

## Version

This rule was added in v0.0.12.

## References

---

---
url: /docs/guide/usage/linter/rules/jest/max-expects.md
---

### What it does

This rule enforces a maximum number of `expect()` calls in a single test.

### Why is this bad?

Tests with many different assertions are likely mixing multiple objectives.
It is generally better to have a single objective per test to ensure that when a test fails,
the problem is easy to identify.

### Examples

Examples of **incorrect** code for this rule:

```javascript
test("should not pass", () => {
  expect(true).toBeDefined();
  expect(true).toBeDefined();
  expect(true).toBeDefined();
  expect(true).toBeDefined();
  expect(true).toBeDefined();
  expect(true).toBeDefined();
});

it("should not pass", () => {
  expect(true).toBeDefined();
  expect(true).toBeDefined();
  expect(true).toBeDefined();
  expect(true).toBeDefined();
  expect(true).toBeDefined();
  expect(true).toBeDefined();
});
```

## Configuration

This rule accepts a configuration object with the following properties:

### max

type: `integer`

default: `5`

Maximum number of `expect()` assertion calls allowed within a single test.

## How to use

## Version

This rule was added in v0.0.18.

## References

---

---
url: /docs/guide/usage/linter/rules/jest/max-nested-describe.md
---

### What it does

This rule enforces a maximum depth to nested `describe()` calls.

### Why is this bad?

Nesting `describe()` blocks too deeply can make the test suite hard to read and understand.

### Examples

The following patterns are considered warnings (with the default option of
`{ "max": 5 } `):

Examples of **incorrect** code for this rule:

```javascript
describe("foo", () => {
  describe("bar", () => {
    describe("baz", () => {
      describe("qux", () => {
        describe("quxx", () => {
          describe("too many", () => {
            it("should get something", () => {
              expect(getSomething()).toBe("Something");
            });
          });
        });
      });
    });
  });
});

describe("foo", function () {
  describe("bar", function () {
    describe("baz", function () {
      describe("qux", function () {
        describe("quxx", function () {
          describe("too many", function () {
            it("should get something", () => {
              expect(getSomething()).toBe("Something");
            });
          });
        });
      });
    });
  });
});
```

Examples of **correct** code for this rule:

```ts
describe("foo", () => {
  describe("bar", () => {
    it("should get something", () => {
      expect(getSomething()).toBe("Something");
    });
  });
  describe("qux", () => {
    it("should get something", () => {
      expect(getSomething()).toBe("Something");
    });
  });
});

describe("foo2", function () {
  it("should get something", () => {
    expect(getSomething()).toBe("Something");
  });
});

describe("foo", function () {
  describe("bar", function () {
    describe("baz", function () {
      describe("qux", function () {
        describe("this is the limit", function () {
          it("should get something", () => {
            expect(getSomething()).toBe("Something");
          });
        });
      });
    });
  });
});
```

## Configuration

This rule accepts a configuration object with the following properties:

### max

type: `integer`

default: `5`

Maximum allowed depth of nested describe calls.

## How to use

## Version

This rule was added in v0.4.4.

## References

---

---
url: /docs/guide/usage/linter/rules/jest/no-alias-methods.md
---

### What it does

Enforces Jest's canonical matcher names instead of aliases.

### Why is this bad?

Jest matcher aliases are deprecated and are going to be removed in the next major version of Jest.
See [jestjs/jest#13164](https://github.com/jestjs/jest/issues/13164) for more.

This rule makes it easier to search for all occurrences of a matcher and ensures consistency among matcher names.

### Examples

Examples of **incorrect** code for this rule:

```javascript
expect(a).toBeCalled();
expect(a).toBeCalledTimes();
expect(a).toBeCalledWith();
expect(a).lastCalledWith();
expect(a).nthCalledWith();
expect(a).toReturn();
expect(a).toReturnTimes();
expect(a).toReturnWith();
expect(a).lastReturnedWith();
expect(a).nthReturnedWith();
expect(a).toThrowError();
```

Examples of **correct** code for this rule:

```javascript
expect(a).toHaveBeenCalled();
expect(a).toHaveBeenCalledTimes();
expect(a).toHaveBeenCalledWith();
expect(a).toHaveBeenLastCalledWith();
expect(a).toHaveBeenNthCalledWith();
expect(a).toHaveReturned();
expect(a).toHaveReturnedTimes();
expect(a).toHaveReturnedWith();
expect(a).toHaveLastReturnedWith();
expect(a).toHaveNthReturnedWith();
expect(a).toThrow();
```

## How to use

## Version

This rule was added in v0.0.12.

## References

---

---
url: /docs/guide/usage/linter/rules/jest/no-commented-out-tests.md
---

### What it does

This rule raises a warning about commented-out tests. It's similar to the
`no-disabled-tests` rule.

### Why is this bad?

You may forget to uncomment some tests. This rule raises a warning about commented-out tests.

It is generally better to skip a test if it's flaky, or remove it if it's no longer needed.

### Examples

Examples of **incorrect** code for this rule:

```javascript
// describe('foo', () => {});
// it('foo', () => {});
// test('foo', () => {});

// describe.skip('foo', () => {});
// it.skip('foo', () => {});
// test.skip('foo', () => {});
```

## How to use

## Version

This rule was added in v0.0.8.

## References

---

---
url: /docs/guide/usage/linter/rules/jest/no-conditional-expect.md
---

### What it does

This rule prevents the use of `expect` in conditional blocks, such as `if` and `catch`.
This includes using `expect` in callbacks to functions named `catch`, which are assumed to be promises.

### Why is this bad?

Jest only considers a test to have failed if it throws an error, meaning if calls to
assertion functions like `expect` occur in conditional code such as a `catch` statement,
tests can end up passing but not actually test anything. Additionally, conditionals
tend to make tests more brittle and complex, as they increase the amount of mental
thinking needed to understand what is actually being tested.

### Examples

Examples of **incorrect** code for this rule:

```js
it("foo", () => {
  doTest && expect(1).toBe(2);
});

it("bar", () => {
  if (!skipTest) {
    expect(1).toEqual(2);
  }
});

it("baz", async () => {
  try {
    await foo();
  } catch (err) {
    expect(err).toMatchObject({ code: "MODULE_NOT_FOUND" });
  }
});

it("throws an error", async () => {
  await foo().catch((error) => expect(error).toBeInstanceOf(error));
});
```

Examples of **correct** code for this rule:

```js
it("foo", () => {
  expect(!value).toBe(false);
});

function getValue() {
  if (process.env.FAIL) {
    return 1;
  }
  return 2;
}

it("foo", () => {
  expect(getValue()).toBe(2);
});

it("validates the request", () => {
  try {
    processRequest(request);
  } catch {
  } finally {
    expect(validRequest).toHaveBeenCalledWith(request);
  }
});

it("throws an error", async () => {
  await expect(foo).rejects.toThrow(Error);
});
```

## How to use

## Version

This rule was added in v0.0.12.

## References

---

---
url: /docs/guide/usage/linter/rules/jest/no-conditional-in-test.md
---

### What it does

Disallow conditional statements in tests.

### Why is this bad?

Conditional statements in tests can make the test harder to read and understand.
It is better to have a single test case per test function.

### Examples

Examples of **incorrect** code for this rule:

```js
it("foo", () => {
  if (true) {
    doTheThing();
  }
});

it("bar", () => {
  switch (mode) {
    case "none":
      generateNone();
    case "single":
      generateOne();
    case "multiple":
      generateMany();
  }

  expect(fixtures.length).toBeGreaterThan(-1);
});

it("baz", async () => {
  const promiseValue = () => {
    return something instanceof Promise ? something : Promise.resolve(something);
  };

  await expect(promiseValue()).resolves.toBe(1);
});
```

Examples of **correct** code for this rule:

```js
describe("my tests", () => {
  if (true) {
    it("foo", () => {
      doTheThing();
    });
  }
});

beforeEach(() => {
  switch (mode) {
    case "none":
      generateNone();
    case "single":
      generateOne();
    case "multiple":
      generateMany();
  }
});

it("bar", () => {
  expect(fixtures.length).toBeGreaterThan(-1);
});

const promiseValue = (something) => {
  return something instanceof Promise ? something : Promise.resolve(something);
};

it("baz", async () => {
  await expect(promiseValue()).resolves.toBe(1);
});
```

## How to use

## Version

This rule was added in v0.8.0.

## References

---

---
url: /docs/guide/usage/linter/rules/jest/no-confusing-set-timeout.md
---

### What it does

Disallow confusing usages of `jest.setTimeout`.

### Why is this bad?

* being called anywhere other than in global scope
* being called multiple times
* being called after other Jest functions like hooks, `describe`, `test`, or `it`

### Examples

All of these are invalid case:

```javascript
escribe("test foo", () => {
  jest.setTimeout(1000);
  it("test-description", () => {
    // test logic;
  });
});

describe("test bar", () => {
  it("test-description", () => {
    jest.setTimeout(1000);
    // test logic;
  });
});

test("foo-bar", () => {
  jest.setTimeout(1000);
});

describe("unit test", () => {
  beforeEach(() => {
    jest.setTimeout(1000);
  });
});
```

## How to use

## Version

This rule was added in v0.0.14.

## References

---

---
url: /docs/guide/usage/linter/rules/jest/no-deprecated-functions.md
---

### What it does

Over the years Jest has accrued some debt in the form of functions that have
either been renamed for clarity, or replaced with more powerful APIs.

This rule can also autofix a number of these deprecations for you.

#### `jest.resetModuleRegistry`

This function was renamed to `resetModules` in Jest 15 and removed in Jest 27.

#### `jest.addMatchers`

This function was replaced with `expect.extend` in Jest 17 and removed in Jest 27.

#### `require.requireActual` & `require.requireMock`

These functions were replaced in Jest 21 and removed in Jest 26.

Originally, the `requireActual` and `requireMock` functions were placed
onto the `require` function.

These functions were later moved onto the `jest` object in order to be easier
for type checkers to handle, and their use via `require` deprecated. Finally,
the release of Jest 26 saw them removed from the `require` function altogether.

#### `jest.runTimersToTime`

This function was renamed to `advanceTimersByTime` in Jest 22 and removed in Jest 27.

#### `jest.genMockFromModule`

This function was renamed to `createMockFromModule` in Jest 26, and is scheduled for removal in Jest 30.

### Why is this bad?

While typically these deprecated functions are kept in the codebase for a number
of majors, eventually they are removed completely.

### Examples

Examples of **incorrect** code for this rule:

```javascript
jest.resetModuleRegistry; // since Jest 15
jest.addMatchers; // since Jest 17
```

## Configuration

This rule accepts a configuration object with the following properties:

### jest

type: `object`

Jest configuration options.
Deprecated config, it will be removed in future versions.
Use please instead { "settings": { "jest": {"version": 29 } } } in `Oxlint config file`.
Beware the value from the config have higher priority than the rule config.

#### jest.version

type: `string`

default: `"29"`

The version of Jest being used.

## How to use

## Version

This rule was added in v0.0.18.

## References

---

---
url: /docs/guide/usage/linter/rules/jest/no-disabled-tests.md
---

### What it does

This rule raises a warning about disabled tests.

### Why is this bad?

Jest has a feature that allows you to temporarily mark tests as disabled. This
feature is often helpful while debugging or to create placeholders for future
tests. Before committing changes we may want to check that all tests are
running.

### Examples

```js
describe.skip("foo", () => {});
it.skip("foo", () => {});
test.skip("foo", () => {});

describe["skip"]("bar", () => {});
it["skip"]("bar", () => {});
test["skip"]("bar", () => {});

xdescribe("foo", () => {});
xit("foo", () => {});
xtest("foo", () => {});

it("bar");
test("bar");

it("foo", () => {
  pending();
});
```

## How to use

## Version

This rule was added in v0.0.7.

## References

---

---
url: /docs/guide/usage/linter/rules/jest/no-done-callback.md
---

### What it does

This rule checks the function parameter of hooks & tests for use of the done argument, suggesting you return a promise instead.

### Why is this bad?

When calling asynchronous code in hooks and tests, jest needs to know when the asynchronous work is complete to progress the current run.
Originally the most common pattern to achieve this was to use callbacks:

```javascript
test("the data is peanut butter", (done) => {
  function callback(data) {
    try {
      expect(data).toBe("peanut butter");
      done();
    } catch (error) {
      done(error);
    }
  }

  fetchData(callback);
});
```

This can be very error-prone however, as it requires careful understanding of how assertions work in tests or otherwise tests won't behave as expected.

### Examples

Examples of **incorrect** code for this rule:

```javascript
beforeEach((done) => {
  // ...
});

test("myFunction()", (done) => {
  // ...
});

test("myFunction()", function (done) {
  // ...
});
```

## How to use

## Version

This rule was added in v0.0.13.

## References

---

---
url: /docs/guide/usage/linter/rules/jest/no-duplicate-hooks.md
---

### What it does

Disallows duplicate hooks in describe blocks.

### Why is this bad?

Having duplicate hooks in a describe block can lead to confusion and unexpected behavior.
When multiple hooks of the same type exist, they all execute in order, which can make it
difficult to understand the test setup flow and may result in redundant or conflicting
operations. This makes tests harder to maintain and debug.

### Examples

Examples of **incorrect** code for this rule:

```javascript
describe("foo", () => {
  beforeEach(() => {
    // some setup
  });
  beforeEach(() => {
    // some setup
  });
  test("foo_test", () => {
    // some test
  });
});

// Nested describe scenario
describe("foo", () => {
  beforeEach(() => {
    // some setup
  });
  test("foo_test", () => {
    // some test
  });
  describe("bar", () => {
    test("bar_test", () => {
      afterAll(() => {
        // some teardown
      });
      afterAll(() => {
        // some teardown
      });
    });
  });
});
```

Examples of **correct** code for this rule:

```javascript
describe("foo", () => {
  beforeEach(() => {
    // some setup
  });
  test("foo_test", () => {
    // some test
  });
});

// Nested describe scenario
describe("foo", () => {
  beforeEach(() => {
    // some setup
  });
  test("foo_test", () => {
    // some test
  });
  describe("bar", () => {
    test("bar_test", () => {
      beforeEach(() => {
        // some setup
      });
    });
  });
});
```

## How to use

## Version

This rule was added in v0.4.0.

## References

---

---
url: /docs/guide/usage/linter/rules/jest/no-export.md
---

### What it does

Prevents using exports if a file has one or more tests in it.

### Why is this bad?

This rule aims to eliminate duplicate runs of tests by exporting things from test files.
If you import from a test file, then all the tests in that file will be run in each imported instance.
so bottom line, don't export from a test, but instead move helper functions into a separate file when they need to be shared across tests.

### Examples

Examples of **incorrect** code for this rule:

```javascript
export function myHelper() {}
describe("a test", () => {
  expect(1).toBe(1);
});
```

## How to use

## Version

This rule was added in v0.0.13.

## References

---

---
url: /docs/guide/usage/linter/rules/jest/no-focused-tests.md
---

### What it does

This rule reminds you to remove `.only` from your tests by raising a warning
whenever you are using the exclusivity feature.

### Why is this bad?

Jest has a feature that allows you to focus tests by appending `.only` or
prepending `f` to a test-suite or a test-case. This feature is really helpful to
debug a failing test, so you don’t have to execute all of your tests. After you
have fixed your test and before committing the changes you have to remove
`.only` to ensure all tests are executed on your build system.

### Examples

Examples of **incorrect** code for this rule:

```javascript
describe.only("foo", () => {});
it.only("foo", () => {});
describe["only"]("bar", () => {});
it["only"]("bar", () => {});
test.only("foo", () => {});
test["only"]("bar", () => {});
fdescribe("foo", () => {});
fit("foo", () => {});
fit.each`
  table
`();
```

## How to use

## Version

This rule was added in v0.0.8.

## References

---

---
url: /docs/guide/usage/linter/rules/jest/no-hooks.md
---

### What it does

Disallows Jest setup and teardown hooks, such as `beforeAll`.

### Why is this bad?

Jest provides global functions for setup and teardown tasks, which are
called before/after each test case and each test suite. The use of these
hooks promotes shared state between tests.

This rule reports for the following function calls:

* `beforeAll`
* `beforeEach`
* `afterAll`
* `afterEach`

### Examples

Examples of **incorrect** code for this rule:

```javascript
function setupFoo(options) {
  /* ... */
}
function setupBar(options) {
  /* ... */
}

describe("foo", () => {
  let foo;
  beforeEach(() => {
    foo = setupFoo();
  });
  afterEach(() => {
    foo = null;
  });
  it("does something", () => {
    expect(foo.doesSomething()).toBe(true);
  });
  describe("with bar", () => {
    let bar;
    beforeEach(() => {
      bar = setupBar();
    });
    afterEach(() => {
      bar = null;
    });
    it("does something with bar", () => {
      expect(foo.doesSomething(bar)).toBe(true);
    });
  });
});
```

## Configuration

This rule accepts a configuration object with the following properties:

### allow

type: `string[]`

default: `[]`

An array of hook function names that are permitted for use.

## How to use

## Version

This rule was added in v0.0.16.

## References

---

---
url: /docs/guide/usage/linter/rules/jest/no-identical-title.md
---

### What it does

This rule looks at the title of every test and test suite.
It will report when two test suites or two test cases at the same level of a test suite have the same title.

### Why is this bad?

Having identical titles for two different tests or test suites may create confusion.
For example, when a test with the same title as another test in the same test suite fails, it is harder to know which one failed and thus harder to fix.

### Examples

Examples of **incorrect** code for this rule:

```javascript
describe("baz", () => {
  //...
});

describe("baz", () => {
  // Has the same title as a previous test suite
  // ...
});
```

## How to use

## Version

This rule was added in v0.0.14.

## References

---

---
url: /docs/guide/usage/linter/rules/jest/no-interpolation-in-snapshots.md
---

### What it does

Prevents the use of string interpolations in snapshots.

### Why is this bad?

Interpolation prevents snapshots from being updated. Instead, properties should
be overloaded with a matcher by using
[property matchers](https://jestjs.io/docs/en/snapshot-testing#property-matchers).

### Examples

Examples of **incorrect** code for this rule:

```javascript
expect(something).toMatchInlineSnapshot(
  `Object {
    property: ${interpolated}
  }`,
);

expect(something).toMatchInlineSnapshot(
  { other: expect.any(Number) },
  `Object {
    other: Any<Number>,
    property: ${interpolated}
  }`,
);

expect(errorThrowingFunction).toThrowErrorMatchingInlineSnapshot(`${interpolated}`);
```

## How to use

## Version

This rule was added in v0.0.13.

## References

---

---
url: /docs/guide/usage/linter/rules/jest/no-jasmine-globals.md
---

### What it does

This rule reports on any usage of Jasmine globals, which are not ported to
Jest, and suggests alternatives from Jest's own API.

### Why is this bad?

When migrating from Jasmine to Jest, relying on Jasmine-specific globals
creates compatibility issues and prevents taking advantage of Jest's
improved testing features and better error reporting.

### Examples

Examples of **incorrect** code for this rule:

```javascript
jasmine.DEFAULT_TIMEOUT_INTERVAL = 5000;
test("my test", () => {
  pending();
});
test("my test", () => {
  jasmine.createSpy();
});
```

Examples of **correct** code for this rule:

```javascript
jest.setTimeout(5000);
test("my test", () => {
  // Use test.skip() instead of pending()
});
test.skip("my test", () => {
  // Skipped test
});
test("my test", () => {
  jest.fn(); // Use jest.fn() instead of jasmine.createSpy()
});
```

## How to use

## Version

This rule was added in v0.0.13.

## References

---

---
url: /docs/guide/usage/linter/rules/jest/no-large-snapshots.md
---

### What it does

Disallow large snapshots.

### Why is this bad?

When using Jest's snapshot capability one should be mindful of the size of
created snapshots. As a general best practice snapshots should be limited in
size in order to be more manageable and reviewable. A stored snapshot is only as
good as its review and as such keeping it short, sweet, and readable is
important to allow for thorough reviews.

### Examples

Examples of **incorrect** code for this rule:

```javascript
exports[`a large snapshot 1`] = `
line 1
line 2
line 3
line 4
line 5
line 6
line 7
line 8
line 9
line 10
line 11
line 12
line 13
line 14
line 15
line 16
line 17
line 18
line 19
line 20
line 21
line 22
line 23
line 24
line 25
line 26
line 27
line 28
line 29
line 30
line 31
line 32
line 33
line 34
line 35
line 36
line 37
line 38
line 39
line 40
line 41
line 42
line 43
line 44
line 45
line 46
line 47
line 48
line 49
line 50
line 51
`;
```

Examples of **incorrect** code for this rule:

```js
exports[`a more manageable and readable snapshot 1`] = `
line 1
line 2
line 3
line 4
`;
```

## Configuration

This rule accepts a configuration object with the following properties:

### allowedSnapshots

type: `Record<string, array>`

default: `{}`

A map of snapshot file paths to arrays of snapshot names that are allowed to exceed the size limit.
Snapshot names can be specified as regular expressions.

### inlineMaxSize

type: `integer`

default: `50`

Maximum number of lines allowed for inline snapshots.

### maxSize

type: `integer`

default: `50`

Maximum number of lines allowed for external snapshot files.

## How to use

## Version

This rule was added in v0.4.3.

## References

---

---
url: /docs/guide/usage/linter/rules/jest/no-mocks-import.md
---

### What it does

This rule reports imports from a path containing a `__mocks__` component.

### Why is this bad?

Manually importing mocks from a `__mocks__` directory can lead to unexpected behavior
and breaks Jest's automatic mocking system. Jest is designed to automatically resolve
and use mocks from `__mocks__` directories when `jest.mock()` is called. Directly
importing from these directories bypasses Jest's module resolution system and can cause
inconsistencies between test and production environments.

### Examples

Examples of **incorrect** code for this rule:

```ts
import thing from "./__mocks__/index";
require("./__mocks__/index");
```

Examples of **correct** code for this rule:

```ts
import thing from "thing";
require("thing");
```

## How to use

## Version

This rule was added in v0.0.13.

## References

---

---
url: /docs/guide/usage/linter/rules/jest/no-restricted-jest-methods.md
---

### What it does

Restrict the use of specific `jest` and `vi` methods.

### Why is this bad?

Certain Jest or Vitest methods may be deprecated, discouraged in specific
contexts, or incompatible with your testing environment. Restricting
them helps maintain consistent and reliable test practices.

By default, no methods are restricted by this rule.
You must configure the rule for it to disable anything.

### Examples

Examples of **incorrect** code for this rule:

```javascript
jest.useFakeTimers();
it("calls the callback after 1 second via advanceTimersByTime", () => {
  // ...

  jest.advanceTimersByTime(1000);

  // ...
});

test("plays video", () => {
  const spy = jest.spyOn(video, "play");

  // ...
});
```

## Configuration

This rule accepts a configuration object with the following properties:

type: `object`

## How to use

## Version

This rule was added in v0.2.3.

## References

---

---
url: /docs/guide/usage/linter/rules/jest/no-restricted-matchers.md
---

### What it does

Ban specific matchers & modifiers from being used, and can suggest alternatives.

### Why is this bad?

Some matchers or modifiers might be discouraged in your codebase for various reasons:
they might be deprecated, cause confusion, have performance implications, or there
might be better alternatives available. This rule allows you to enforce consistent
testing patterns by restricting certain Jest matchers and providing guidance on
preferred alternatives.

### Examples

Bans are expressed in the form of a map, with the value being either a string message to be shown,
or null if only the default rule message should be used. Bans are checked against the start of
the expect chain - this means that to ban a specific matcher entirely you must specify all
six permutations, but allows you to ban modifiers as well. By default, this map is empty, meaning
no matchers or modifiers are banned.

Example configuration:

```json
{
  "jest/no-restricted-matchers": [
    "error",
    {
      "toBeFalsy": null,
      "resolves": "Use `expect(await promise)` instead.",
      "toHaveBeenCalledWith": null,
      "not.toHaveBeenCalledWith": null,
      "resolves.toHaveBeenCalledWith": null,
      "rejects.toHaveBeenCalledWith": null,
      "resolves.not.toHaveBeenCalledWith": null,
      "rejects.not.toHaveBeenCalledWith": null
    }
  ]
}
```

Examples of **incorrect** code for this rule with the above configuration:

```javascript
it("is false", () => {
  // if this has a modifier (i.e. `not.toBeFalsy`), it would be considered fine
  expect(a).toBeFalsy();
});

it("resolves", async () => {
  // all uses of this modifier are disallowed, regardless of matcher
  await expect(myPromise()).resolves.toBe(true);
});

describe("when an error happens", () => {
  it("does not upload the file", async () => {
    // all uses of this matcher are disallowed
    expect(uploadFileMock).not.toHaveBeenCalledWith("file.name");
  });
});
```

## Configuration

This rule accepts a configuration object with the following properties:

type: `object`

## How to use

## Version

This rule was added in v0.2.3.

## References

---

---
url: /docs/guide/usage/linter/rules/jest/no-standalone-expect.md
---

### What it does

Prevents `expect` statements outside of a `test` or `it` block. An `expect`
within a helper function (but outside of a `test` or `it` block) will not
trigger this rule.

Statements like `expect.hasAssertions()` will NOT trigger this rule since these
calls will execute if they are not in a test block.

### Why is this bad?

`expect` statements outside of test blocks will not be executed by the Jest
test runner, which means they won't actually test anything. This can lead to
false confidence in test coverage and may hide bugs that would otherwise be
caught by proper testing.

### Examples

Examples of **incorrect** code for this rule:

```javascript
describe("a test", () => {
  expect(1).toBe(1);
});
```

## Configuration

This rule accepts a configuration object with the following properties:

### additionalTestBlockFunctions

type: `string[]`

default: `[]`

An array of function names that should also be treated as test blocks.

## How to use

## Version

This rule was added in v0.0.13.

## References

---

---
url: /docs/guide/usage/linter/rules/jest/no-test-prefixes.md
---

### What it does

Require using `.only` and `.skip` over `f` and `x`.

### Why is this bad?

Jest allows you to choose how you want to define focused and skipped tests,
with multiple permutations for each:

* only & skip: it.only, test.only, describe.only, it.skip, test.skip, describe.skip.
* 'f' & 'x': fit, fdescribe, xit, xtest, xdescribe.

This rule enforces usages from the only & skip list.

### Examples

Examples of **incorrect** code for this rule:

```javascript
fit("foo"); // invalid
fdescribe("foo"); // invalid
xit("foo"); // invalid
xtest("foo"); // invalid
xdescribe("foo"); // invalid
```

## How to use

## Version

This rule was added in v0.0.7.

## References

---

---
url: /docs/guide/usage/linter/rules/jest/no-test-return-statement.md
---

### What it does

Disallow explicitly returning from tests.

### Why is this bad?

Tests in Jest should be void and not return values.
If you are returning Promises then you should update the test to use
`async/await`.

### Examples

Examples of **incorrect** code for this rule:

```javascript
test("one", () => {
  return expect(1).toBe(1);
});
```

Examples of **correct** code for this rule:

```javascript
test("one", () => {
  expect(1).toBe(1);
});
```

## How to use

## Version

This rule was added in v0.2.0.

## References

---

---
url: /docs/guide/usage/linter/rules/jest/no-unneeded-async-expect-function.md
---

### What it does

Disallows unnecessary async function wrapper for expected promises.

### Why is this bad?

When the only statement inside an async wrapper is `await someCall()`,
the call should be passed directly to `expect` instead. This makes the
test code more concise and easier to read.

### Examples

Examples of **incorrect** code for this rule:

```js
await expect(async () => {
  await doSomethingAsync();
}).rejects.toThrow();

await expect(async () => await doSomethingAsync()).rejects.toThrow();
```

Examples of **correct** code for this rule:

```js
await expect(doSomethingAsync()).rejects.toThrow();
```

## How to use

## Version

This rule was added in v1.39.0.

## References

---

---
url: /docs/guide/usage/linter/rules/jest/no-untyped-mock-factory.md
---

### What it does

This rule triggers a warning if `mock()` or `doMock()` is used without a generic
type parameter or return type.

### Why is this bad?

By default, `jest.mock` and `jest.doMock` allow any type to be returned by a
mock factory. A generic type parameter can be used to enforce that the factory
returns an object with the same shape as the original module, or some other
strict type. Requiring a type makes it easier to use TypeScript to catch changes
needed in test mocks when the source module changes.

### Examples

Examples of **incorrect** code for this rule:

```typescript
jest.mock("../moduleName", () => {
  return jest.fn(() => 42);
});

jest.mock("./module", () => ({
  ...jest.requireActual("./module"),
  foo: jest.fn(),
}));

jest.mock("random-num", () => {
  return jest.fn(() => 42);
});
```

Examples of **correct** code for this rule:

```typescript
// Uses typeof import()
jest.mock<typeof import("../moduleName")>("../moduleName", () => {
  return jest.fn(() => 42);
});

jest.mock<typeof import("./module")>("./module", () => ({
  ...jest.requireActual("./module"),
  foo: jest.fn(),
}));

// Uses custom type
jest.mock<() => number>("random-num", () => {
  return jest.fn(() => 42);
});

// No factory
jest.mock("random-num");

// Virtual mock
jest.mock(
  "../moduleName",
  () => {
    return jest.fn(() => 42);
  },
  { virtual: true },
);
```

## How to use

## Version

This rule was added in v0.2.15.

## References

---

---
url: /docs/guide/usage/linter/rules/jest/padding-around-after-all-blocks.md
---

### What it does

This rule enforces a line of padding before and after 1 or more
`afterAll` statements.

### Why is this bad?

Inconsistent formatting of code can make the code more difficult to read
and follow. This rule helps ensure that `afterAll` blocks are visually
separated from the rest of the code, making them easier to identify while
looking through test files.

### Examples

Examples of **incorrect** code for this rule:

```js
const thing = 123;
afterAll(() => {});
```

Examples of **correct** code for this rule:

```js
const thing = 123;

afterAll(() => {});
```

## How to use

## Version

This rule was added in v1.59.0.

## References

---

---
url: /docs/guide/usage/linter/rules/jest/padding-around-test-blocks.md
---

### What it does

This rule enforces a line of padding before and after 1 or more
`test`/`it` statements.

### Why is this bad?

Inconsistent formatting of code can make the code more difficult to read
and follow. This rule helps ensure that test blocks are visually
separated from the rest of the code, making them easier to identify while
looking through test files.

### Examples

Examples of **incorrect** code for this rule:

```js
const thing = 123;
test("foo", () => {});
test("bar", () => {});
```

```js
const thing = 123;
it("foo", () => {});
it("bar", () => {});
```

Examples of **correct** code for this rule:

```js
const thing = 123;

test("foo", () => {});

test("bar", () => {});
```

```js
const thing = 123;

it("foo", () => {});

it("bar", () => {});
```

## How to use

## Version

This rule was added in v1.13.0.

## References

---

---
url: /docs/guide/usage/linter/rules/jest/prefer-called-with.md
---

### What it does

Suggest using `toBeCalledWith()` or `toHaveBeenCalledWith()`

### Why is this bad?

When testing function calls, it's often more valuable to assert both
that a function was called AND what arguments it was called with.
Using `toBeCalled()` or `toHaveBeenCalled()` only verifies the function
was invoked, but doesn't validate the arguments, potentially missing
bugs where functions are called with incorrect parameters.

### Examples

Examples of **incorrect** code for this rule:

```javascript
expect(someFunction).toBeCalled();
expect(someFunction).toHaveBeenCalled();
```

Examples of **correct** code for this rule:

```javascript
expect(noArgsFunction).toBeCalledWith();
expect(roughArgsFunction).toBeCalledWith(expect.anything(), expect.any(Date));
expect(anyArgsFunction).toBeCalledTimes(1);
expect(uncalledFunction).not.toBeCalled();
```

## How to use

## Version

This rule was added in v0.2.5.

## References

---

---
url: /docs/guide/usage/linter/rules/jest/prefer-comparison-matcher.md
---

### What it does

This rule checks for comparisons in tests that could be replaced with one of the
following built-in comparison matchers:

* `toBeGreaterThan`
* `toBeGreaterThanOrEqual`
* `toBeLessThan`
* `toBeLessThanOrEqual`

### Why is this bad?

Using generic matchers like `toBe(true)` with comparison expressions
makes tests less readable and provides less helpful error messages when
they fail. Jest's specific comparison matchers offer clearer intent and
better error output that shows the actual values being compared.

### Examples

Examples of **incorrect** code for this rule:

```js
expect(x > 5).toBe(true);
expect(x < 7).not.toEqual(true);
expect(x <= y).toStrictEqual(true);
```

Examples of **correct** code for this rule:

```js
expect(x).toBeGreaterThan(5);
expect(x).not.toBeLessThanOrEqual(7);
expect(x).toBeLessThanOrEqual(y);
// special case - see below
expect(x < "Carl").toBe(true);
```

## How to use

## Version

This rule was added in v0.2.15.

## References

---

---
url: /docs/guide/usage/linter/rules/jest/prefer-each.md
---

### What it does

This rule enforces using `each` rather than manual loops.

### Why is this bad?

Manual loops for tests can be less readable and more error-prone. Using
`each` provides a clearer and more concise way to run parameterized tests,
improving readability and maintainability.

### Examples

Examples of **incorrect** code for this rule:

```js
for (const item of items) {
  describe(item, () => {
    expect(item).toBe("foo");
  });
}
```

Examples of **correct** code for this rule:

```js
describe.each(items)("item", (item) => {
  expect(item).toBe("foo");
});
```

## How to use

## Version

This rule was added in v0.9.0.

## References

---

---
url: /docs/guide/usage/linter/rules/jest/prefer-ending-with-an-expect.md
---

### What it does

Enforces that test blocks end with an assertion (`expect` or a configured
assertion function).

### Why is this bad?

A test that doesn't end with an assertion may be performing side effects
or setup after its last check, which makes the test harder to understand
and can hide failures. Ending with an assertion ensures the test's final
action is verifying behavior.

### Examples

Examples of **incorrect** code for this rule with default values:

```js
it("lets me change the selected option", () => {
  const container = render(MySelect, {
    props: { options: [1, 2, 3], selected: 1 },
  });

  expect(container).toBeDefined();
  expect(container.toHTML()).toContain('<option value="1" selected>');

  container.setProp("selected", 2);
});
```

Examples of **correct** code for this rule with defaults values:

```js
it("lets me change the selected option", () => {
  const container = render(MySelect, {
    props: { options: [1, 2, 3], selected: 1 },
  });

  expect(container).toBeDefined();
  expect(container.toHTML()).toContain('<option value="1" selected>');

  container.setProp("selected", 2);

  expect(container.toHTML()).not.toContain('<option value="1" selected>');
  expect(container.toHTML()).toContain('<option value="2" selected>');
});
```

Examples of **incorrect** code for this rule with `{ "assertFunctionNames": ["expect"] }`:

```js
import { expectSaga } from "redux-saga-test-plan";
import { addSaga } from "../src/sagas";

test("returns sum", () => {
  expectSaga(addSaga, 1, 1).returns(2).run();
});
```

Examples of **correct** code for this rule with `{ "assertFunctionNames": ["expect"] }`:

```js
import { expectSaga } from "redux-saga-test-plan";
import { addSaga } from "../src/sagas";

test("returns sum", () => {
  expectSaga(addSaga, 1, 1).returns(2).run();
});
```

Examples of **correct** code for this rule with `{ "additionalTestBlockFunctions": ["each.test"] }`:

```js
each([
  [2, 3],
  [1, 3],
]).test("the selection can change from %d to %d", (firstSelection, secondSelection) => {
  const container = render(MySelect, {
    props: { options: [1, 2, 3], selected: firstSelection },
  });

  expect(container).toBeDefined();
  expect(container.toHTML()).toContain(`<option value="${firstSelection}" selected>`);

  container.setProp("selected", secondSelection);

  expect(container.toHTML()).not.toContain(`<option value="${firstSelection}" selected>`);
  expect(container.toHTML()).toContain(`<option value="${secondSelection}" selected>`);
});
```

## Configuration

This rule accepts a configuration object with the following properties:

### additionalTestBlockFunctions

type: `string[]`

default: `[]`

An array of function names that should also be treated as test blocks.

### assertFunctionNames

type: `string[]`

A list of function names that should be treated as assertion functions.
Default: `["expect"]`

## How to use

## Version

This rule was added in v1.60.0.

## References

---

---
url: /docs/guide/usage/linter/rules/jest/prefer-equality-matcher.md
---

### What it does

Jest has built-in matchers for expecting equality, which allow for more readable
tests and error messages if an expectation fails.

### Why is this bad?

Testing equality expressions with generic matchers like `toBe(true)`
makes tests harder to read and understand. When tests fail, the error
messages are less helpful because they don't show what the actual values
were. Using specific equality matchers provides clearer test intent and
better debugging information.

### Examples

Examples of **incorrect** code for this rule:

```javascript
expect(x === 5).toBe(true);
expect(name === "Carl").not.toEqual(true);
expect(myObj !== thatObj).toStrictEqual(true);
```

Examples of **correct** code for this rule:

```javascript
expect(x).toBe(5);
expect(name).not.toEqual("Carl");
expect(myObj).toStrictEqual(thatObj);
```

## How to use

## Version

This rule was added in v0.2.9.

## References

---

---
url: /docs/guide/usage/linter/rules/jest/prefer-expect-assertions.md
---

### What it does

Enforces that every test has either `expect.assertions(<number>)` or
`expect.hasAssertions()` as its first expression.

### Why is this bad?

Without explicit assertion counts, tests with asynchronous code,
callbacks, or loops may pass even if some `expect` calls are never
reached, silently hiding bugs.

### Examples

Examples of **incorrect** code for this rule:

```javascript
test("no assertions", () => {
  // ...
});
test("assertions not first", () => {
  expect(true).toBe(true);
  // ...
});
```

Examples of **correct** code for this rule:

```javascript
test("with assertion count", () => {
  expect.assertions(1);
  expect(true).toBe(true);
});
test("with hasAssertions", () => {
  expect.hasAssertions();
  expect(true).toBe(true);
});
```

///Examples of **incorrect** code with `{ "onlyFunctionsWithAsyncKeyword": true }`:

```javascript
test("fetches data", async () => {
  const data = await fetchData();
  expect(data).toBe("peanut butter");
});
```

Examples of **correct** code with `{ "onlyFunctionsWithAsyncKeyword": true }`:

```javascript
test("fetches data", async () => {
  expect.assertions(1);
  const data = await fetchData();
  expect(data).toBe("peanut butter");
});
```

Examples of **incorrect** code with `{ "onlyFunctionsWithExpectInLoop": true }`:

```javascript
test("all numbers are greater than zero", () => {
  for (const number of getNumbers()) {
    expect(number).toBeGreaterThan(0);
  }
});
```

Examples of **correct** code with `{ "onlyFunctionsWithExpectInLoop": true }`:

```javascript
test("all numbers are greater than zero", () => {
  expect.hasAssertions();
  for (const number of getNumbers()) {
    expect(number).toBeGreaterThan(0);
  }
});
```

Examples of **incorrect** code with `{ "onlyFunctionsWithExpectInCallback": true }`:

```javascript
test("callback test", () => {
  fetchData((data) => {
    expect(data).toBe("peanut butter");
  });
});
```

Examples of **correct** code with `{ "onlyFunctionsWithExpectInCallback": true }`:

```javascript
test("callback test", () => {
  expect.assertions(1);
  fetchData((data) => {
    expect(data).toBe("peanut butter");
  });
});
```

## Configuration

This rule accepts a configuration object with the following properties:

### onlyFunctionsWithAsyncKeyword

type: `boolean`

default: `false`

### onlyFunctionsWithExpectInCallback

type: `boolean`

default: `false`

### onlyFunctionsWithExpectInLoop

type: `boolean`

default: `false`

## How to use

## Version

This rule was added in v1.62.0.

## References

---

---
url: /docs/guide/usage/linter/rules/jest/prefer-expect-resolves.md
---

### What it does

Prefer `await expect(...).resolves` over `expect(await ...)` when testing
promises.

### Why is this bad?

When working with promises, there are two primary ways you can test the
resolved value:

1. use the `resolve` modifier on `expect`
   (`await expect(...).resolves.<matcher>` style)
2. `await` the promise and assert against its result
   (`expect(await ...).<matcher>` style)

While the second style is arguably less dependent on `jest`, if the
promise rejects it will be treated as a general error, resulting in less
predictable behaviour and output from `jest`.

Additionally, favoring the first style ensures consistency with its
`rejects` counterpart, as there is no way of "awaiting" a rejection.

### Examples

Examples of **incorrect** code for this rule:

```javascript
it("passes", async () => {
  expect(await someValue()).toBe(true);
});
it("is true", async () => {
  const myPromise = Promise.resolve(true);
  expect(await myPromise).toBe(true);
});
```

Examples of **correct** code for this rule:

```javascript
it("passes", async () => {
  await expect(someValue()).resolves.toBe(true);
});
it("is true", async () => {
  const myPromise = Promise.resolve(true);

  await expect(myPromise).resolves.toBe(true);
});
it("errors", async () => {
  await expect(Promise.reject(new Error("oh noes!"))).rejects.toThrowError("oh noes!");
});
```

## How to use

## Version

This rule was added in v0.2.14.

## References

---

---
url: /docs/guide/usage/linter/rules/jest/prefer-hooks-in-order.md
---

### What it does

Ensures that hooks are in the order that they are called in.

### Why is this bad?

While hooks can be setup in any order, they're always called by `jest` in this
specific order:

1. `beforeAll`
2. `beforeEach`
3. `afterEach`
4. `afterAll`

This rule aims to make that more obvious by enforcing grouped hooks be setup in
that order within tests.

### Examples

Examples of **incorrect** code for this rule:

```javascript
describe("foo", () => {
  beforeEach(() => {
    seedMyDatabase();
  });
  beforeAll(() => {
    createMyDatabase();
  });
  it("accepts this input", () => {
    // ...
  });
  it("returns that value", () => {
    // ...
  });
  describe("when the database has specific values", () => {
    const specificValue = "...";
    beforeEach(() => {
      seedMyDatabase(specificValue);
    });
    it("accepts that input", () => {
      // ...
    });
    it("throws an error", () => {
      // ...
    });
    afterEach(() => {
      clearLogger();
    });
    beforeEach(() => {
      mockLogger();
    });
    it("logs a message", () => {
      // ...
    });
  });
  afterAll(() => {
    removeMyDatabase();
  });
});
```

Examples of **correct** code for this rule:

```javascript
describe("foo", () => {
  beforeAll(() => {
    createMyDatabase();
  });
  beforeEach(() => {
    seedMyDatabase();
  });
  it("accepts this input", () => {
    // ...
  });
  it("returns that value", () => {
    // ...
  });
  describe("when the database has specific values", () => {
    const specificValue = "...";
    beforeEach(() => {
      seedMyDatabase(specificValue);
    });
    it("accepts that input", () => {
      // ...
    });
    it("throws an error", () => {
      // ...
    });
    beforeEach(() => {
      mockLogger();
    });
    afterEach(() => {
      clearLogger();
    });
    it("logs a message", () => {
      // ...
    });
  });
  afterAll(() => {
    removeMyDatabase();
  });
});
```

## How to use

## Version

This rule was added in v0.6.0.

## References

---

---
url: /docs/guide/usage/linter/rules/jest/prefer-hooks-on-top.md
---

### What it does

While hooks can be setup anywhere in a test file, they are always called in a
specific order, which means it can be confusing if they're intermixed with test
cases.

### Why is this bad?

When hooks are mixed with test cases, it becomes harder to understand
the test setup and execution order. This can lead to confusion about
which hooks apply to which tests and when they run. Grouping hooks at
the top of each `describe` block makes the test structure clearer and
more maintainable.

### Examples

Examples of **incorrect** code for this rule:

```javascript
describe("foo", () => {
  beforeEach(() => {
    seedMyDatabase();
  });

  it("accepts this input", () => {
    // ...
  });

  beforeAll(() => {
    createMyDatabase();
  });

  it("returns that value", () => {
    // ...
  });

  describe("when the database has specific values", () => {
    const specificValue = "...";
    beforeEach(() => {
      seedMyDatabase(specificValue);
    });

    it("accepts that input", () => {
      // ...
    });

    it("throws an error", () => {
      // ...
    });

    afterEach(() => {
      clearLogger();
    });

    beforeEach(() => {
      mockLogger();
    });

    it("logs a message", () => {
      // ...
    });
  });

  afterAll(() => {
    removeMyDatabase();
  });
});
```

Examples of **correct** code for this rule:

```javascript
describe("foo", () => {
  beforeAll(() => {
    createMyDatabase();
  });

  beforeEach(() => {
    seedMyDatabase();
  });

  afterAll(() => {
    clearMyDatabase();
  });

  it("accepts this input", () => {
    // ...
  });

  it("returns that value", () => {
    // ...
  });

  describe("when the database has specific values", () => {
    const specificValue = "...";

    beforeEach(() => {
      seedMyDatabase(specificValue);
    });

    beforeEach(() => {
      mockLogger();
    });

    afterEach(() => {
      clearLogger();
    });

    it("accepts that input", () => {
      // ...
    });

    it("throws an error", () => {
      // ...
    });

    it("logs a message", () => {
      // ...
    });
  });
});
```

## How to use

## Version

This rule was added in v0.4.2.

## References

---

---
url: /docs/guide/usage/linter/rules/jest/prefer-importing-jest-globals.md
---

### What it does

Prefer importing Jest globals (`describe`, `test`, `expect`, etc.) from
`@jest/globals` rather than relying on ambient globals.

### Why is this bad?

Using global Jest functions without explicit imports makes dependencies
implicit and can cause issues with type checking, editor tooling, and
when migrating between test runners.

### Examples

Examples of **incorrect** code for this rule:

```javascript
describe("suite", () => {
  test("foo");
  expect(true).toBeDefined();
});
```

Examples of **correct** code for this rule:

```javascript
import { describe, expect, test } from "@jest/globals";
describe("suite", () => {
  test("foo");
  expect(true).toBeDefined();
});
```

## Configuration

This rule accepts a configuration object with the following properties:

### types

type: `array`

default: `["hook", "describe", "test", "expect", "jest", "unknown"]`

Jest function types to enforce importing for.

#### types\[n]

type: `"hook" | "describe" | "test" | "expect" | "jest" | "unknown"`

## How to use

## Version

This rule was added in v1.60.0.

## References

---

---
url: /docs/guide/usage/linter/rules/jest/prefer-jest-mocked.md
---

### What it does

When working with mocks of functions using Jest, it's recommended to use the
`jest.mocked()` helper function to properly type the mocked functions. This rule
enforces the use of `jest.mocked()` for better type safety and readability.

Restricted types:

* `jest.Mock`
* `jest.MockedFunction`
* `jest.MockedClass`
* `jest.MockedObject`

### Why is this bad?

Using type assertions like `fn as jest.Mock` is a less safe approach
than using `jest.mocked()`. The `jest.mocked()` helper provides better
type safety by preserving the original function signature while adding
mock capabilities. It also makes the code more readable and explicit
about mocking intentions.

### Examples

Examples of **incorrect** code for this rule:

```typescript
(foo as jest.Mock).mockReturnValue(1);
const mock = (foo as jest.Mock).mockReturnValue(1);
(foo as unknown as jest.Mock).mockReturnValue(1);
(Obj.foo as jest.Mock).mockReturnValue(1);
([].foo as jest.Mock).mockReturnValue(1);
```

Examples of **correct** code for this rule:

```typescript
jest.mocked(foo).mockReturnValue(1);
const mock = jest.mocked(foo).mockReturnValue(1);
jest.mocked(Obj.foo).mockReturnValue(1);
jest.mocked([].foo).mockReturnValue(1);
```

## How to use

## Version

This rule was added in v0.5.0.

## References

---

---
url: /docs/guide/usage/linter/rules/jest/prefer-lowercase-title.md
---

### What it does

Enforce `it`, `test`, `describe`, and `bench` to have descriptions that begin with a
lowercase letter. This provides more readable test failures.

### Why is this bad?

Lowercase messages for test failures generally result in more grammatically correct
failure messages when you have a test failure.

### Examples

Examples of **incorrect** code for this rule:

```javascript
it("Adds 1 + 2 to equal 3", () => {
  expect(sum(1, 2)).toBe(3);
});
```

Examples of **correct** code for this rule:

```javascript
it("adds 1 + 2 to equal 3", () => {
  expect(sum(1, 2)).toBe(3);
});
```

## Configuration

This rule accepts a configuration object with the following properties:

### allowedPrefixes

type: `string[]`

default: `[]`

This array option allows specifying prefixes, which contain capitals that titles
can start with. This can be useful when writing tests for API endpoints, where
you'd like to prefix with the HTTP method.
By default, nothing is allowed (the equivalent of `{ "allowedPrefixes": [] }`).

Example of **correct** code for the `{ "allowedPrefixes": ["GET"] }` option:

```js
/* jest/prefer-lowercase-title: ["error", { "allowedPrefixes": ["GET"] }] */
describe("GET /live");
```

### ignore

type: `string[]`

default: `[]`

This array option controls which Jest or Vitest functions are checked by this rule. There
are four possible values:

* `"describe"`
* `"test"`
* `"it"`
* `"bench"`

By default, none of these options are enabled (the equivalent of
`{ "ignore": [] }`).

Example of **correct** code for the `{ "ignore": ["describe"] }` option:

```js
/* jest/prefer-lowercase-title: ["error", { "ignore": ["describe"] }] */
describe("Uppercase description");
```

Example of **correct** code for the `{ "ignore": ["test"] }` option:

```js
/* jest/prefer-lowercase-title: ["error", { "ignore": ["test"] }] */
test("Uppercase description");
```

Example of **correct** code for the `{ "ignore": ["it"] }` option:

```js
/* jest/prefer-lowercase-title: ["error", { "ignore": ["it"] }] */
it("Uppercase description");
```

### ignoreTopLevelDescribe

type: `boolean`

default: `false`

This option can be set to allow only the top-level `describe` blocks to have a
title starting with an upper-case letter.

Example of **correct** code for the `{ "ignoreTopLevelDescribe": true }` option:

```js
/* jest/prefer-lowercase-title: ["error", { "ignoreTopLevelDescribe": true }] */
describe("MyClass", () => {
  describe("#myMethod", () => {
    it("does things", () => {
      //
    });
  });
});
```

### lowercaseFirstCharacterOnly

type: `boolean`

default: `true`

This option can be set to only validate that the first character of a test name is lowercased.

Example of **correct** code for the `{ "lowercaseFirstCharacterOnly": true }` option:

```js
/* vitest/prefer-lowercase-title: ["error", { "lowercaseFirstCharacterOnly": true }] */
describe("myClass", () => {
  describe("myMethod", () => {
    it("does things", () => {
      //
    });
  });
});
```

Example of **incorrect** code for the `{ "lowercaseFirstCharacterOnly": true }` option:

```js
/* vitest/prefer-lowercase-title: ["error", { "lowercaseFirstCharacterOnly": true }] */
describe("MyClass", () => {
  describe("MyMethod", () => {
    it("does things", () => {
      //
    });
  });
});
```

## How to use

## Version

This rule was added in v0.15.9.

## References

---

---
url: /docs/guide/usage/linter/rules/jest/prefer-mock-promise-shorthand.md
---

### What it does

When working with mocks of functions that return promises, Jest provides some
API sugar functions to reduce the amount of boilerplate you have to write.
These methods should be preferred when possible.

### Why is this bad?

Using generic mock functions like `mockImplementation(() => Promise.resolve())`
or `mockReturnValue(Promise.reject())` is more verbose and less readable than
Jest's specialized promise shorthands. The shorthand methods like
`mockResolvedValue()` and `mockRejectedValue()` are more expressive and
make the test intent clearer.

### Examples

Examples of **incorrect** code for this rule:

```javascript
jest.fn().mockImplementation(() => Promise.resolve(123));
jest.spyOn(fs.promises, "readFile").mockReturnValue(Promise.reject(new Error("oh noes!")));

myFunction
  .mockReturnValueOnce(Promise.resolve(42))
  .mockImplementationOnce(() => Promise.resolve(42))
  .mockReturnValue(Promise.reject(new Error("too many calls!")));
```

Examples of **correct** code for this rule:

```javascript
jest.fn().mockResolvedValue(123);
jest.spyOn(fs.promises, "readFile").mockRejectedValue(new Error("oh noes!"));

myFunction
  .mockResolvedValueOnce(42)
  .mockResolvedValueOnce(42)
  .mockRejectedValue(new Error("too many calls!"));
```

## How to use

## Version

This rule was added in v0.2.16.

## References

---

---
url: /docs/guide/usage/linter/rules/jest/prefer-mock-return-shorthand.md
---

### What it does

When working with mocks of functions that return simple values, Jest provides some API sugar functions to reduce the amount of boilerplate you have to write.

### Why is this bad?

Not using Jest's API sugar functions adds unnecessary boilerplate and makes tests harder to read. These helpers clearly express intent
and reduce errors, keeping tests simple and maintainable.

### Examples

Examples of **incorrect** code for this rule:

```js
jest.fn().mockImplementation(() => "hello world");

jest
  .spyOn(fs.promises, "readFile")
  .mockImplementationOnce(() => Promise.reject(new Error("oh noes!")));

myFunction
  .mockImplementationOnce(() => 42)
  .mockImplementationOnce(() => Promise.resolve(42))
  .mockReturnValue(0);
```

Examples of **correct** code for this rule:

```js
jest.fn().mockResolvedValue(123);

jest.spyOn(fs.promises, "readFile").mockReturnValue(Promise.reject(new Error("oh noes!")));
jest.spyOn(fs.promises, "readFile").mockRejectedValue(new Error("oh noes!"));

jest.spyOn(fs, "readFileSync").mockImplementationOnce(() => {
  throw new Error("oh noes!");
});

myFunction.mockResolvedValueOnce(42).mockResolvedValueOnce(42).mockReturnValue(0);
```

## How to use

## Version

This rule was added in v1.49.0.

## References

---

---
url: /docs/guide/usage/linter/rules/jest/prefer-snapshot-hint.md
---

### What it does

Enforces including a hint string with snapshot matchers (toMatchSnapshot and toThrowErrorMatchingSnapshot).

### Why is this bad?

Auto-numbered snapshot names are fragile — adding or reordering assertions shifts all subsequent numbers, causing unrelated snapshots to appear changed and obscuring real differences in code review.

### Examples

Examples of **incorrect** code for this rule configured as `always`:

```js
const snapshotOutput = ({ stdout, stderr }) => {
  expect(stdout).toMatchSnapshot();
  expect(stderr).toMatchSnapshot();
};

describe("cli", () => {
  describe("--version flag", () => {
    it("prints the version", async () => {
      snapshotOutput(await runCli(["--version"]));
    });
  });

  describe("--config flag", () => {
    it("reads the config", async () => {
      const { stdout, parsedConfig } = await runCli(["--config", "jest.config.js"]);

      expect(stdout).toMatchSnapshot();
      expect(parsedConfig).toMatchSnapshot();
    });

    it("prints nothing to stderr", async () => {
      const { stderr } = await runCli(["--config", "jest.config.js"]);

      expect(stderr).toMatchSnapshot();
    });

    describe("when the file does not exist", () => {
      it("throws an error", async () => {
        await expect(
          runCli(["--config", "does-not-exist.js"]),
        ).rejects.toThrowErrorMatchingSnapshot();
      });
    });
  });
});
```

Examples of **incorrect** code for this rule configured as `multi`:

```js
const snapshotOutput = ({ stdout, stderr }) => {
  expect(stdout).toMatchSnapshot();
  expect(stderr).toMatchSnapshot();
};

describe("cli", () => {
  describe("--version flag", () => {
    it("prints the version", async () => {
      snapshotOutput(await runCli(["--version"]));
    });
  });

  describe("--config flag", () => {
    it("reads the config", async () => {
      const { stdout, parsedConfig } = await runCli(["--config", "jest.config.js"]);

      expect(stdout).toMatchSnapshot();
      expect(parsedConfig).toMatchSnapshot();
    });

    it("prints nothing to stderr", async () => {
      const { stderr } = await runCli(["--config", "jest.config.js"]);

      expect(stderr).toMatchSnapshot();
    });
  });
});
```

Examples of **correct** code for this rule configured as `always`:

```js
const snapshotOutput = ({ stdout, stderr }, hints) => {
  expect(stdout).toMatchSnapshot({}, `stdout: ${hints.stdout}`);
  expect(stderr).toMatchSnapshot({}, `stderr: ${hints.stderr}`);
};

describe("cli", () => {
  describe("--version flag", () => {
    it("prints the version", async () => {
      snapshotOutput(await runCli(["--version"]), {
        stdout: "version string",
        stderr: "empty",
      });
    });
  });

  describe("--config flag", () => {
    it("reads the config", async () => {
      const { stdout } = await runCli(["--config", "jest.config.js"]);

      expect(stdout).toMatchSnapshot({}, "stdout: config settings");
    });

    it("prints nothing to stderr", async () => {
      const { stderr } = await runCli(["--config", "jest.config.js"]);

      expect(stderr).toMatchInlineSnapshot();
    });

    describe("when the file does not exist", () => {
      it("throws an error", async () => {
        await expect(
          runCli(["--config", "does-not-exist.js"]),
        ).rejects.toThrowErrorMatchingSnapshot("stderr: config error");
      });
    });
  });
});
```

Examples of **correct** code for this rule configured as `multi`:

```js
const snapshotOutput = ({ stdout, stderr }, hints) => {
  expect(stdout).toMatchSnapshot({}, `stdout: ${hints.stdout}`);
  expect(stderr).toMatchSnapshot({}, `stderr: ${hints.stderr}`);
};

describe("cli", () => {
  describe("--version flag", () => {
    it("prints the version", async () => {
      snapshotOutput(await runCli(["--version"]), {
        stdout: "version string",
        stderr: "empty",
      });
    });
  });

  describe("--config flag", () => {
    it("reads the config", async () => {
      const { stdout } = await runCli(["--config", "jest.config.js"]);

      expect(stdout).toMatchSnapshot();
    });

    it("prints nothing to stderr", async () => {
      const { stderr } = await runCli(["--config", "jest.config.js"]);

      expect(stderr).toMatchInlineSnapshot();
    });

    describe("when the file does not exist", () => {
      it("throws an error", async () => {
        await expect(
          runCli(["--config", "does-not-exist.js"]),
        ).rejects.toThrowErrorMatchingSnapshot();
      });
    });
  });
});
```

## Configuration

This rule accepts one of the following string values:

### `"always"`

Require a hint to always be provided when using external snapshot matchers.

### `"multi"`

Require a hint to be provided when there are multiple external snapshot matchers within the scope (meaning it includes nested calls).

## How to use

## Version

This rule was added in v1.59.0.

## References

---

---
url: /docs/guide/usage/linter/rules/jest/prefer-spy-on.md
---

### What it does

When mocking a function by overwriting a property you have to manually restore
the original implementation when cleaning up. When using `jest.spyOn()` Jest
keeps track of changes, and they can be restored with `jest.restoreAllMocks()`,
`mockFn.mockRestore()` or by setting `restoreMocks` to `true` in the Jest
config.

Note: The mock created by `jest.spyOn()` still behaves the same as the original
function. The original function can be overwritten with
`mockFn.mockImplementation()` or by some of the
[other mock functions](https://jestjs.io/docs/en/mock-function-api).

### Why is this bad?

Directly overwriting properties with mock functions can lead to cleanup issues
and test isolation problems. When you manually assign a mock to a property,
you're responsible for restoring the original implementation, which is easy to
forget and can cause tests to interfere with each other. Using `jest.spyOn()`
provides automatic cleanup capabilities and makes your tests more reliable.

### Examples

Examples of **incorrect** code for this rule:

```javascript
Date.now = jest.fn();
Date.now = jest.fn(() => 10);
```

Examples of **correct** code for this rule:

```javascript
jest.spyOn(Date, "now");
jest.spyOn(Date, "now").mockImplementation(() => 10);
```

## How to use

## Version

This rule was added in v0.2.14.

## References

---

---
url: /docs/guide/usage/linter/rules/jest/prefer-strict-equal.md
---

### What it does

This rule triggers a warning if `toEqual()` is used to assert equality.

### Why is this bad?

The `toEqual()` matcher performs a deep equality check but ignores
`undefined` values in objects and arrays. This can lead to false
positives where tests pass when they should fail. `toStrictEqual()`
provides more accurate comparison by checking for `undefined` values.

### Examples

Examples of **incorrect** code for this rule:

```javascript
expect({ a: "a", b: undefined }).toEqual({ a: "a" });
```

Examples of **correct** code for this rule:

```javascript
expect({ a: "a", b: undefined }).toStrictEqual({ a: "a" });
```

## How to use

## Version

This rule was added in v0.2.13.

## References

---

---
url: /docs/guide/usage/linter/rules/jest/prefer-to-be.md
---

### What it does

Recommends using `toBe` matcher for primitive literals and specific
matchers for `null`, `undefined`, and `NaN`.

### Why is this bad?

When asserting against primitive literals such as numbers and strings,
the equality matchers all operate the same, but read slightly
differently in code.

This rule recommends using the `toBe` matcher in these situations, as
it forms the most grammatically natural sentence. For `null`,
`undefined`, and `NaN` this rule recommends using their specific `toBe`
matchers, as they give better error messages as well.

### Examples

Examples of **incorrect** code for this rule:

```javascript
expect(value).not.toEqual(5);
expect(getMessage()).toStrictEqual("hello world");
expect(loadMessage()).resolves.toEqual("hello world");
```

Examples of **correct** code for this rule:

```javascript
expect(value).not.toBe(5);
expect(getMessage()).toBe("hello world");
expect(loadMessage()).resolves.toBe("hello world");
expect(didError).not.toBe(true);
expect(catchError()).toStrictEqual({ message: "oh noes!" });
```

## How to use

## Version

This rule was added in v0.2.14.

## References

---

---
url: /docs/guide/usage/linter/rules/jest/prefer-to-contain.md
---

### What it does

In order to have a better failure message, `toContain()` should be used upon
asserting expectations on an array containing an object.

### Why is this bad?

This rule triggers a warning if `toBe()`, `toEqual()` or `toStrictEqual()` is
used to assert object inclusion in an array

### Examples

Examples of **incorrect** code for this rule:

```javascript
expect(a.includes(b)).toBe(true);
expect(a.includes(b)).not.toBe(true);
expect(a.includes(b)).toBe(false);
expect(a.includes(b)).toEqual(true);
expect(a.includes(b)).toStrictEqual(true);
```

Examples of **correct** code for this rule:

```javascript
expect(a).toContain(b);
expect(a).not.toContain(b);
```

## How to use

## Version

This rule was added in v0.2.14.

## References

---

---
url: /docs/guide/usage/linter/rules/jest/prefer-to-have-been-called.md
---

### What it does

Suggests using `toHaveBeenCalled()` or `not.toHaveBeenCalled()` over `toHaveBeenCalledTimes(0)` or `toBeCalledTimes(0)`.

### Why is this bad?

`toHaveBeenCalled()` is more explicit and readable than `toHaveBeenCalledTimes(0)`.

### Examples

Examples of **incorrect** code for this rule:

```js
expect(mock).toHaveBeenCalledTimes(0);
expect(mock).toBeCalledTimes(0);
expect(mock).not.toHaveBeenCalledTimes(0);
```

Examples of **correct** code for this rule:

```js
expect(mock).not.toHaveBeenCalled();
expect(mock).toHaveBeenCalled();
expect(mock).toHaveBeenCalledTimes(1);
```

## How to use

## Version

This rule was added in v1.34.0.

## References

---

---
url: /docs/guide/usage/linter/rules/jest/prefer-to-have-been-called-times.md
---

### What it does

In order to have a better failure message, [`toHaveBeenCalledTimes` should be used
instead of directly checking the length of `mock.calls`](https://github.com/jest-community/eslint-plugin-jest/blob/v29.5.0/docs/rules/prefer-to-have-been-called-times.md).

### Why is this bad?

This rule triggers a warning if `toHaveLength` is used to assert the number of times a mock is called.

### Examples

Examples of **incorrect** code for this rule:

```js
expect(someFunction.mock.calls).toHaveLength(1);
expect(someFunction.mock.calls).toHaveLength(0);
expect(someFunction.mock.calls).not.toHaveLength(1);
```

Examples of **correct** code for this rule:

```js
expect(someFunction).toHaveBeenCalledTimes(1);
expect(someFunction).toHaveBeenCalledTimes(0);
expect(someFunction).not.toHaveBeenCalledTimes(0);
expect(uncalledFunction).not.toBeCalled();
expect(method.mock.calls[0][0]).toStrictEqual(value);
```

## How to use

## Version

This rule was added in v1.34.0.

## References

---

---
url: /docs/guide/usage/linter/rules/jest/prefer-to-have-length.md
---

### What it does

In order to have a better failure message, `toHaveLength()` should be used upon
asserting expectations on objects length property.

### Why is this bad?

This rule triggers a warning if `toBe()`, `toEqual()` or `toStrictEqual()` is
used to assert objects length property.

### Examples

Examples of **incorrect** code for this rule:

```javascript
expect(files["length"]).toBe(1);
expect(files["length"]).toBe(1);
expect(files["length"])["not"].toBe(1);
```

Examples of **correct** code for this rule:

```javascript
expect(files).toHaveLength(1);
```

## How to use

## Version

This rule was added in v0.2.13.

## References

---

---
url: /docs/guide/usage/linter/rules/jest/prefer-todo.md
---

### What it does

When test cases are empty then it is better to mark them as `test.todo` as it
will be highlighted in the summary output.

### Why is this bad?

This rule triggers a warning if empty test cases are used without 'test.todo'.

### Examples

Examples of **incorrect** code for this rule:

```javascript
test("i need to write this test"); // invalid
test("i need to write this test", () => {}); // invalid
test.skip("i need to write this test", () => {}); // invalid
```

Examples of **correct** code for this rule:

```javascript
test.todo("i need to write this test");
```

## How to use

## Version

This rule was added in v0.0.16.

## References

---

---
url: /docs/guide/usage/linter/rules/jest/require-hook.md
---

### What it does

This rule flags any expression that is either at the toplevel of a test file or
directly within the body of a `describe`, *except* for the following:

* `import` statements
* `const` variables
* `let` *declarations*, and initializations to `null` or `undefined`
* Classes
* Types
* Calls to the standard Jest globals

### Why is this bad?

Having setup and teardown code outside of hooks can lead to unpredictable test
behavior. Code that runs at the top level executes when the test file is loaded,
not when tests run, which can cause issues with test isolation and make tests
dependent on execution order. Using proper hooks like `beforeEach`, `beforeAll`,
`afterEach`, and `afterAll` ensures that setup and teardown code runs at the
correct time and maintains test isolation.

### Examples

Examples of **incorrect** code for this rule:

```javascript
import { database, isCity } from "../database";
import { Logger } from "../../../src/Logger";
import { loadCities } from "../api";

jest.mock("../api");

const initializeCityDatabase = () => {
  database.addCity("Vienna");
  database.addCity("San Juan");
  database.addCity("Wellington");
};

const clearCityDatabase = () => {
  database.clear();
};

initializeCityDatabase();

test("that persists cities", () => {
  expect(database.cities.length).toHaveLength(3);
});
test("city database has Vienna", () => {
  expect(isCity("Vienna")).toBeTruthy();
});

test("city database has San Juan", () => {
  expect(isCity("San Juan")).toBeTruthy();
});

describe("when loading cities from the api", () => {
  let consoleWarnSpy = jest.spyOn(console, "warn");
  loadCities.mockResolvedValue(["Wellington", "London"]);

  it("does not duplicate cities", async () => {
    await database.loadCities();
    expect(database.cities).toHaveLength(4);
  });
});
clearCityDatabase();
```

Examples of **correct** code for this rule:

```javascript
import { database, isCity } from "../database";
import { Logger } from "../../../src/Logger";
import { loadCities } from "../api";

jest.mock("../api");
const initializeCityDatabase = () => {
  database.addCity("Vienna");
  database.addCity("San Juan");
  database.addCity("Wellington");
};

const clearCityDatabase = () => {
  database.clear();
};

beforeEach(() => {
  initializeCityDatabase();
});

test("that persists cities", () => {
  expect(database.cities.length).toHaveLength(3);
});

test("city database has Vienna", () => {
  expect(isCity("Vienna")).toBeTruthy();
});

test("city database has San Juan", () => {
  expect(isCity("San Juan")).toBeTruthy();
});

describe("when loading cities from the api", () => {
  let consoleWarnSpy;
  beforeEach(() => {
    consoleWarnSpy = jest.spyOn(console, "warn");
    loadCities.mockResolvedValue(["Wellington", "London"]);
  });

  it("does not duplicate cities", async () => {
    await database.loadCities();
    expect(database.cities).toHaveLength(4);
  });
});
afterEach(() => {
  clearCityDatabase();
});
```

## Configuration

This rule accepts a configuration object with the following properties:

### allowedFunctionCalls

type: `string[]`

default: `[]`

An array of function names that are allowed to be called outside of hooks.

## How to use

## Version

This rule was added in v0.3.2.

## References

---

---
url: /docs/guide/usage/linter/rules/jest/require-to-throw-message.md
---

### What it does

This rule triggers a warning if `toThrow()` or `toThrowError()` is used without an error message.

### Why is this bad?

Using `toThrow()` or `toThrowError()` without specifying an expected error message
makes tests less specific and harder to debug. When a test only checks that an
error was thrown but not what kind of error, it can pass even when the wrong
error is thrown, potentially hiding bugs. Providing an expected error message
or error type makes tests more precise and helps catch regressions more effectively.

### Examples

Examples of **incorrect** code for this rule:

```javascript
test("all the things", async () => {
  expect(() => a()).toThrow();
  expect(() => a()).toThrowError();
  await expect(a()).rejects.toThrow();
  await expect(a()).rejects.toThrowError();
});
```

Examples of **correct** code for this rule:

```javascript
test("all the things", async () => {
  expect(() => a()).toThrow("a");
  expect(() => a()).toThrowError("a");
  await expect(a()).rejects.toThrow("a");
  await expect(a()).rejects.toThrowError("a");
});
```

## How to use

## Version

This rule was added in v0.2.9.

## References

---

---
url: /docs/guide/usage/linter/rules/jest/require-top-level-describe.md
---

### What it does

Requires test cases and hooks to be inside a top-level `describe` block.

### Why is this bad?

Having tests and hooks organized within `describe` blocks provides better
structure and grouping for test suites. It makes test output more readable
and helps with test organization, especially in larger codebases.

This rule triggers a warning if a test case (`test` and `it`) or a hook
(`beforeAll`, `beforeEach`, `afterEach`, `afterAll`) is not located in a
top-level `describe` block.

### Examples

Examples of **incorrect** code for this rule:

```javascript
// Above a describe block
test("my test", () => {});
describe("test suite", () => {
  it("test", () => {});
});

// Below a describe block
describe("test suite", () => {});
test("my test", () => {});

// Same for hooks
beforeAll("my beforeAll", () => {});
describe("test suite", () => {});
afterEach("my afterEach", () => {});
```

Examples of **correct** code for this rule:

```javascript
// Above a describe block
// In a describe block
describe("test suite", () => {
  test("my test", () => {});
});

// In a nested describe block
describe("test suite", () => {
  test("my test", () => {});
  describe("another test suite", () => {
    test("my other test", () => {});
  });
});
```

## Configuration

This rule accepts a configuration object with the following properties:

### maxNumberOfTopLevelDescribes

type: `integer`

default: `Infinity`

The maximum number of top-level `describe` blocks allowed in a test file.

## How to use

## Version

This rule was added in v0.4.2.

## References

---

---
url: /docs/guide/usage/linter/rules/jest/valid-describe-callback.md
---

### What it does

This rule validates that the second parameter of a `describe()` function is a
callback function. This callback function:

* should not be
  [async](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/async_function)
* should not contain any parameters
* should not contain any `return` statements

### Why is this bad?

Using an improper `describe()` callback function can lead to unexpected test
errors.

### Examples

Examples of **incorrect** code for this rule:

```javascript
// Async callback functions are not allowed
describe("myFunction()", async () => {
  // ...
});

// Callback function parameters are not allowed
describe("myFunction()", (done) => {
  // ...
});

// Returning a value from a describe block is not allowed
describe("myFunction", () =>
  it("returns a truthy value", () => {
    expect(myFunction()).toBeTruthy();
  }));
```

## How to use

## Version

This rule was added in v0.0.8.

## References

---

---
url: /docs/guide/usage/linter/rules/jest/valid-expect.md
---

### What it does

Checks that `expect()` is called correctly.

### Why is this bad?

`expect()` is a function that is used to assert values in tests.
It should be called with a single argument, which is the value to be tested.
If you call `expect()` with no arguments, or with more than one argument, it will not work as expected.

### Examples

Examples of **incorrect** code for this rule:

```javascript
expect();
expect("something");
expect(true).toBeDefined;
expect(Promise.resolve("Hi!")).resolves.toBe("Hi!");
```

Examples of **correct** code for this rule:

```javascript
expect("something").toEqual("something");
expect(true).toBeDefined();
await expect(Promise.resolve("Hi!")).resolves.toBe("Hi!");
```

## Configuration

This rule accepts a configuration object with the following properties:

### alwaysAwait

type: `boolean`

default: `false`

When `true`, async assertions must be awaited in all contexts (not just return statements).

### asyncMatchers

type: `string[]`

default: `["toResolve", "toReject"]`

List of matchers that are considered async and therefore require awaiting (e.g. `toResolve`, `toReject`).

### maxArgs

type: `integer`

default: `1`

Maximum number of arguments `expect` should be called with.

### minArgs

type: `integer`

default: `1`

Minimum number of arguments `expect` should be called with.

## How to use

## Version

This rule was added in v0.0.14.

## References

---

---
url: /docs/guide/usage/linter/rules/jest/valid-expect-in-promise.md
---

### What it does

Ensures that `expect` calls inside promise chains (`.then()`, `.catch()`,
`.finally()`) are properly awaited or returned from the test.

### Why is this bad?

When `expect` is called inside a promise callback that is not awaited or
returned, the test may pass even if the assertion fails because the test
completes before the promise resolves. This leads to silently passing
tests with broken assertions.

### Examples

Examples of **incorrect** code for this rule:

```javascript
test("promise test", async () => {
  something().then((value) => {
    expect(value).toBe("red");
  });
});

test("promises test", () => {
  const onePromise = something().then((value) => {
    expect(value).toBe("red");
  });
  const twoPromise = something().then((value) => {
    expect(value).toBe("blue");
  });

  return Promise.any([onePromise, twoPromise]);
});
```

Examples of **correct** code for this rule:

```javascript
test("promise test", async () => {
  await something().then((value) => {
    expect(value).toBe("red");
  });
});

test("promises test", () => {
  const onePromise = something().then((value) => {
    expect(value).toBe("red");
  });
  const twoPromise = something().then((value) => {
    expect(value).toBe("blue");
  });

  return Promise.all([onePromise, twoPromise]);
});
```

## How to use

## Version

This rule was added in v1.60.0.

## References

---

---
url: /docs/guide/usage/linter/rules/jest/valid-title.md
---

### What it does

Checks that the titles of Jest and Vitest blocks are valid.

Titles must be:

* not empty,
* strings,
* not prefixed with their block name,
* have no leading or trailing spaces.

### Why is this bad?

Titles that are not valid can be misleading and make it harder to understand the purpose of the test.

### Examples

Examples of **incorrect** code for this rule:

```javascript
describe("", () => {});
describe("foo", () => {
  it("", () => {});
});
it("", () => {});
test("", () => {});
xdescribe("", () => {});
xit("", () => {});
xtest("", () => {});
```

Examples of **correct** code for this rule:

```javascript
describe("foo", () => {});
it("bar", () => {});
test("baz", () => {});
```

### Options

```typescript
interface Options {
  ignoreSpaces?: boolean;
  ignoreTypeOfTestName?: boolean;
  ignoreTypeOfDescribeName?: boolean;
  allowArguments?: boolean;
  disallowedWords?: string[];
  mustNotMatch?: Partial<Record<"describe" | "test" | "it", string>> | string;
  mustMatch?: Partial<Record<"describe" | "test" | "it", string>> | string;
}
```

## How to use

## Version

This rule was added in v0.0.14.

## References

---

---
url: /docs/guide/usage/linter/js-plugins.md
---

# JS Plugins

Oxlint supports plugins written in JS - either custom-written, or from npm.

Oxlint's plugin API is compatible with ESLint v9+, so most existing ESLint plugins should work out of the box with Oxlint.

Almost the entirety of ESLint's plugin API is now implemented (see [below](#api-support)), so most existing ESLint plugins should work out of the box.

:::info
JS plugins are currently in alpha, and remain under active development.

All APIs should behave identically to ESLint. If you find any differences in behavior,
that's a bug - please [report it](https://github.com/oxc-project/oxc/issues/new?template=linter_bug_report.yaml).
:::

## Using JS plugins

1. Add a path to the plugin to the `.oxlintrc.json` config file, under `jsPlugins`.
2. Add rules from the plugin, under `rules`.

The path can be any valid import specifier e.g. `./plugin.js`, `eslint-plugin-foo`, or `@foo/eslint-plugin`.
Paths are resolved relative to the config file itself.

::: code-group

```jsonc [.oxlintrc.json]
{
  "jsPlugins": ["./path/to/my-plugin.js", "eslint-plugin-whatever", "@foobar/eslint-plugin"],
  "rules": {
    "my-plugin/rule1": "error",
    "my-plugin/rule2": "warn",
    "whatever/rule1": "error",
    "whatever/rule2": "warn",
    "@foobar/rule1": "error",
  },
  // ... other config ...
}
```

```ts [oxlint.config.ts]
import { defineConfig } from "oxlint";

export default defineConfig({
  jsPlugins: ["./path/to/my-plugin.js", "eslint-plugin-whatever", "@foobar/eslint-plugin"],
  rules: {
    "my-plugin/rule1": "error",
    "my-plugin/rule2": "warn",
    "whatever/rule1": "error",
    "whatever/rule2": "warn",
    "@foobar/rule1": "error",
  },
  // ... other config ...
});
```

:::

### Plugin aliases

You can also define a different name (alias) for a plugin. This is useful if:

* The default plugin name clashes with name of a native Oxlint plugin (e.g. jsdoc, react, etc.).
* The default plugin name is very long.
* You want to use a plugin that Oxlint supports natively, but a specific rule you need is not yet implemented in Oxlint's native version.

::: code-group

```jsonc [.oxlintrc.json]
{
  "jsPlugins": [
    // `jsdoc` is a reserved name, as Oxlint supports it natively
    {
      "name": "jsdoc-js",
      "specifier": "eslint-plugin-jsdoc",
    },
    // Shorten name
    {
      "name": "short",
      "specifier": "eslint-plugin-with-name-so-very-very-long",
    },
    // List plugins you don't want to alias as just specifiers
    "eslint-plugin-whatever",
  ],
  "rules": {
    "jsdoc-js/check-alignment": "error",
    "short/rule1": "error",
    "whatever/rule2": "error",
  },
}
```

```ts [oxlint.config.ts]
import { defineConfig } from "oxlint";

export default defineConfig({
  jsPlugins: [
    // `jsdoc` is a reserved name, as Oxlint supports it natively
    {
      name: "jsdoc-js",
      specifier: "eslint-plugin-jsdoc",
    },
    // Shorten name
    {
      name: "short",
      specifier: "eslint-plugin-with-name-so-very-very-long",
    },
    // List plugins you don't want to alias as just specifiers
    "eslint-plugin-whatever",
  ],
  rules: {
    "jsdoc-js/check-alignment": "error",
    "short/rule1": "error",
    "whatever/rule2": "error",
  },
});
```

:::

See the [Writing JS Plugins](./writing-js-plugins) page for information on writing your own JS plugins and custom rules for Oxlint.

## Known-supported ESLint plugins

We run conformance tests on a number of popular ESLint plugins to ensure they work with Oxlint. These include:

* `eslint-plugin-cypress` ([conformance test results](https://github.com/oxc-project/oxc/blob/main/apps/oxlint/conformance/snapshots/cypress.md))
* `@e18e/eslint-plugin` ([conformance test results](https://github.com/oxc-project/oxc/blob/main/apps/oxlint/conformance/snapshots/e18e.md))
* `eslint-plugin-mocha` ([conformance test results](https://github.com/oxc-project/oxc/blob/main/apps/oxlint/conformance/snapshots/mocha.md))
* `eslint-plugin-playwright` ([conformance test results](https://github.com/oxc-project/oxc/blob/main/apps/oxlint/conformance/snapshots/playwright.md))
* `eslint-plugin-react-hooks` ([conformance test results](https://github.com/oxc-project/oxc/blob/main/apps/oxlint/conformance/snapshots/react-hooks.md)): Note that some of these rules are already supported natively in Oxlint, and so those should generally be used instead
* `eslint-plugin-regexp` ([conformance test results](https://github.com/oxc-project/oxc/blob/main/apps/oxlint/conformance/snapshots/regexp.md))
* `eslint-plugin-sonarjs` ([conformance test results](https://github.com/oxc-project/oxc/blob/main/apps/oxlint/conformance/snapshots/sonarjs.md))
* `eslint-plugin-storybook` ([conformance test results](https://github.com/oxc-project/oxc/blob/main/apps/oxlint/conformance/snapshots/storybook.md))
* `@stylistic/eslint-plugin` ([conformance test results](https://github.com/oxc-project/oxc/blob/main/apps/oxlint/conformance/snapshots/stylistic.md))
* `eslint-plugin-testing-library` ([conformance test results](https://github.com/oxc-project/oxc/blob/main/apps/oxlint/conformance/snapshots/testing_library.md))

Note that the above list is not exhaustive, and *many* other ESLint plugins will work with Oxlint as well. These are just some popular plugins that we have explicitly tested.

You can see more info about plugins that are known to work with Oxlint in the [GitHub Discussion](https://github.com/oxc-project/oxc/discussions/20245).

## API Support

Oxlint supports almost all of ESLint's API surface:

* AST traversal.
* AST exploration (`node.parent`, `context.sourceCode.getAncestors`).
* Fixes.
* Rule options.
* Selectors ([ESLint docs](https://eslint.org/docs/latest/extend/selectors)).
* `SourceCode` APIs (e.g. `context.sourceCode.getText(node)`).
* `SourceCode` tokens APIs (e.g. `context.sourceCode.getTokens(node)`).
* Scope analysis.
* Control flow analysis (code paths).
* Inline disable directives. (`// oxlint-disable`)
* Language server (IDE) support + suggestions (in-editor diagnostics and quick-fixes)

Not supported yet:

* Custom file formats and parsers (e.g. Svelte, Vue, Angular).
* Lint rules that rely on TypeScript type-awareness.

ESLint APIs that were removed in ESLint v9 or earlier will not be implemented in most cases. If an ESLint plugin is unmaintained and was never updated to upgrade their API usage for ESLint v9, you may need to modify the plugin yourself or find an alternative.

We will be implementing the remaining features over the next few months, aiming to support 100% of ESLint's
plugin API surface.

---

---
url: /docs/guide/usage/linter/rules/jsdoc/check-access.md
---

### What it does

Checks that `@access` tags use one of the following values:

* "package", "private", "protected", "public"

Also reports:

* Mixing of `@access` with `@public`, `@private`, `@protected`, or `@package` on the same doc block.
* Use of multiple instances of `@access` (or the `@public`, etc) on the same doc block.

### Why is this bad?

It is important to have a consistent way of specifying access levels in JSDoc
comments. Using invalid or multiple access level tags creates confusion about
the intended visibility of documented elements and can lead to inconsistencies
in API documentation generation. Mixing different access tags or using invalid
values makes the documentation unclear and potentially misleading.

### Examples

Examples of **incorrect** code for this rule:

```javascript
/** @access private @public */

/** @access invalidlevel */
```

Examples of **correct** code for this rule:

```javascript
/** @access private */

/** @private */
```

## How to use

## Version

This rule was added in v0.2.16.

## References

---

---
url: /docs/guide/usage/linter/rules/jsdoc/check-property-names.md
---

### What it does

Ensures that property names in JSDoc are not duplicated on the same block and that nested properties have defined roots.

### Why is this bad?

`@property` tags with the same name can be confusing and may indicate a mistake.

### Examples

Examples of **incorrect** code for this rule:

```javascript
/**
 * @typedef {object} state
 * @property {number} foo
 * @property {string} foo
 */

/**
 * @typedef {object} state
 * @property {number} foo.bar
 */
```

Examples of **correct** code for this rule:

```javascript
/**
 * @typedef {object} state
 * @property {number} foo
 */

/**
 * @typedef {object} state
 * @property {object} foo
 * @property {number} foo.bar
 */
```

## How to use

## Version

This rule was added in v0.2.18.

## References

---

---
url: /docs/guide/usage/linter/rules/jsdoc/check-tag-names.md
---

### What it does

Reports invalid block tag names.
Additionally checks for tag names that are redundant when using a type checker such as TypeScript.

### Why is this bad?

Using invalid tags can lead to confusion and make the documentation harder to read.

### Examples

Examples of **incorrect** code for this rule:

```javascript
/** @Param */
/** @foo */

/**
 * This is redundant when typed.
 * @type {string}
 */
```

Examples of **correct** code for this rule:

```javascript
/** @param */
```

### Settings

Configuration for allowed tags is done via [`settings.jsdoc.tagNamePreference`](/docs/guide/usage/linter/config-file-reference.html#settings-jsdoc-tagnamepreference).
There is no CLI-only parameter for this rule.

You can add custom tags by adding a key-value pair where both match the name of the tag you want to add, like so:

::: code-group

```json [Config (.oxlintrc.json)]
{
  "plugins": ["jsdoc"],
  "rules": {
    "jsdoc/check-tag-names": "error"
  },
  "settings": {
    // [!code highlight:7]
    "jsdoc": {
      "tagNamePreference": {
        "customTagName": "customTagName"
      }
    }
  }
}
```

:::

Examples of correct code for this rule with the above configuration, adding the `customTagName` tag:

```js
/**
 * @customTagName
 */
```

## Configuration

This rule accepts a configuration object with the following properties:

### definedTags

type: `string[]`

default: `[]`

Additional tag names to allow.

### jsxTags

type: `boolean`

default: `false`

Whether to allow JSX-related tags:

* `jsx`
* `jsxFrag`
* `jsxImportSource`
* `jsxRuntime`

### typed

type: `boolean`

default: `false`

If typed is `true`, disallow tags that are unnecessary/duplicative of TypeScript functionality.

## How to use

## Version

This rule was added in v0.3.2.

## References

---

---
url: /docs/guide/usage/linter/rules/jsdoc/empty-tags.md
---

### What it does

Expects the following tags to be empty of any content:

* `@abstract`
* `@async`
* `@generator`
* `@global`
* `@hideconstructor`
* `@ignore`
* `@inner`
* `@instance`
* `@override`
* `@readonly`
* `@inheritDoc`
* `@internal`
* `@overload`
* `@package`
* `@private`
* `@protected`
* `@public`
* `@static`

### Why is this bad?

The void tags should be empty.

### Examples

Examples of **incorrect** code for this rule:

```javascript
/** @async foo */

/** @private bar */
```

Examples of **correct** code for this rule:

```javascript
/** @async */

/** @private */
```

## Configuration

This rule accepts a configuration object with the following properties:

### tags

type: `string[]`

default: `[]`

Additional tags to check for their descriptions.

## How to use

## Version

This rule was added in v0.2.16.

## References

---

---
url: /docs/guide/usage/linter/rules/jsdoc/implements-on-classes.md
---

### What it does

Reports an issue with any non-constructor function using `@implements`.

### Why is this bad?

Constructor functions should be
whether marked with `@class`, `@constructs`, or being a class constructor.

### Examples

Examples of **incorrect** code for this rule:

```javascript
/**
 * @implements {SomeClass}
 */
function quux() {}
```

Examples of **correct** code for this rule:

```javascript
class Foo {
  /**
   * @implements {SomeClass}
   */
  constructor() {}
}
/**
 * @implements {SomeClass}
 * @class
 */
function quux() {}
```

## How to use

## Version

This rule was added in v0.3.2.

## References

---

---
url: /docs/guide/usage/linter/rules/jsdoc/no-blank-blocks.md
---

### What it does

Reports and optionally removes blocks with whitespace only.

### Why is this bad?

Blank JSDoc blocks add noise without providing any documentation.

### Examples

Examples of **incorrect** code for this rule:

```js
/** */

/**
 *
 */
```

Examples of **correct** code for this rule:

```js
/** @tag */

/**
 * Text
 */

/**
 * @tag
 */
```

## Configuration

This rule accepts a configuration object with the following properties:

### enableFixer

type: `boolean`

default: `false`

Whether to automatically remove blank JSDoc blocks.

## How to use

## Version

This rule was added in vnext.

## References

---

---
url: /docs/guide/usage/linter/rules/jsdoc/no-defaults.md
---

### What it does

This rule reports defaults being used on the relevant portion of `@param` or `@default`.
It also optionally reports the presence of the square-bracketed optional arguments at all.

### Why is this bad?

The rule is intended to prevent the indication of defaults on tags
where this would be redundant with ES2015 default parameters.

### Examples

Examples of **incorrect** code for this rule:

```javascript
/** @param {number} [foo="7"] */
function quux(foo) {}
```

Examples of **correct** code for this rule:

```javascript
/** @param {number} foo */
function quux(foo) {}

/** @param foo */
function quux(foo) {}
```

## Configuration

This rule accepts a configuration object with the following properties:

### noOptionalParamNames

type: `boolean`

default: `false`

If true, report the presence of optional param names (square brackets) on `@param` tags.

## How to use

## Version

This rule was added in v0.3.2.

## References

---

---
url: /docs/guide/usage/linter/rules/jsdoc/require-param.md
---

### What it does

Requires that all function parameters are documented with JSDoc `@param` tags.

### Why is this bad?

The rule is aimed at enforcing code quality and maintainability by requiring
that all function parameters are documented.

### Examples

Examples of **incorrect** code for this rule:

```javascript
/** @param foo */
function quux(foo, bar) {}
```

Examples of **correct** code for this rule:

```javascript
/** @param foo */
function quux(foo) {}
```

## Configuration

This rule accepts a configuration object with the following properties:

### checkConstructors

type: `boolean`

default: `false`

Whether to check constructor methods.

### checkDestructured

type: `boolean`

default: `true`

Whether to check destructured parameters.

### checkDestructuredRoots

type: `boolean`

default: `true`

Whether to check destructured parameters when you have code like
`function doSomething({ a, b }) { ... }`. Because there is no named
parameter in this example, when this option is `true` you must
have a `@param` tag that corresponds to `{a, b}`.

### checkGetters

type: `boolean`

default: `true`

Whether to check getter methods.

### checkRestProperty

type: `boolean`

default: `false`

Whether to check rest properties.

### checkSetters

type: `boolean`

default: `true`

Whether to check setter methods.

### checkTypesPattern

type: `string`

default: `"^(?:[oO]bject|[aA]rray|PlainObject|Generic(?:Object|Array))$"`

Regex pattern to match types that exempt parameters from checking.

### exemptedBy

type: `string[]`

default: `["inheritdoc"]`

List of JSDoc tags that exempt functions from `@param` checking.

### ignoreWhenAllParamsMissing

type: `boolean`

default: `false`

Set to `true` to ignore reporting when all params are missing. Defaults to `false`.

### interfaceExemptsParamsCheck

type: `boolean`

default: `false`

Set if you wish TypeScript interfaces to exempt checks for the existence of `@param`'s.
Will check for a type defining the function itself (on a variable declaration) or if there is a single destructured object with a type. Defaults to `false`.

### useDefaultObjectProperties

type: `boolean`

default: `false`

Set to `true` if you wish to expect documentation of properties on objects supplied as default values. Defaults to `false`.

## How to use

## Version

This rule was added in v0.4.3.

## References

---

---
url: /docs/guide/usage/linter/rules/jsdoc/require-param-description.md
---

### What it does

Requires that each `@param` tag has a description value.

### Why is this bad?

The description of a param should be documented.

### Examples

Examples of **incorrect** code for this rule:

```javascript
/** @param foo */
function quux(foo) {}
```

Examples of **correct** code for this rule:

```javascript
/** @param foo Foo. */
function quux(foo) {}
```

## Configuration

This rule accepts a configuration object with the following properties:

### defaultDestructuredRootDescription

type: `string`

default: `"The root object"`

The description string to set by default for destructured roots. Defaults to "The root object".

### setDefaultDestructuredRootDescription

type: `boolean`

default: `false`

Whether to set a default destructured root description.
For example, you may wish to avoid manually having to set the description for a @param corresponding to a destructured root object as it should always be the same type of object.
Uses `defaultDestructuredRootDescription` for the description string. Defaults to `false`.

## How to use

## Version

This rule was added in v0.4.4.

## References

---

---
url: /docs/guide/usage/linter/rules/jsdoc/require-param-name.md
---

### What it does

Requires that all `@param` tags have names.

### Why is this bad?

The name of a param should be documented.

### Examples

Examples of **incorrect** code for this rule:

```javascript
/** @param {SomeType} */
function quux(foo) {}
```

Examples of **correct** code for this rule:

```javascript
/** @param {SomeType} foo */
function quux(foo) {}
```

## How to use

## Version

This rule was added in v0.4.3.

## References

---

---
url: /docs/guide/usage/linter/rules/jsdoc/require-param-type.md
---

### What it does

Requires that each `@param` tag has a type value (within curly brackets).

### Why is this bad?

The type of a parameter should be documented.

### Examples

Examples of **incorrect** code for this rule:

```javascript
/** @param foo */
function quux(foo) {}
```

Examples of **correct** code for this rule:

```javascript
/** @param {SomeType} foo */
function quux(foo) {}
```

## Configuration

This rule accepts a configuration object with the following properties:

### defaultDestructuredRootType

type: `string`

default: `"object"`

The type string to set by default for destructured roots. Defaults to "object".

### setDefaultDestructuredRootType

type: `boolean`

default: `false`

Whether to set a default destructured root type. For example, you may wish to avoid manually having to set the type for a `@param` corresponding to a destructured root object as it is always going to be an object. Uses `defaultDestructuredRootType` for the type string. Defaults to `false`.

## How to use

## Version

This rule was added in v0.4.4.

## References

---

---
url: /docs/guide/usage/linter/rules/jsdoc/require-property.md
---

### What it does

Requires that all `@typedef` and `@namespace` tags have `@property` tags
when their type is a plain `object`, `Object`, or `PlainObject`.

Note: this rule can be configured via [jsdoc settings](https://oxc.rs/docs/guide/usage/linter/config-file-reference.html#settings) option.

### Why is this bad?

Object type should have properties defined.

### Examples

Examples of **incorrect** code for this rule:

```javascript
/**
 * @typedef {Object} SomeTypedef
 */

/**
 * @namespace {Object} SomeNamespace
 */
```

Examples of **correct** code for this rule:

```javascript
/**
 * @typedef {Object} SomeTypedef
 * @property {SomeType} propName Prop description
 */

/**
 * @typedef {object} Foo
 * @property someProp
 */
```

## How to use

## Version

This rule was added in v0.2.18.

## References

---

---
url: /docs/guide/usage/linter/rules/jsdoc/require-property-description.md
---

### What it does

Requires that all `@property` tags have descriptions.

### Why is this bad?

The description of a property should be documented.

### Examples

Examples of **incorrect** code for this rule:

```javascript
/**
 * @typedef {SomeType} SomeTypedef
 * @property {number} foo
 */
```

Examples of **correct** code for this rule:

```javascript
/**
 * @typedef {SomeType} SomeTypedef
 * @property {number} foo Foo.
 */
```

## How to use

## Version

This rule was added in v0.2.18.

## References

---

---
url: /docs/guide/usage/linter/rules/jsdoc/require-property-name.md
---

### What it does

Requires that all `@property` tags have names.

### Why is this bad?

The name of a property type should be documented.

### Examples

Examples of **incorrect** code for this rule:

```javascript
/**
 * @typedef {SomeType} SomeTypedef
 * @property {number}
 */
```

Examples of **correct** code for this rule:

```javascript
/**
 * @typedef {SomeType} SomeTypedef
 * @property {number} foo
 */
```

## How to use

## Version

This rule was added in v0.2.18.

## References

---

---
url: /docs/guide/usage/linter/rules/jsdoc/require-property-type.md
---

### What it does

Requires that each `@property` tag has a type value (within curly brackets).

### Why is this bad?

The type of a property should be documented.

### Examples

Examples of **incorrect** code for this rule:

```javascript
/**
 * @typedef {SomeType} SomeTypedef
 * @property foo
 */
```

Examples of **correct** code for this rule:

```javascript
/**
 * @typedef {SomeType} SomeTypedef
 * @property {number} foo
 */
```

## How to use

## Version

This rule was added in v0.2.18.

## References

---

---
url: /docs/guide/usage/linter/rules/jsdoc/require-returns.md
---

### What it does

Requires that return statements are documented.
Will also report if multiple `@returns` tags are present.

### Why is this bad?

The rule is intended to prevent the omission of `@returns` tag when necessary.

### Examples

Examples of **incorrect** code for this rule:

```javascript
/** Foo. */
function quux() {
  return foo;
}

/**
 * @returns Foo!
 * @returns Foo?
 */
function quux() {
  return foo;
}
```

Examples of **correct** code for this rule:

```javascript
/** @returns Foo. */
function quux() {
  return foo;
}
```

## Configuration

This rule accepts a configuration object with the following properties:

### checkConstructors

type: `boolean`

default: `false`

Whether to check constructor methods.

### checkGetters

type: `boolean`

default: `true`

Whether to check getter methods.

### exemptedBy

type: `string[]`

default: `["inheritdoc"]`

Tags that exempt functions from requiring `@returns`.

### forceRequireReturn

type: `boolean`

default: `false`

Whether to require a `@returns` tag even if the function doesn't return a value.

### forceReturnsWithAsync

type: `boolean`

default: `false`

Whether to require a `@returns` tag for async functions.

## How to use

## Version

This rule was added in v0.4.0.

## References

---

---
url: /docs/guide/usage/linter/rules/jsdoc/require-returns-description.md
---

### What it does

Requires that the `@returns` tag has a description value.
The error will not be reported if the return value is `void `or `undefined` or if it is `Promise<void>` or `Promise<undefined>`.

### Why is this bad?

A `@returns` tag should have a description value.

### Examples

Examples of **incorrect** code for this rule:

```javascript
/** @returns */
function quux(foo) {}
```

Examples of **correct** code for this rule:

```javascript
/** @returns Foo. */
function quux(foo) {}
```

## How to use

## Version

This rule was added in v0.4.0.

## References

---

---
url: /docs/guide/usage/linter/rules/jsdoc/require-returns-type.md
---

### What it does

Requires that the `@returns` tag has a type value (in curly brackets).

### Why is this bad?

A `@returns` tag should have a type value.

### Examples

Examples of **incorrect** code for this rule:

```javascript
/** @returns */
function quux(foo) {}
```

Examples of **correct** code for this rule:

```javascript
/** @returns {string} */
function quux(foo) {}
```

## How to use

## Version

This rule was added in v0.4.3.

## References

---

---
url: /docs/guide/usage/linter/rules/jsdoc/require-throws-description.md
---

### What it does

Requires a description for `@throws` tags.

### Why is this bad?

A `@throws` tag should explain the condition or reason an error may be thrown.

### Examples

Examples of **incorrect** code for this rule:

```js
/**
 * @throws {Error}
 */
function quux() {
  throw new Error("error");
}
```

Examples of **correct** code for this rule:

```js
/**
 * @throws {Error} Has a description
 */
function quux() {
  throw new Error("error");
}
```

## How to use

## Version

This rule was added in v1.65.0.

## References

---

---
url: /docs/guide/usage/linter/rules/jsdoc/require-throws-type.md
---

### What it does

Requires a type on the `@throws` tag.

### Why is this bad?

A `@throws` tag should document the type of error that may be thrown.

### Examples

Examples of **incorrect** code for this rule:

```js
/** @throws */
function quux() {
  throw new Error("error");
}
```

Examples of **correct** code for this rule:

```js
/** @throws {Error} */
function quux() {
  throw new Error("error");
}
```

## How to use

## Version

This rule was added in v1.65.0.

## References

---

---
url: /docs/guide/usage/linter/rules/jsdoc/require-yields.md
---

### What it does

Requires that yields are documented.
Will also report if multiple `@yields` tags are present.

### Why is this bad?

The rule is intended to prevent the omission of `@yields` tags when they are necessary.

### Examples

Examples of **incorrect** code for this rule:

```javascript
function* quux(foo) {
  yield foo;
}

/**
 * @yields {undefined}
 * @yields {void}
 */
function* quux(foo) {}
```

Examples of **correct** code for this rule:

```javascript
/** * @yields Foo */
function* quux(foo) {
  yield foo;
}
```

## Configuration

This rule accepts a configuration object with the following properties:

### exemptedBy

type: `string[]`

default: `["inheritdoc"]`

Functions with these tags will be exempted from the lint rule.

### forceRequireYields

type: `boolean`

default: `false`

When `true`, all generator functions must have a `@yields` tag, even if they don't yield a value or have an empty body.

### withGeneratorTag

type: `boolean`

default: `false`

When `true`, require `@yields` when a `@generator` tag is present.

## How to use

## Version

This rule was added in v0.3.2.

## References

---

---
url: /docs/guide/usage/linter/rules/jsdoc/require-yields-description.md
---

### What it does

Requires a description for `@yields` tags.

### Why is this bad?

A `@yields` tag should explain what the generator yields.

### Examples

Examples of **incorrect** code for this rule:

```js
/**
 * @yields {string}
 */
function* quux() {
  yield "value";
}
```

Examples of **correct** code for this rule:

```js
/**
 * @yields {string} The next value.
 */
function* quux() {
  yield "value";
}
```

## How to use

## Version

This rule was added in v1.68.0.

## References

---

---
url: /docs/guide/usage/linter/rules/jsdoc/require-yields-type.md
---

### What it does

Requires a type on the `@yields` tag.

### Why is this bad?

A `@yields` tag should document the type yielded by the generator.

### Examples

Examples of **incorrect** code for this rule:

```js
/** @yields */
function* quux() {}
```

Examples of **correct** code for this rule:

```js
/** @yields {string} */
function* quux() {}
```

## How to use

## Version

This rule was added in v1.65.0.

## References

---

---
url: /docs/guide/usage/transformer/jsx.md
---
# JSX

Oxc transformer supports transforming JSX.

## General Usage

```js
import { transform } from "oxc-transform";

const result = await transform("App.jsx", sourceCode, {
  jsx: {
    runtime: "automatic", // or "classic"
    development: false, // or true
    throwIfNamespace: true, // or false
    pure: true, // or false
    importSource: "react",
    pragma: "React.createElement",
    pragmaFrag: "React.Fragment",
    refresh: false, // see below
  },
  // When transforming TSX files:
  typescript: {
    jsxPragma: "React.createElement", // same value with `jsx.pragma`
    jsxPragmaFrag: "React.Fragment", // same value with `jsx.pragmaFrag`
  },
});
```

You can also set `jsx: 'preserve'` to disable JSX transformation.

Oxc transformer also supports JSX pragma comments, which is also supported by [Babel](https://babeljs.io/docs/babel-preset-react/) and [esbuild](https://esbuild.github.io/api/#jsx). Pragma comments are useful for configuring JSX options on a per-file basis.

### Pragma Comment Scanning

Oxc only scans comments that appear **before the first statement** in a file for JSX pragmas. This means pragma comments placed inside functions, classes, or after any statement are ignored.

```jsx
// @jsx h  ← ✅ This pragma is recognized (before first statement)

import { h } from "preact";

// @jsx React.createElement  ← ❌ This pragma is ignored (after first statement)
function App() {
  return <div />;
}
```

This behavior aligns with TypeScript and SWC, which both restrict pragma scanning to leading comments. Note that Babel and esbuild scan all comments in a file (with the last one winning).

## Runtime

By default, the `"automatic"` runtime transform is used. This transform was [introduced in React 17+](https://legacy.reactjs.org/blog/2020/09/22/introducing-the-new-jsx-transform.html). In this mode, Oxc injects the required `import` statements automatically, so `import React from 'react';` is unnecessary in `.jsx`/`.tsx` files.

You can also use the classic runtime transform by setting `jsx.runtime` option to `"classic"`.

`// @jsxRuntime classic` / `// @jsxRuntime automatic` at the start of a file are pragma comments that can be used to configure this.

## Common Options for Both Runtimes

### Development Transform

By default, the development-specific transforms are disabled. You can enable them by setting the `jsx.development` option to `true`.

### XML Namespaced Tag Names

By default, an error is thrown if the XML namespaced tag names (e.g. `<foo:bar baz:qux="foobar" />`) are used. Though the JSX spec allows this, it is disallowed by default since React's JSX does not currently support them. You can allow them by setting `jsx.throwIfNamespace` option to `false`.

### Pure Annotation

By default, JSX elements are annotated with pure annotations. Pure annotations are annotation comments that marks expressions that can be safely removed if their return values are not used. But this may not be desired if the JSX elements should be kept. You can disable this by setting `jsx.pure` option to `false`.

## Automatic Runtime Specific Options

### Import Source

This option specifies the import source for the JSX helper functions. The default value is `"react"`.

For example, if you want to use the `preact` package instead of `react`, you can set `jsx.importSource` to `"preact"`, then the following import statements may be injected:

```js
import { createElement } from "preact";
import { Fragment, jsxDEV } from "preact/jsx-dev-runtime";
import { Fragment, jsx, jsxs } from "preact/jsx-runtime";
```

`// @jsxImportSource preact` is the way to configure this via pragma comments.

## Classic Runtime Specific Options

### Pragma

This option specifies the function name to use when transforming JSX expressions. It should be a qualified name (e.g. `React.createElement`) or an identifier (e.g. `createElement`). This option is called `jsxFactory` in esbuild.

`// @jsx createElement` is the way to configure this via pragma comments.

### Pragma Fragment

This option specifies the function name to use when transforming JSX fragments. It should be a valid JSX tag name. This option is called `jsxFragment` in esbuild.

`// @jsxFrag Fragment` is the way to configure this via pragma comments.

## React Refresh

React Refresh (also known as React Fast Refresh) provides hot reloading capabilities for React components during development.

### Usage

To enable React Refresh transformation, set `jsx.refresh` option:

```javascript
import { transform } from "oxc-transform";

const result = await transform("App.jsx", sourceCode, {
  jsx: {
    development: true,
    refresh: true,
    // or...
    // refresh: {
    //   refreshReg: "$RefreshReg$",
    //   refreshSig: "$RefreshSig$",
    //   emitFullSignatures: true,
    // },
  },
});
```

### Configuration Options

| Option               | Type      | Default          | Description                                                 |
| -------------------- | --------- | ---------------- | ----------------------------------------------------------- |
| `refreshReg`         | `string`  | `"$RefreshReg$"` | The name of the function to register components for refresh |
| `refreshSig`         | `string`  | `"$RefreshSig$"` | The name of the function to create signatures for refresh   |
| `emitFullSignatures` | `boolean` | `false`          | Whether to emit full signatures for better debugging        |

---

---
url: /docs/guide/usage/linter/rules/jsx_a11y/alt-text.md
---

### What it does

Enforce that all elements that require alternative text have meaningful
information to relay back to the end user.

### Why is this bad?

Alternative text is a critical component of accessibility for screen
reader users, enabling them to understand the content and function of
an element. Missing or inadequate alt text makes content inaccessible
to users who rely on assistive technologies.

### Examples

Examples of **incorrect** code for this rule:

```jsx
<img src="flower.jpg" />
<img src="flower.jpg" alt="" />
<object />
<area />
```

Examples of **correct** code for this rule:

```jsx
<img src="flower.jpg" alt="A close-up of a white daisy" />
<img src="decorative.jpg" alt="" role="presentation" />
<object aria-label="Interactive chart" />
<area alt="Navigation link" />
```

## Configuration

This rule accepts a configuration object with the following properties:

### area

type: `string[]`

default: `[]`

Custom components to check for alt text on `area` elements.

### elements

type: `array`

Custom components to check for alt text on any of the supported elements.

#### elements\[n]

type: `"img" | "object" | "area" | "input[type="image"]"`

### img

type: `string[]`

default: `[]`

Custom components to check for alt text on `img` elements.

### input\[type="image"]

type: `string[]`

default: `[]`

Custom components to check for alt text on `input[type="image"]` elements.

### object

type: `string[]`

default: `[]`

Custom components to check for alt text on `object` elements.

## How to use

## Version

This rule was added in v0.0.16.

## References

---

---
url: /docs/guide/usage/linter/rules/jsx_a11y/anchor-ambiguous-text.md
---

### What it does

Inspects anchor link text for the use of ambiguous words.

This rule checks the text from the anchor element `aria-label` if available.
In absence of an anchor `aria-label` it combines the following text of it's children:

* `aria-label` if available
* if the child is an image, the `alt` text
* the text content of the HTML element

### Why is this bad?

Screen readers users rely on link text for context, ambiguous words such as "click here" do
not provide enough context.

### Examples

Examples of **incorrect** code for this rule:

```jsx
<a>link</a>
<a>click here</a>
```

Examples of **correct** code for this rule:

```jsx
<a>read this tutorial</a>
<a aria-label="oxc linter documentation">click here</a>
```

## Configuration

This rule accepts a configuration object with the following properties:

### words

type: `string[]`

default: `["click here", "here", "link", "a link", "learn more"]`

List of ambiguous words or phrases that should be flagged in anchor text.

## How to use

## Version

This rule was added in v0.13.2.

## References

---

---
url: /docs/guide/usage/linter/rules/jsx_a11y/anchor-has-content.md
---

### What it does

Enforce that anchors have content and that the content is accessible to screen readers.
Accessible means that it is not hidden using the `aria-hidden` prop.

Alternatively, you may use the `title` prop or the `aria-label` prop.

### Why is this bad?

Anchor elements without content can be confusing for users relying
on screen readers to understand.

### Examples

Examples of **correct** code for this rule:

```jsx
<a>Anchor Content!</a>
<a><TextWrapper /></a>
<a dangerouslySetInnerHTML={{ __html: 'foo' }} />
<a title='foo' />
<a aria-label='foo' />
```

Examples of **incorrect** code for this rule:

```jsx
<a />
<a><TextWrapper aria-hidden /></a>
```

## Configuration

This rule accepts a configuration object with the following properties:

### components

type: `string[]`

default: `[]`

Additional custom component names to treat as anchor elements.

## How to use

## Version

This rule was added in v0.0.18.

## References

---

---
url: /docs/guide/usage/linter/rules/jsx_a11y/anchor-is-valid.md
---

### What it does

The HTML `<a>` element, with a valid href attribute, is formally defined as representing a **hyperlink**.
That is, a link between one HTML document and another, or between one location inside an HTML document and another location inside the same document.

While before it was possible to attach logic to an anchor element, with the advent of JSX libraries,
it's now easier to attach logic to any HTML element, anchors included.

This rule is designed to prevent users to attach logic at the click of anchors, and also makes
sure that the `href` provided to the anchor element is valid. If the anchor has logic attached to it,
the rules suggests to turn it to a `button`, because that's likely what the user wants.

Anchor `<a></a>` elements should be used for navigation, while `<button></button>` should be
used for user interaction.

Consider the following:

```jsx
<>
  <a href="javascript:void(0)" onClick={foo}>
    Perform action
  </a>
  <a href="#" onClick={foo}>
    Perform action
  </a>
  <a onClick={foo}>Perform action</a>
</>
```

All these anchor implementations indicate that the element is only used to execute JavaScript code. All the above should be replaced with:

```jsx
<button onClick={foo}>Perform action</button>
```

### Why is this bad?

There are **many reasons** why an anchor should not have logic and have a correct `href` attribute:

* it can disrupt the correct flow of the user navigation e.g. a user that wants to open the link
  in another tab, but the default "click" behaviour is prevented
* it can source of invalid links, and crawlers can't navigate the website, risking to penalise SEO ranking

### Examples

Examples of **valid** code for this rule:

```jsx
<>
  <a href={`https://www.javascript.com`}>navigate here</a>
  <a href={somewhere}>navigate here</a>
  <a {...spread}>navigate here</a>
</>
```

Examples of **invalid** code for this rule:

```jsx
<>
  <a href={null}>navigate here</a>
  <a href={undefined}>navigate here</a>
  <a href>navigate here</a>
  <a href="javascript:void(0)">navigate here</a>
  <a href="https://example.com" onClick={something}>
    navigate here
  </a>
</>
```

### Reference

* [WCAG 2.1.1](https://www.w3.org/WAI/WCAG21/Understanding/keyboard)

## Configuration

This rule accepts a configuration object with the following properties:

### aspects

type: `array`

Sub-rule aspects to run.

#### aspects\[n]

type: `"noHref" | "invalidHref" | "preferButton"`

### components

type: `string[]`

default: `[]`

Custom components to treat as anchor elements.

### specialLink

type: `string[]`

default: `[]`

Custom prop names to treat as link destinations.

## How to use

## Version

This rule was added in v0.0.19.

## References

---

---
url: /docs/guide/usage/linter/rules/jsx_a11y/aria-activedescendant-has-tabindex.md
---

### What it does

Enforce elements with aria-activedescendant are tabbable.

### Why is this bad?

Elements with `aria-activedescendant` must be tabbable for users to
navigate to them using keyboard input. Without proper tabindex, screen
reader users cannot access the element through keyboard navigation,
making the functionality inaccessible.

### Examples

Examples of **incorrect** code for this rule:

```jsx
const Bad = <div aria-activedescendant={someID} />;
```

Examples of **correct** code for this rule:

```jsx
const Good = (
  <>
    <CustomComponent />
    <CustomComponent aria-activedescendant={someID} />
    <CustomComponent aria-activedescendant={someID} tabIndex={0} />
    <CustomComponent aria-activedescendant={someID} tabIndex={-1} />
    <div />
    <input />
    <div tabIndex={0} />
    <div aria-activedescendant={someID} tabIndex={0} />
    <div aria-activedescendant={someID} tabIndex="0" />
    <div aria-activedescendant={someID} tabIndex={1} />
    <div aria-activedescendant={someID} tabIndex={-1} />
    <div aria-activedescendant={someID} tabIndex="-1" />
    <input aria-activedescendant={someID} />
    <input aria-activedescendant={someID} tabIndex={0} />
    <input aria-activedescendant={someID} tabIndex={-1} />
  </>
);
```

## How to use

## Version

This rule was added in v0.2.1.

## References

---

---
url: /docs/guide/usage/linter/rules/jsx_a11y/aria-props.md
---

### What it does

Enforces that elements do not use invalid ARIA attributes.

### Why is this bad?

Using invalid ARIA attributes can mislead screen readers and other assistive technologies.
It may cause the accessibility features of the website to fail, making it difficult
for users with disabilities to use the site effectively.

This rule includes fixes for some common typos.

### Examples

Examples of **incorrect** code for this rule:

```jsx
<input aria-labeledby="address_label" />
```

Examples of **correct** code for this rule:

```jsx
<input aria-labelledby="address_label" />
```

## How to use

## Version

This rule was added in v0.0.22.

## References

---

---
url: /docs/guide/usage/linter/rules/jsx_a11y/aria-proptypes.md
---

### What it does

Enforces that elements do not use invalid ARIA state and property values.

### Why is this bad?

Using invalid ARIA state and property values can mislead screen readers and other assistive technologies.
It may cause the accessibility features of the website to fail, making it difficult for users with disabilities to use the site effectively.

### Examples

Examples of **incorrect** code for this rule:

```jsx
<div aria-level="yes" />
<div aria-relevant="additions removalss" />
```

Examples of **correct** code for this rule:

```jsx
<div aria-label="foo" />
<div aria-labelledby="foo bar" />
<div aria-checked={false} />
<div aria-invalid="grammar" />
```

## How to use

## Version

This rule was added in v1.36.0.

## References

---

---
url: /docs/guide/usage/linter/rules/jsx_a11y/aria-role.md
---

### What it does

Elements with ARIA roles must use a valid, non-abstract ARIA role. A
reference to role definitions can be found at
[WAI-ARIA](https://www.w3.org/TR/wai-aria/#role_definitions) site.

### Why is this bad?

The intent of this Success Criterion is to ensure that Assistive
Technologies (AT) can gather information about, activate (or set) and
keep up to date on the status of user interface controls in the
content(such as screen readers, screen magnifiers, and speech
recognition software, used by people with disabilities).

When standard controls from accessible technologies are used, this
process is straightforward. If the user interface elements are used
according to specification the conditions of this provision will be met.

If custom controls are created, however, or interface elements are
programmed (in code or script) to have a different role and/or function
than usual, then additional measures need to be taken to ensure that the
controls provide important information to assistive technologies and
allow themselves to be controlled by assistive technologies. A
particularly important state of a user interface control is whether or
not it has focus. The focus state of a control can be programmatically
determined, and notifications about change of focus are sent to user
agents and assistive technology. Other examples of user interface
control state are whether or not a checkbox or radio button has been
selected, or whether or not a collapsible tree or list node is expanded
or collapsed.

### Examples

Examples of **incorrect** code for this rule:

```jsx
<div role="datepicker"></div> <!-- Bad: "datepicker" is not an ARIA role -->
<div role="range"></div>      <!-- Bad: "range" is an _abstract_ ARIA role -->
<div role=""></div>           <!-- Bad: An empty ARIA role is not allowed -->
<Foo role={role}></Foo>       <!-- Bad: ignoreNonDOM is set to false or not set -->
```

Examples of **correct** code for this rule:

```jsx
<div role="button"></div>     <!-- Good: "button" is a valid ARIA role -->
<div role={role}></div>       <!-- Good: role is a variable & cannot be determined until runtime. -->
<div></div>                   <!-- Good: No ARIA role -->
<Foo role={role}></Foo>       <!-- Good: ignoreNonDOM is set to true -->
```

## Configuration

This rule accepts a configuration object with the following properties:

### allowedInvalidRoles

type: `string[]`

default: `[]`

Custom roles that should be allowed in addition to the ARIA spec.

### ignoreNonDOM

type: `boolean`

default: `false`

Determines if developer-created components are checked.

## How to use

## Version

This rule was added in v0.1.1.

## References

---

---
url: /docs/guide/usage/linter/rules/jsx_a11y/aria-unsupported-elements.md
---

### What it does

Enforces that reserved DOM elements do not contain ARIA roles, states,
or properties.

### Why is this bad?

Certain reserved DOM elements do not support ARIA roles, states and
properties. This is often because they are not visible, for example
`meta`, `html`, `script`, `style`. Adding ARIA attributes to these
elements is meaningless and can create confusion for screen readers.

### Examples

Examples of **incorrect** code for this rule:

```jsx
<meta charset="UTF-8" aria-hidden="false" />
```

Examples of **correct** code for this rule:

```jsx
<meta charset="UTF-8" />
```

## How to use

## Version

This rule was added in v0.1.1.

## References

---

---
url: /docs/guide/usage/linter/rules/jsx_a11y/autocomplete-valid.md
---

### What it does

Enforces that an element's autocomplete attribute must be a valid value.

### Why is this bad?

Incorrectly using the autocomplete attribute may decrease the accessibility of the website for users.

### Examples

Examples of **incorrect** code for this rule:

```jsx
<input autocomplete="invalid-value" />
```

Examples of **correct** code for this rule:

```jsx
<input autocomplete="name" />
```

## Configuration

This rule accepts a configuration object with the following properties:

### inputComponents

type: `string[]`

default: `["input"]`

List of custom component names that should be treated as input elements.

## How to use

## Version

This rule was added in v0.2.0.

## References

---

---
url: /docs/guide/usage/linter/rules/jsx_a11y/click-events-have-key-events.md
---

### What it does

Enforce onClick is accompanied by at least one of the following: onKeyUp, onKeyDown, onKeyPress.

### Why is this bad?

Coding for the keyboard is important for users with physical disabilities who cannot use a mouse, AT compatibility, and screen reader users.
This does not apply for interactive or hidden elements.

### Examples

Examples of **incorrect** code for this rule:

```jsx
<div onClick={() => void 0} />
```

Examples of **correct** code for this rule:

```jsx
<div onClick={() => void 0} onKeyDown={() => void 0} />
```

## How to use

## Version

This rule was added in v0.2.1.

## References

---

---
url: /docs/guide/usage/linter/rules/jsx_a11y/control-has-associated-label.md
---

### What it does

Enforce that a control (an interactive element) has a text label.

### Why is this bad?

An interactive element (such as a `<button>`) without an accessible
text label makes it difficult or impossible for users of assistive
technologies to understand the purpose of the control.

### Examples

Examples of **incorrect** code for this rule:

```jsx
<button />
<a href="/path" />
<th />
<div role="button" />
<div role="checkbox" />
```

Examples of **correct** code for this rule:

```jsx
<button>Save</button>
<button aria-label="Save" />
<label>Name <input type="text" /></label>
<a href="/path">Learn more</a>
<th>Column Header</th>
<div role="button">Submit</div>
<div role="checkbox" aria-labelledby="label_id" />
```

## Configuration

This rule accepts a configuration object with the following properties:

### controlComponents

type: `string[]`

default: `[]`

Custom JSX components to be treated as interactive controls.

### depth

type: `integer`

default: `2`

Maximum depth to search for an accessible label within the element.
Defaults to `2`.

### ignoreElements

type: `string[]`

default: `["audio", "canvas", "embed", "input", "textarea", "tr", "video"]`

Elements to ignore.
Defaults to `["audio", "canvas", "embed", "input", "textarea", "tr", "video"]`.

### ignoreRoles

type: `string[]`

default: `["grid", "listbox", "menu", "menubar", "radiogroup", "row", "tablist", "toolbar", "tree", "treegrid"]`

Interactive roles to ignore.
Defaults to `["grid", "listbox", "menu", "menubar", "radiogroup", "row", "tablist", "toolbar", "tree", "treegrid"]`.

### labelAttributes

type: `string[]`

default: `[]`

Additional attributes to check for accessible label text.

## How to use

## Version

This rule was added in v1.65.0.

## References

---

---
url: /docs/guide/usage/linter/rules/jsx_a11y/heading-has-content.md
---

### What it does

Enforce that heading elements (h1, h2, etc.) have content and
that the content is accessible to screen readers.
Accessible means that it is not hidden using the aria-hidden prop.

### Why is this bad?

Screen readers alert users to the presence of a heading tag.
If the heading is empty or the text cannot be accessed,
this could either confuse users or even prevent them
from accessing information on the page's structure.

### Examples

Examples of **incorrect** code for this rule:

```jsx
<h1 />
```

Examples of **correct** code for this rule:

```jsx
<h1>Foo</h1>
```

## Configuration

This rule accepts a configuration object with the following properties:

### components

type: `string[]`

default: `null`

Additional custom component names to treat as heading elements.
These will be validated in addition to the standard h1-h6 elements.

## How to use

## Version

This rule was added in v0.0.19.

## References

---

---
url: /docs/guide/usage/linter/rules/jsx_a11y/html-has-lang.md
---

### What it does

Ensures that every HTML document has a lang attribute.

### Why is this bad?

If the language of a webpage is not specified,
the screen reader assumes the default language set by the user.
Language settings become an issue for users who speak multiple languages
and access website in more than one language.

### Examples

Examples of **incorrect** code for this rule:

```jsx
<html />
```

Examples of **correct** code for this rule:

```jsx
<html lang="en" />
```

## How to use

## Version

This rule was added in v0.0.18.

## References

---

---
url: /docs/guide/usage/linter/rules/jsx_a11y/iframe-has-title.md
---

### What it does

Enforce iframe elements have a title attribute.

### Why is this bad?

Screen reader users rely on a iframe title to describe the contents of
the iframe. Navigating through iframe and iframe elements quickly
becomes difficult and confusing for users of this technology if the
markup does not contain a title attribute.

### Examples

Examples of **incorrect** code for this rule:

```jsx
<iframe />
<iframe {...props} />
<iframe title="" />
<iframe title={''} />
<iframe title={``} />
<iframe title={undefined} />
<iframe title={false} />
<iframe title={true} />
<iframe title={42} />
```

Examples of **correct** code for this rule:

```jsx
<iframe title="This is a unique title" />
<iframe title={uniqueTitle} />
```

## How to use

## Version

This rule was added in v0.0.19.

## References

---

---
url: /docs/guide/usage/linter/rules/jsx_a11y/img-redundant-alt.md
---

### What it does

Enforce that `img` alt attributes do not contain redundant words like
"image", "picture", or "photo".

### Why is this bad?

Screen readers already announce `img` elements as an image, so there is
no need to use words such as "image", "photo", or "picture" in the alt
text. This creates redundant information for users of assistive
technologies and makes the alt text less concise and useful.

### Examples

Examples of **incorrect** code for this rule:

```jsx
<img src="foo" alt="Photo of foo being weird." />
<img src="bar" alt="Image of me at a bar!" />
<img src="baz" alt="Picture of baz fixing a bug." />
```

Examples of **correct** code for this rule:

```jsx
<img src="foo" alt="Foo eating a sandwich." />
<img src="bar" aria-hidden alt="Picture of me taking a photo of an image" /> // Will pass because it is hidden.
<img src="baz" alt={`Baz taking a ${photo}`} /> // This is valid since photo is a variable name.
```

## Configuration

This rule accepts a configuration object with the following properties:

### components

type: `string[]`

default: `["img"]`

JSX element types to validate (component names) where the rule applies.
For example, `["img", "Image"]`.

### words

type: `string[]`

default: `["image", "photo", "picture"]`

Words considered redundant in alt text that should trigger a warning.

## How to use

## Version

This rule was added in v0.0.19.

## References

---

---
url: /docs/guide/usage/linter/rules/jsx_a11y/interactive-supports-focus.md
---

### What it does

Enforce that elements with interactive roles and interaction handlers
(mouse or key press) must be focusable.

### Why is this bad?

Elements that handle user interaction (e.g., `onClick`) but are not
natively focusable (like `<div>` or `<span>`) must be made focusable so
that keyboard-only users and assistive technology users can reach and
activate them.

Without a `tabIndex`, these elements are unreachable via keyboard navigation,
creating a barrier for users who cannot use a mouse.

### Examples

Examples of **incorrect** code for this rule:

```jsx
<span onClick={submitForm} role="button">Submit</span>
<a onClick={showNextPage} role="button">Next page</a>
```

Examples of **correct** code for this rule:

```jsx
<div aria-hidden onClick={() => void 0} />
<span onClick={doSomething} tabIndex={0} role="button">Click me!</span>
<span onClick={doSomething} tabIndex={-1} role="menuitem">Click me too!</span>
<a href="javascript:void(0);" onClick={doSomething}>Click ALL the things!</a>
<button onClick={doSomething}>Click the button :)</button>
```

## Configuration

This rule accepts a configuration object with the following properties:

### tabbable

type: `string[]`

default: `["button", "checkbox", "link", "searchbox", "spinbutton", "switch", "textbox"]`

An array of interactive ARIA roles that should be considered tabbable (require `tabIndex={0}`).
Interactive roles not in this list are only required to be focusable (`tabIndex={-1}` is sufficient).
Defaults to `["button", "checkbox", "link", "searchbox", "spinbutton", "switch", "textbox"]`.

## How to use

## Version

This rule was added in v1.63.0.

## References

---

---
url: /docs/guide/usage/linter/rules/jsx_a11y/label-has-associated-control.md
---

### What it does

Enforce that a label tag has a text label and an associated control.

### Why is this bad?

A form label that either isn't properly associated with a form control (such as an `<input>`), or doesn't contain accessible text, hinders accessibility for users using assistive technologies such as screen readers. The user may not have enough information to understand the purpose of the form control.

### Examples

Examples of **incorrect** code for this rule:

```jsx
function Foo(props) {
    return <label {...props} />
}

<input type="text" />
<label>Surname</label>
```

Examples of **correct** code for this rule:

```jsx
function Foo(props) {
  const { htmlFor, ...otherProps } = props;

  return <label htmlFor={htmlFor} {...otherProps} />;
}

<label>
  <input type="text" />
  Surname
</label>;
```

## Configuration

This rule accepts a configuration object with the following properties:

### assert

type: `"htmlFor" | "nesting" | "both" | "either"`

default: `"either"`

The type of association required between the label and the control.

#### `"htmlFor"`

Assert that the label uses `htmlFor` to associate a control.

#### `"nesting"`

Assert that the label has a nested control

#### `"both"`

Assert that the label uses both `htmlFor` and nesting for associating a control

#### `"either"`

Assert that the label uses either `htmlFor` or nesting for associating a control

### controlComponents

type: `string[]`

default: `[]`

Custom JSX components to be treated as form controls.

### depth

type: `integer`

default: `2`

Maximum depth to search for a nested control.

### labelAttributes

type: `string[]`

default: `["alt", "aria-label", "aria-labelledby"]`

Attributes to check for accessible label text.

### labelComponents

type: `string[]`

default: `["label"]`

Custom JSX components to be treated as labels.

## How to use

## Version

This rule was added in v0.9.1.

## References

---

---
url: /docs/guide/usage/linter/rules/jsx_a11y/lang.md
---

### What it does

The lang prop on the `<html>` element must be a valid IETF BCP 47 language tag.

### Why is this bad?

If the language of a webpage is not specified as valid,
the screen reader assumes the default language set by the user.
Language settings become an issue for users who speak multiple languages
and access website in more than one language.

### Examples

Examples of **incorrect** code for this rule:

```jsx
<html>
<html lang="foo">
```

Examples of **correct** code for this rule:

```jsx
<html lang="en">
<html lang="en-US">
```

### Resources

* [eslint-plugin-jsx-a11y/lang](https://github.com/jsx-eslint/eslint-plugin-jsx-a11y/blob/v6.9.0/docs/rules/lang.md)
* [IANA Language Subtag Registry](https://www.iana.org/assignments/language-subtag-registry/language-subtag-registry)

## How to use

## Version

This rule was added in v0.1.1.

## References

---

---
url: /docs/guide/usage/linter/rules/jsx_a11y/media-has-caption.md
---

### What it does

Checks if `<audio>` and `<video>` elements have a `<track>` element for captions.
This ensures media content is accessible to all users, including those with hearing impairments.

### Why is this bad?

Without captions, audio and video content is not accessible to users who are deaf or hard of hearing.
Captions are also useful for users in noisy environments or where audio is not available.

### Examples

Examples of **incorrect** code for this rule:

```jsx
<audio></audio>
<video></video>
```

Examples of **correct** code for this rule:

```jsx
<audio><track kind="captions" src="caption_file.vtt" /></audio>
<video><track kind="captions" src="caption_file.vtt" /></video>
```

## Configuration

This rule accepts a configuration object with the following properties:

### audio

type: `string[]`

default: `["audio"]`

Element names to treat as `<audio>` elements

### track

type: `string[]`

default: `["track"]`

Element names to treat as `<track>` elements

### video

type: `string[]`

default: `["video"]`

Element names to treat as `<video>` elements

## How to use

## Version

This rule was added in v0.1.1.

## References

---

---
url: /docs/guide/usage/linter/rules/jsx_a11y/mouse-events-have-key-events.md
---

### What it does

Enforce `onMouseOver`/`onMouseOut` are accompanied by `onFocus`/`onBlur`.

### Why is this bad?

Coding for the keyboard is important for users with physical disabilities who cannot use a mouse,
AT compatibility, and screen reader users.

### Examples

Examples of **incorrect** code for this rule:

```jsx
<div onMouseOver={() => void 0} />
```

Examples of **correct** code for this rule:

```jsx
<div onMouseOver={() => void 0} onFocus={() => void 0} />
```

## Configuration

This rule accepts a configuration object with the following properties:

### hoverInHandlers

type: `string[]`

default: `["onMouseOver"]`

List of hover-in mouse event handlers that require corresponding keyboard event handlers.

### hoverOutHandlers

type: `string[]`

default: `["onMouseOut"]`

List of hover-out mouse event handlers that require corresponding keyboard event handlers.

## How to use

## Version

This rule was added in v0.1.1.

## References

---

---
url: /docs/guide/usage/linter/rules/jsx_a11y/no-access-key.md
---

### What it does

Enforces that the `accessKey` prop is not used on any element to avoid complications with keyboard commands used by a screen reader.

### Why is this bad?

Access keys are HTML attributes that allow web developers to assign keyboard shortcuts to elements.
Inconsistencies between keyboard shortcuts and keyboard commands used by screen readers and keyboard-only users create accessibility complications so to avoid complications, access keys should not be used.

### Examples

Examples of **incorrect** code for this rule:

```jsx
<div accessKey="h" />
```

Examples of **correct** code for this rule:

```jsx
<div />
```

## How to use

## Version

This rule was added in v0.0.21.

## References

---

---
url: /docs/guide/usage/linter/rules/jsx_a11y/no-aria-hidden-on-focusable.md
---

### What it does

Enforces that `aria-hidden="true"` is not set on focusable elements.

### Why is this bad?

`aria-hidden="true"` on focusable elements can lead to confusion or unexpected behavior for screen reader users.

### Examples

Examples of **incorrect** code for this rule:

```jsx
<div aria-hidden="true" tabIndex="0" />
```

Examples of **correct** code for this rule:

```jsx
<div aria-hidden="true" />
```

## How to use

## Version

This rule was added in v0.0.22.

## References

---

---
url: /docs/guide/usage/linter/rules/jsx_a11y/no-autofocus.md
---

### What it does

Enforce that `autoFocus` prop is not used on elements.

### Why is this bad?

Autofocusing elements can cause usability issues for sighted and
non-sighted users alike. It can be disorienting when focus is shifted
without user input and can interfere with assistive technologies.
Users should control when and where focus moves on a page.

### Exceptions

`<dialog>` elements, elements with `role="dialog"`, and elements with the
`popover` attribute (and their descendants) are exempt, since directing
focus into them when opened is the expected behavior.
See [MDN: `<dialog>` accessibility](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/dialog#accessibility).

### Examples

Examples of **incorrect** code for this rule:

```jsx
<div autoFocus />
<div autoFocus="true" />
<div autoFocus="false" />
<div autoFocus={undefined} />
```

Examples of **correct** code for this rule:

```jsx
<div />
<dialog><input autoFocus /></dialog>
<div role="dialog"><input autoFocus /></div>
<div popover><input autoFocus /></div>
```

## Configuration

This rule accepts a configuration object with the following properties:

### ignoreNonDOM

type: `boolean`

default: `false`

Determines if developer-created components are checked.

## How to use

## Version

This rule was added in v0.0.19.

## References

---

---
url: /docs/guide/usage/linter/rules/jsx_a11y/no-distracting-elements.md
---

### What it does

Enforces that no distracting elements are used.

### Why is this bad?

Elements that can be visually distracting can cause accessibility issues
with visually impaired users. Such elements are most likely deprecated,
and should be avoided. By default, `<marquee>` and `<blink>` elements
are visually distracting and can trigger vestibular disorders.

### Examples

Examples of **incorrect** code for this rule:

```jsx
<marquee />
<marquee {...props} />
<marquee lang={undefined} />
<blink />
<blink {...props} />
<blink foo={undefined} />
```

Examples of **correct** code for this rule:

```jsx
<div />
<Marquee />
<Blink />
```

## Configuration

This rule accepts a configuration object with the following properties:

### elements

type: `array`

List of distracting elements to check for.

#### elements\[n]

type: `"marquee" | "blink"`

## How to use

## Version

This rule was added in v0.0.22.

## References

---

---
url: >-
  /docs/guide/usage/linter/rules/jsx_a11y/no-interactive-element-to-noninteractive-role.md
---

### What it does

Interactive HTML elements indicate controls in the user interface. Interactive elements include `<a href>`, `<button>`, `<input>`, `<select>`, `<textarea>`.

WAI-ARIA roles should not be used to convert an interactive element to a non-interactive element.
Non-interactive ARIA roles include `article`, `banner`, `complementary`, `img`, `listitem`, `main`, `region` and `tooltip`.

### Why is this bad?

Using a non-interactive role on an interactive element can confuse assistive technology users.

### Examples

Examples of **incorrect** code for this rule:

```jsx
<button role="img">Save</button>
```

Examples of **correct** code for this rule:

```jsx
<div role="img">
  <button>Save</button>
</div>
```

## Configuration

This rule accepts a configuration object with the following properties:

type: `Record<string, array>`

## How to use

## Version

This rule was added in v1.65.0.

## References

---

---
url: >-
  /docs/guide/usage/linter/rules/jsx_a11y/no-noninteractive-element-interactions.md
---

### What it does

Prevents non-interactive HTML elements and elements with non-interactive ARIA roles from
being assigned mouse or keyboard event handlers.

### Why is this bad?

Non-interactive elements such as `<main>`, `<h1>`, `<p>`, `<img>`, `<li>`, `<ul>`, and
`<ol>` represent content or containers. Adding interaction handlers to them can make the
UI difficult or impossible to operate with assistive technology.

Move the handler to an interactive element, such as `<button>` or `<a href>`, or use an
element with an appropriate interactive role and keyboard behavior.

### Examples

Examples of **incorrect** code for this rule:

```jsx
<li onClick={() => {}} />
<div role="listitem" onKeyDown={() => {}} />
```

Examples of **correct** code for this rule:

```jsx
<button onClick={() => {}} />
<div role="button" onClick={() => {}} />
<div onClick={() => {}} role="presentation" />
```

## Configuration

This rule accepts a configuration object with the following properties:

### handlers

type: `string[]`

default: `["onError", "onLoad", "onKeyPress", "onKeyDown", "onKeyUp", "onFocus", "onBlur", "onClick", "onContextMenu", "onDblClick", "onDoubleClick", "onDrag", "onDragEnd", "onDragEnter", "onDragExit", "onDragLeave", "onDragOver", "onDragStart", "onDrop", "onMouseDown", "onMouseEnter", "onMouseLeave", "onMouseMove", "onMouseOut", "onMouseOver", "onMouseUp"]`

An array of event handler names that should trigger this rule.

## How to use

## Version

This rule was added in v1.65.0.

## References

---

---
url: >-
  /docs/guide/usage/linter/rules/jsx_a11y/no-noninteractive-element-to-interactive-role.md
---

### What it does

Non-interactive HTML elements indicate *content* and *containers* in the user interface.
Non-interactive elements include `<main>`, `<area>`, `<h1>` (through `<h6>`), `<p>`,
`<img>`, `<li>`, `<ul>`, and `<ol>`.

Interactive HTML elements indicate *controls* in the user interface.
Interactive elements include `<a href>`, `<button>`, `<input>`, `<select>`,
`<textarea>`.

[WAI-ARIA roles](https://www.w3.org/TR/wai-aria-1.1/#usage_intro) should not be used
to convert a non-interactive element to an interactive element. Interactive ARIA roles
include `button`, `link`, `checkbox`, `menuitem`, `menuitemcheckbox`,
`menuitemradio`, `option`, `radio`, `searchbox`, `switch`, and `textbox`.

### Why is this bad?

Overriding the semantic meaning of non-interactive elements with interactive roles
creates confusion for assistive technology users. The element lacks the expected
keyboard interaction patterns and focus management that interactive elements provide.

### Examples

Examples of **incorrect** code for this rule:

```jsx
<h1 role="button">Click me</h1>
<li role="link">Navigate</li>
<article role="button">Submit</article>
```

Examples of **correct** code for this rule:

```jsx
<button>Click me</button>
<a href="/page">Navigate</a>
<div role="button">Submit</div>
<ul role="menu"><li role="menuitem">Item</li></ul>
```

## Configuration

This rule accepts a configuration object with the following properties:

type: `Record<string, array>`

## How to use

## Version

This rule was added in v1.64.0.

## References

---

---
url: /docs/guide/usage/linter/rules/jsx_a11y/no-noninteractive-tabindex.md
---

### What it does

This rule checks that non-interactive elements don't have a tabIndex which would make them interactive via keyboard navigation.

### Why is this bad?

Tab key navigation should be limited to elements on the page that can be interacted with.
Thus it is not necessary to add a tabindex to items in an unordered list, for example,
to make them navigable through assistive technology.

These applications already afford page traversal mechanisms based on the HTML of the page.
Generally, we should try to reduce the size of the page's tab ring rather than increasing it.

### Examples

Examples of **incorrect** code for this rule:

```jsx
<div tabIndex="0" />
<div role="article" tabIndex="0" />
<article tabIndex="0" />
<article tabIndex={0} />
```

Examples of **correct** code for this rule:

```jsx
<div />
<MyButton tabIndex={0} />
<button />
<button tabIndex="0" />
<button tabIndex={0} />
<div />
<div tabIndex="-1" />
<div role="button" tabIndex="0" />
<div role="article" tabIndex="-1" />
<article tabIndex="-1" />
```

## Configuration

This rule accepts a configuration object with the following properties:

### allowExpressionValues

type: `boolean`

default: `true`

If `true`, allows tabIndex values to be expression values (e.g., variables, ternaries). If `false`, only string literal values are allowed.

### roles

type: `string[]`

default: `["tabpanel"]`

An array of ARIA roles that should be considered interactive.

### tags

type: `string[]`

default: `[]`

An array of custom HTML elements that should be considered interactive.

## How to use

## Version

This rule was added in v0.15.4.

## References

---

---
url: /docs/guide/usage/linter/rules/jsx_a11y/no-redundant-roles.md
---

### What it does

Enforces that code does not include a redundant `role` property, in the
case that it's identical to the implicit `role` property of the
element type.

### Why is this bad?

Redundant roles can lead to confusion and verbosity in the codebase.

### Examples

This rule applies for the following elements and their implicit roles:

* `<button>`: `button`

Examples of **incorrect** code for this rule:

```jsx
<button role="button"></button>
```

Examples of **correct** code for this rule:

```jsx
<button></button>
```

### Options

This rule takes an object whose keys are element names and whose values
are arrays of redundant roles to allow on that element. Providing an
entry overrides the default exceptions for that element.

By default `role="navigation"` is allowed on `<nav>`. Additional roles
can be allowed, for example to keep explicit list semantics that some
browsers drop when `list-style: none` is applied:

```json
{
  "jsx-a11y/no-redundant-roles": ["error", { "ul": ["list"], "ol": ["list"], "li": ["listitem"] }]
}
```

## Configuration

This rule accepts a configuration object with the following properties:

type: `Record<string, array>`

## How to use

## Version

This rule was added in v0.2.1.

## References

---

---
url: /docs/guide/usage/linter/rules/jsx_a11y/no-static-element-interactions.md
---

### What it does

Enforces that static HTML elements with event handlers must have appropriate ARIA roles.

### Why is this bad?

Static HTML elements do not have semantic meaning in accessibility contexts.
When these elements receive click or keyboard event handlers, they must declare a role
to indicate their interactive purpose to assistive technologies.

### Examples

Examples of **incorrect** code for this rule:

```jsx
<div onClick={() => {}} />
<span onKeyDown={handleKeyDown} />
```

Examples of **correct** code for this rule:

```jsx
<button onClick={() => {}} />
<div onClick={() => {}} role="button" />
<input type="text" onClick={() => {}} />
```

## Configuration

This rule accepts a configuration object with the following properties:

### allowExpressionValues

type: `boolean`

default: `false`

If `true`, role attribute values that are JSX expressions (e.g., `role={ROLE}`) are allowed.
If `false`, only string literal role values are permitted.

### handlers

type: `string[]`

default: `null`

An array of event handler names that should trigger this rule (e.g., `onClick`, `onKeyDown`).

## How to use

## Version

This rule was added in v1.37.0.

## References

---

---
url: /docs/guide/usage/linter/rules/jsx_a11y/prefer-tag-over-role.md
---

### What it does

Enforces using semantic HTML tags over `role` attribute.

### Why is this bad?

Using semantic HTML tags can improve accessibility and readability of the code.

### Examples

Examples of **incorrect** code for this rule:

```jsx
<div role="button" />
```

Examples of **correct** code for this rule:

```jsx
<button />
```

## How to use

## Version

This rule was added in v0.1.1.

## References

---

---
url: /docs/guide/usage/linter/rules/jsx_a11y/role-has-required-aria-props.md
---

### What it does

Enforces that elements with ARIA roles must have all required attributes
for that role.

### Why is this bad?

Certain ARIA roles require specific attributes to express necessary
semantics for assistive technology.

### Examples

Examples of **incorrect** code for this rule:

```jsx
<div role="checkbox" />
```

Examples of **correct** code for this rule:

```jsx
<div role="checkbox" aria-checked="false" />
```

## How to use

## Version

This rule was added in v0.2.0.

## References

---

---
url: /docs/guide/usage/linter/rules/jsx_a11y/role-supports-aria-props.md
---

### What it does

Enforce that elements with explicit or implicit roles defined contain only `aria-*` properties supported by that `role`.
Many ARIA attributes (states and properties) can only be used on elements with particular roles.
Some elements have implicit roles, such as `<a href="#" />`, which will resolve to `role="link"`.

### Why is this bad?

Using ARIA attributes that are inconsistent with the element's role can cause problems for assistive
technologies and their ability to understand or engage with the content of a page.

### Examples

Examples of **incorrect** code for this rule:

```jsx
<ul role="radiogroup" aria-labelledby="foo">
  <li aria-required tabIndex="-1" role="radio" aria-checked="false">
    Rainbow Trout
  </li>
  <li aria-required tabIndex="-1" role="radio" aria-checked="false">
    Brook Trout
  </li>
  <li aria-required tabIndex="0" role="radio" aria-checked="true">
    Lake Trout
  </li>
</ul>
```

Examples of **correct** code for this rule:

```jsx
<ul role="radiogroup" aria-required aria-labelledby="foo">
  <li tabIndex="-1" role="radio" aria-checked="false">
    Rainbow Trout
  </li>
  <li tabIndex="-1" role="radio" aria-checked="false">
    Brook Trout
  </li>
  <li tabIndex="0" role="radio" aria-checked="true">
    Lake Trout
  </li>
</ul>
```

## How to use

## Version

This rule was added in v0.2.0.

## References

---

---
url: /docs/guide/usage/linter/rules/jsx_a11y/scope.md
---

### What it does

The scope prop should be used only on `<th>` elements.

### Why is this bad?

The scope attribute makes table navigation much easier for screen reader users, provided that it is used correctly.
Incorrectly used, scope can make table navigation much harder and less efficient.
A screen reader operates under the assumption that a table has a header and that this header specifies a scope. Because of the way screen readers function, having an accurate header makes viewing a table far more accessible and more efficient for people who use the device.

### Examples

Examples of **incorrect** code for this rule:

```jsx
<div scope />
```

Examples of **correct** code for this rule:

```jsx
<th scope="col" />
<th scope={scope} />
```

## How to use

## Version

This rule was added in v0.0.19.

## References

---

---
url: /docs/guide/usage/linter/rules/jsx_a11y/tabindex-no-positive.md
---

### What it does

Enforces that positive values for the `tabIndex` attribute are not used
in JSX.

### Why is this bad?

Using `tabIndex` values greater than `0` can make navigation and
interaction difficult for keyboard and assistive technology users,
disrupting the logical order of content.

### Examples

Examples of **incorrect** code for this rule:

```jsx
<span tabIndex="1">foo</span>
```

Examples of **correct** code for this rule:

```jsx
<span tabIndex="0">foo</span>
<span tabIndex="-1">bar</span>
```

## How to use

## Version

This rule was added in v0.0.21.

## References

---

---
url: /docs/contribute/language_server.md
---

This page tells you the main concept of the `oxc_language_server` and what the differences to the CLI are.
If you want to learn more about the communication between the language server and the editor, the official [LSP/LSIF documentation](https://microsoft.github.io/language-server-protocol/) is a great start.
The [`README.md`](https://github.com/oxc-project/oxc/blob/main/crates/oxc_language_server/README.md) of the language server has a quick overview of the relevant specs.

Note: In this document we will talk a lot about "tools", this is an abstract concept of the core logic for `oxlint` and `oxfmt`.

## `oxc_language_server` concept of implementing tools

`oxc_language_server` can be used to upgrade your own script with the capability to work as a language server.
The server on its own does not change your files or create suggestions. This is the responsibility of the tool.
Instead, it manages the workspace folders and all the communication for loading the right configuration.
To communicate with the provided tools, the server provides a [`ToolBuilder` and `Tool` trait](https://github.com/oxc-project/oxc/blob/main/crates/oxc_language_server/src/tool.rs).

## Difference between Language Server and CLI

### Editors changes the file, server communicates the changes

A small but important part about the communication of a file and the fix of it.
The CLI Tools are writing the changes to the file system.
The (oxc) language server should NEVER write to it, instead it just communicates it changes to the editor.

### Workspace Folders

You know when you open a git project in the editor? That is a workspace folder. The LSP has the concept of opening multiple (git) projects at the same time.
Each of the projects can have its own configuration (see next part), but the most important part is the own "context" with a workspace URI.
You can think of a workspace URI as the same as a "current working directory" for the CLI tool.
Keep in mind that a workspace folder can be added / removed by the editor.

### Configurations (with folders)

The language server can (like the CLI flags) be configured, the oxc language server follows the concept:
Each workspace folder can have its own configuration. As an example: git project A uses type aware linting, git project B uses dangerous fixes on auto save.

### Changing Configuration

Surprise! The user can change the language server configuration on the fly. The editor will send us the updated configuration.
Currently, the server will send each tool the old and new configuration, so it can handle all kinds of stuff.
Depending on the configuration the tool can restart/rebuild itself.

### Watch Patterns & Changing watched files

Your tool can tell the editor to watch for specific file (glob) patterns and notify the server, when the file is changed/created/deleted.
This is mostly used for the `.ox**rc.json` configuration and the referenced files inside of it (example `extends` from `oxlint`).
Depending on the configuration of the workspace and the tool, the tool may need to restart/rebuild itself again.

---

---
url: /docs/guide/usage/formatter/language-support.md
---

# Language support

Oxfmt formats a wide range of file types. Most are handled by Oxfmt's own **native** engine, written in Rust. The rest are delegated to a **bundled Prettier** for languages Oxfmt has not yet reimplemented natively. We are actively porting every language to Rust for maximum performance, so the Prettier-backed list keeps shrinking as native support lands.

:::info
Native formats run entirely in Rust with no Node.js round-trip, so they are the fastest. Prettier-backed formats ship inside the `oxfmt` package and need no extra setup. Except `.svelte`, which additionally requires the `svelte` package to be installed and the [`svelte`](./config-file-reference) option to be enabled.
:::

## Native

Formatted directly by Oxfmt, with no Prettier dependency:

| Language             | Extensions                                    |
| -------------------- | --------------------------------------------- |
| JavaScript / JSX     | `.js`, `.jsx`, `.mjs`, `.cjs`, and more       |
| TypeScript / TSX     | `.ts`, `.tsx`, `.mts`, `.cts`, `.d.ts`        |
| JSON / JSONC / JSON5 | `.json`, `.jsonc`, `.json5`                   |
| CSS / SCSS / Less    | `.css`, `.scss`, `.less`, `.pcss`, `.postcss` |
| GraphQL              | `.graphql`, `.gql`, `.graphqls`               |
| TOML                 | `.toml`                                       |
| YAML                 | `.yml`, `.yaml`                               |

Detection also covers many well-known config files by name. For example `.babelrc` and `.swcrc` are treated as JSON.

## Prettier-backed

Delegated to the bundled Prettier. No separate `prettier` install is required.

:::warning
These formats require Node.js and are only available with the `oxfmt` npm package. The standalone binary from GitHub Releases skips these files. See [Quickstart](./quickstart#install) for details.
:::

:::tip
These are being actively ported to Rust. As each native formatter lands, its language moves to the [Native](#native) list above for maximum performance. No change needed on your side.
:::

| Language   | Extensions                |
| ---------- | ------------------------- |
| HTML       | `.html`, `.htm`, `.xhtml` |
| Angular    | `*.component.html`        |
| Vue        | `.vue`                    |
| Svelte     | `.svelte`                 |
| Markdown   | `.md`, `.markdown`        |
| MDX        | `.mdx`                    |
| Handlebars | `.hbs`, `.handlebars`     |
| MJML       | `.mjml`                   |

## Embedded languages

Oxfmt also formats code embedded inside JS/TS template literals. The same split as above applies: languages in the [Native](#native) list are formatted natively, while those in the [Prettier-backed](#prettier-backed) list go through Prettier. See [Embedded Formatting](./embedded-formatting) for details and examples.

For Vue and Svelte files, embedded JS/TS (such as `<script>` blocks) is formatted by native formatter rather than Prettier. Embedded JS/TS in the other Prettier-backed formats (such as `<script>` tags in HTML) is still formatted by Prettier.

## See also

* [Compatibility matrix](/compatibility) — framework- and file-type-level support at a glance
* [Unsupported features](./unsupported-features)

---

---
url: /docs/learn/parser_in_rust/lexer.md
---

# Lexer

## Token

The lexer, also known as tokenizer or scanner, is responsible for transforming source text into tokens.
The tokens will later be consumed by the parser so we don't have to worry about whitespaces and comments from the original text.

Let's start simple and transform a single `+` text into a token.

```rust
#[derive(Debug, Clone, Copy, PartialEq)]
pub struct Token {
    /// Token Type
    pub kind: Kind,

    /// Start offset in source
    pub start: usize,

    /// End offset in source
    pub end: usize,
}

#[derive(Debug, Clone, Copy, PartialEq)]
pub enum Kind {
    Eof, // end of file
    Plus,
}
```

A single `+` gives us

```
[
    Token { kind: Kind::Plus, start: 0, end: 1 },
    Token { kind: Kind::Eof,  start: 1, end: 1 }
]
```

To loop through the string, we can either keep track of an index and pretend that we are writing C code,
or we can take a look at the [string documentation](https://doc.rust-lang.org/std/primitive.str.html#)
and find ourselves a [`Chars`](https://doc.rust-lang.org/std/str/struct.Chars.html) iterator to work with.

:::info
The `Chars` iterator abstracts away the tracking index and boundary checking to make us feel truly safe.

It gives us an `Option<char>` when we call `chars.next()`.
But please note that a `char` is not a 0-255 ASCII value,
it is a utf8 Unicode point value with the range of 0 to 0x10FFFF.
:::

Let's define a starter lexer abstraction

```rust
use std::str::Chars;

struct Lexer<'a> {
    /// Source Text
    source: &'a str,

    /// The remaining characters
    chars: Chars<'a>
}

impl<'a> Lexer<'a> {
    pub fn new(source: &'a str) -> Self {
        Self {
            source,
            chars: source.chars()
        }
    }
}
```

:::info
The lifetime `'a` here indicates the iterator has a reference to somewhere, it references to a `&'a str` in this case.
:::

To convert the source text to tokens, just keep calling `chars.next()` and match on the returned `char`s.
The final token will always be `Kind::Eof`.

```rust
impl<'a> Lexer<'a> {
    fn read_next_kind(&mut self) -> Kind {
        while let Some(c) = self.chars.next() {
            match c {
              '+' => return Kind::Plus,
              _ => {}
            }
        }
        Kind::Eof
    }

    fn read_next_token(&mut self) -> Token {
        let start = self.offset();
        let kind = self.read_next_kind();
        let end = self.offset();
        Token { kind, start, end }
    }

    /// Get the length offset from the source text, in UTF-8 bytes
    fn offset(&self) -> usize {
        self.source.len() - self.chars.as_str().len()
    }
}
```

The `.len()` and `.as_str().len()` method calls inside `fn offset` feel like O(n), so let's dig deeper.

[`.as_str()`](https://doc.rust-lang.org/src/core/str/iter.rs.html#112) returns a pointer to a string slice

```rust
// https://github.com/rust-lang/rust/blob/b998821e4c51c44a9ebee395c91323c374236bbb/library/core/src/str/iter.rs#L112-L115

pub fn as_str(&self) -> &'a str {
    // SAFETY: `Chars` is only made from a str, which guarantees the iter is valid UTF-8.
    unsafe { from_utf8_unchecked(self.iter.as_slice()) }
}
```

A [slice](https://doc.rust-lang.org/std/slice/index.html) is a view into a block of memory represented as a pointer and a length.
The `.len()` method returns the metadata stored inside the slice

```rust
// https://github.com/rust-lang/rust/blob/b998821e4c51c44a9ebee395c91323c374236bbb/library/core/src/str/mod.rs#L157-L159

pub const fn len(&self) -> usize {
    self.as_bytes().len()
}
```

```rust
// https://github.com/rust-lang/rust/blob/b998821e4c51c44a9ebee395c91323c374236bbb/library/core/src/str/mod.rs#L323-L325

pub const fn as_bytes(&self) -> &[u8] {
    // SAFETY: const sound because we transmute two types with the same layout
    unsafe { mem::transmute(self) }
}
```

```rust
// https://github.com/rust-lang/rust/blob/b998821e4c51c44a9ebee395c91323c374236bbb/library/core/src/slice/mod.rs#L129-L138

pub const fn len(&self) -> usize {
    // FIXME: Replace with `crate::ptr::metadata(self)` when that is const-stable.
    // As of this writing this causes a "Const-stable functions can only call other
    // const-stable functions" error.

    // SAFETY: Accessing the value from the `PtrRepr` union is safe since *const T
    // and PtrComponents<T> have the same memory layouts. Only std can make this
    // guarantee.
    unsafe { crate::ptr::PtrRepr { const_ptr: self }.components.metadata }
}
```

All the above code will get compiled into a single data access, so `.as_str().len()` is actually O(1).

## Peek

To tokenize multi-character operators such as `++` or `+=`, a helper function `peek` is required:

```rust
fn peek(&self) -> Option<char> {
    self.chars.clone().next()
}
```

We don't want to advance the original `chars` iterator so we clone the iterator and advance the index.

:::info
The `clone` is cheap if we dig into the [source code](https://doc.rust-lang.org/src/core/slice/iter.rs.html#148-152),
it just copies the tracking and boundary index.

```rust
// https://github.com/rust-lang/rust/blob/b998821e4c51c44a9ebee395c91323c374236bbb/library/core/src/slice/iter.rs#L148-L152

impl<T> Clone for Iter<'_, T> {
    fn clone(&self) -> Self {
        Iter { ptr: self.ptr, end: self.end, _marker: self._marker }
    }
}
```

:::

The difference between `peek` and `chars.next()` is the former will always return the **same** next `char`,
while the later will move forward and return a different `char`.

To demonstrate, consider the string `abc`:

* repeated `peek()` call returns `Some(a)`, `Some(a)`, `Some(a)`, ...
* repeated `chars.next()` call returns `Some('a')`, `Some('b')`, `Some('c')`, `None`.

Equipped with `peek`, tokenizing `++` and `+=` are just nested if statements.

Here is a real-world implementation from [jsparagus](https://github.com/mozilla-spidermonkey/jsparagus):

```rust
// https://github.com/mozilla-spidermonkey/jsparagus/blob/master/crates/parser/src/lexer.rs#L1769-L1791

'+' => match self.peek() {
    Some('+') => {
        self.chars.next();
        return self.set_result(
            TerminalId::Increment,
            SourceLocation::new(start, self.offset()),
            TokenValue::None,
        );
    }
    Some('=') => {
        self.chars.next();
        return self.set_result(
            TerminalId::AddAssign,
            SourceLocation::new(start, self.offset()),
            TokenValue::None,
        );
    }
    _ => return self.set_result(
        TerminalId::Plus,
        SourceLocation::new(start, self.offset()),
        TokenValue::None,
    ),
},
```

The above logic applies to all operators, so let us expand our knowledge on lexing JavaScript.

## JavaScript

A lexer written in Rust is rather boring, it feels like writing C code
where we write long chained if statements and check for each `char` and then return the respective token.

The real fun begins when we start lexing for JavaScript.

Let's open up the [ECMAScript Language Specification](https://tc39.es/ecma262/) and re-learn JavaScript.

:::tip
I still remember the first time I opened up the specification and went into a little corner
and cried in agony because it feels like reading foreign text with jargons everywhere.
So head over to my [guide on reading the specification](/docs/learn/ecmascript/spec.html) if things don't make sense.
:::

### Comments

Comments have no semantic meaning, they can be skipped if we are writing a runtime,
but they need to be taken into consideration if we are writing a linter or a bundler.

### Identifiers and Unicode

We mostly code in ASCII,
but [Chapter 11 ECMAScript Language: Source Text](https://tc39.es/ecma262/#sec-ecmascript-language-source-code)
states the source text should be in Unicode.
And [Chapter 12.6 Names and Keywords](https://tc39.es/ecma262/#sec-names-and-keywords)
states the identifiers are interpreted according to the Default Identifier Syntax given in Unicode Standard Annex #31.
In detail:

```
IdentifierStartChar ::
    UnicodeIDStart

IdentifierPartChar ::
    UnicodeIDContinue

UnicodeIDStart ::
    any Unicode code point with the Unicode property “ID_Start”

UnicodeIDContinue ::
    any Unicode code point with the Unicode property “ID_Continue”
```

This means that we can write `var ಠ_ಠ` but not `var 🦀`,
`ಠ` has the Unicode property "ID\_Start" while `🦀` does not.

:::info

I published the [unicode-id-start](https://crates.io/crates/unicode-id-start) crate for this exact purpose.
`unicode_id_start::is_id_start(char)` and `unicode_id_start::is_id_continue(char)` can be called to check Unicode.

:::

### Keywords

All the [keywords](https://tc39.es/ecma262/#sec-keywords-and-reserved-words) such as `if`, `while` and `for`
need to be tokenized and interpreted as a whole.
They need to be added to the token kind enum so we don't have to make string comparisons in the parser.

```rust
pub enum Kind {
    Identifier,
    If,
    While,
    For
}
```

:::tip
`undefined` is not a keyword, it is unnecessary to add it here.
:::

Tokenizing keywords will just be matching the identifier from above.

```rust
fn match_keyword(&self, ident: &str) -> Kind {
    // all keywords are 1 < length <= 10
    if ident.len() == 1 || ident.len() > 10 {
        return Kind::Identifier;
    }
    match ident {
        "if" => Kind::If,
        "while" => Kind::While,
        "for" => Kind::For,
        _ => Kind::Identifier
    }
}
```

### Token Value

We often need to compare identifiers, numbers and strings in later stages of the compiler phases,
for example testing against identifiers inside a linter.

These values are currently in plain source text,
let's convert them to Rust types so they are easier to work with.

```rust{4-6}
pub enum Kind {
    Eof, // end of file
    Plus,
    Identifier,
    Number,
    String,
}

#[derive(Debug, Clone, Copy, PartialEq)]
pub struct Token {
    /// Token Type
    pub kind: Kind,

    /// Start offset in source
    pub start: usize,

    /// End offset in source
    pub end: usize,

    pub value: TokenValue,// [!code highlight]
}

#[derive(Debug, Clone, PartialEq)]
pub enum TokenValue {
    None,
    Number(f64),
    String(String),
}
```

When an identifier `foo` or string `"bar"` is tokenized , we get

```
Token { kind: Kind::Identifier, start: 0, end: 2, value: TokenValue::String("foo") }
Token { kind: Kind::String, start: 0, end: 4, value: TokenValue::String("bar") }
```

To convert them to Rust strings, call `let s = self.source[token.start..token.end].to_string()`
and save it with `token.value = TokenValue::String(s)`.

When we tokenize a number `1.23`, we get a token with `Token { start: 0, end: 3 }`.
To convert it to Rust `f64`, we can use the string [`parse`](https://doc.rust-lang.org/std/primitive.str.html#method.parse)
method by calling `self.source[token.start..token.end].parse::<f64>()`, and then save the value into `token.value`.
For binary, octal and integers, an example of their parsing techniques can be found in [jsparagus](https://github.com/mozilla-spidermonkey/jsparagus/blob/master/crates/parser/src/numeric_value.rs).

## Rust Optimizations

### Smaller Tokens

It is tempting to put the token values inside the `Kind` enum and aim for simpler and safer code:

```rust
pub enum Kind {
    Number(f64),
    String(String),
}
```

But it is known that the byte size of a Rust enum is the union of all its variants.
This enum packs a lot of bytes compared to the original enum, which has only 1 byte.
There will be heavy usages of this `Kind` enum in the parser,
dealing with a 1 byte enum will obviously be faster than a multi-byte enum.

### String Interning

It is not performant to use `String` in compilers, mainly due to:

* `String` is a heap allocated object
* String comparison is an O(n) operation

[String Interning](https://en.wikipedia.org/wiki/String_interning) solves these problems by
storing only one copy of each distinct string value with a unique identifier in a cache.
There will only be one heap allocation per distinct identifier or string, and string comparisons become O(1).

There are lots of string interning libraries on [crates.io](https://crates.io/search?q=string%20interning)
with different pros and cons.

A sufficient starting point is to use [`string-cache`](https://crates.io/crates/string_cache),
it has an `Atom` type and a compile time `atom!("string")` interface.

With `string-cache`, `TokenValue` becomes

```rust
#[derive(Debug, Clone, PartialEq)]
pub enum TokenValue {
    None,
    Number(f64),
    String(Atom), // [!code highlight]
}
```

and string comparison becomes `matches!(value, TokenValue::String(atom!("string")))`.

---

---
url: /docs/contribute/linter.md
---

# Linter

## Contributing New Rules

See the [adding rules](./linter/adding-rules.md) guide for how to add new rules to Oxlint.

## Development

Create a `./test.ts` and then

```bash
just watch "cargo run --bin oxlint -- test.ts"
```

Or test and filter against the rule:

```bash
just watch "cargo test -p oxc_linter -- rule-name"
```

### Testing oxlint against a full codebase

To test oxlint on a full codebase, for example to test your changes with a large JavaScript/TypeScript project, you can build the `oxlint` CLI and run it against that codebase.

```bash
# build the oxlint cli in the oxc repo
just oxlint-node
# and then in the directory of the codebase you want to test with, run oxlint with node:
node <path-to-oxc-repo>/apps/oxlint/dist/cli.js
# You can also pass flags to it, like -D to enable a specific rule, and --disable-x-plugin to turn off default plugins:
node <path-to-oxc-repo>/apps/oxlint/dist/cli.js -D rulename --disable-unicorn-plugin --disable-oxc-plugin --disable-typescript-plugin
```

### Snapshot Testing

[`cargo insta`](https://insta.rs/docs) is used for snapshot testing.

After running `cargo test -p oxc_linter` and the line `Tester::new(RULE::NAME, pass, fail).test_and_snapshot()` is called, a new `rule.snap.new` file will be generated.

Use `cargo insta accept` to accept all snapshot changes.

## Rule Category

* **correctness** - code that is outright wrong or useless
* **suspicious** - code that is most likely wrong or useless
* **pedantic** - lints which are rather strict or have occasional false positives
* **perf** - code that can be written to run faster
* **style** - code that should be written in a more idiomatic way
* **restriction** - lints should be considered on a case-by-case basis before enabling.
* **nursery** - new lints that are still under development

---

---
url: /docs/learn/architecture/linter.md
---

# Linter Architecture

This article is originally posted on [leaysgur.github.io/posts](https://leaysgur.github.io/posts/2024/01/15/160838) by [@leaysgur](https://github.com/leaysgur).

## apps/oxlint

The `oxlint` binary is the result of building `main.rs` from the `apps/oxlint` crate.

> [Cargo.toml Configuration](https://github.com/oxc-project/oxc/blob/main/apps/oxlint/Cargo.toml)

Here, it parses arguments and then runs the `LintRunner`.

> [Lint Execution Flow](https://github.com/oxc-project/oxc/blob/oxlint_v0.2.0/crates/oxc_cli/src/lint/main.rs#L17-L19)

## crates/oxc\_diagnostics

The `LintService` passes the `mpsc::channel` Sender to `oxc_diagnostics` to receive lint results.

> [Receiving Lint Results](https://github.com/oxc-project/oxc/blob/oxlint_v0.2.0/crates/oxc_diagnostics/src/service.rs#L96)

It formats and displays the received messages. The formatting is done by the `miette` crate.

> [miette Crate Reference](https://github.com/zkat/miette)

## crates/oxc\_linter

Starting with the `LintService`:

* Holds `self.runtime` as `Arc<Runtime>`
* `Runtime` holds paths for linting
* Upon running, it iterates over `Runtime` paths in parallel using `rayon`
* It sends a `None` to finish

> [LintService Implementation](https://github.com/oxc-project/oxc/blob/oxlint_v0.2.0/crates/oxc_linter/src/service.rs#L51)

### `Runtime`: `process_path()`

* Infers extension and content from the path
* Supports `.[m|c]?[j|t]s` or `.[j|t]sx` extensions
* Exceptions for `.vue`, `.astro`, and `.svelte` with partial support for `script` blocks
* Processes JavaScript and TypeScript sources
* Executes linting and sends results to `DiagnosticService`

> [Runtime Path Processing](https://github.com/oxc-project/oxc/blob/oxlint_v0.2.0/crates/oxc_linter/src/service.rs#L162)

### `Runtime`: `process_source()`

* Processes the source with a parser into an AST
* Creates a `LintContext` from `SemanticBuilder` and runs it through `Linter`

> [Runtime Source Processing](https://github.com/oxc-project/oxc/blob/oxlint_v0.2.0/crates/oxc_linter/src/service.rs#L206)

## crates/oxc\_semantic: `SemanticBuilder`

`SemanticBuilder` builds semantic information extracted from the source.

> [SemanticBuilder Source](https://github.com/oxc-project/oxc/blob/oxlint_v0.2.0/crates/oxc_semantic/src/builder.rs#L156)

* `source_text`: Source code
* `nodes`: AST nodes
* `classes`: Classes
* `scopes`: Scopes
* `trivias`: Comments
* `jsdoc`: JSDoc
* etc.

When `SemanticBuilder` builds, it generates `SemanticBuilderReturn`, but only `Semantic` is passed to `LintContext`.

> [SemanticBuilder Return](https://github.com/oxc-project/oxc/blob/oxlint_v0.2.0/crates/oxc_semantic/src/lib.rs#L34)

## crates/oxc\_linter: `LintContext`

> [LintContext Source](https://github.com/oxc-project/oxc/blob/oxlint_v0.2.0/crates/oxc_linter/src/context.rs#L14)

Represents the context, with `Semantic` as the main body. It includes getters for each piece of information and methods like `diagnostic()` to notify of linting issues.

## crates/oxc\_linter: `Linter`

> [Linter Source](https://github.com/oxc-project/oxc/blob/oxlint_v0.2.0/crates/oxc_linter/src/lib.rs#L140)

The `run()` function of this `Linter` is the core of the linting process.

* `Linter` holds rules to execute on the target source in `self.rules`
* Each rule can implement three types of processing as per the trait
* It sequentially executes these three patterns

For the currently implemented rules, refer to this list.

> [Implemented Rules](https://github.com/oxc-project/oxc/blob/oxlint_v0.2.0/crates/oxc_linter/src/rules.rs)

For adding new rules, remember to update this list.

## Linter Example

The repository provides the minimum code configuration for creating a linter.

> [Minimal Linter Code](https://github.com/oxc-project/oxc/blob/main/crates/oxc_linter/examples/linter.rs)

---

---
url: /docs/guide/usage/linter/lsp-config-reference.md
---

# LSP Options

::: info
This document describe the native LSP options for `oxlint`. Depending on your editor, you may have different options.
See [Editor setup](/docs/guide/usage/linter/editors.md) to configure your editor options.
:::

These options can be defined for each workspace folder separately.
File references in the options (e.g. `configPath`, `tsConfigPath`) are resolved relative to the workspace folder.

They can be sent by the client in `initialize` or `workspace/didChangeConfiguration` requests.
If the client supports `workspace/configuration`, the server will request the options from the client.

Example of `initialize` request:

```json
{
  "processId": 123,
  "rootUri": null,
  "workspaceFolders": [],
  "capabilities": {},
  "initializationOptions": [
    {
      "workspaceUri": "file:///home/user/project",
      "options": {
        "unusedDisableDirectives": "deny",
        "typeAware": true
      }
    }
  ]
}
```

Example of `workspace/didChangeConfiguration` request:

```json
{
  "settings": [
    {
      "workspaceUri": "file:///home/user/project",
      "options": {
        "unusedDisableDirectives": "deny",
        "disableNestedConfig": true
      }
    }
  ]
}
```

## configPath

type: `string`

Path to the config file. Similar to `--config` CLI option.
If set, it disables searching for config files.

## disableNestedConfig

type: `boolean`

Whether to disable nested config support. Similar to `--disable-nested-config` CLI option.
It gets automatically enabled when `configPath` is set.

## fixKind

type: `"safe_fix" | "safe_fix_or_suggestion" | "dangerous_fix" | "dangerous_fix_or_suggestion" | "none" | "all"`

What kind of fixes to generate for code actions.

## rulesCustomization

type: `Record<string, object>`

Customization for individual rules, allows to override the linter's diagnostics and autofix.
Example of lowering the severity of "no-unused-vars" rule to "hint" and disabling autofix for it:

```json
{
  "rulesCustomization": {
    "no-unused-vars": {
      "severity": "hint",
      "autofix": false
    }
  }
}
```

## run

type: `"onSave" | "onType"`

If your editor does not support `textDocument/diagnostic`,
this option handles when diagnostics are sent to the client.

## tsConfigPath

type: `string`

Path to the tsconfig file. Similar to `--tsconfig` CLI option.
If set, it disables auto discovery for tsconfig files.

## typeAware

type: `boolean`

Whether to enable/disable type-aware linting.
It will override the root config's `typeAware` option if set.

## unusedDisableDirectives

type: `"allow" | "warn" | "deny"`

How to handle unused disable directives. By default, they are allowed and ignored.

---

---
url: /docs/guide/usage/minifier/mangling.md
---
# Mangling

Oxc minifier supports mangling variable names and private class fields.

This feature is enabled by default and can be disabled by setting the `mangle` option to `false`.

## Top Level Variables

Top level variables are not mangled by default for non module code. You can enable mangling for top level variables by setting the `mangle.toplevel` option to `true`.

```js
// input
var foo = 1;

// output
var e = 1;
```

```js
// Example
import { minify } from "oxc-minify";

const result = await minify("lib.js", code, {
  module: false, // non-module code
  compress: {
    mangle: {
      toplevel: true,
    },
  },
});
```

## Keep `name` Property Values

Mangling variable names can change the `name` property values of functions / classes. You can keep the original `name` property values by enabling the `mangle.keepNames` option.

```js
// input
var foo = function () {};

// output
var foo = function () {};
```

```js
// Example
import { minify } from "oxc-minify";

const result = await minify("lib.js", code, {
  compress: {
    mangle: {
      keepNames: true, // shorthand of { function: true, class: true }
    },
  },
});
```

::: tip `compress.keepNames` option

When enabling this option, you may also want to enable [the `compress.keepNames` option](./dead-code-elimination#keep-name-property-values).

:::

## Debugging The Mangler

To debug the mangler, you can enable the `mangle.debug` option. When this option is enabled, the mangler will use `slot_0`, `slot_1`, ... as variable names.

```js
// input
var foo = 1;

// output
var slot_0 = 1;
```

```js
// Example
import { minify } from "oxc-minify";

const result = await minify("lib.js", code, {
  compress: {
    mangle: {
      debug: true,
    },
  },
});
```

---

---
url: /docs/guide/usage/linter/migrate-from-eslint.md
---

# Migrate from ESLint

This guide is for existing JavaScript and TypeScript projects that currently use ESLint and want to migrate to Oxlint.

## When to migrate from ESLint

Migrate to Oxlint if you want a dedicated linter with better speed, simpler adoption, and strong compatibility with modern ESLint workflows. Choose [Vite+](https://npmx.dev/package/vite-plus) instead if you want Oxlint as part of a larger unified toolchain.

* Move to Oxlint for dedicated linting.
* Move to [Vite+](https://npmx.dev/package/vite-plus) for an integrated workflow.
* Stay on ESLint if a specific missing behavior still blocks migration.

## Overview

Oxlint and ESLint share similar configuration concepts, but they differ in supported rules and config formats.

Oxlint already supports more than 800 rules from ESLint core and various popular plugins. We intend to support nearly all existing ESLint core rules, and this work is ongoing. Check the [compatibility matrix](/compatibility) to verify support for your frameworks and file types.

When migrating, expect the following:

* Most ESLint core rules and popular plugin rules are supported
* Some rules may not yet be available
* ESLint configuration files must be converted to Oxlint’s config format
* Oxlint is designed for incremental adoption; a full migration is not required upfront
* Oxlint's JS Plugins allow usage of ESLint plugins that are not implemented natively by Oxlint

## Migrate with Skills

The [`migrate-oxlint`](https://skills.sh/oxc-project/oxc/migrate-oxlint) skill provides an interactive, agent-guided migration. Install it into your coding agent:

```bash
npx skills add https://github.com/oxc-project/oxc --skill migrate-oxlint
```

Once installed, run `/migrate-oxlint` to perform the migration.

## Migrating from an ESLint flat config

If your project uses an ESLint v9/v10 flat config (e.g. `eslint.config.js` or `eslint.config.mjs`), you can migrate automatically using [`@oxlint/migrate`](https://npmx.dev/package/@oxlint/migrate).

### Run the migration tool

From the project root:

```bash
npx @oxlint/migrate <optional-eslint-flat-config-path>
```

This command:

* Reads your ESLint flat config file
* Converts supported rules to an Oxlint config
* Preserves rule severities and options
* Preserves file and path-specific overrides to allow different rulesets for different parts of a repo
* Converts `globals` (e.g. `...globals.browser`) to equivalent `env` and `globals` values
* Preserves root `ignore` patterns for ignoring specific paths/files

The generated `.oxlintrc.json` config can be edited manually after migration.

`.eslintignore` files will be respected by Oxlint and can be left in place during migration, but we recommend moving the contents to the `"ignorePatterns"` field in `.oxlintrc.json` after migrating. Files/paths ignored via a repo's `.gitignore` file will also be respected by Oxlint automatically.

See the list of [available options](https://github.com/oxc-project/oxlint-migrate?tab=readme-ov-file#options) for more details.

### Type-Aware TypeScript rules

If your ESLint setup uses `typescript-eslint` with type-aware rules, you can pass the `--type-aware` flag:

```bash
npx @oxlint/migrate --type-aware
```

This ensures the generated Oxlint config includes type-aware rules.

Note that type-aware linting requires [oxlint-tsgolint](https://github.com/oxc-project/tsgolint), and is based on the TypeScript native rewrite (aka TypeScript 7), but should be possible to adopt in most TypeScript projects without too much upgrade work.

For further information on Oxlint's type-aware support, see [the Type-Aware Linting page](/docs/guide/usage/linter/type-aware).

### JavaScript plugins

If your ESLint config uses plugins that are not supported natively by Oxlint, you can retain them using JavaScript plugins. `@oxlint/migrate` will migrate these plugins for you by default.

This allows you to continue using those rules via Oxlint alongside the native rules/plugins. The JS Plugins functionality does not support all ESLint plugins, but Oxlint's JavaScript plugin system covers a vast majority of the ESLint v9 API and is actively being improved. Most ESLint plugins covering JavaScript/TypeScript code should work in Oxlint without problems.

If you do not want to migrate your ESLint plugins to use as JS Plugins, you can pass `--js-plugins=false`.

For more information on JavaScript Plugins, see [the JS Plugins page](/docs/guide/usage/linter/js-plugins).

#### Local custom ESLint plugins

If you use local custom ESLint plugins from within your own repo (e.g. `import pluginMyCompany from './eslint-plugin-my-company/lib/index.js'`), these will not be migrated automatically by `@oxlint/migrate` right now.

However, they can be added manually to the Oxlint config file after running the migration script:

::: code-group

```json [.oxlintrc.json]
{
  "$schema": "./node_modules/oxlint/configuration_schema.json",
  "jsPlugins": ["./eslint-plugin-company/lib/index.js"]
}
```

```ts [oxlint.config.ts]
import { defineConfig } from "oxlint";

export default defineConfig({
  jsPlugins: ["./eslint-plugin-company/lib/index.js"],
});
```

:::

## Running Oxlint and ESLint together

If not all required rules are available in Oxlint, you can run Oxlint and ESLint side by side.

A common setup is:

1. Enable Oxlint for all supported rules
2. Keep ESLint for unsupported rules
3. Disable overlapping rules in ESLint

Because Oxlint is significantly faster than ESLint, it is recommended to run Oxlint first to catch errors early, then fall back to ESLint only if needed.

For example:

```bash
oxlint && eslint
```

### Disabling overlapping rules in ESLint

You can use [`eslint-plugin-oxlint`](https://npmx.dev/package/eslint-plugin-oxlint) to disable ESLint rules that are already handled by Oxlint:

```bash
npm install --save-dev eslint-plugin-oxlint
```

This reduces duplicate diagnostics, can help cut down your linting time considerably, and allows ESLint to focus only on rules that Oxlint does not yet support.

Long-term - once remaining important rules have been added in Oxlint - we strongly recommend moving fully to Oxlint to simplify your setup and reduce the number of dependencies for your project.

## Migrating from legacy ESLint (v8.x) configs

If your project uses ESLint v8.x with legacy config files (such as `.eslintrc.js` or `.eslintrc.json`), they cannot be migrated automatically by `@oxlint/migrate`.

In some cases, you can [migrate them automatically to an ESLint flat config with `@eslint/migrate-config`](https://npmx.dev/package/@eslint/migrate-config) first, and *then* to Oxlint using `@oxlint/migrate`.

The "legacy" ESLint v8.x configuration file shape maps closely to Oxlint’s config format, so for simple setups most rules and options can be translated directly.

## Rule/plugin support

You may have specific rules that you rely on in ESLint that are not yet ported to Oxlint.

Almost all rules from our supported plugins will be ported - and a majority already have been. For those that will not be ported, some rules are deprecated in the original plugins, or have alternatives implemented already.

You can check the [meta issue](https://github.com/oxc-project/oxc/issues/481) for rule/plugin implementation status to see if the rules you rely on are planned for implementation, or if they have already been implemented by other, equivalent rules.

For plugins that are not implemented natively in Oxlint, it is recommended to use [JS Plugins](/docs/guide/usage/linter/js-plugins).

---

---
url: /docs/guide/usage/formatter/migrate-from-prettier.md
---

# Migrate from Prettier

This guide covers migrating from Prettier to Oxfmt.

## When to migrate from Prettier

Migrate to Oxfmt if you want to keep a Prettier-like workflow while getting faster formatting and built-in formatting features. Choose [Vite+](https://npmx.dev/package/vite-plus) instead if you want Oxfmt as part of a larger unified toolchain.

* Move to Oxfmt for dedicated formatting.
* Move to [Vite+](https://npmx.dev/package/vite-plus) for an integrated workflow.
* Stay on Prettier if exact plugin behavior is still required.

## Quick start

For simple setups, migrate with a single command:

::: code-group

```bash [npm]
$ npm add -D oxfmt@latest && npx oxfmt --migrate=prettier && npx oxfmt
```

```bash [pnpm]
$ pnpm add -D oxfmt@latest && pnpm oxfmt --migrate=prettier && pnpm oxfmt
```

```bash [yarn]
$ yarn add -D oxfmt@latest && yarn oxfmt --migrate=prettier && yarn oxfmt
```

```bash [bun]
$ bun add -D oxfmt@latest && bunx oxfmt --migrate=prettier && bunx oxfmt
```

:::

## Migrate with Skills

The [`migrate-oxfmt`](https://skills.sh/oxc-project/oxc/migrate-oxfmt) skill provides an interactive, agent-guided migration. Install it into your coding agent:

```bash
npx skills add https://github.com/oxc-project/oxc --skill migrate-oxfmt
```

Once installed, run `/migrate-oxfmt` to perform the migration.

## Before you migrate

Oxfmt is compatible with Prettier v3.8 for many configurations.

Key differences:

* Default `printWidth` is 100 (Prettier uses 80)
* Prettier plugins are not supported (though some popular plugins have been implemented natively)
* Some options are not supported (see [config reference](/docs/guide/usage/formatter/config-file-reference.html))

See [Unsupported features](/docs/guide/usage/formatter/unsupported-features) for details, and the [compatibility matrix](/compatibility) for file type support.

## Step 1: Upgrade Prettier to v3.8 (optional)

Oxfmt's output is closest to Prettier v3.8. Upgrading first minimizes formatting differences.

## Step 2: Install Oxfmt

::: code-group

```bash [npm]
$ npm add -D oxfmt@latest
```

```bash [pnpm]
$ pnpm add -D oxfmt@latest
```

```bash [yarn]
$ yarn add -D oxfmt@latest
```

```bash [bun]
$ bun add -D oxfmt@latest
```

```bash [deno]
$ deno add -D npm:oxfmt@latest
```

:::

## Step 3: Migrate configuration

Oxfmt uses `.oxfmtrc.json`, `.oxfmtrc.jsonc`, `oxfmt.config.ts`, or `oxfmt.config.mts`. Basic example:

```jsonc [.oxfmtrc.jsonc]
{
  "$schema": "./node_modules/oxfmt/configuration_schema.json",
  "printWidth": 80,
}
```

Run `oxfmt --migrate prettier` to convert your Prettier config automatically.

### `prettierrc.js` example

Before:

```js [prettierrc.js]
module.exports = {
  singleQuote: true,
  jsxSingleQuote: true,
};
```

After (`oxfmt.config.ts`):

```ts [oxfmt.config.ts]
import { defineConfig } from "oxfmt";

export default defineConfig({
  singleQuote: true,
  jsxSingleQuote: true,
  printWidth: 80,
});
```

### `prettierrc.yaml` example

Before:

```yaml [prettierrc.yaml]
trailingComma: "es5"
tabWidth: 4
semi: false
singleQuote: true
```

After (`.oxfmtrc.jsonc`):

```jsonc [.oxfmtrc.jsonc]
{
  "$schema": "./node_modules/oxfmt/configuration_schema.json",
  "trailingComma": "es5",
  "tabWidth": 4,
  "semi": false,
  "singleQuote": true,
  "printWidth": 80,
}
```

## Step 4: Update scripts

### `package.json` scripts

```diff
{
  "scripts": {
-   "format": "prettier --write .",
+   "format": "oxfmt",
-   "format:check": "prettier --check ."
+   "format:check": "oxfmt --check"
  }
}
```

### CI workflows

```diff
  - name: Check formatting
-   run: yarn prettier --check .
+   run: yarn oxfmt --check
```

### Git hooks (husky, lint-staged)

In `package.json`:

```diff
"lint-staged": {
- "*": "prettier --write --no-error-on-unmatched-pattern"
+ "*": "oxfmt --no-error-on-unmatched-pattern"
}
```

## Step 5: Run formatter

```sh
npm run format
```

Uninstall Prettier if it is no longer needed.

## Optional steps

### Update editor integrations

See [Setup editors](./editors).

### Update documentation

Update references to Prettier in `CONTRIBUTING.md`, `AGENTS.md`, and `CLAUDE.md` if applicable.

### Update lint rules

Remove `eslint-plugin-prettier` if present. If needed, it can be replaced by a `oxfmt --check` job in your CI pipelines.

Note that if you intend to continue using ESLint, you *should* keep or add [`eslint-config-prettier`](https://github.com/prettier/eslint-config-prettier) to disable styling-related ESLint rules that might conflict with Oxfmt. `eslint-config-prettier` is different from `eslint-plugin-prettier`, as it has no new lint rules. It is only a config.

Also, consider migrating to [Oxlint](../linter.md).

### Update `.git-blame-ignore-revs`

Add the reformatting commit SHA to `.git-blame-ignore-revs` to hide it from `git blame`.

### Replace `.prettierignore` with `"ignorePatterns"`

If you no longer use Prettier, you can optionally move its contents from `.prettierignore` to `"ignorePatterns"` in your Oxfmt config. Note that `.prettierignore` applies globally, while `ignorePatterns` is scoped to the config file it belongs to. In a [nested config](./config#create-a-config-file) setup, this may change which files are ignored. See [Ignore files](/docs/guide/usage/formatter/ignore-files) for more information.

### Update `// prettier-ignore` comments

Oxfmt supports `// prettier-ignore` comments, but also supports `// oxfmt-ignore` comments.

However, `// oxfmt-ignore` will only work for JS and TS files. See [Inline ignore comments](/docs/guide/usage/formatter/ignore-comments) for more information.

---

---
url: /docs/contribute/minifier.md
---

# Minifier

JavaScript minification plays a crucial role in optimizing website performance as it reduces the amount of data sent to users,
resulting in faster page loads.
This holds tremendous economic value, particularly for e-commerce websites, where every second can equate to millions of dollars.

However, existing minifiers typically require a trade-off between compression quality and speed.
You have to choose between the slowest for the best compression or the fastest for less compression.
But what if we could develop a faster minifier without compromising on compression?

## Project Goals

We are actively working on a prototype that aims to achieve this goal,
by porting all test cases from well-known minifiers such as [google-closure-compiler], [terser], [esbuild], and [tdewolff-minify].

Preliminary results indicate that we are on track to achieve our objectives.
With the Oxc minifier, you can expect faster minification times without sacrificing compression quality.

### Target Performance

* **Speed**: faster than Terser, competitive with esbuild
* **Compression**: Match or exceed Terser's compression ratio
* **Correctness**: Pass all major minifier test suites

## Architecture Overview

### Design Principles

The Oxc minifier is built around several key principles:

1. **Semantic-Aware**: Uses semantic analysis to enable safe optimizations
2. **Incremental**: Designed for incremental compilation workflows
3. **Configurable**: Supports various optimization levels and targets
4. **Correct**: Prioritizes correctness over aggressive optimization

## Current Status

### Implemented Features

* ✅ **Dead Code Elimination**: Remove unreachable code
* ✅ **Constant Folding**: Evaluate constant expressions
* ✅ **Tree Shaking**: Remove unused exports (basic)
* ✅ **Variable Merging**: Merge variable declarations
* ✅ **Statement Merging**: Combine compatible statements
* ✅ **Name Mangling**: Shorten variable and function names
* ✅ **Control Flow Optimization**: Simplify control structures
* ✅ **Function Inlining**: Inline small functions
* ✅ **Advanced Tree Shaking**: Cross-module optimization

### Performance Optimization

Key strategies for maintaining performance:

1. **Minimal AST Traversals**: Combine multiple optimizations in single passes
2. **Efficient Data Structures**: Use arena allocation and compact representations
3. **Early Termination**: Skip optimizations when no benefit is possible

## Resources

### Documentation

* [Minifier API Documentation](https://docs.rs/oxc_minifier)

### External References

* [Google Closure Compiler Optimizations](https://github.com/google/closure-compiler/wiki/JS-Modules)
* [Terser Options](https://github.com/terser/terser#minify-options)
* [esbuild Minification](https://esbuild.github.io/api/#minification)

#### Playgrounds

* esbuild: https://esbuild.github.io/try
* rollup: https://rollupjs.org/repl
* swc: https://play.swc.rs
* terser: https://try.terser.org
* closure compiler: https://jscompressor.treblereel.dev
  * Official website is no longer available: [Closure Compiler Webservice Turndown - 2025](https://github.com/google/closure-compiler/issues/4199)

[google-closure-compiler]: https://github.com/google/closure-compiler

[terser]: https://github.com/terser/terser

[esbuild]: https://github.com/evanw/esbuild

[tdewolff-minify]: https://github.com/tdewolff/minify

---

---
url: /docs/guide/usage/minifier.md
---
# Minifier

A high-performance minifier that shrinks your code by removing unused code and transforming to a shorter equivalent.

## Features

* [Eliminate dead code.](./minifier/dead-code-elimination)
* [Transforms syntaxes to make the output shorter and repetitive.](./minifier/syntax-normalization)
* [Mangle variable names.](./minifier/mangling)
* [Remove whitespace and comments.](./minifier/whitespace-stripping)

## Assumptions

To allow better optimizations, Oxc minifier makes some assumptions about your code. See [Assumptions document](https://github.com/oxc-project/oxc/blob/main/crates/oxc_minifier/docs/ASSUMPTIONS.md) for more information.

## FAQ

See [FAQ](./minifier/faq) for common questions.

## Installation

### With Rolldown

If you are using [Rolldown][url-rolldown], `oxc-minify` will be used for minification by default. No extra installation is required.

### Node.js

* Use the node binding [oxc-minify][url-oxc-minify-npm].
* Try on [stackblitz](https://stackblitz.com/fork/github/oxc-project/website/tree/main/stackblitz-templates/oxc-minify).

### Rust

Use the umbrella crate [oxc][url-oxc-crate] with the `minifier` feature.

Rust usage example can be found [here](https://github.com/oxc-project/oxc/blob/main/crates/oxc_minifier/examples/minifier.rs).

## Integrations

* [`unplugin-oxc`](https://npmx.dev/package/unplugin-oxc)

[url-oxc-crate]: https://docs.rs/oxc

[url-oxc-minify-npm]: https://npmx.dev/package/oxc-minify

[url-rolldown]: https://rolldown.rs

---

---
url: /docs/guide/usage/linter/multi-file-analysis.md
description: Project-wide linting for import cycles and cross-file issues
---

# Multi-file analysis

Multi-file analysis allows rules to use project-wide information, such as the module dependency graph, instead of analyzing each file in isolation.

## Performance and architecture

ESLint evaluates rules per file and does not provide a built-in project graph. Plugins such as
[`eslint-plugin-import`](https://npmx.dev/package/eslint-plugin-import) must rebuild module resolution and the module graph outside of ESLint’s core. Projects report the original `import/no-cycle` rule taking tens of seconds, or - on larger repositories - over a minute.

Oxlint implements multi-file analysis in the core engine. It lints files and builds the module graph in parallel, shares parsing and resolution across rules, and typically completes comparable `import/no-cycle` checks in a few seconds.

## Enable the `import` plugin

To use multi-file analysis, you must enable the `import` plugin and configure at
least one `import/*` rule. For an example, see the config file in the next section.

## Detect cycles with `import/no-cycle`

Enable
[`import/no-cycle`](/docs/guide/usage/linter/rules/import/no-cycle.html)
to detect circular dependencies.

Import cycles:

* obscure dependency direction
* make refactors harder
* can cause imported values to be `undefined` due to evaluation order

::: code-group

```json [.oxlintrc.json]
{
  "$schema": "./node_modules/oxlint/configuration_schema.json",
  "plugins": ["import"],
  "rules": {
    "import/no-cycle": ["error", { "maxDepth": 3 }]
  }
}
```

```ts [oxlint.config.ts]
import { defineConfig } from "oxlint";

export default defineConfig({
  plugins: ["import"],
  rules: {
    "import/no-cycle": ["error", { maxDepth: 3 }],
  },
});
```

:::

## TypeScript path aliases

When running `import/*` rules, Oxlint automatically discovers `tsconfig.json`
to resolve TypeScript path aliases such as `compilerOptions.paths`.

---

---
url: /docs/guide/usage/linter/nested-config.md
description: >-
  Use multiple configuration files to apply different Oxlint settings to
  different parts of a repository.
---

# Nested configuration files

Oxlint can use multiple configuration files in the same repository. It automatically detects configuration files named `.oxlintrc.json`, `.oxlintrc.jsonc`, `oxlint.config.ts`, or `oxlint.config.mts` and applies them based on where files live in the directory tree.

This is useful in monorepos where packages need their own settings, while still keeping a shared baseline.

If you only need to exclude files or folders, use [Ignores](./ignore-files) instead.

## How it works

For each file being linted, Oxlint uses the nearest config file (e.g. `.oxlintrc.json` or `oxlint.config.ts`) relative to that file.

Given the following structure:

```
my-project/
├── .oxlintrc.json
├── src/
│   ├── index.js
├── package1/
│   ├── oxlint.config.ts
│   └── index.js
└── package2/
    ├── .oxlintrc.json
    └── index.js
```

Configuration resolution works as follows:

* `src/index.js` uses `my-project/.oxlintrc.json`
* `package1/index.js` uses `my-project/package1/oxlint.config.ts`
* `package2/index.js` uses `my-project/package2/.oxlintrc.json`

## What to expect

Configuration files are not automatically merged. A config in a child directory does not affect the parent config.

Command line options override configuration files, regardless of whether they come from a parent or child directory.

Passing an explicit config file location using `-c` or `--config` disables nested config lookup, and Oxlint will only use that single configuration file.

You can also disable nested configs with the `--disable-nested-config` flag.

`options.typeAware` and `options.typeCheck` are root-config-only. If either is set in a nested config file, Oxlint reports an error.

## Monorepo pattern: share a base config with extends

In a monorepo, you often want one shared baseline at the root, and small package specific adjustments.

You do this by keeping a root config file (either `.oxlintrc.json` or `oxlint.config.ts`), then having package configs extend it.

::: code-group

```json [my-project/.oxlintrc.json]
{
  "rules": {
    "no-debugger": "error"
  }
}
```

```ts [my-project/oxlint.config.ts]
import { defineConfig } from "oxlint";

export default defineConfig({
  rules: {
    "no-debugger": "error",
  },
});
```

:::

::: code-group

```json [my-project/package1/.oxlintrc.json]
{
  "extends": ["../.oxlintrc.json"],
  "rules": {
    "no-console": "off"
  }
}
```

```ts [my-project/package1/oxlint.config.ts]
import baseConfig from "../oxlint.config.ts";
import { defineConfig } from "oxlint";

export default defineConfig({
  extends: [baseConfig],
  rules: {
    "no-console": "off",
  },
});
```

:::

This keeps the shared baseline in one place and makes package configs small and focused.

## Extending configuration files

A config can reuse settings from other configs using `extends`.

In `.oxlintrc.json`, `extends` is an array of file paths, resolved relative to the config file that declares them. Extended files can have any name. They do not need to be named `.oxlintrc.json`, as long as they are valid JSON configuration files. Package imports are not supported in the `.oxlintrc.json` format.

In `oxlint.config.ts`, import the config objects you want to extend and pass them to `extends` (file paths are not supported). The imported files can have any name; only the entry config that Oxlint loads must be auto-discoverable (`oxlint.config.ts` or `oxlint.config.mts`) or passed via `--config`. Use a TypeScript config when extending config objects imported from a shared package.

Example:

::: code-group

```json [oxlint-typescript.json]
{
  "plugins": ["typescript"],
  "rules": {
    "typescript/no-explicit-any": "error"
  }
}
```

```ts [oxlint-typescript.config.ts]
import { defineConfig } from "oxlint";

export default defineConfig({
  plugins: ["typescript"],
  rules: {
    "typescript/no-explicit-any": "error",
  },
});
```

:::

::: code-group

```json [.oxlintrc.json]
{
  "extends": ["oxlint-typescript.json"],
  "rules": {
    "no-unused-vars": "warn"
  }
}
```

```ts [oxlint.config.ts]
import typescriptConfig from "./oxlint-typescript.config.ts";
import { defineConfig } from "oxlint";

export default defineConfig({
  extends: [typescriptConfig],
  rules: {
    "no-unused-vars": "warn",
  },
});
```

:::

Shared packages work the same way in `oxlint.config.ts`:

```ts [oxlint.config.ts]
import sharedConfig from "@example-org/oxlint-config";
import { defineConfig } from "oxlint";

export default defineConfig({
  extends: [sharedConfig],
});
```

Only some properties can be extended. The supported properties are:

* `rules`
* `plugins`
* `overrides`

### How `plugins` merges

Each config in an `extends` chain contributes its `plugins` list, and the result is the union of all contributions. A config that does not declare `plugins` contributes the default plugins instead.

This means extending a config with a narrower `plugins` list than the defaults is not enough on its own: if the extending config omits `plugins`, the defaults are added back on top of the extended list.

To inherit exactly the plugins of the extended config, declare an empty array:

::: code-group

```json [.oxlintrc.json]
{
  "extends": ["./base.json"],
  "plugins": []
}
```

```ts [oxlint.config.ts]
import baseConfig from "./base.config.ts";
import { defineConfig } from "oxlint";

export default defineConfig({
  extends: [baseConfig],
  plugins: [],
});
```

:::

The empty array is an empty contribution, so the result is exactly the plugins declared by `base.json`. Declaring a non-empty list works the same way: the union of that list and the extended lists, with the defaults only appearing if some config in the chain omits `plugins`.

This is the same mechanism as [disabling the default plugins](./plugins) with `"plugins": []` in a standalone config: an explicit array replaces the config's default contribution.

---

---
url: /docs/guide/usage/linter/rules/nextjs/google-font-display.md
---

### What it does

Enforce font-display behavior with Google Fonts.

### Why is this bad?

Specifying display=optional minimizes the risk of invisible text or
layout shift. If swapping to the custom font after it has loaded is
important to you, then use \`display=swap\`\` instead.

### Examples

Examples of **incorrect** code for this rule:

```jsx
import Head from "next/head";

export default (Test = () => {
  return (
    <Head>
      <link href="https://fonts.googleapis.com/css2?family=Krona+One" rel="stylesheet" />
    </Head>
  );
});
```

Examples of **correct** code for this rule:

```jsx
import Head from "next/head";

export default (Test = () => {
  return (
    <Head>
      <link
        href="https://fonts.googleapis.com/css2?family=Krona+One&display=optional"
        rel="stylesheet"
      />
    </Head>
  );
});
```

## How to use

## Version

This rule was added in v0.2.0.

## References

---

---
url: /docs/guide/usage/linter/rules/nextjs/google-font-preconnect.md
---

### What it does

Enforces the presence of `rel="preconnect"` when using Google Fonts via `<link>` tags.

### Why is this bad?

When using Google Fonts, it's recommended to include a preconnect resource hint to establish early connections to the required origin.
Without preconnect, the browser needs to perform DNS lookups, TCP handshakes, and TLS negotiations before it can download the font files,
which can delay font loading and impact performance.

### Examples

Examples of **incorrect** code for this rule:

```javascript
<link href="https://fonts.gstatic.com" />
<link rel="preload" href="https://fonts.gstatic.com" />
```

Examples of **correct** code for this rule:

```javascript
<link rel="preconnect" href="https://fonts.gstatic.com" />
```

## How to use

## Version

This rule was added in v0.2.0.

## References

---

---
url: /docs/guide/usage/linter/rules/nextjs/inline-script-id.md
---

### What it does

Enforces that all `next/script` components with inline content or `dangerouslySetInnerHTML` must have an `id` prop.

### Why is this bad?

Next.js requires a unique `id` prop for inline scripts to properly deduplicate them during page renders.
Without an `id`, the same inline script might be executed multiple times, leading to unexpected behavior
or performance issues. This is particularly important for scripts that modify global state or perform
one-time initializations.

### Examples

Examples of **incorrect** code for this rule:

```javascript
import Script from 'next/script';

export default function Page() {
  return (
    <Script>
      {`console.log('Hello world');`}
    </Script>
  );
}

// Also incorrect with dangerouslySetInnerHTML
export default function Page() {
  return (
    <Script
      dangerouslySetInnerHTML={{
        __html: `console.log('Hello world');`
      }}
    />
  );
}
```

Examples of **correct** code for this rule:

```javascript
import Script from 'next/script';

export default function Page() {
  return (
    <Script id="my-script">
      {`console.log('Hello world');`}
    </Script>
  );
}

// Correct with dangerouslySetInnerHTML
export default function Page() {
  return (
    <Script
      id="my-script"
      dangerouslySetInnerHTML={{
        __html: `console.log('Hello world');`
      }}
    />
  );
}

// No id required for external scripts
export default function Page() {
  return (
    <Script src="https://example.com/script.js" />
  );
}
```

## How to use

## Version

This rule was added in v0.2.0.

## References

---

---
url: /docs/guide/usage/linter/rules/nextjs/next-script-for-ga.md
---

### What it does

Enforces the use of the `next/script` component when implementing Google Analytics in Next.js applications,
instead of using regular `<script>` tags.

### Why is this bad?

Using regular `<script>` tags for Google Analytics can lead to several issues:

* Scripts may load in a blocking manner, impacting page performance
* No built-in optimization or loading strategies
* Lack of automatic resource handling that Next.js provides

### Examples

Examples of **incorrect** code for this rule:

```jsx
// Using regular script tag with GA source
<script src="https://www.googletagmanager.com/gtag/js?id=GA_MEASUREMENT_ID"></script>

// Using inline script for GA initialization
<script dangerouslySetInnerHTML={{
  __html: `
    window.dataLayer = window.dataLayer || [];
    function gtag(){dataLayer.push(arguments);}
    gtag('js', new Date());
    gtag('config', 'GA_MEASUREMENT_ID');
  `
}} />
```

Examples of **correct** code for this rule:

```jsx
import Script from 'next/script'

// Using next/script for GA source
<Script
  src="https://www.googletagmanager.com/gtag/js?id=GA_MEASUREMENT_ID"
  strategy="lazyOnload"
/>

// Using next/script for GA initialization
<Script id="google-analytics">
  {`
    window.dataLayer = window.dataLayer || [];
    function gtag(){dataLayer.push(arguments);}
    gtag('js', new Date());
    gtag('config', 'GA_MEASUREMENT_ID');
  `}
</Script>
```

## How to use

## Version

This rule was added in v0.2.0.

## References

---

---
url: /docs/guide/usage/linter/rules/nextjs/no-assign-module-variable.md
---

### What it does

Prevents the assignment or declaration of variables named `module` in Next.js applications.

### Why is this bad?

The variable name `module` is reserved in Next.js for internal use and module system
functionality. Declaring your own `module` variable can conflict with Next.js's internal
module system, lead to unexpected behavior in your application, and cause issues with code
splitting and hot module replacement.

### Examples

Examples of **incorrect** code for this rule:

```javascript
// Declaring module variable
let module = {};

// Using module in variable declaration
const module = {
  exports: {},
};

// Assigning to module
module = { id: "my-module" };
```

Examples of **correct** code for this rule:

```javascript
// Use a different variable name
let myModule = {};

// Use a more descriptive name
const customModule = {
  exports: {},
};

// Access actual module object (when available)
console.log(module.exports);
```

## How to use

## Version

This rule was added in v0.2.0.

## References

---

---
url: /docs/guide/usage/linter/rules/nextjs/no-async-client-component.md
---

### What it does

Prevents the use of async functions for client components in Next.js applications.
This rule checks for any async function that:

* Is marked with "use client" directive
* Has a name starting with an uppercase letter (indicating it's a component)
* Is either exported as default or assigned to a variable

### Why is this bad?

Using async functions for client components can cause hydration mismatches between server and client,
can break component rendering lifecycle, and can lead to unexpected behavior with React's concurrent features.

### Examples

Examples of **incorrect** code for this rule:

```javascript
"use client"

// Async component with default export
export default async function MyComponent() {
  return <></>
}

// Async component with named export
async function MyComponent() {
  return <></>
}
export default MyComponent

// Async arrow function component
const MyComponent = async () => {
  return <></>
}
export default MyComponent
```

Examples of **correct** code for this rule:

```javascript
"use client"

// Regular synchronous component
export default function MyComponent() {
  return <></>
}

// Handling async operations in effects
export default function MyComponent() {
  useEffect(() => {
    async function fetchData() {
      // async operations here
    }
    fetchData();
  }, []);
  return <></>
}

// Async operations in event handlers
export default function MyComponent() {
  const handleClick = async () => {
    // async operations here
  }
  return <button onClick={handleClick}>Click me</button>
}
```

## How to use

## Version

This rule was added in v0.2.0.

## References

---

---
url: >-
  /docs/guide/usage/linter/rules/nextjs/no-before-interactive-script-outside-document.md
---

### What it does

Prevents the usage of `next/script`'s `beforeInteractive` strategy outside of `pages/_document.js`.
This rule ensures that scripts with the `beforeInteractive` loading strategy are only used in the
document component where they are most effective.

### Why is this bad?

The `beforeInteractive` strategy is specifically designed to load scripts before any page hydration
occurs, which is only guaranteed to work correctly when placed in `pages/_document.js`. Using it elsewhere:

* May not achieve the intended early loading behavior
* Can lead to inconsistent script loading timing
* Might cause hydration mismatches or other runtime issues
* Could impact the application's performance optimization

### Examples

Examples of **incorrect** code for this rule:

```jsx
// pages/index.js
import Script from "next/script";

export default function HomePage() {
  return (
    <div>
      <Script
        src="https://example.com/script.js"
        strategy="beforeInteractive" // ❌ Wrong placement
      />
    </div>
  );
}
```

Examples of **correct** code for this rule:

```jsx
// pages/_document.js
import Document, { Html, Head, Main, NextScript } from "next/document";
import Script from "next/script";

class MyDocument extends Document {
  render() {
    return (
      <Html>
        <Head />
        <body>
          <Script
            src="https://example.com/script.js"
            strategy="beforeInteractive" // ✅ Correct placement
          />
          <Main />
          <NextScript />
        </body>
      </Html>
    );
  }
}

export default MyDocument;
```

## How to use

## Version

This rule was added in v0.2.7.

## References

---

---
url: /docs/guide/usage/linter/rules/nextjs/no-css-tags.md
---

### What it does

Prevents manual inclusion of stylesheets using `<link>` tags in Next.js applications.
This rule checks for `<link>` tags with `rel="stylesheet"` that reference local CSS files.

### Why is this bad?

Next.js handles CSS imports automatically through its built-in CSS support.
Manual stylesheet inclusion bypasses Next.js's built-in CSS optimization,
prevents proper code splitting and optimization of styles, and may cause
Flash of Unstyled Content (FOUC). This also breaks automatic CSS hot reloading
during development.

### Examples

Examples of **incorrect** code for this rule:

```jsx
// Manually including local CSS file
<link href="/_next/static/css/styles.css" rel="stylesheet" />

// In pages/_document.js
<Head>
  <link href="css/my-styles.css" rel="stylesheet" />
</Head>
```

Examples of **correct** code for this rule:

```jsx
// Importing CSS file directly
import '../styles/global.css'

// Using CSS Modules
import styles from './Button.module.css'

// Using external stylesheets (allowed)
<link
  href="https://fonts.googleapis.com/css?family=Open+Sans"
  rel="stylesheet"
/>

// Using styled-jsx
<style jsx>{`
  .button { color: blue; }
`}</style>
```

## How to use

## Version

This rule was added in v0.2.0.

## References

---

---
url: /docs/guide/usage/linter/rules/nextjs/no-document-import-in-page.md
---

### What it does

Prevent importing `next/document` outside of `pages/_document.js`.

### Why is this bad?

Importing `next/document` outside of `pages/_document.js` can cause
unexpected issues in your Next.js application.

### Examples

Examples of **incorrect** code for this rule:

```jsx
// `components/MyDocument.jsx`
import Document from "next/document";

class MyDocument extends Document {
  //...
}

export default MyDocument;
```

Examples of **correct** code for this rule:

```jsx
// `pages/_document.jsx`
import Document from "next/document";

class MyDocument extends Document {
  //...
}

export default MyDocument;
```

## How to use

## Version

This rule was added in v0.2.1.

## References

---

---
url: /docs/guide/usage/linter/rules/nextjs/no-duplicate-head.md
---

### What it does

Prevent duplicate usage of `<Head>` in `pages/_document.js`.

### Why is this bad?

This can cause unexpected behavior in your application.

### Examples

Examples of **incorrect** code for this rule:

```jsx
import Document, { Html, Head, Main, NextScript } from "next/document";
class MyDocument extends Document {
  static async getInitialProps(ctx) {}
  render() {
    return (
      <Html>
        <Head />
        <Head />
        <body>
          <Main />
          <NextScript />
        </body>
      </Html>
    );
  }
}
export default MyDocument;
```

Examples of **correct** code for this rule:

```jsx
import Document, { Html, Head, Main, NextScript } from "next/document";
class MyDocument extends Document {
  static async getInitialProps(ctx) {}
  render() {
    return (
      <Html>
        <Head />
        <body>
          <Main />
          <NextScript />
        </body>
      </Html>
    );
  }
}
export default MyDocument;
```

## How to use

## Version

This rule was added in v0.3.3.

## References

---

---
url: /docs/guide/usage/linter/rules/nextjs/no-head-element.md
---

### What it does

Prevents the usage of the native `<head>` element inside a Next.js application.

### Why is this bad?

A `<head>` element can cause unexpected behavior in a Next.js application.
Use Next.js' built-in `next/head` component instead.

### Examples

Examples of **incorrect** code for this rule:

```jsx
function Index() {
  return (
    <>
      <head>
        <title>My page title</title>
        <meta name="viewport" content="initial-scale=1.0, width=device-width" />
      </head>
    </>
  );
}

export default Index;
```

Examples of **correct** code for this rule:

```jsx
import Head from "next/head";

function Index() {
  return (
    <>
      <Head>
        <title>My page title</title>
        <meta name="viewport" content="initial-scale=1.0, width=device-width" />
      </Head>
    </>
  );
}

export default Index;
```

## How to use

## Version

This rule was added in v0.2.1.

## References

---

---
url: /docs/guide/usage/linter/rules/nextjs/no-head-import-in-document.md
---

### What it does

Prevents the usage of `next/head` inside a Next.js document.

### Why is this bad?

Importing `next/head` inside `pages/_document.js` can cause
unexpected issues in your Next.js application.

### Examples

Examples of **incorrect** code for this rule:

```jsx
import Document, { Html, Main, NextScript } from "next/document";
import Head from "next/head";

class MyDocument extends Document {
  static async getInitialProps(ctx) {
    //...
  }

  render() {
    return (
      <Html>
        <Head></Head>
      </Html>
    );
  }
}

export default MyDocument;
```

Examples of **correct** code for this rule:

```jsx
import Document, { Html, Head, Main, NextScript } from "next/document";

class MyDocument extends Document {
  static async getInitialProps(ctx) {
    //...
  }

  render() {
    return (
      <Html>
        <Head></Head>
      </Html>
    );
  }
}

export default MyDocument;
```

## How to use

## Version

This rule was added in v0.2.0.

## References

---

---
url: /docs/guide/usage/linter/rules/nextjs/no-html-link-for-pages.md
---

### What it does

Prevents the usage of `<a>` elements to navigate between Next.js pages.

### Why is this bad?

Using `<a>` elements for internal navigation in Next.js applications can cause:

* Full page reloads instead of client-side navigation
* Loss of application state
* Slower navigation performance
* Broken prefetching capabilities

Next.js provides the `<Link />` component from `next/link` for client-side navigation
between pages, which provides better performance and user experience.

### Examples

Examples of **incorrect** code for this rule:

```jsx
function HomePage() {
  return (
    <div>
      <a href="/about">About Us</a>
      <a href="/contact">Contact</a>
    </div>
  );
}
```

Examples of **correct** code for this rule:

```jsx
import Link from "next/link";

function HomePage() {
  return (
    <div>
      <Link href="/about">About Us</Link>
      <Link href="/contact">Contact</Link>
    </div>
  );
}
```

External links are allowed:

```jsx
function HomePage() {
  return (
    <div>
      <a href="https://example.com">External Link</a>
      <a href="mailto:contact@example.com">Email</a>
      <a href="tel:+1234567890">Phone</a>
    </div>
  );
}
```

## How to use

## Version

This rule was added in v1.7.0.

## References

---

---
url: /docs/guide/usage/linter/rules/nextjs/no-img-element.md
---

### What it does

Prevent the usage of the `<img>` element due to slower
[LCP](https://nextjs.org/learn/seo/lcp) and higher bandwidth.

### Why is this bad?

`<img>` elements are not optimized for performance and can result in
slower LCP and higher bandwidth. Using [`<Image />`](https://nextjs.org/docs/pages/api-reference/components/image)
from `next/image` will automatically optimize images and serve them as
static assets.

### Examples

Examples of **incorrect** code for this rule:

```javascript
export function MyComponent() {
  return (
    <div>
      <img src="/test.png" alt="Test picture" />
    </div>
  );
}
```

Examples of **correct** code for this rule:

```javascript
import Image from "next/image";
import testImage from "./test.png";
export function MyComponent() {
  return (
    <div>
      <Image src={testImage} alt="Test picture" />
    </div>
  );
}
```

## How to use

## Version

This rule was added in v0.2.0.

## References

---

---
url: /docs/guide/usage/linter/rules/nextjs/no-page-custom-font.md
---

### What it does

Prevent page-only custom fonts.

### Why is this bad?

* The custom font you're adding was added to a page - this only adds the font to the specific page and not the entire application.
* The custom font you're adding was added to a separate component within `pages/_document.js` - this disables automatic font optimization.

### Examples

Examples of **incorrect** code for this rule:

```jsx
// pages/index.jsx
import Head from "next/head";
function IndexPage() {
  return (
    <Head>
      <link
        href="https://fonts.googleapis.com/css2?family=Krona+One&display=swap"
        rel="stylesheet"
      />
    </Head>
  );
}
export default IndexPage;
```

Examples of **correct** code for this rule:

```jsx
// pages/_document.jsx
import NextDocument, { Html, Head } from "next/document";
class Document extends NextDocument {
  render() {
    return (
      <Html>
        <Head>
          <link
            href="https://fonts.googleapis.com/css2?family=Krona+One&display=swap"
            rel="stylesheet"
          />
        </Head>
      </Html>
    );
  }
}
export default Document;
```

## How to use

## Version

This rule was added in v0.3.3.

## References

---

---
url: /docs/guide/usage/linter/rules/nextjs/no-script-component-in-head.md
---

### What it does

Prevent usage of `next/script` in `next/head` component.

### Why is this bad?

The `next/script` component should not be used in a `next/head` component.
Instead move the `<Script />` component outside of `<Head>` instead.

### Examples

Examples of **incorrect** code for this rule:

```jsx
import Script from "next/script";
import Head from "next/head";

export default function Index() {
  return (
    <Head>
      <title>Next.js</title>
      <Script src="/my-script.js" />
    </Head>
  );
}
```

Examples of **correct** code for this rule:

```jsx
import Script from "next/script";
import Head from "next/head";

export default function Index() {
  return (
    <>
      <Head>
        <title>Next.js</title>
      </Head>
      <Script src="/my-script.js" />
    </>
  );
}
```

## How to use

## Version

This rule was added in v0.2.0.

## References

---

---
url: /docs/guide/usage/linter/rules/nextjs/no-styled-jsx-in-document.md
---

### What it does

Prevent usage of styled-jsx in `pages/_document.js`.

### Why is this bad?

Custom CSS like styled-jsx is not allowed in a [Custom Document](https://nextjs.org/docs/pages/building-your-application/routing/custom-document).

### Examples

Examples of **incorrect** code for this rule:

```javascript
// pages/_document.js
import Document, { Html, Head, Main, NextScript } from "next/document";

class MyDocument extends Document {
  render() {
    return (
      <Html>
        <Head />
        <body>
          <Main />
          <NextScript />
          <style jsx>{`
            body {
              background: hotpink;
            }
          `}</style>
        </body>
      </Html>
    );
  }
}
```

Examples of **correct** code for this rule:

```javascript
// pages/_document.js
import Document, { Html, Head, Main, NextScript } from "next/document";

class MyDocument extends Document {
  render() {
    return (
      <Html>
        <Head />
        <body>
          <Main />
          <NextScript />
        </body>
      </Html>
    );
  }
}
```

## How to use

## Version

This rule was added in v0.3.3.

## References

---

---
url: /docs/guide/usage/linter/rules/nextjs/no-sync-scripts.md
---

### What it does

Prevent the use of synchronous `<script>` tags in Next.js applications.
Require any `<script>` tag with a `src` attribute to also have either
the `async` or `defer` attribute.

### Why is this bad?

Synchronous scripts can block the page rendering and negatively impact performance.
In Next.js applications, it's recommended to use `async` or `defer` attributes
to load scripts asynchronously, which improves page load times and user experience.

### Examples

Examples of **incorrect** code for this rule:

```javascript
// Synchronous script without async/defer
<script src="https://example.com/script.js"></script>

// Dynamic src without async/defer
<script src={dynamicSrc}></script>
```

Examples of **correct** code for this rule:

```javascript
// Script with async attribute
<script src="https://example.com/script.js" async></script>

// Script with defer attribute
<script src="https://example.com/script.js" defer></script>

// Script with spread props (allowed as it might include async/defer)
<script {...props}></script>
```

## How to use

## Version

This rule was added in v0.2.0.

## References

---

---
url: /docs/guide/usage/linter/rules/nextjs/no-title-in-document-head.md
---

### What it does

Prevent usage of `<title>` with `Head` component from `next/document`.

### Why is this bad?

A `<title>` element should only be used for any `<head>` code that is common for all pages.
Title tags should be defined at the page-level using `next/head` instead.

### Examples

Examples of **incorrect** code for this rule:

```javascript
import { Head } from "next/document";

export function Home() {
  return (
    <div>
      <Head>
        <title>My page title</title>
      </Head>
    </div>
  );
}
```

Examples of **correct** code for this rule:

```javascript
import Head from "next/head";

export function Home() {
  return (
    <div>
      <Head>
        <title>My page title</title>
      </Head>
    </div>
  );
}
```

## How to use

## Version

This rule was added in v0.2.0.

## References

---

---
url: /docs/guide/usage/linter/rules/nextjs/no-typos.md
---

### What it does

Detects common typos in Next.js data fetching function names.

### Why is this bad?

Next.js will not call incorrectly named data fetching functions, causing pages to render without expected data.

### Examples

Examples of **incorrect** code for this rule:

```javascript
export default function Page() {
  return <div></div>;
}
export async function getServurSideProps() {}
```

Examples of **correct** code for this rule:

```javascript
export default function Page() {
  return <div></div>;
}
export async function getServerSideProps() {}
```

## How to use

## Version

This rule was added in v0.2.1.

## References

---

---
url: /docs/guide/usage/linter/rules/nextjs/no-unwanted-polyfillio.md
---

### What it does

Prevent use of unsafe polyfill.io domains and duplicate polyfills.

### Why is this bad?

**Security Risk:**
The domains `cdn.polyfill.io` and `polyfill.io` were compromised in a supply chain attack in 2024,
where the domain was acquired by a malicious actor and began injecting harmful code into websites.
Over 380,000+ websites were affected. These domains should not be used under any circumstances.

**Performance Issue:**
For safe alternatives like `cdnjs.cloudflare.com/polyfill/`, including polyfills already shipped
with Next.js unnecessarily increases page weight which can affect loading performance.

### Examples

Examples of **incorrect** code for this rule:

```javascript
// Security risk - compromised domain
<script src='https://cdn.polyfill.io/v2/polyfill.min.js'></script>
<script src='https://polyfill.io/v3/polyfill.min.js'></script>

// Duplicate polyfills
<script src='https://cdnjs.cloudflare.com/polyfill/v3/polyfill.min.js?features=Array.prototype.copyWithin'></script>
<script src='https://cdnjs.cloudflare.com/polyfill/v3/polyfill.min.js?features=WeakSet%2CPromise'></script>
```

## How to use

## Version

This rule was added in v0.2.7.

## References

---

---
url: /docs/guide/usage/linter/rules/node/callback-return.md
---

### What it does

Require `return` statements after callbacks.

### Why is this bad?

This rule is aimed at ensuring that callbacks used outside of the main function block are always part-of or immediately preceding a `return` statement.
This rule decides what is a callback based on the name of the function being called.

### Examples

Examples of **incorrect** code for this rule:

```js
function done(err) {
  if (err) {
    callback(err);
  }
  callback();
}
```

Examples of **correct** code for this rule:

```js
function done(err) {
  if (err) {
    return callback(err);
  }
  callback();
}
```

### Known Limitations

Because it is difficult to understand the meaning of a program through static analysis, this rule has limitations:

* *false negatives* when this rule reports correct code, but the program calls the callback more than one time (which is incorrect behavior)
* *false positives* when this rule reports incorrect code, but the program calls the callback only one time (which is correct behavior)

#### Passing the callback by reference

The static analysis of this rule does not detect that the program calls the callback if it is an argument of a function (for example, `setTimeout`).

Example of a *false negative* when this rule reports correct code:

```js
function foo(err, callback) {
  if (err) {
    setTimeout(callback, 0); // this is bad, but WILL NOT warn
  }
  callback();
}
```

#### Triggering the callback within a nested function

The static analysis of this rule does not detect that the program calls the callback from within a nested function or an immediately-invoked function expression (IIFE).

Example of a *false negative* when this rule reports correct code:

```js
function foo(err, callback) {
  if (err) {
    process.nextTick(function () {
      return callback(); // this is bad, but WILL NOT warn
    });
  }
  callback();
}
```

#### If/else statements

The static analysis of this rule does not detect that the program calls the callback only one time in each branch of an `if` statement.

Example of a *false positive* when this rule reports incorrect code:

```js
function foo(err, callback) {
  if (err) {
    callback(err); // this is fine, but WILL warn
  } else {
    callback(); // this is fine, but WILL warn
  }
}
```

## Configuration

The rule takes a single option - an array of possible callback names - which may include object methods. The default callback names are `callback`, `cb`, `next`.

type: `string[]`

default: `[]`

## How to use

## Version

This rule was added in v1.67.0.

## References

---

---
url: /docs/guide/usage/linter/rules/node/exports-style.md
---

### What it does

Enforce either `module.exports` or `exports`.

### Why is this bad?

`module.exports` and `exports` are the same instance by default. But those come to be different if one of them is modified.

```js
module.exports = {
  foo: 1,
};

exports.bar = 2;
```

In this case, `exports.bar` will be lost since only the instance of `module.exports` will be exported.

### Examples

Examples of **incorrect** code for the `"module.exports"` option:

```js
exports.foo = 1;
exports.bar = 2;
```

Examples of **correct** code for the `"module.exports"` option:

```js
module.exports = {
  foo: 1,
  bar: 2,
};
module.exports.baz = 3;
```

Examples of **incorrect** code for the `"exports"` option:

```js
module.exports = {
  foo: 1,
  bar: 2,
};
module.exports.baz = 3;
```

Examples of **correct** code for the `"exports"` option:

```js
exports.foo = 1;
exports.bar = 2;
```

## Configuration

### The 1st option

type: `"module.exports" | "exports"`

#### `"module.exports"`

Requires `module.exports` and disallows `exports`

#### `"exports"`

Requires `exports` and disallows `module.exports`

### The 2nd option

This option is an object with the following properties:

#### allowBatchAssign

type: `boolean`

default: `false`

If this option is set to `true`, `module.exports = exports = obj` are allowed.

## How to use

## Version

This rule was added in v1.76.0.

## References

---

---
url: /docs/guide/usage/linter/rules/node/global-require.md
---

### What it does

Require `require()` calls to be placed at top-level module scope.

### Why is this bad?

In Node.js, module dependencies are included using the `require()` function, such as:

```js
var fs = require("fs");
```

While `require()` may be called anywhere in code, some style guides prescribe that it should be called only in the top level of a module to make it easier to identify dependencies.
For instance, it's arguably harder to identify dependencies when they are deeply nested inside of functions and other statements:

```js
function foo() {
  if (condition) {
    var fs = require("fs");
  }
}
```

Since `require()` does a synchronous load, it can cause performance problems when used in other locations.
Further, ES6 modules mandate that import and export statements can only occur in the top level of the module's body.

### Examples

Examples of **incorrect** code for this rule:

```js
// calling require() inside of a function is not allowed
function readFile(filename, callback) {
  var fs = require("fs");
  fs.readFile(filename, callback);
}

// conditional requires like this are also not allowed
if (DEBUG) {
  require("debug");
}

// a require() in a switch statement is also flagged
switch (x) {
  case "1":
    require("1");
    break;
}

// you may not require() inside an arrow function body
var getModule = (name) => require(name);

// you may not require() inside of a function body as well
function getModule(name) {
  return require(name);
}

// you may not require() inside of a try/catch block
try {
  require(unsafeModule);
} catch (e) {
  console.log(e);
}
```

Examples of **correct** code for this rule:

```js
// all these variations of require() are ok
require("x");
var y = require("y");
var z;
z = require("z").initialize();

// requiring a module and using it in a function is ok
var fs = require("fs");
function readFile(filename, callback) {
  fs.readFile(filename, callback);
}

// you can use a ternary to determine which module to require
var logger = DEBUG ? require("dev-logger") : require("logger");

// if you want you can require() at the end of your module
function doSomethingA() {}
function doSomethingB() {}
var x = require("x"),
  z = require("z");
```

## How to use

## Version

This rule was added in v1.36.0.

## References

---

---
url: /docs/guide/usage/linter/rules/node/handle-callback-err.md
---

### What it does

This rule expects that when you're using the callback pattern in Node.js you'll handle the error.

### Why is this bad?

In Node.js, a common pattern for dealing with asynchronous behavior is called the callback pattern.
This pattern expects an `Error` object or `null` as the first argument of the callback.
Forgetting to handle these errors can lead to some really strange behavior in your application.

```js
function loadData(err, data) {
  doSomething(); // forgot to handle error
}
```

### Examples

Examples of **incorrect** code for this rule with the default `"err"` parameter name:

```js
function loadData(err, data) {
  doSomething();
}
```

Examples of **correct** code for this rule with the default `"err"` parameter name:

```js
function loadData(err, data) {
  if (err) {
    console.log(err.stack);
  }
  doSomething();
}

function generateError(err) {
  if (err) {
  }
}
```

Examples of correct code for this rule with a sample `"error"` parameter name:

```js
function loadData(error, data) {
  if (error) {
    console.log(error.stack);
  }
  doSomething();
}
```

## Configuration

The rule takes a single string option: the name of the error parameter.

This can be either:

* an exact name (e.g. `"err"`, `"error"`)
* a regexp pattern (e.g. `"^(err|error)$"`)

If the configured name of the error variable begins with a `^` it is considered to be a regexp pattern.
Invalid regexp patterns are rejected during configuration parsing.

Default: `"err"`.

type: `string`

## How to use

## Version

This rule was added in v1.56.0.

## References

---

---
url: /docs/guide/usage/linter/rules/node/no-exports-assign.md
---

### What it does

Disallows assignment to `exports`.

### Why is this bad?

Directly using `exports = {}` can lead to confusion and potential bugs
because it reassigns the `exports` object, which may break module
exports. It is more predictable and clearer to use `module.exports`
directly or in conjunction with `exports`.

This rule is aimed at disallowing `exports = {}`, but allows
`module.exports = exports = {}` to avoid conflict with `n/exports-style`
rule's `allowBatchAssign` option.

### Examples

Examples of **incorrect** code for this rule:

```js
exports = {};
```

Examples of **correct** code for this rule:

```js
module.exports.foo = 1;
exports.bar = 2;
module.exports = {};

// allows `exports = {}` if along with `module.exports =`
module.exports = exports = {};
exports = module.exports = {};
```

## How to use

## Version

This rule was added in v0.9.3.

## References

---

---
url: /docs/guide/usage/linter/rules/node/no-mixed-requires.md
---

### What it does

Disallows `require` calls to be mixed with regular variable declarations.

### Why is this bad?

In the Node.js community it is often customary to separate initializations with calls to
`require` modules from other variable declarations, sometimes also grouping them by the type
of module.

### Examples

Examples of **incorrect** code for this rule:

```js
var fs = require("fs"),
  i = 0;

var async = require("async"),
  debug = require("diagnostics").someFunction("my-module"),
  eslint = require("eslint");
```

Examples of **correct** code for this rule:

```js
var eventEmitter = require("events").EventEmitter,
  myUtils = require("./utils"),
  util = require("util"),
  bar = require(getBarModuleName());

var foo = 42,
  bar = "baz";
```

## Configuration

### allowCall

type: `boolean`

default: `false`

### grouping

type: `boolean`

default: `false`

## How to use

## Version

This rule was added in v1.71.0.

## References

---

---
url: /docs/guide/usage/linter/rules/node/no-new-require.md
---

### What it does

Warn about calling `new` on `require`.

### Why is this bad?

The `require` function is used to include modules and might return a constructor. As this
is not always the case this can be confusing.

### Examples

Examples of **incorrect** code for this rule:

```js
var appHeader = new require("app-header");
```

Examples of **correct** code for this rule:

```js
var AppHeader = require("app-header");
var appHeader = new AppHeader();
```

## How to use

## Version

This rule was added in v0.10.0.

## References

---

---
url: /docs/guide/usage/linter/rules/node/no-path-concat.md
---

### What it does

Disallows string concatenation with `__dirname` and `__filename`.

### Why is this bad?

In Node.js, the `__dirname` and `__filename` global variables contain the directory path and the file path of the currently executing script file, respectively.
Sometimes, developers try to use these variables to create paths to other files, such as:

```js
var fullPath = __dirname + "/foo.js";
```

However, this is error-prone because it doesn't account for different
operating systems, which use different path separators. Using `path.join()`
or `path.resolve()` is the proper way to create cross-platform file paths.

### Examples

Examples of **incorrect** code for this rule:

```js
const fullPath1 = __dirname + "/foo.js";
const fullPath2 = __filename + "/foo.js";
const fullPath3 = `${__dirname}/foo.js`;
const fullPath4 = `${__filename}/foo.js`;
```

Examples of **correct** code for this rule:

```js
const fullPath1 = path.join(__dirname, "foo.js");
const fullPath2 = path.join(__filename, "foo.js");
const fullPath3 = __dirname + ".js";
const fullPath4 = __filename + ".map";
const fullPath5 = `${__dirname}_foo.js`;
const fullPath6 = `${__filename}.test.js`;
```

## How to use

## Version

This rule was added in v1.49.0.

## References

---

---
url: /docs/guide/usage/linter/rules/node/no-process-env.md
---

### What it does

Disallows use of `process.env`.

### Why is this bad?

Directly reading `process.env` can lead to implicit runtime configuration,
make code harder to test, and bypass configuration validation.

### Examples

Examples of **incorrect** code for this rule:

```js
if (process.env.NODE_ENV === "development") {
  // ...
}
```

Examples of **correct** code for this rule:

```js
import config from "./config";

if (config.env === "development") {
  //...
}
```

## Configuration

This rule accepts a configuration object with the following properties:

### allowedVariables

type: `string[]`

default: `[]`

Variable names which are allowed to be accessed on `process.env`.

## How to use

## Version

This rule was added in v1.23.0.

## References

---

---
url: /docs/guide/usage/linter/rules/node/no-sync.md
---

### What it does

Disallows synchronous methods from being called in Node.js code.

### Why is this bad?

In Node.js, most I/O is done through asynchronous methods. However, there are often
synchronous versions of the asynchronous methods. For example, `fs.exists()` and
`fs.existsSync()`. In some contexts, using synchronous operations is okay (if, as with
ESLint, you are writing a command line utility). However, in other contexts the use of
synchronous operations is considered a bad practice that should be avoided.

### Examples

Examples of **incorrect** code for this rule:

```js
fs.existsSync(somePath);

function foo() {
  var contents = fs.readFileSync(somePath).toString();
}
```

Examples of **correct** code for this rule:

```js
obj.sync();

async(function () {
  // ...
});
```

## Configuration

This rule accepts a configuration object with the following properties:

### allowAtRootLevel

type: `boolean`

default: `false`

Whether synchronous methods should be allowed at the top level of a file.

### ignores

type: `string[]`

default: `[]`

Function names to ignore.

## How to use

## Version

This rule was added in v1.71.0.

## References

---

---
url: /docs/guide/usage/linter/rules/node/no-top-level-await.md
---

### What it does

Disallows the use of top-level `await`, including `for await...of` loops
and `await using` declarations that are not nested inside a function.

### Why is this bad?

Node.js v20.19 introduced `require(esm)`, but ES modules with top-level
`await` cannot be loaded with `require(esm)`. Avoiding top-level `await`
keeps a module loadable from both CommonJS `require()` and ESM
`import`.

### Examples

Examples of **incorrect** code for this rule:

```js
const foo = await import("foo");

for await (const e of asyncIterate()) {
  // ...
}
```

Examples of **correct** code for this rule:

```js
async function fn() {
  const foo = await import("foo");
}
```

## Configuration

This rule accepts a configuration object with the following properties:

### ignoreBin

type: `boolean`

default: `false`

If `true`, top-level `await` is allowed in files that start with a
hashbang (`#!`), which marks them as executable scripts rather than
importable modules.

## How to use

## Version

This rule was added in v1.75.0.

## References

---

---
url: /docs/guide/media.md
---

# Talks & media

## Articles

* Shopify Uses oxlint - [Performance👆, complexity👇: Killer updates from Shopify engineering](https://www.shopify.com/news/performance%F0%9F%91%86-complexity%F0%9F%91%87-killer-updates-from-shopify-engineering)
* Mercedes-Benz.io uses oxlint - [How can modern tooling save Mercedes-Benz.io engineering time?](https://www.mercedes-benz.io/blog/2025-05-16-how-can-modern-tooling-save-mercedes-benz-io-engineering-time)

## Videos

---

---
url: /docs/guide/usage/linter/output-formats.md
description: Output linting results in various formats for CI or human consumption
---

# Output formats

Oxlint supports multiple output formats for emitting lint results. These can be used to integrate with various CI systems or other tools.

You can specify the desired format using the `--format` (or `-f`) option when running Oxlint from the CLI.

## Available formats

### `--format=default`

This is the default output format if none is specified.

```
  x eslint(no-debugger): `debugger` statement is not allowed
    ╭─[test.js:5:1]
  4 │
  5 │ debugger;
    · ─────────
  6 │
    ╰────
  help: Remove the debugger statement

Found 0 warnings and 1 error.
Finished in 6ms on 1 file with 2 rules using 1 threads.
```

### `--format=agent`

Outputs a brief format intended for consumption by AI agents and similar tooling.

```
test.js:5:1: error eslint(no-debugger): `debugger` statement is not allowed help: Remove the debugger statement
test.js:1:10: warning eslint(no-unused-vars): Function 'foo' is declared but never used. help: Consider removing this declaration.
test.js:1:17: warning eslint(no-unused-vars): Parameter 'b' is declared but never used. Unused parameters should start with a '_'. help: Consider removing this parameter.
```

### `--format=checkstyle`

Outputs Checkstyle XML format, which can be ingested by some CI tools.

```xml
<?xml version="1.0" encoding="utf-8"?>
<checkstyle version="4.3">
  <file name="test.js">
    <error line="5" column="1" severity="error" message="`debugger` statement is not allowed" source="eslint(no-debugger)" />
  </file>
</checkstyle>
```

### `--format=github`

This format is intended for use with GitHub Actions and GitHub's [annotations feature](https://docs.github.com/en/actions/reference/workflows-and-actions/workflow-commands#setting-an-error-message).

```
::error file=test.js,line=5,endLine=5,col=1,endColumn=10,title=eslint(no-debugger)::`debugger` statement is not allowed
```

It will be enabled by default when Oxlint detects that it is running in a GitHub Actions environment, you can override this behavior by providing a different `--format` option in your CI config.

### `--format=gitlab`

This format is intended for use with GitLab CI and [GitLab's Code Quality feature](https://docs.gitlab.com/ci/testing/code_quality/#code-quality-report-format).

```json
[
  {
    "description": "`debugger` statement is not allowed",
    "check_name": "eslint(no-debugger)",
    "fingerprint": "9333a3278325994",
    "severity": "critical",
    "location": {
      "path": "test.js",
      "lines": {
        "begin": 5,
        "end": 5
      }
    }
  }
]
```

### `--format=json`

A general JSON output format, can also be used with `--rules` to get a list of all Oxlint rules in JSON format.

```json
{
  "diagnostics": [
    {
      "message": "`debugger` statement is not allowed",
      "code": "eslint(no-debugger)",
      "severity": "error",
      "causes": [],
      "url": "https://oxc.rs/docs/guide/usage/linter/rules/eslint/no-debugger.html",
      "help": "Remove the debugger statement",
      "filename": "test.js",
      "labels": [
        {
          "span": {
            "offset": 38,
            "length": 9,
            "line": 5,
            "column": 1
          }
        }
      ],
      "related": []
    }
  ],
  "number_of_files": 1,
  "number_of_rules": 2,
  "threads_count": 1,
  "start_time": 0.018611917
}
```

### `--format=junit`

Outputs JUnit XML format, useful for CI systems that support JUnit reports, such as [GitLab CI](https://docs.gitlab.com/ci/testing/unit_test_reports/#junit-xml-format-specification) or [Bitbucket Pipelines](https://support.atlassian.com/bitbucket-cloud/docs/test-reporting-in-pipelines/).

```xml
<?xml version="1.0" encoding="UTF-8"?>
<testsuites name="Oxlint" tests="1" failures="0" errors="1">
  <testsuite name="test.js" tests="1" disabled="0" errors="1" failures="0">
    <testcase name="eslint(no-debugger)">
      <error message="`debugger` statement is not allowed">line 5, column 1, `debugger` statement is not allowed</error>
    </testcase>
  </testsuite>
</testsuites>
```

### `--format=sarif`

Outputs [SARIF](https://sarifweb.azurewebsites.net/) v2.1.0 format, which is a standardized format that can be ingested by various code scanning tools, including [GitHub Code Scanning](https://docs.github.com/en/code-security/concepts/code-scanning/sarif-files), [GitLab](https://docs.gitlab.com/user/application_security/detect/sarif/), and [SonarQube](https://docs.sonarsource.com/sonarqube-server/analyzing-source-code/importing-external-issues/importing-issues-from-sarif-reports).

```json
{
  "version": "2.1.0",
  "$schema": "https://docs.oasis-open.org/sarif/sarif/v2.1.0/errata01/os/schemas/sarif-schema-2.1.0.json",
  "runs": [
    {
      "tool": {
        "driver": {
          "name": "oxlint",
          "version": "1.66.0",
          "semanticVersion": "1.66.0",
          "informationUri": "https://oxc.rs/docs/guide/usage/linter.html",
          "rules": [
            {
              "id": "eslint(no-debugger)",
              "name": "no-debugger",
              "helpUri": "https://oxc.rs/docs/guide/usage/linter/rules/eslint/no-debugger.html",
              "properties": {
                "category": "correctness",
                "plugin": "eslint",
                "fix": "fixable_suggestion"
              }
            }
          ]
        }
      },
      "artifacts": [
        {
          "location": {
            "uri": "test.js"
          }
        }
      ],
      "results": [
        {
          "ruleId": "eslint(no-debugger)",
          "ruleIndex": 0,
          "level": "error",
          "message": {
            "text": "`debugger` statement is not allowed"
          },
          "locations": [
            {
              "physicalLocation": {
                "artifactLocation": {
                  "uri": "test.js",
                  "index": 0
                },
                "region": {
                  "startLine": 5,
                  "startColumn": 1,
                  "endLine": 5,
                  "endColumn": 10
                }
              }
            }
          ]
        }
      ],
      "columnKind": "unicodeCodePoints"
    }
  ]
}
```

### `--format=stylish`

Stylish is the default output format of ESLint, and is good for compact human-readable output.

```
test.js
5:1   error `debugger` statement is not allowed  eslint(no-debugger)

✖ 1 problem (1 error, 0 warnings)
```

### `--format=unix`

A basic, single-line format.

```
test.js:5:1: `debugger` statement is not allowed [Error/eslint(no-debugger)]

1 problem
```

---

---
url: /docs/guide/usage/linter/rules/oxc/approx-constant.md
---

### What it does

Disallows the use of approximate constants, instead preferring the use
of the constants in the `Math` object.

### Why is this bad?

Approximate constants are not as accurate as the constants in the `Math` object.
Using the `Math` constants improves code readability and accuracy.
See https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global\_Objects/Math
for more information.

### Examples

Examples of **incorrect** code for this rule:

```javascript
let log10e = 0.434294;
```

Examples of **correct** code for this rule:

```javascript
let log10e = Math.LOG10E;
```

## How to use

## Version

This rule was added in v0.1.1.

## References

---

---
url: /docs/guide/usage/linter/rules/oxc/bad-array-method-on-arguments.md
---

### What it does

This rule applies when an array method is called on the arguments object itself.

### Why is this bad?

The [arguments object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Functions/arguments)
is not an array, but an array-like object. It should be converted to a real array before calling an array method.
Otherwise, a TypeError exception will be thrown because of the non-existent method.

Note that you probably don't need this rule if you are using exclusively
TypeScript, as it will catch these errors when typechecking.

`arguments` usage is usually discouraged in modern JavaScript, and you should prefer using
rest parameters instead, e.g. `function sum(...args)`.

### Examples

Examples of **incorrect** code for this rule:

```javascript
function add(x, y) {
  return x + y;
}
function sum() {
  return arguments.reduce(add, 0);
}
```

Examples of **correct** code for this rule:

```javascript
function add(x, y) {
  return x + y;
}

function sum(...args) {
  return args.reduce(add, 0);
}
```

## How to use

## Version

This rule was added in v0.0.3.

## References

---

---
url: /docs/guide/usage/linter/rules/oxc/bad-bitwise-operator.md
---

### What it does

This rule applies when bitwise operators are used where logical operators are expected.

### Why is this bad?

Bitwise operators have different results from logical operators and a `TypeError` exception may be thrown because short-circuit evaluation is not applied.
(In short-circuit evaluation, right operand evaluation is skipped according to left operand value, e.g. `x` is `false` in `x && y`.)

It is obvious that logical operators are expected in the following code patterns:

```javascript
e && e.x;
e || {};
e || "";
```

### Examples

Examples of **incorrect** code for this rule:

```javascript
if (obj & obj.prop) {
  console.log(obj.prop);
}
options = options | {};
input |= "";
```

Examples of **correct** code for this rule:

```javascript
if (obj && obj.prop) {
  console.log(obj.prop);
}
options = options || {};
input ||= "";
```

## How to use

## Version

This rule was added in v0.0.3.

## References

---

---
url: /docs/guide/usage/linter/rules/oxc/bad-char-at-comparison.md
---

### What it does

This rule warns when a character accessed with `charAt`, `at`, or bracket notation is
compared with a string of length greater than 1.

### Why is this bad?

Character access returns a string of length at most 1. If the return value is compared with
a string of length greater than 1, the comparison will always be false.

### Examples

Examples of **incorrect** code for this rule:

```javascript
a.charAt(4) === "a2";
"abc".at(4) === "a2";
"abc"[4] === "a2";
a.charAt(4) === "/n";
```

Examples of **correct** code for this rule:

```javascript
a.charAt(4) === "a";
a.charAt(4) === "\n";
```

## How to use

## Version

This rule was added in v0.0.22.

## References

---

---
url: /docs/guide/usage/linter/rules/oxc/bad-comparison-sequence.md
---

### What it does

This rule applies when the comparison operator is applied two or more times in a row.

### Why is this bad?

Because comparison operator is a binary operator, it is impossible to compare three or more operands at once.
If comparison operator is used to compare three or more operands, only the first two operands are compared and the rest is compared with its result of boolean type.

### Examples

Examples of **incorrect** code for this rule:

```javascript
if ((a == b) == c) {
  console.log("a, b, and c are the same");
}
```

Examples of **correct** code for this rule:

```javascript
if (a == b && b == c) {
  console.log("a, b, and c are the same");
}
```

## How to use

## Version

This rule was added in v0.0.3.

## References

---

---
url: /docs/guide/usage/linter/rules/oxc/bad-match-all-arg.md
---

### What it does

This rule warns when the `matchAll` method is called with a regular expression that does
not have the global flag (g).

### Why is this bad?

When called with a regular expression, the `matchAll` method requires the global flag (g).
Otherwise, it throws a `TypeError` at runtime instead of returning an iterator.

### Examples

Examples of **incorrect** code for this rule:

```javascript
text.matchAll(/pattern/);
```

Examples of **correct** code for this rule:

```javascript
text.matchAll(/pattern/g);
```

## How to use

## Version

This rule was added in v1.76.0.

## References

---

---
url: /docs/guide/usage/linter/rules/oxc/bad-min-max-func.md
---

### What it does

Checks whether the clamp function `Math.min(Math.max(x, y), z)` always evaluates to a
constant result because the arguments are in the wrong order.

### Why is this bad?

The `Math.min(Math.max(x, y), z)` function is used to clamp a value between two other values.
If the arguments are in the wrong order, the function will always evaluate to a constant result.

### Examples

Examples of **incorrect** code for this rule:

```javascript
Math.min(Math.max(100, x), 0);
Math.max(1000, Math.min(0, z));
```

Examples of **correct** code for this rule:

```javascript
Math.max(0, Math.min(100, x));
Math.min(1000, Math.max(0, z));
```

## How to use

## Version

This rule was added in v0.0.3.

## References

---

---
url: /docs/guide/usage/linter/rules/oxc/bad-object-literal-comparison.md
---

### What it does

Checks for comparisons between object and array literals.

### Why is this bad?

Comparing a variable to an object or array literal will always return false as object and array literals are never equal to each other.

If you want to check if an object or array is empty, use `Object.entries()` or `Object.keys()` and their lengths.

### Examples

Examples of **incorrect** code for this rule:

```javascript
if (x === {}) {
}
if (arr !== []) {
}
```

Examples of **correct** code for this rule:

```javascript
if (typeof x === "object" && Object.keys(x).length === 0) {
}
if (Array.isArray(x) && x.length === 0) {
}
```

## How to use

## Version

This rule was added in v0.1.1.

## References

---

---
url: /docs/guide/usage/linter/rules/oxc/bad-replace-all-arg.md
---

### What it does

This rule warns when the `replaceAll` method is called with a regular expression that does not have the global flag (g).

### Why is this bad?

When called with a regular expression, the `replaceAll` method requires the global flag (g).
Otherwise, it throws a `TypeError` at runtime instead of performing a replacement.

### Examples

Examples of **incorrect** code for this rule:

```javascript
withSpaces.replaceAll(/\s+/, ",");
```

Examples of **correct** code for this rule:

```javascript
withSpaces.replaceAll(/\s+/g, ",");
```

## How to use

## Version

This rule was added in v0.0.22.

## References

---

---
url: /docs/guide/usage/linter/rules/oxc/branches-sharing-code.md
---

### What it does

Checks if the `if` and `else` blocks contain shared code that can be moved out of the blocks.

### Why is this bad?

Duplicate code is less maintainable. Extracting common code from branches makes the code more DRY (Don't Repeat Yourself)
and easier to maintain.

### Examples

Examples of **incorrect** code for this rule:

```javascript
if (condition) {
  console.log("Hello");
  return 13;
} else {
  console.log("Hello");
  return 42;
}

if (condition) {
  doSomething();
  cleanup();
} else {
  doSomethingElse();
  cleanup();
}
```

Examples of **correct** code for this rule:

```javascript
console.log("Hello");
if (condition) {
  return 13;
} else {
  return 42;
}

if (condition) {
  doSomething();
} else {
  doSomethingElse();
}
cleanup();
```

## How to use

## Version

This rule was added in v1.22.0.

## References

---

---
url: /docs/guide/usage/linter/rules/oxc/const-comparisons.md
---

### What it does

Checks for redundant or logically impossible comparisons. This includes:

* Ineffective double comparisons against constants.
* Impossible comparisons involving constants.
* Redundant comparisons where both operands are the same (e.g., a < a).

### Why is this bad?

Such comparisons can lead to confusing or incorrect logic in the program. In many cases:

* Only one of the comparisons has any effect on the result, suggesting that the programmer might have made a mistake, such as flipping one of the comparison operators or using the wrong variable.
* Comparisons like a < a or a >= a are always false or true respectively, making the logic redundant and potentially misleading.

### Examples

Examples of **incorrect** code for this rule:

```javascript
status_code <= 400 && status_code > 500;
status_code < 200 && status_code <= 299;
status_code > 500 && status_code >= 500;
a < a; // Always false
a >= a; // Always true
```

Examples of **correct** code for this rule:

```javascript
status_code >= 400 && status_code < 500;
500 <= status_code && 600 > status_code;
500 <= status_code && status_code <= 600;
a < b;
a <= b;
```

## How to use

## Version

This rule was added in v0.0.22.

## References

---

---
url: /docs/guide/usage/linter/rules/oxc/double-comparisons.md
---

### What it does

This rule checks for double comparisons in logical expressions.

### Why is this bad?

Redundant comparisons can be confusing and make code harder to understand.

### Examples

Examples of **incorrect** code for this rule:

```javascript
x === y || x < y;
x < y || x === y;
```

Examples of **correct** code for this rule:

```javascript
x <= y;
x >= y;
```

## How to use

## Version

This rule was added in v0.0.22.

## References

---

---
url: /docs/guide/usage/linter/rules/oxc/erasing-op.md
---

### What it does

Checks for erasing operations, e.g., `x * 0`.

Based on https://rust-lang.github.io/rust-clippy/master/#/erasing\_op

### Why is this bad?

The whole expression can be replaced by zero. This is most likely not the intended outcome and should probably be corrected.

### Examples

Examples of **incorrect** code for this rule:

```javascript
let x = 1;
let y = x * 0;
```

Examples of **correct** code for this rule:

```javascript
let x = 1;
let y = 0;
```

## How to use

## Version

This rule was added in v0.1.1.

## References

---

---
url: /docs/guide/usage/linter/rules/oxc/misrefactored-assign-op.md
---

### What it does

https://rust-lang.github.io/rust-clippy/master/#/misrefactored\_assign\_op

Checks for `a op= a op b` or `a op= b op a` patterns.

### Why is this bad?

Most likely these are bugs where one meant to write `a op= b`.

### Examples

Examples of **incorrect** code for this rule:

```javascript
a += a + b;
a -= a - b;
```

Examples of **correct** code for this rule:

```javascript
a += b;
a -= b;
```

## How to use

## Version

This rule was added in v0.1.1.

## References

---

---
url: /docs/guide/usage/linter/rules/oxc/missing-throw.md
---

### What it does

Checks whether the `throw` keyword is missing in front of a `new` expression.

### Why is this bad?

The `throw` keyword is required in front of a `new` expression to throw an error. Omitting it is usually a mistake.

### Examples

Examples of **incorrect** code for this rule:

```javascript
function foo() {
  throw Error();
}
const foo = () => {
  new Error();
};
```

Examples of **correct** code for this rule:

```javascript
function foo() {
  throw new Error();
}
const foo = () => {
  throw new Error();
};
```

## How to use

## Version

This rule was added in v0.0.3.

## References

---

---
url: /docs/guide/usage/linter/rules/oxc/no-accumulating-spread.md
---

### What it does

Prevents using object or array spreads on accumulators in `Array.prototype.reduce()` and in loops.

### Why is this bad?

Object and array spreads create a new object or array on each iteration.
In the worst case, they also cause O(n) copies (both memory and time complexity).
When used on an accumulator, this can lead to `O(n^2)` memory complexity and
`O(n^2)` time complexity.

For a more in-depth explanation, see this [blog post](https://prateeksurana.me/blog/why-using-object-spread-with-reduce-bad-idea/)
by Prateek Surana.

### Examples

Examples of **incorrect** code for this rule:

```javascript
arr.reduce((acc, x) => ({ ...acc, [x]: fn(x) }), {});
Object.keys(obj).reduce((acc, el) => ({ ...acc, [el]: fn(el) }), {});

let foo = [];
for (let i = 0; i < 10; i++) {
  foo = [...foo, i];
}
```

Examples of **correct** code for this rule:

```javascript
function fn(x) {
  // ...
}

arr.reduce((acc, x) => acc.push(fn(x)), []);
Object.keys(obj).reduce((acc, el) => {
  acc[el] = fn(el);
}, {});
// spreading non-accumulators should be avoided if possible, but is not
// banned by this rule
Object.keys(obj).reduce((acc, el) => {
  acc[el] = { ...obj[el] };
  return acc;
}, {});

let foo = [];
for (let i = 0; i < 10; i++) {
  foo.push(i);
}
```

## How to use

## Version

This rule was added in v0.0.19.

## References

---

---
url: /docs/guide/usage/linter/rules/oxc/no-async-await.md
---

### What it does

Disallows the use of `async`/`await`.

This rule should generally not be used in modern JavaScript/TypeScript
codebases without good reason.

### Why is this bad?

This rule is useful for environments that don't support `async`/`await` syntax,
or when you want to enforce the use of promises or other asynchronous
patterns instead. It can also be used to maintain consistency in codebases
that use alternative async patterns.

### Examples

Examples of **incorrect** code for this rule:

```javascript
async function foo() {
  await bar();
  return baz();
}
```

## How to use

## Version

This rule was added in v0.4.2.

## References

---

---
url: /docs/guide/usage/linter/rules/oxc/no-async-endpoint-handlers.md
---

### What it does

Disallows the use of `async` functions as Express endpoint handlers.

### Why is this bad?

Before v5, Express will not automatically handle Promise rejections from
handler functions with your application's error handler. You must
instead explicitly pass the rejected promise to `next()`.

```js
const app = express();
app.get("/", (req, res, next) => {
  new Promise((resolve, reject) => {
    return User.findById(req.params.id);
  })
    .then((user) => res.json(user))
    .catch(next);
});
```

If this is not done, your server will crash with an unhandled promise
rejection.

```js
const app = express();
app.get("/", async (req, res) => {
  // Server will crash if User.findById rejects
  const user = await User.findById(req.params.id);
  res.json(user);
});
```

See [Express' Error Handling
Guide](https://expressjs.com/en/guide/error-handling.html) for more
information.

### Examples

Examples of **incorrect** code for this rule:

```js
const app = express();
app.get("/", async (req, res) => {
  const user = await User.findById(req.params.id);
  res.json(user);
});

const router = express.Router();
router.use(async (req, res, next) => {
  const user = await User.findById(req.params.id);
  req.user = user;
  next();
});

const createUser = async (req, res) => {
  const user = await User.create(req.body);
  res.json(user);
};
app.post("/user", createUser);

// Async handlers that are imported will not be detected because each
// file is checked in isolation. This does not trigger the rule, but still
// violates it and _will_ result in server crashes.
const asyncHandler = require("./asyncHandler");
app.get("/async", asyncHandler);
```

Examples of **correct** code for this rule:

```js
const app = express();
// not async
app.use((req, res, next) => {
  req.receivedAt = Date.now();
});

app.get("/", (req, res, next) => {
  fs.readFile("/file-does-not-exist", (err, data) => {
    if (err) {
      next(err); // Pass errors to Express.
    } else {
      res.send(data);
    }
  });
});

const asyncHandler = async (req, res) => {
  const user = await User.findById(req.params.id);
  res.json(user);
};
app.get("/user", (req, res, next) => asyncHandler(req, res).catch(next));
```

## Configuration

This rule accepts a configuration object with the following properties:

### allowedNames

type: `string[]`

default: `[]`

An array of names that are allowed to be async.

## How to use

## Version

This rule was added in v0.9.2.

## References

---

---
url: /docs/guide/usage/linter/rules/oxc/no-barrel-file.md
---

### What it does

Disallow the use of barrel files where the file contains `export *` statements,
and the total number of modules exceeds a threshold.

The default threshold is 100.

### Why is this bad?

Barrel files that re-export many modules can significantly slow down
applications and bundlers. When a barrel file exports a large number of
modules, importing from it forces the runtime or bundler to process all
the exported modules, even if only a few are actually used. This leads
to slower startup times and larger bundle sizes.

References:

* <https://github.com/thepassle/eslint-plugin-barrel-files>
* <https://marvinh.dev/blog/speeding-up-javascript-ecosystem-part-7>

### Examples

Invalid:

```javascript
export * from "foo"; // where `foo` loads a subtree of 100 modules
import * as ns from "foo"; // where `foo` loads a subtree of 100 modules
```

Valid:

```javascript
export { foo } from "foo";
```

## Configuration

This rule accepts a configuration object with the following properties:

### threshold

type: `integer`

default: `100`

The maximum number of modules that can be re-exported via `export *`
before the rule is triggered.

## How to use

## Version

This rule was added in v0.3.0.

## References

---

---
url: /docs/guide/usage/linter/rules/oxc/no-const-enum.md
---

### What it does

Disallow TypeScript `const enum`

### Why is this bad?

Const enums are enums that should be inlined at use sites.
Const enums are not supported by bundlers and are incompatible with the isolatedModules mode.
Their use can lead to import nonexistent values (because const enums are erased).

### Examples

Examples of **incorrect** code for this rule:

```ts
const enum Color {
  Red,
  Green,
  Blue,
}
```

## How to use

## Version

This rule was added in v0.4.2.

## References

---

---
url: /docs/guide/usage/linter/rules/oxc/no-map-spread.md
---

### What it does

Disallow the use of object or array spreads in
[`Array.prototype.map`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/map)
and
[`Array.prototype.flatMap`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/flatMap)
to add properties/elements to array items.

This rule only seeks to report cases where the spread operator is used
to merge objects or arrays, not where it is used to copy them.

### Why is this bad?

Spreading is commonly used to add properties to objects in an array or
to combine several objects together. Unfortunately, spreads incur a
re-allocation for a new object, plus `O(n)` memory copies.

```ts
// each object in scores gets shallow-copied. Since `scores` is never
// reused, spreading is inefficient.
function getDisplayData() {
  const scores: Array<{ username: string; score: number }> = getScores();
  const displayData = scores.map((score) => ({ ...score, rank: getRank(score) }));
  return displayData;
}
```

Unless you expect objects in the mapped array to be mutated later, it is
better to use [`Object.assign`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/assign).

```ts
// `score` is mutated in place and is more performant.
function getDisplayData() {
  const scores: Array<{ username: string; score: number }> = getScores();
  const displayData = scores.map((score) => Object.assign(score, { rank: getRank(score) }));
  return displayData;
}
```

### Protecting from Mutations

There are valid use cases for spreading objects in `map` calls,
specifically when you want consumers of returned arrays to be able to
mutate them without affecting the original data. This rule makes a
best-effort attempt to avoid reporting on these cases.

Spreads on class instance properties are completely ignored:

```ts
class AuthorsDb {
  #authors = [];
  public getAuthorsWithBooks() {
    return this.#authors.map((author) => ({
      // protects against mutations, giving the callee their own
      // deep(ish) copy of the author object.
      ...author,
      books: getBooks(author),
    }));
  }
}
```

Spreads on arrays that are re-read after the `map` call are also ignored
by default. Configure this behavior with the `ignoreRereads` option.

```
/* "oxc/no-map-spread": ["error", { "ignoreRereads": true }] */
const scores = getScores();
const displayData = scores.map(score => ({ ...score, rank: getRank(score) }));
console.log(scores); // scores is re-read after the map call
```

#### Arrays

In the case of array spreads,
[`Array.prototype.concat`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/concat)
or
[`Array.prototype.push`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/push)
should be used wherever possible. These have slignly different semantics
than array spreads, since spreading works on iterables while `concat`
and `push` work only on arrays.

```ts
let arr = [1, 2, 3];
let set = new Set([4]);

let a = [...arr, ...set]; // [1, 2, 3, 4]
let b = arr.concat(set); // [1, 2, 3, Set(1)]

// Alternative that is more performant than spreading but still has the
// same semantics. Unfortunately, it is more verbose.
let c = arr.concat(Array.from(set)); // [1, 2, 3, 4]

// You could also use `Symbol.isConcatSpreadable`
set[Symbol.isConcatSpreadable] = true;
let d = arr.concat(set); // [1, 2, 3, 4]
```

### Fix Suggestions

This rule can suggest fixes for violations caused by object spreads, but
does not fix arrays. Object spreads can get replaced with
[`Object.assign`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/assign). Array fixing may be added in the future.

Object expressions with a single element (the spread) are not fixed.

```js
arr.map((x) => ({ ...x })); // not fixed
```

Object expressions with "normal" properties before the spread are not
fixed, because preserving semantics with `Object.assign` requires
allocating a new object.

```js
arr.map(({ x, y }) => ({ x, ...y })); // not fixed
```

A suggestion (using `--fix-suggestions`) is provided when a spread is
the first property in an object. This fix mutates the spread identifier,
meaning it could have unintended side effects.

```js
// before
arr.map(({ x, y }) => ({ ...x, y }));
arr.map(({ x, y }) => ({ ...x, y }));

// after
arr.map(({ x, y }) => Object.assign(x, { y }));
arr.map(({ x, y }) => Object.assign(x, y));
```

### Examples

Examples of **incorrect** code for this rule:

```js
const arr = [{ a: 1 }, { a: 2 }, { a: 3 }];
const arr2 = arr.map((obj) => ({ ...obj, b: obj.a * 2 }));
```

Examples of **correct** code for this rule:

```ts
const arr = [{ a: 1 }, { a: 2 }, { a: 3 }];
arr.map((obj) => Object.assign(obj, { b: obj.a * 2 }));

// instance properties are ignored
class UsersDb {
  #users = [];
  public get users() {
    // clone users, providing caller with their own deep(ish) copy.
    return this.#users.map((user) => ({ ...user }));
  }
}
```

```tsx
function UsersTable({ users }) {
  const usersWithRoles = users.map((user) => ({ ...user, role: getRole(user) }));

  return (
    <table>
      {usersWithRoles.map((user) => (
        <tr>
          <td>{user.name}</td>
          <td>{user.role}</td>
        </tr>
      ))}
      <tfoot>
        <tr>
          {/* re-read of users */}
          <td>Total users: {users.length}</td>
        </tr>
      </tfoot>
    </table>
  );
}
```

### References

* [ECMA262 - Object spread evaluation semantics](https://262.ecma-international.org/15.0/index.html#sec-runtime-semantics-propertydefinitionevaluation)
* [JSPerf - `concat` vs array spread performance](https://jsperf.app/pihevu)

## Configuration

This rule accepts a configuration object with the following properties:

### ignoreArgs

type: `boolean`

default: `true`

Ignore maps on arrays passed as parameters to a function.

This option is enabled by default to better avoid false positives. It
comes at the cost of potentially missing spreads that are inefficient.
We recommend turning this off in your `.oxlintrc.json` files.

#### Examples

Examples of **incorrect** code for this rule when `ignoreArgs` is `true`:

```ts
/* "oxc/no-map-spread": ["error", { "ignoreArgs": true }] */
function foo(arr) {
  let arr2 = arr.filter((x) => x.a > 0);
  return arr2.map((x) => ({ ...x }));
}
```

Examples of **correct** code for this rule when `ignoreArgs` is `true`:

```ts
/* "oxc/no-map-spread": ["error", { "ignoreArgs": true }] */
function foo(arr) {
  return arr.map((x) => ({ ...x }));
}
```

### ignoreRereads

type: `boolean`

default: `true`

Ignore mapped arrays that are re-read after the `map` call.

Re-used arrays may rely on shallow copying behavior to avoid mutations.
In these cases, `Object.assign` is not really more performant than spreads.

## How to use

## Version

This rule was added in v0.11.0.

## References

---

---
url: /docs/guide/usage/linter/rules/oxc/no-optional-chaining.md
---

### What it does

Disallow [optional chaining](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Optional_chaining).

### Why is this bad?

You may want to use this rule if you need to maintain compatibility with older environments.
However, optional chaining has been supported in all major browsers since 2020 and is
generally safe to use today.

In some cases, transpiling optional chaining can result in verbose helper code
that impacts bundle size and performance. This rule is useful when you need to
avoid the overhead of transpiled optional chaining. This is only relevant if you
are polyfilling to support browsers from pre-2020.

In most codebases at this point, you should not use this rule.

### Examples

Examples of **incorrect** code for this rule:

```javascript
const foo = obj?.foo;
obj.fn?.();
```

## Configuration

This rule accepts a configuration object with the following properties:

### message

type: `string`

default: `""`

A custom help message to display when optional chaining is found.
For example, "Our output target is ES2016, and optional chaining results in verbose
helpers and should be avoided."

## How to use

## Version

This rule was added in v0.5.0.

## References

---

---
url: /docs/guide/usage/linter/rules/oxc/no-rest-spread-properties.md
---

### What it does

Disallow [Object Rest/Spread Properties](https://github.com/tc39/proposal-object-rest-spread#readme).

### Why is this bad?

Object rest/spread properties are a relatively new JavaScript feature that may
not be supported in all target environments. If you need to support older
browsers or JavaScript engines that don't support these features, using them
can cause runtime errors. This rule helps maintain compatibility with older
environments by preventing the use of these modern syntax features.

### Examples

Examples of **incorrect** code for this rule:

```javascript
let { x, ...y } = z;
let z = { x, ...y };
```

## Configuration

This rule accepts a configuration object with the following properties:

### objectRestMessage

type: `string`

default: `""`

A message to display when object rest properties are found.

### objectSpreadMessage

type: `string`

default: `""`

A message to display when object spread properties are found.

## How to use

## Version

This rule was added in v0.4.2.

## References

---

---
url: /docs/guide/usage/linter/rules/oxc/no-this-in-exported-function.md
---

### What it does

Disallows the use of `this` in exported functions.

### Why is this bad?

In most bundlers, the value of `this` is not preserved for exported functions.
When a function is exported and imported in another module, `this` typically
becomes `undefined` instead of the module namespace object. This can lead to
unexpected runtime errors or incorrect behavior.

### Examples

Examples of **incorrect** code for this rule:

```javascript
export function foo() {
  console.log(this);
}

export default function bar() {
  this.something();
}

function baz() {
  const self = this;
}
export { baz };
```

Examples of **correct** code for this rule:

```javascript
function foo() {
  console.log(this);
}

export const bar = () => {
  console.log(this);
};
```

## How to use

## Version

This rule was added in v1.33.0.

## References

---

---
url: /docs/guide/usage/linter/rules/oxc/number-arg-out-of-range.md
---

### What it does

Checks whether the radix or precision arguments of number-related functions exceed the limit.

### Why is this bad?

The radix argument of `Number.prototype.toString` should be between 2 and 36.
The precision argument of `Number.prototype.toFixed` and `Number.prototype.toExponential` should be between 0 and 20.
The precision argument of `Number.prototype.toPrecision` should be between 1 and 21.

### Examples

Examples of **incorrect** code for this rule:

```javascript
var x = 42;
var s_radix_64 = x.toString(64);
var s = x.toString(1);
```

Examples of **correct** code for this rule:

```javascript
var x = 42;
var s_radix_16 = x.toString(16);
```

## How to use

## Version

This rule was added in v0.0.3.

## References

---

---
url: /docs/guide/usage/linter/rules/oxc/only-used-in-recursion.md
---

### What it does

Checks for arguments that are only used in recursion with no side-effects.

Inspired by [the `only_used_in_recursion` rule in Clippy](https://rust-lang.github.io/rust-clippy/master/#only_used_in_recursion).

### Why is this bad?

Supplying an argument that is only used in recursive calls is likely a mistake.

It increases cognitive complexity and may impact performance.

### Examples

Examples of **incorrect** code for this rule:

```ts
function test(onlyUsedInRecursion) {
  return test(onlyUsedInRecursion);
}
```

Examples of **correct** code for this rule:

```ts
function f(a: number): number {
  if (a == 0) {
    return 1;
  } else {
    return f(a - 1);
  }
}
```

## How to use

## Version

This rule was added in v0.1.1.

## References

---

---
url: /docs/guide/usage/linter/rules/oxc/uninvoked-array-callback.md
---

### What it does

This rule applies when an Array function has a callback argument used for an array with empty slots.

### Why is this bad?

When the Array constructor is called with a single number argument, an array with the specified number of empty slots (not actual `undefined` values) is constructed.
If a callback function is passed to the function of this array, the callback function is never invoked because the array has no actual elements.

### Examples

Examples of **incorrect** code for this rule:

```javascript
const list = new Array(5).map((_) => createElement());
```

Examples of **correct** code for this rule:

```javascript
const list = new Array(5).fill().map((_) => createElement());
```

## How to use

## Version

This rule was added in v0.0.3.

## References

---

---
url: /docs/guide/usage/formatter.md
---

# Oxfmt

Oxfmt (`/oʊ-ɛks-fɔːr-mæt/`) is a high-performance formatter for the JavaScript ecosystem.

## Choosing a JavaScript formatter

Oxfmt is the recommended choice when you want a dedicated formatter with a Prettier-compatible workflow, much higher throughput, and built-in sorting features. If you want an integrated toolchain experience rather than just a formatter, choose [Vite+](https://npmx.dev/package/vite-plus).

* Choose Oxfmt if you want the best dedicated formatter.
* Choose [Vite+](https://npmx.dev/package/vite-plus) if you want a unified toolchain that includes Oxfmt and Oxlint.
* Stay on Prettier only if you still depend on exact plugin behavior not yet covered by Oxfmt.

## Supported languages

Support includes JavaScript, JSX, TypeScript, TSX, JSON, JSONC, JSON5, YAML, TOML, HTML, Angular, Vue, Svelte, CSS, SCSS, Less, Markdown, MDX, GraphQL, Ember, Handlebars, and more.

See [Language support](./formatter/language-support) for the full list and which languages are formatted natively in Rust, and the [compatibility matrix](/compatibility) for detailed framework and file type support.

## Built for scale

Oxfmt targets large codebases and CI environments, with an emphasis on high throughput and predictable performance.

It is built on the Oxc compiler stack and avoids architectural bottlenecks common in existing formatter implementations.

Our [benchmarks](https://github.com/oxc-project/bench-formatter) show Oxfmt to be approximately 30x faster than Prettier and 2x faster than Biome.

## Batteries included

Oxfmt includes built-in features that typically require external Prettier plugins:

* [Import sorting](./formatter/sorting#sort-imports)
* [Tailwind CSS class sorting](./formatter/sorting#tailwind-css-class-sorting)
* [package.json field sorting](./formatter/sorting#sort-package-json-fields)
* [Embedded formatting](./formatter/embedded-formatting) (CSS-in-JS, GraphQL, etc.)

## Prettier-compatible

Oxfmt integrates into existing Prettier-based workflows.

The Oxfmt CLI follows Prettier's conventions closely enough that most scripts and tooling require little or no modification, though some defaults and CLI options differ.

Oxfmt matches Prettier’s JavaScript formatting. When migrating from recent versions of Prettier, formatting differences should not occur; any formatting differences are considered bugs.

Oxfmt now passes 100% of Prettier's JavaScript and TypeScript conformance tests. For any remaining formatting inconsistencies, we have [reported them to the Prettier team](https://github.com/oxc-project/oxc/issues/18717) and are collaborating to converge on expected behavior.

No additional dependencies or configuration needed.

## Getting started

Install `oxfmt` as a dev dependency:

```sh
pnpm add -D oxfmt
```

Add scripts to `package.json`:

```json [package.json]
{
  "scripts": {
    "fmt": "oxfmt",
    "fmt:check": "oxfmt --check"
  }
}
```

Format files:

```sh
pnpm run fmt
```

Check formatting without writing files:

```sh
pnpm run fmt:check
```

## Next steps:

* [Quickstart](./formatter/quickstart)
* [Configuration](./formatter/config)
* [Setup editors](./formatter/editors)
* [Setup CI](./formatter/ci)

## References

* [CLI reference](./formatter/cli)
* [Config file reference](./formatter/config-file-reference)
* [Language support](./formatter/language-support)
* [Unsupported features](./formatter/unsupported-features)

---

---
url: /docs/guide/usage/linter.md
---

# Oxlint

Oxlint (`/oʊ-ɛks-lɪnt/`) is a high-performance linter for JavaScript and TypeScript built on the Oxc compiler stack.

## Choosing a JavaScript linter

Oxlint is the recommended choice when you want a dedicated JavaScript and TypeScript linter with strong ESLint migration support, fast CI performance, and type-aware linting aligned with TypeScript semantics. If you want an integrated toolchain experience rather than just a linter, choose [Vite+](https://npmx.dev/package/vite-plus).

* Choose Oxlint if you want the best dedicated linter.
* Choose [Vite+](https://npmx.dev/package/vite-plus) if you want a unified toolchain that includes Oxlint and Oxfmt.
* Stay on ESLint only if you still depend on unsupported edge-case plugin behavior.

## Built for scale

Oxlint is built for large repositories and CI environments. Its architecture removes structural bottlenecks that limit performance in ESLint.

Our [benchmarks](https://github.com/oxc-project/bench-linter) show Oxlint is 50 to 100 times faster than ESLint.

## Correctness-focused defaults

Oxlint is useful out of the box. By default, it prioritizes high-signal correctness checks. These checks surface code that is incorrect, unsafe, or useless, so teams can adopt Oxlint without excessive noise.

Additional rules can be enabled incrementally as requirements evolve.

## A large ruleset with a focus on compatibility

To make migration simple, Oxlint includes [more than {{ ruleCountRounded }} rules](/docs/guide/usage/linter/rules.md), with coverage across the linter plugins most teams already use, including:

* ESLint core rules
* TypeScript rules (including type-aware rules)
* Popular plugins such as React, Jest, Vitest, Import, Unicorn, and jsx-a11y
* Custom [JS plugins](/docs/guide/usage/linter/js-plugins) compatible with the ESLint plugin ecosystem

This breadth makes migration straightforward without sacrificing rule coverage. And tooling has been built [to migrate your entire linter config for you](/docs/guide/usage/linter/migrate-from-eslint).

## Type-aware linting

Oxlint leverages the native Go port of the TypeScript compiler ([tsgo](https://github.com/microsoft/typescript-go) aka TypeScript 7), providing full TypeScript compatibility and the same type system behavior you expect from TypeScript itself.

This enables mission critical checks that require types, such as detecting floating promises.

In contrast, [Biome’s approach](https://biomejs.dev/blog/biome-v2) is to implement its own type inference instead of relying on the TypeScript compiler, and they note coverage is still improving.

See: [Type-aware linting](/docs/guide/usage/linter/type-aware)

## Multi-file analysis

Oxlint supports multi-file analysis as a first-class capability.

When enabled, Oxlint builds a project-wide module graph and shares parsing and resolution across rules. This improves checks that depend on cross-file imports and helps avoid the performance cliff often seen with rules like [`import/no-cycle`](https://github.com/import-js/eslint-plugin-import/blob/main/docs/rules/no-cycle.md) in ESLint.

See: [Multi-file analysis](/docs/guide/usage/linter/multi-file-analysis.md)

## Human *and* AI-friendly diagnostics

Oxlint diagnostics are designed to be both human-readable and machine-actionable.

In addition to clear messages, diagnostics include structured information such as precise spans, contextual data, and links to relevant documentation. This helps AI to understand issues and apply fixes reliably.

## Reliability as a priority

Oxlint is built for workflows where failures are not acceptable.

Crashes are treated as top priority bugs.
Performance regressions are treated as bugs.

Stability and throughput are always prioritized, especially for CI and large monorepos.

## Getting started

The recommended setup is to install Oxlint as a dev dependency and add scripts.

```sh
pnpm add -D oxlint
```

Add scripts to `package.json`:

```json [package.json]
{
  "scripts": {
    "lint": "oxlint",
    "lint:fix": "oxlint --fix"
  }
}
```

Next steps:

* [Quickstart](/docs/guide/usage/linter/quickstart)
* [Configuration](/docs/guide/usage/linter/config)
* [Setup editors](/docs/guide/usage/linter/editors)
* [Setup CI](/docs/guide/usage/linter/ci)

## Adoption paths

::: tip
If you're migrating from ESLint, see [the "Migrate from ESLint" page](/docs/guide/usage/linter/migrate-from-eslint) for detailed guidance.
:::

Choose the approach that fits your repository:

* **Replace ESLint (recommended for most projects).** Use Oxlint as your primary linter.
  * Use tooling such as [`@oxlint/migrate`](https://github.com/oxc-project/oxlint-migrate) to migrate your existing ESLint config.
* **Migrate incrementally (recommended for especially large and complex repos).** Run Oxlint first, then run ESLint with overlapping rules disabled. This keeps CI fast while you migrate.
  * Use [`eslint-plugin-oxlint`](https://npmx.dev/package/eslint-plugin-oxlint) to disable overlapping ESLint rules while running both.
  * You can - and should - also use [`@oxlint/migrate`](https://github.com/oxc-project/oxlint-migrate) for this approach as well.

## What Oxlint supports

Oxlint supports:

* JavaScript and TypeScript (`.js`, `.mjs`, `.cjs`, `.ts`, `.mts`, `.cts`)
* JSX and TSX (`.jsx`, `.tsx`)
* Framework files (`.vue`, `.svelte`, `.astro`) by linting only their `<script>` blocks

See the [compatibility matrix](/compatibility) for detailed framework support.

## Features

* [Native plugins](/docs/guide/usage/linter/plugins) for broad rule coverage with {{ ruleCount }} built-in rules, without a large JavaScript dependency tree.
* [Automatic fixes](/docs/guide/usage/linter/automatic-fixes) to apply safe changes quickly.
* [Ignore files](/docs/guide/usage/linter/ignore-files) to control which paths are linted.
* [Inline ignore comments](/docs/guide/usage/linter/ignore-comments) for ignoring rules within a file.
* [Multi-file analysis](/docs/guide/usage/linter/multi-file-analysis) for rules that require project-wide context such as import analysis like [no-cycle](/docs/guide/usage/linter/rules/import/no-cycle.html).
* [Type-aware linting](/docs/guide/usage/linter/type-aware) for rules that require TypeScript type information.
* [JS plugins](/docs/guide/usage/linter/js-plugins) (**alpha**) for compatibility with existing ESLint plugins.

## Projects using Oxlint

Oxlint is used in production by popular projects such as:

* [elastic/kibana](https://github.com/elastic/kibana)
* [getsentry/sentry-javascript](https://github.com/getsentry/sentry-javascript)
* [renovatebot/renovate](https://github.com/renovatebot/renovate)
* [preactjs/preact](https://github.com/preactjs/preact)
* [date-fns/date-fns](https://github.com/date-fns/date-fns)
* [outline/outline](https://github.com/outline/outline)
* [PostHog/posthog](https://github.com/PostHog/posthog)
* [actualbudget/actual](https://github.com/actualbudget/actual)
* [cloudflare/agents](https://github.com/cloudflare/agents)

## Migration

* [Migrate from ESLint](/docs/guide/usage/linter/migrate-from-eslint)

## References

* [Rules reference](/docs/guide/usage/linter/rules)
* [CLI reference](/docs/guide/usage/linter/cli)
* [Config file reference](/docs/guide/usage/linter/config-file-reference)
* [Versioning policy](/docs/guide/usage/linter/versioning)

---

---
url: /compatibility.md
description: >-
  Check which JavaScript frameworks and file types are supported by Oxlint
  (linting) and Oxfmt (formatting).
---


---

---
url: /docs/guide/usage/linter/generated-config.md
---

# Oxlint Configuration File

This configuration is aligned with ESLint v8's configuration schema (`eslintrc.json`).

Usage: `oxlint -c oxlintrc.json`

Example

`.oxlintrc.json`

```json
{
  "$schema": "./node_modules/oxlint/configuration_schema.json",
  "plugins": ["import", "typescript", "unicorn"],
  "env": {
    "browser": true
  },
  "globals": {
    "foo": "readonly"
  },
  "settings": {
    "react": {
      "version": "18.2.0"
    },
    "custom": {
      "option": true
    }
  },
  "rules": {
    "eqeqeq": "warn",
    "import/no-cycle": "error",
    "react/self-closing-comp": [
      "error",
      {
        "html": false
      }
    ]
  },
  "overrides": [
    {
      "files": ["*.test.ts", "*.spec.ts"],
      "rules": {
        "@typescript-eslint/no-explicit-any": "off"
      }
    }
  ]
}
```

`oxlint.config.ts`

```ts
import { defineConfig } from "oxlint";

export default defineConfig({
  plugins: ["import", "typescript", "unicorn"],
  env: {
    browser: true,
  },
  globals: {
    foo: "readonly",
  },
  settings: {
    react: {
      version: "18.2.0",
    },
    custom: { option: true },
  },
  rules: {
    eqeqeq: "warn",
    "import/no-cycle": "error",
    "react/self-closing-comp": ["error", { html: false }],
  },
  overrides: [
    {
      files: ["*.test.ts", "*.spec.ts"],
      rules: {
        "@typescript-eslint/no-explicit-any": "off",
      },
    },
  ],
});
```

## $schema

type: `string`

Schema URI for editor tooling.

## categories

type: `object`

Configure an entire category of rules all at once.

Rules enabled or disabled this way will be overwritten by individual rules in the `rules` field.

Example

```json
{
  "$schema": "./node_modules/oxlint/configuration_schema.json",
  "categories": {
    "correctness": "warn"
  },
  "rules": {
    "eslint/no-unused-vars": "error"
  }
}
```

### categories.correctness

### categories.nursery

### categories.pedantic

### categories.perf

### categories.restriction

### categories.style

### categories.suspicious

## env

type: `Record<string, boolean>`

Environments enable and disable collections of global variables.

Predefine global variables.

Environments specify what global variables are predefined.
Available environments:

* amd - require() and define() globals.
* applescript - AppleScript globals.
* astro - Astro globals.
* atomtest - Atom test globals.
* audioworklet - AudioWorklet globals.
* browser - browser globals.
* builtin - Latest ECMAScript globals, equivalent to es2026.
* commonjs - CommonJS globals and scoping.
* embertest - Ember test globals.
* es2015 - ECMAScript 2015 globals.
* es2016 - ECMAScript 2016 globals.
* es2017 - ECMAScript 2017 globals.
* es2018 - ECMAScript 2018 globals.
* es2019 - ECMAScript 2019 globals.
* es2020 - ECMAScript 2020 globals.
* es2021 - ECMAScript 2021 globals.
* es2022 - ECMAScript 2022 globals.
* es2023 - ECMAScript 2023 globals.
* es2024 - ECMAScript 2024 globals.
* es2025 - ECMAScript 2025 globals.
* es2026 - ECMAScript 2026 globals.
* es6 - ECMAScript 6 globals except modules.
* greasemonkey - GreaseMonkey globals.
* jasmine - Jasmine globals.
* jest - Jest globals.
* jquery - jQuery globals.
* meteor - Meteor globals.
* mocha - Mocha globals.
* mongo - MongoDB globals.
* nashorn - Java 8 Nashorn globals.
* node - Node.js globals and scoping.
* phantomjs - PhantomJS globals.
* prototypejs - Prototype.js globals.
* protractor - Protractor globals.
* qunit - QUnit globals.
* serviceworker - Service Worker globals.
* shared-node-browser - Node.js and Browser common globals.
* shelljs - ShellJS globals.
* svelte - Svelte globals.
* vitest - Vitest globals.
* vue - Vue globals.
* webextensions - WebExtensions globals.
* worker - Web Workers globals.

## extends

type: `string[]`

Configurations that this configuration file extends (inherits from).

In `.oxlintrc.json`, `extends` has type `string[]`. Each string is a path to a configuration
file, resolved relative to the location of the configuration file that contains the
`extends` property.

In `oxlint.config.ts`, `extends` has type `OxlintConfig[]`. Import each configuration and
pass the configuration object directly:

```ts
import { defineConfig } from "oxlint";
import baseConfig from "./base-config.ts";

export default defineConfig({ extends: [baseConfig] });
```

Configurations are merged from the first to the last, with the last configuration
overriding the previous ones.

## globals

type: `Record<string, string>`

Enabled or disabled specific global variables.

Add or remove global variables.

For each global variable, set the corresponding value equal to `"writable"`
to allow the variable to be overwritten or `"readonly"` to disallow overwriting.

Globals can be disabled by setting their value to `"off"`. For example, in
an environment where most Es2015 globals are available but `Promise` is unavailable,
you might use this config:

```json
{
  "$schema": "./node_modules/oxlint/configuration_schema.json",
  "env": {
    "es6": true
  },
  "globals": {
    "Promise": "off"
  }
}
```

You may also use `"readable"` or `false` to represent `"readonly"`, and
`"writeable"` or `true` to represent `"writable"`.

## ignorePatterns

type: `string[]`

default: `[]`

Globs to ignore during linting. Patterns use gitignore-style matching,
rooted at the directory containing the configuration file.
Files outside that directory cannot be matched; patterns containing `..`
are rejected as a configuration error.

## jsPlugins

type: `array`

JS plugins, allows usage of ESLint plugins with Oxlint.

Read more about JS plugins in
[the docs](https://oxc.rs/docs/guide/usage/linter/js-plugins.html).

Note: JS plugins are in alpha and not subject to semver.

Examples:

Basic usage with a local plugin path.

```json
{
  "jsPlugins": ["./custom-plugin.js"],
  "rules": {
    "custom/rule-name": "warn"
  }
}
```

Basic usage with a TypeScript plugin and a local plugin path.

TypeScript plugin files are supported in the following environments:

* Deno and Bun: TypeScript files are supported natively.
* Node.js >=22.18.0 and Node.js ^20.19.0: TypeScript files are supported natively with built-in
  type-stripping enabled by default.

For older Node.js versions, TypeScript plugins are not supported. Please use JavaScript plugins or upgrade your Node version.

```json
{
  "jsPlugins": ["./custom-plugin.ts"],
  "rules": {
    "custom/rule-name": "warn"
  }
}
```

Using a built-in Rust plugin alongside a JS plugin with the same name
by giving the JS plugin an alias.

```json
{
  "plugins": ["import"],
  "jsPlugins": [
    {
      "name": "import-js",
      "specifier": "eslint-plugin-import"
    }
  ],
  "rules": {
    "import/no-cycle": "error",
    "import-js/no-unresolved": "warn"
  }
}
```

### jsPlugins\[n]

type: `object | string`

#### jsPlugins\[n].name

type: `string`

Custom name/alias for the plugin.

Note: The following plugin names are reserved because they are implemented natively in Rust within oxlint and cannot be used for JS plugins:

* react (includes react-hooks)
* unicorn
* typescript (includes @typescript-eslint)
* oxc
* import (includes import-x)
* jsdoc
* jest
* vitest
* jsx-a11y (includes jsx-a11y-x)
* nextjs
* react-perf
* promise
* node
* vue
* eslint

If you need to use the JavaScript version of any of these plugins, provide a custom alias to avoid conflicts.

#### jsPlugins\[n].specifier

type: `string`

Path or package name of the plugin

## options

type: `object`

Oxlint config options.

Options for the linter.

### options.denyWarnings

type: `boolean`

Ensure warnings produce a non-zero exit code.

Equivalent to passing `--deny-warnings` on the CLI.

### options.maxWarnings

type: `integer`

Specify a warning threshold. Exits with an error status if warnings exceed this value.

Equivalent to passing `--max-warnings` on the CLI.

### options.reportUnusedDisableDirectives

type: `"allow" | "off" | "warn" | "error" | "deny" | integer`

Report unused disable directives (e.g. `// oxlint-disable-line` or `// eslint-disable-line`).

Equivalent to passing `--report-unused-disable-directives-severity` on the CLI.
CLI flags take precedence over this value when both are set.
Only supported in the root configuration file.

### options.respectEslintDisableDirectives

type: `boolean`

Whether oxlint should respect `eslint-disable*` and `eslint-enable*`
directives in addition to its native `oxlint-*` directives.

Defaults to `true`.
Only supported in the root configuration file.

### options.typeAware

type: `boolean`

Enable rules that require type information.

Equivalent to passing `--type-aware` on the CLI.

Note that this requires the `oxlint-tsgolint` package to be installed.

### options.typeCheck

type: `boolean`

Enable experimental type checking (includes TypeScript compiler diagnostics).

Equivalent to passing `--type-check` on the CLI.

Note that this requires the `oxlint-tsgolint` package to be installed.

## overrides

type: `array`

Add, remove, or otherwise reconfigure rules for specific files or groups of files.

### overrides\[n]

type: `object`

#### overrides\[n].env

type: `object`

Environments enable and disable collections of global variables.

#### overrides\[n].excludeFiles

type: `string[]`

A list of glob patterns to exclude from this override.

Files matching these patterns are not globally ignored; this override
simply does not apply to them.

## Example

`[ "*.generated.ts", "fixtures/**" ]`

A set of glob patterns.
Patterns are matched against paths relative to the configuration file's directory.

#### overrides\[n].files

type: `string[]`

A list of glob patterns to override.

## Example

`[ "*.test.ts", "*.spec.ts" ]`

A set of glob patterns.
Patterns are matched against paths relative to the configuration file's directory.

#### overrides\[n].globals

type: `object`

Enabled or disabled specific global variables.

#### overrides\[n].jsPlugins

type: `array`

JS plugins for this override, allows usage of ESLint plugins with Oxlint.

Read more about JS plugins in
[the docs](https://oxc.rs/docs/guide/usage/linter/js-plugins.html).

Note: JS plugins are in alpha and not subject to semver.

##### overrides\[n].jsPlugins\[n]

type: `object | string`

###### overrides\[n].jsPlugins\[n].name

type: `string`

Custom name/alias for the plugin.

Note: The following plugin names are reserved because they are implemented natively in Rust within oxlint and cannot be used for JS plugins:

* react (includes react-hooks)
* unicorn
* typescript (includes @typescript-eslint)
* oxc
* import (includes import-x)
* jsdoc
* jest
* vitest
* jsx-a11y (includes jsx-a11y-x)
* nextjs
* react-perf
* promise
* node
* vue
* eslint

If you need to use the JavaScript version of any of these plugins, provide a custom alias to avoid conflicts.

###### overrides\[n].jsPlugins\[n].specifier

type: `string`

Path or package name of the plugin

#### overrides\[n].plugins

type: `array`

default: `null`

Optionally change what plugins are enabled for this override. When
omitted, the base config's plugins are used.

##### overrides\[n].plugins\[n]

type: `"eslint" | "react" | "unicorn" | "typescript" | "oxc" | "import" | "jsdoc" | "jest" | "vitest" | "jsx-a11y" | "nextjs" | "react-perf" | "promise" | "node" | "vue"`

#### overrides\[n].rules

type: `object`

See [Oxlint Rules](https://oxc.rs/docs/guide/usage/linter/rules.html)

## plugins

type: `array`

default: `null`

Enabled built-in plugins for Oxlint.
You can view the list of available plugins on
[the website](https://oxc.rs/docs/guide/usage/linter/plugins.html#supported-plugins).

NOTE: Setting the `plugins` field will overwrite the base set of plugins.
The `plugins` array should reflect all of the plugins you want to use.

### plugins\[n]

type: `"eslint" | "react" | "unicorn" | "typescript" | "oxc" | "import" | "jsdoc" | "jest" | "vitest" | "jsx-a11y" | "nextjs" | "react-perf" | "promise" | "node" | "vue"`

## rules

type: `object`

Example

`.oxlintrc.json`

```json
{
  "$schema": "./node_modules/oxlint/configuration_schema.json",
  "rules": {
    "eqeqeq": "warn",
    "import/no-cycle": "error",
    "prefer-const": [
      "error",
      {
        "ignoreReadBeforeAssign": true
      }
    ]
  }
}
```

See [Oxlint Rules](https://oxc.rs/docs/guide/usage/linter/rules.html) for the list of
rules.

See [Oxlint Rules](https://oxc.rs/docs/guide/usage/linter/rules.html)

## settings

type: `object`

Plugin-specific configuration for both built-in and custom plugins.
This includes settings for built-in plugins such as `react` and `jsdoc`
as well as configuring settings for JS custom plugins loaded via `jsPlugins`.

Configure the behavior of linter plugins.

Here's an example if you're using Next.js in a monorepo:

```json
{
  "settings": {
    "next": {
      "rootDir": "apps/dashboard/"
    },
    "react": {
      "linkComponents": [
        {
          "name": "Link",
          "linkAttribute": "to"
        }
      ]
    },
    "jsx-a11y": {
      "components": {
        "Link": "a",
        "Button": "button"
      }
    }
  }
}
```

### settings.jest

type: `object`

Configure Jest plugin rules.

See [eslint-plugin-jest](https://github.com/jest-community/eslint-plugin-jest)'s
configuration for a full reference.

#### settings.jest.version

type: `integer | string`

default: `null`

Jest version — accepts a number (`29`) or a semver string (`"29.1.0"` or `"v29.1.0"`),
storing only the major version.
::: warning
Using this config will override the `no-deprecated-functions` config set.
:::

### settings.jsdoc

type: `object`

#### settings.jsdoc.augmentsExtendsReplacesDocs

type: `boolean`

default: `false`

Only for `require-(yields|returns|description|example|param|throws)` rule

#### settings.jsdoc.exemptDestructuredRootsFromChecks

type: `boolean`

default: `false`

Only for `require-param-type` and `require-param-description` rule

#### settings.jsdoc.ignoreInternal

type: `boolean`

default: `false`

For all rules but NOT apply to `empty-tags` rule

#### settings.jsdoc.ignorePrivate

type: `boolean`

default: `false`

For all rules but NOT apply to `check-access` and `empty-tags` rule

#### settings.jsdoc.ignoreReplacesDocs

type: `boolean`

default: `true`

Only for `require-(yields|returns|description|example|param|throws)` rule

#### settings.jsdoc.implementsReplacesDocs

type: `boolean`

default: `false`

Only for `require-(yields|returns|description|example|param|throws)` rule

#### settings.jsdoc.overrideReplacesDocs

type: `boolean`

default: `true`

Only for `require-(yields|returns|description|example|param|throws)` rule

#### settings.jsdoc.tagNamePreference

type: `object`

default: `{}`

### settings.jsx-a11y

type: `object`

Configure JSX A11y plugin rules.

See
[eslint-plugin-jsx-a11y](https://github.com/jsx-eslint/eslint-plugin-jsx-a11y#configurations)'s
configuration for a full reference.

#### settings.jsx-a11y.attributes

type: `Record<string, array>`

default: `{}`

Map of attribute names to their DOM equivalents.
This is useful for non-React frameworks that use different attribute names.

Example:

```json
{
  "settings": {
    "jsx-a11y": {
      "attributes": {
        "for": ["htmlFor", "for"]
      }
    }
  }
}
```

#### settings.jsx-a11y.components

type: `Record<string, string>`

default: `{}`

To have your custom components be checked as DOM elements, you can
provide a mapping of your component names to the DOM element name.

Example:

```json
{
  "settings": {
    "jsx-a11y": {
      "components": {
        "Link": "a",
        "IconButton": "button"
      }
    }
  }
}
```

#### settings.jsx-a11y.polymorphicPropName

type: `string`

An optional setting that define the prop your code uses to create polymorphic components.
This setting will be used to determine the element type in rules that
require semantic context.

For example, if you set the `polymorphicPropName` to `as`, then this element:

```jsx
<Box as="h3">Hello</Box>
```

Will be treated as an `h3`. If not set, this component will be treated
as a `Box`.

### settings.next

type: `object`

Configure Next.js plugin rules.

#### settings.next.rootDir

type: `array | string`

The root directory of the Next.js project.

This is particularly useful when you have a monorepo and your Next.js
project is in a subfolder.

Example:

```json
{
  "settings": {
    "next": {
      "rootDir": "apps/dashboard/"
    }
  }
}
```

##### settings.next.rootDir\[n]

type: `string`

### settings.react

type: `object`

Configure React plugin rules.

Derived from [eslint-plugin-react](https://github.com/jsx-eslint/eslint-plugin-react#configuration-legacy-eslintrc-)

#### settings.react.componentWrapperFunctions

type: `string[]`

default: `[]`

Functions that wrap React components and should be treated as HOCs.

Example:

```jsonc
{
  "settings": {
    "react": {
      "componentWrapperFunctions": ["observer", "withRouter"],
    },
  },
}
```

#### settings.react.formComponents

type: `array`

default: `[]`

Components used as alternatives to `<form>` for forms, such as `<Formik>`.

Example:

```jsonc
{
  "settings": {
    "react": {
      "formComponents": [
        "CustomForm",
        // OtherForm is considered a form component and has an endpoint attribute
        { "name": "OtherForm", "formAttribute": "endpoint" },
        // allows specifying multiple properties if necessary
        { "name": "Form", "formAttribute": ["registerEndpoint", "loginEndpoint"] },
      ],
    },
  },
}
```

##### settings.react.formComponents\[n]

type: `object | string`

###### settings.react.formComponents\[n].attribute

type: `string`

###### settings.react.formComponents\[n].name

type: `string`

#### settings.react.linkComponents

type: `array`

default: `[]`

Components used as alternatives to `<a>` for linking, such as `<Link>`.

Example:

```jsonc
{
  "settings": {
    "react": {
      "linkComponents": [
        "HyperLink",
        // Use `linkAttribute` for components that use a different prop name
        // than `href`.
        { "name": "MyLink", "linkAttribute": "to" },
        // allows specifying multiple properties if necessary
        { "name": "Link", "linkAttribute": ["to", "href"] },
      ],
    },
  },
}
```

##### settings.react.linkComponents\[n]

type: `object | string`

###### settings.react.linkComponents\[n].attribute

type: `string`

###### settings.react.linkComponents\[n].name

type: `string`

#### settings.react.version

type: `string`

default: `null`

React version to use for version-specific rules.

Accepts semver versions (e.g., "18.2.0", "17.0").

Example:

```jsonc
{
  "settings": {
    "react": {
      "version": "18.2.0",
    },
  },
}
```

### settings.vitest

type: `object`

Configure Vitest plugin rules.

See [eslint-plugin-vitest](https://github.com/vitest-dev/eslint-plugin-vitest)'s
configuration for a full reference.

#### settings.vitest.typecheck

type: `boolean`

default: `false`

Whether to enable typecheck mode for Vitest rules.
When enabled, some rules will skip certain checks for describe blocks
to accommodate TypeScript type checking scenarios.

---

---
url: /docs/contribute/parser.md
---

# Parser

The Oxc parser is designed to be the fastest and most conformant JavaScript and TypeScript parser available. Contributing to the parser requires understanding both the implementation details and the extensive test infrastructure.

## Architecture Overview

The parser follows a traditional compiler frontend architecture:

```
Source Text → Lexer → Tokens → Parser → AST
```

### Key Components

* **Lexer**: Tokenizes source text into structured tokens
* **Parser**: Recursive descent parser that builds the AST
* **AST**: Memory-efficient abstract syntax tree
* **Error Recovery**: Advanced error handling and recovery
* **Semantic Analysis**: Symbol resolution and scope management

### Design Goals

We aim to be the fastest Rust-based ready-for-production parser with:

* **Speed**: 3x faster than SWC, 5x faster than Biome
* **Conformance**: 100% Test262 compliance, 99%+ Babel/TypeScript compatibility
* **Memory Efficiency**: Arena-based allocation, minimal heap usage
* **Error Quality**: Helpful error messages with recovery

## Development Workflow

### Setting Up

```bash
# Run parser tests
cargo test -p oxc_parser

# Run conformance tests
just c  # or `just coverage`
```

### Project Structure

```
crates/oxc_parser/
├── src/
│   ├── lib.rs              # Public API
│   ├── lexer/              # Tokenization
│   ├── parser/             # Parsing logic
│   ├── cursor.rs           # Token stream management
│   └── diagnostics.rs      # Error handling
├── tests/                  # Unit tests
└── examples/               # Usage examples
```

### Core Parser Files

* **`parser/mod.rs`**: Main parser entry point
* **`parser/statement.rs`**: Statement parsing
* **`parser/expression.rs`**: Expression parsing
* **`parser/typescript.rs`**: TypeScript-specific parsing
* **`parser/jsx.rs`**: JSX parsing logic

## Conformance Testing

### Running Conformance Tests

```bash
just c
```

This runs conformance test suites using the runner in [tasks/coverage](https://github.com/oxc-project/oxc/tree/main/tasks/coverage):

### Test262 - ECMAScript Conformance

JavaScript has the [ECMAScript Test Suite](https://github.com/tc39/test262) called Test262.
The goal of Test262 is to provide test material that covers every observable behavior specified in the specification.

Parser conformance uses the [parse phase tests](https://github.com/tc39/test262/blob/main/INTERPRETING.md#negative).

**Current Status**: `43765/43765 (100.00%)`

### Babel Parser Tests

When new language features are added to JavaScript, Babel implements them first.
Babel has comprehensive [parser tests](https://github.com/babel/babel/tree/main/packages/babel-parser/test) for cutting-edge features.

**Current Status**: `2093/2101 (99.62%)`

### TypeScript Conformance

The TypeScript conformance tests can be found [here](https://github.com/microsoft/TypeScript/tree/main/tests/cases/conformance).

**Current Status**: `6470/6479 (99.86%)`

### Viewing Results

Test results are stored in snapshot files for tracking changes:

* [`parser_test262.snap`](https://github.com/oxc-project/oxc/blob/main/tasks/coverage/snapshots/parser_test262.snap)
* [`parser_babel.snap`](https://github.com/oxc-project/oxc/blob/main/tasks/coverage/snapshots/parser_babel.snap)
* [`parser_typescript.snap`](https://github.com/oxc-project/oxc/blob/main/tasks/coverage/snapshots/parser_typescript.snap)

---

---
url: /docs/learn/architecture/parser.md
---

# Parser Architecture

Oxc maintains its own AST and parser, which is by far the fastest and most conformant JavaScript and TypeScript (including JSX and TSX) parser written in Rust.

As the parser often represents a key performance bottleneck in JavaScript tooling,
any minor improvements can have a cascading effect on our downstream tools.
By developing our parser, we have the opportunity to explore and implement well-researched performance techniques.

## AST Design Philosophy

While many existing JavaScript tools rely on [estree] as their AST specification,
a notable drawback is its abundance of ambiguous nodes.
This ambiguity often leads to confusion during development with [estree].

The Oxc AST differs from the [estree] AST by removing ambiguous nodes and introducing distinct types.
For example, instead of using a generic [estree] `Identifier`,
the Oxc AST provides specific types such as `BindingIdentifier`, `IdentifierReference`, and `IdentifierName`.

This clear distinction greatly enhances the development experience by aligning more closely with the ECMAScript specification.

### AST Node Types

```rust
// Instead of generic Identifier
pub struct BindingIdentifier<'a> {
    pub span: Span,
    pub name: Atom<'a>,
}

pub struct IdentifierReference<'a> {
    pub span: Span,
    pub name: Atom<'a>,
    pub reference_id: Cell<Option<ReferenceId>>,
}

pub struct IdentifierName<'a> {
    pub span: Span,
    pub name: Atom<'a>,
}
```

### Semantic Clarity

This approach provides semantic clarity:

* **`BindingIdentifier`**: Variable declarations (`let x = 1`)
* **`IdentifierReference`**: Variable usage (`console.log(x)`)
* **`IdentifierName`**: Property names (`obj.property`)

## Performance Architecture

### How is it so fast

* **Memory Arena**: AST is allocated in a [memory arena](https://crates.io/crates/bumpalo) for fast allocation and deallocation
* **String Optimization**: Short strings are inlined by [CompactString](https://crates.io/crates/compact_str)
* **Minimal Heap Usage**: No other heap allocations are done except the above two
* **Separation of Concerns**: Scope binding, symbol resolution and some syntax errors are delegated to the semantic analyzer

### Memory Management Details

#### Arena Allocation

```rust
use oxc_allocator::Allocator;

// All AST nodes are allocated in this arena
let allocator = Allocator::default();
let ast_node = allocator.alloc(Expression::NumericLiteral(
    allocator.alloc(NumericLiteral { value: 42.0, span: SPAN })
));
```

Benefits:

* **O(1) allocation**: Simple pointer bump
* **O(1) deallocation**: Drop entire arena at once
* **Cache-friendly**: Linear memory layout
* **No fragmentation**: Continuous memory usage

#### String Interning with CompactString

```rust
// Strings ≤ 24 bytes are stored inline (no heap allocation)
let short_name = CompactString::from("variableName");  // Stack allocated
let long_name = CompactString::from("a_very_long_variable_name_that_exceeds_limit");  // Heap allocated
```

This reduces memory allocations for the majority of JavaScript identifiers and string literals.

## Parser Architecture

### Two-Phase Design

The Oxc parser follows a two-phase approach:

1. **Parsing Phase**: Build AST structure with minimal semantic analysis
2. **Semantic Phase**: Perform scope analysis, symbol resolution, and advanced error checking

```rust
// Phase 1: Parse to AST
let parser_result = Parser::new(&allocator, &source_text, source_type).parse();

// Phase 2: Semantic analysis
let semantic_result = SemanticBuilder::new()
    // Enable additional syntax checks not performed by the parser
    .with_check_syntax_error(true)
    .build(&parser_result.program);
```

### Parser Components

#### Lexer

* **Token generation**: Converts source text to structured tokens
* **SIMD optimization**: Uses SIMD instructions for whitespace skipping
* **Context-aware**: Handles regex vs division operator disambiguation

#### Recursive Descent Parser

* **Hand-written**: Custom implementation for maximum performance
* **Error recovery**: Advanced error handling with meaningful messages
* **Grammar compliance**: Follows ECMAScript specification precisely

#### AST Builder

* **Type safety**: Leverages Rust's type system for correctness
* **Memory efficiency**: Direct arena allocation
* **Builder pattern**: Convenient node construction methods

## Conformance Strategy

### Test Suite Coverage

* **Test262**: 100% pass rate on ECMAScript conformance tests
* **Babel**: 99.62% compatibility with Babel parser tests
* **TypeScript**: 99.86% compatibility with TypeScript compiler tests

### Error Handling Philosophy

```rust
// Meaningful error messages with source location
pub struct OxcDiagnostic {
    pub message: String,
    pub span: Span,
    pub severity: Severity,
    pub help: Option<String>,
}
```

The parser provides:

* **Precise error locations**: Exact source positions
* **Recovery strategies**: Continue parsing after errors
* **Helpful suggestions**: Actionable error messages

## Advanced Features

### TypeScript Support

* **Type stripping**: Removes TypeScript-specific syntax
* **Decorator parsing**: Handles experimental decorators
* **Namespace support**: Full module and namespace parsing
* **JSX integration**: TypeScript + JSX (TSX) support

### Research Areas

* **SIMD text processing**: Vectorized string operations
* **Cache optimization**: Minimize memory access patterns
* **Branch prediction**: Optimize hot parsing paths
* **Zero-copy parsing**: Eliminate unnecessary string copies

[estree]: https://github.com/estree/estree

---

---
url: /docs/guide/usage/parser.md
---

# Parser

A high-performance JavaScript / TypeScript parser written in Rust, powering other tools in the Oxc project.

## Features

* 3x faster than swc parser ([benchmark][url-benchmark]).
* Parses `.js(x)` and `.ts(x)`.
* Passes all parser tests from Test262 and 99% from Babel and TypeScript.
* Returns ESM information directly, no need for [`es-module-lexer`](https://npmx.dev/package/es-module-lexer).
* [✅ works with checker.ts](https://x.com/robpalmer2/status/1805502964435505559)

## Installation

### Node.js

* Use the node binding [oxc-parser][url-oxc-parser-npm].
* Try on [stackblitz](https://stackblitz.com/fork/github/oxc-project/website/tree/main/stackblitz-templates/oxc-parser).

### Rust

Use the umbrella crate [oxc][url-oxc-crate] or the individual [oxc\_ast][url-oxc-ast-crate] and [oxc\_parser][url-oxc-parser-crate] crates.

Rust usage example can be found [here](https://github.com/oxc-project/oxc/blob/main/crates/oxc_parser/examples/parser.rs).

## Print

After parsing and transforming, you can print code.

Here's a direct example using [esrap](https://npmx.dev/package/esrap) *(`parse` in reverse!)*:

```js
import { print } from "esrap";
import ts from "esrap/languages/ts";
import { parseSync } from "oxc-parser";

const { program } = parseSync("test.js", 'alert("hello oxc & esrap");');
const { code } = print(program, ts());

console.log(code); // alert("hello oxc & esrap");
```

:::info
Today, comments are not printed. *It will be supported thanks to [oxc-parser #13285](https://github.com/oxc-project/oxc/pull/13285).*
:::

[url-swc]: https://swc.rs

[url-benchmark]: https://github.com/oxc-project/bench-javascript-parser-written-in-rust

[url-oxc-crate]: https://docs.rs/oxc

[url-oxc-ast-crate]: https://docs.rs/oxc_ast

[url-oxc-parser-crate]: https://docs.rs/oxc_parser

[url-oxc-parser-npm]: https://npmx.dev/package/oxc-parser

---

---
url: /docs/learn/parser_in_rust/parser.md
---

# Parser

The parser we are going to construct is called a [recursive descent parser](https://en.wikipedia.org/wiki/Recursive_descent_parser),
it is the manual process of going down the grammar and building up the AST.

The parser starts simple, it holds the source code, the lexer, and the current token consumed from the lexer.

```rust
pub struct Parser<'a> {
    /// Source Code
    source: &'a str,

    lexer: Lexer<'a>,

    /// Current Token consumed from the lexer
    cur_token: Token,

    /// The end range of the previous token
    prev_token_end: usize,
}

impl<'a> Parser<'a> {
    pub fn new(source: &'a str) -> Self {
        Self {
            source,
            lexer: Lexer::new(source),
            cur_token: Token::default(),
        }
    }

    pub fn parse(&mut self) -> Program<'a> {
        Ok(Program {
            node: Node {
                start: 0,
                end: self.source.len(),
            }
            body: vec![]
        })
    }
}
```

## Helper functions

The current token `cur_token: Token` holds the current token returned from the lexer.
We'll make the parser code cleaner by adding some helper functions for navigating and inspecting this token.

```rust
impl<'a> Parser<'a> {
    fn start_node(&self) -> Node {
        let token = self.cur_token();
        Node::new(token.start, 0)
    }

    fn finish_node(&self, node: Node) -> Node {
        Node::new(node.start, self.prev_token_end)
    }

    fn cur_token(&self) -> &Token {
        &self.cur_token
    }

    fn cur_kind(&self) -> Kind {
        self.cur_token.kind
    }

    /// Checks if the current index has token `Kind`
    fn at(&self, kind: Kind) -> bool {
        self.cur_kind() == kind
    }

    /// Advance if we are at `Kind`
    fn bump(&mut self, kind: Kind) {
        if self.at(kind) {
            self.advance();
        }
    }

    /// Advance any token
    fn bump_any(&mut self) {
        self.advance();
    }

    /// Advance and return true if we are at `Kind`, return false otherwise
    fn eat(&mut self, kind: Kind) -> bool {
        if self.at(kind) {
            self.advance();
            return true;
        }
        false
    }

    /// Move to the next token
    fn advance(&mut self) {
        let token = self.lexer.next_token();
        self.prev_token_end = self.cur_token.end;
        self.cur_token = token;
    }
}
```

## Parse Functions

The `DebuggerStatement` is the most simple statement to parse, so let's try and parse it and return a valid program

```rust
impl<'a> Parser<'a> {
    pub fn parse(&mut self) -> Program {
        let stmt = self.parse_debugger_statement();
        let body = vec![stmt];
        Program {
            node: Node {
                start: 0,
                end: self.source.len(),
            }
            body,
        }
    }

    fn parse_debugger_statement(&mut self) -> Statement {
        let node = self.start_node();
        // NOTE: the token returned from the lexer is `Kind::Debugger`, we'll fix this later.
        self.bump_any();
        Statement::DebuggerStatement {
            node: self.finish_node(node),
        }
    }
}
```

All the other parse functions build on these primitive helper functions,
for example parsing the `while` statement in swc:

```rust
// https://github.com/swc-project/swc/blob/554b459e26b24202f66c3c58a110b3f26bbd13cd/crates/swc_ecma_parser/src/parser/stmt.rs#L952-L970

fn parse_while_stmt(&mut self) -> PResult<Stmt> {
    let start = cur_pos!(self);

    assert_and_bump!(self, "while");

    expect!(self, '(');
    let test = self.include_in_expr(true).parse_expr()?;
    expect!(self, ')');

    let ctx = Context {
        is_break_allowed: true,
        is_continue_allowed: true,
        ..self.ctx()
    };
    let body = self.with_ctx(ctx).parse_stmt(false).map(Box::new)?;

    let span = span!(self, start);
    Ok(Stmt::While(WhileStmt { span, test, body }))
}
```

## Parsing Expressions

The grammar for expressions is deeply nested and recursive,
which may cause stack overflow on long expressions (for example in [this TypeScript test](https://github.com/microsoft/TypeScript/blob/main/tests/cases/compiler/binderBinaryExpressionStressJs.ts)),

To avoid recursion, we can use a technique called "Pratt Parsing". A more in-depth tutorial can be found [here](https://matklad.github.io/2020/04/13/simple-but-powerful-pratt-parsing.html), written by the author of Rust-Analyzer.
And a Rust version here in [Rome](https://github.com/rome/tools/blob/5a059c0413baf1d54436ac0c149a829f0dfd1f4d/crates/rome_js_parser/src/syntax/expr.rs#L442).

## Lists

There are lots of places where we need to parse a list separated by a punctuation, for example `[a, b, c]` or `{a, b, c}`.

The code for parsing lists are all similar, we can use the [template method pattern](https://en.wikipedia.org/wiki/Template_method_pattern)
to avoid duplication by using traits.

```rust
// https://github.com/rome/tools/blob/85ddb4b2c622cac9638d5230dcefb6cf571677f8/crates/rome_js_parser/src/parser/parse_lists.rs#L131-L157

fn parse_list(&mut self, p: &mut Parser) -> CompletedMarker {
    let elements = self.start_list(p);
    let mut progress = ParserProgress::default();
    let mut first = true;
    while !p.at(JsSyntaxKind::EOF) && !self.is_at_list_end(p) {
        if first {
            first = false;
        } else {
            self.expect_separator(p);

            if self.allow_trailing_separating_element() && self.is_at_list_end(p) {
                break;
            }
        }

        progress.assert_progressing(p);

        let parsed_element = self.parse_element(p);

        if parsed_element.is_absent() && p.at(self.separating_element_kind()) {
            // a missing element
            continue;
        } else if self.recover(p, parsed_element).is_err() {
            break;
        }
    }
    self.finish_list(p, elements)
}
```

This pattern can also prevent us from infinite loops, specifically `progress.assert_progressing(p);`.

Implementation details can then be provided for different lists, for example:

```rust
// https://github.com/rome/tools/blob/85ddb4b2c622cac9638d5230dcefb6cf571677f8/crates/rome_js_parser/src/syntax/expr.rs#L1543-L1580

struct ArrayElementsList;

impl ParseSeparatedList for ArrayElementsList {
    fn parse_element(&mut self, p: &mut Parser) -> ParsedSyntax {
        match p.cur() {
            T![...] => parse_spread_element(p, ExpressionContext::default()),
            T![,] => Present(p.start().complete(p, JS_ARRAY_HOLE)),
            _ => parse_assignment_expression_or_higher(p, ExpressionContext::default()),
        }
    }

    fn is_at_list_end(&self, p: &mut Parser) -> bool {
        p.at(T![']'])
    }

    fn recover(&mut self, p: &mut Parser, parsed_element: ParsedSyntax) -> RecoveryResult {
        parsed_element.or_recover(
            p,
            &ParseRecovery::new(
                JS_UNKNOWN_EXPRESSION,
                EXPR_RECOVERY_SET.union(token_set!(T![']'])),
            ),
            js_parse_error::expected_array_element,
        )
    }

    fn list_kind() -> JsSyntaxKind {
        JS_ARRAY_ELEMENT_LIST
    }

    fn separating_element_kind(&mut self) -> JsSyntaxKind {
        T![,]
    }

    fn allow_trailing_separating_element(&self) -> bool {
        true
    }
}
```

## Cover Grammar

Detailed in [cover grammar](/docs/learn/ecmascript/grammar.html#cover-grammar), there are times when we need to convert an `Expression` to a `BindingIdentifier`. Dynamic languages such as JavaScript can simply rewrite the node type:

```javascript reference
https://github.com/acornjs/acorn/blob/11735729c4ebe590e406f952059813f250a4cbd1/acorn/src/lval.js#L11-L26
```

But in Rust, we need to do a struct to struct transformation. A nice and clean way to do this is to use an trait.

```rust
pub trait CoverGrammar<'a, T>: Sized {
    fn cover(value: T, p: &mut Parser<'a>) -> Result<Self>;
}
```

The trait accepts `T` as the input type, and `Self` and the output type, so we can define the following:

```rust
impl<'a> CoverGrammar<'a, Expression<'a>> for BindingPattern<'a> {
    fn cover(expr: Expression<'a>, p: &mut Parser<'a>) -> Result<Self> {
        match expr {
            Expression::Identifier(ident) => Self::cover(ident.unbox(), p),
            Expression::ObjectExpression(expr) => Self::cover(expr.unbox(), p),
            Expression::ArrayExpression(expr) => Self::cover(expr.unbox(), p),
            _ => Err(()),
        }
    }
}

impl<'a> CoverGrammar<'a, ObjectExpression<'a>> for BindingPattern<'a> {
    fn cover(obj_expr: ObjectExpression<'a>, p: &mut Parser<'a>) -> Result<Self> {
        ...
        BindingIdentifier::ObjectPattern(ObjectPattern { .. })
    }
}

impl<'a> CoverGrammar<'a, ArrayExpression<'a>> for BindingPattern<'a> {
    fn cover(expr: ArrayExpression<'a>, p: &mut Parser<'a>) -> Result<Self> {
        ...
        BindingIdentifier::ArrayPattern(ArrayPattern { .. })
    }
}
```

Then for anywhere we need to convert an `Expression` to `BindingPattern`,
call `BindingPattern::cover(expression)`.

***

# TypeScript

So you are done with JavaScript and you want to challenge parsing TypeScript?
The bad news is that there is no specification,
but the good news is that the TypeScript parser is in [a single file](https://github.com/microsoft/TypeScript/blob/main/src/compiler/parser.ts) 🙃.

## JSX vs TSX

For the following code,

```javascript
let foo = <string> bar;
```

It is a syntax error if this is `tsx` (Unterminated JSX),
but it is correct `VariableDeclaration` with `TSTypeAssertion`.

## Lookahead

In certain places, the parser need to lookahead and peek more than one token to determine the correct grammar.

### TSIndexSignature

For example, to parse `TSIndexSignature`, consider the following two cases:

```typescript
type A = { readonly [a: number]: string }
           ^__________________________^ TSIndexSignature

type B = { [a]: string }
           ^_________^ TSPropertySignature
```

For `type A` on the first `{`, we need to peek 5 tokens (`readonly`, `[`, `a`, `:` and `number`) in order to make sure
it is a `TSIndexSignature` and not a `TSPropertySignature`.

To make this possible and efficient, the lexer requires a buffer for storing multiple tokens.

### Arrow Expressions

Discussed in [cover grammar](/docs/learn/ecmascript/grammar.html#cover-grammar),
we need to convert from `Expression`s to `BindingPattern`s when the `=>` token is found after a SequenceExpression.

But this approach does not work for TypeScript as each item inside the `()` can have TypeScript syntax, there are just too many cases to cover, for example:

```typescript
(<x>a, b as c, d!);
(a?: b = {} as c!) => {};
```

It is recommended to study the TypeScript source code for this specific case. The relevant code are:

```typescript
function tryParseParenthesizedArrowFunctionExpression(
  allowReturnTypeInArrowFunction: boolean,
): Expression | undefined {
  const triState = isParenthesizedArrowFunctionExpression();
  if (triState === Tristate.False) {
    // It's definitely not a parenthesized arrow function expression.
    return undefined;
  }

  // If we definitely have an arrow function, then we can just parse one, not requiring a
  // following => or { token. Otherwise, we *might* have an arrow function.  Try to parse
  // it out, but don't allow any ambiguity, and return 'undefined' if this could be an
  // expression instead.
  return triState === Tristate.True
    ? parseParenthesizedArrowFunctionExpression(
        /*allowAmbiguity*/ true,
        /*allowReturnTypeInArrowFunction*/ true,
      )
    : tryParse(() =>
        parsePossibleParenthesizedArrowFunctionExpression(allowReturnTypeInArrowFunction),
      );
}

//  True        -> We definitely expect a parenthesized arrow function here.
//  False       -> There *cannot* be a parenthesized arrow function here.
//  Unknown     -> There *might* be a parenthesized arrow function here.
//                 Speculatively look ahead to be sure, and rollback if not.
function isParenthesizedArrowFunctionExpression(): Tristate {
  if (
    token() === SyntaxKind.OpenParenToken ||
    token() === SyntaxKind.LessThanToken ||
    token() === SyntaxKind.AsyncKeyword
  ) {
    return lookAhead(isParenthesizedArrowFunctionExpressionWorker);
  }

  if (token() === SyntaxKind.EqualsGreaterThanToken) {
    // ERROR RECOVERY TWEAK:
    // If we see a standalone => try to parse it as an arrow function expression as that's
    // likely what the user intended to write.
    return Tristate.True;
  }
  // Definitely not a parenthesized arrow function.
  return Tristate.False;
}
```

In summary, the TypeScript parser uses a combination of lookahead (fast path) and backtracking to parse arrow functions.

---

---
url: /docs/learn/performance.md
---

# Pursuit of Performance on Building a JavaScript Compiler

Originally posted on https://rustmagazine.org/issue-3/javascript-compiler/

## On Performance

After two years of writing Rust, performance has become an ingrained discipline for me - it boils down to
**allocate less memory** and **use fewer CPU cycles**.

However, achieving optimal performance can be difficult without the knowledge of the problem domain or awareness of potential solutions.

I will take you on my journey of performance and optimization in the following sections.
My preferred method of learning is through a combination of research, trial, and error,
so the following sections will be organized as such.

# Parsing

Oxc is a standard compiler that includes an abstract syntax tree (AST), a lexer, and a recursive descent parser.

## Abstract Syntax Tree (AST)

The first architectural design for a compiler is its AST.

All JavaScript tools work on the AST level, for example:

* A linter (e.g. ESLint) checks the AST for errors
* A formatter (e.g. prettier) prints the AST back to JavaScript text
* A minifier (e.g. terser) transforms the AST
* A bundler connects all import and export statements between ASTs from different files

It will be painful to build these tools if the AST is not user-friendly.

For JavaScript, the most used AST specification is [estree](https://github.com/estree/estree).
My first AST version replicates estree:

```rust
pub struct Program {
    pub node: Node,
    pub body: Vec<Statement>,
}

pub enum Statement {
    VariableDeclarationStatement(VariableDeclaration),
}

pub struct VariableDeclaration {
    pub node: Node,
    pub declarations: Vec<VariableDeclarator>,
}
```

In Rust, declaring a tree is relatively straightforward, as it involves using structs and enums.

### Memory Allocation

I worked on this version of AST for a couple of months while writing the parser.
And one day I decided to profile it. The profiler showed the program was spending a lot of time calling `drop`.

💡 Nodes of the AST are allocated on the heap via `Box` or `Vec`, they are allocated individually so they are dropped in sequential order.

Is there a solution to mitigate this?

So while working on the parser I studied some of the other JavaScript parsers written in Rust,
mainly [ratel](https://github.com/ratel-rust/ratel-core) and [jsparagus](https://github.com/mozilla-spidermonkey/jsparagus).

Both of these parsers declare their AST with a lifetime annotation,

```rust
pub enum Statement<'ast> {
    Expression(ExpressionNode<'ast>),
}
```

and they have an accompanying file called `arena.rs`.

I did not understand what it does so I neglected them until I started reading about their usage of memory arenas:
[bumpalo](https://docs.rs/bumpalo/latest/bumpalo/) and [toolshed](https://docs.rs/toolshed/latest/toolshed/struct.Arena.html).

In summary, memory arena allocates memory upfront in chunks or pages and deallocate altogether when the arena is dropped.
The AST is allocated on the arena so dropping the AST is a fast operation.

Another nice side effect that comes with this is that,
the AST is constructed in a specific order, and tree traversal also follows the same order, resulting in linear memory access during the visitation process.
This access pattern will be efficient since all nearby memory will be read into the CPU cache in pages, resulting in faster access times.

Unfortunately it can be challenging for Rust beginners to use memory arenas because all data structures and relevant functions need to be parameterized by lifetime annotations.
It took me five attempts to allocate the AST inside `bumpalo`.

Changing to a memory arena for the AST resulted around 20% performance improvement.

### Enum Sizes

Due to the recursive nature of ASTs, we need to define the types in a way to avoid the "recursive without indirection" error:

```
error[E0072]: recursive types `Enum` and `Variant` have infinite size
 --> crates/oxc_linter/src/lib.rs:1:1
  |
1 | enum Enum {
  | ^^^^^^^^^
2 |     Variant(Variant),
  |             ------- recursive without indirection
3 | }
4 | struct Variant {
  | ^^^^^^^^^^^^^^
5 |     field: Enum,
  |            ---- recursive without indirection
  |
help: insert some indirection (e.g., a `Box`, `Rc`, or `&`) to break the cycle
  |
2 ~     Variant(Box<Variant>),
3 | }
4 | struct Variant {
5 ~     field: Box<Enum>,
```

There are two ways to do this. Either box the enum in the enum variant or box the struct field.

I found the same question in the Rust forum back in 2017,
[Is there a better way to represent an abstract syntax tree?](https://users.rust-lang.org/t/is-there-a-better-way-to-represent-an-abstract-syntax-tree/9549/4)

Aleksey (matklad) told us to box the enum variants to keep the `Expression` enum small. But what does this mean?

As it turns out, the memory layout of a Rust enum is dependent on the sizes of all its variants, its total byte size dependents on the largest variant.
For example, the following enum will take up 56 bytes (1 byte for the tag, 48 bytes for the payload, and 8 bytes for alignment).

```rust
enum Enum {
    A, // 0 byte payload
    B(String), // 24 byte payload
    C { first: String, last: String }, // 48 byte payload
}
```

In a typical JavaScript AST, the `Expression` enum holds 45 variants and the `Statement` enum holds 20 variants. They take up more than 200 bytes if not boxed by enum variants.
These 200 bytes have to be passed around, and also accessed every time we do a `matches!(expr, Expression::Variant(_))` check, which is not very cache friendly for performance.

So to make memory access efficient, it is best to box the enum variants.

The [perf-book](https://nnethercote.github.io/perf-book/type-sizes.html) describes additional info on how to find large types.

I also copied the test for restricting small enum sizes.

```rust
#[cfg(all(target_arch = "x86_64", target_pointer_width = "64"))]
#[test]
fn no_bloat_enum_sizes() {
    use std::mem::size_of;
    use crate::ast::*;
    assert_eq!(size_of::<Statement>(), 16);
    assert_eq!(size_of::<Expression>(), 16);
    assert_eq!(size_of::<Declaration>(), 16);
}
```

Boxing the enum variants resulted around 10% speed-up.

### Span

Occasionally, we may not realize that a smaller memory footprint is possible until we spend some extra time examining the data structures.

In this instance, the leaf of all AST nodes contains a small data structure called the "span", which is used for storing the byte offset from the source text and comprises two `usize`s.

```rust
pub struct Node {
    pub start: usize,
    pub end: usize,
}
```

It was [pointed out to me](https://github.com/oxc-project/oxc/pull/4#pullrequestreview-1294538874) that I can safely change `usize` to `u32`
to reduce peak memory because larger than `u32` is a 4GB file.

Changing to `u32` improved the performance [up to 5% performance on large files](https://github.com/oxc-project/oxc/pull/31).

### Strings and Identifiers

Inside the AST, one may attempt to use a string reference to the source text for identifier names and string literals.

```rust
pub struct StringLiteral<'a> {
    pub value: &'a str,
}

pub struct Identifier<'a> {
    pub name: &'a str,
}
```

But unfortunately in JavaScript, strings and identifiers can have [escape sequences](https://mathiasbynens.be/notes/javascript-escapes),
i.e. `'\251'`, `'\xA9'` and `'©'` are the same for the copyright symbol.

This implies that we must compute the escaped values and allocate a new `String`.

### String interning

When there are lots of heap-allocated strings,
a technique called [string interning](https://en.wikipedia.org/wiki/String_interning) can be used to reduce total memory by storing only one copy of each distinct string value.

[string-cache](https://crates.io/crates/string_cache) is a popular and widely used library published by the servo team.
Initially, I used the `string-cache` library for identifiers and strings in the AST.
The performance of the parser was fast in a single thread,
but when I started implementing the linter where there are multiples parser running parallel with rayon,
CPU utilization was at about 50% of all cores.

Upon profiling, a method called `parking_lot::raw_mutex::RawMutex::lock_slow` showed up on the top of the execution time.
I did not know much about locks and multi-core programming,
but a global lock was just strange to start with,
so I decided to remove the `string-cache` library to enable full CPU utilization.

Removing `string-cache` from the AST improved the performance of parallel parsing by about 30%.

#### string-cache

Half a year later, while working on another performance-critical project,
the `string-cache` library resurfaced again. It was blocking all the threads during parallel text parsing.

I decided to study what `string-cache` does because I am
prepared this time after reading the book [Rust Atomics and Locks](https://marabos.nl/atomics/) by Mara Bos.

Here are the
[relevant](https://github.com/servo/string-cache/blob/6c044c91bb3d8212dae931152a7895f498574f71/src/dynamic_set.rs#L41-L42)
[code](https://github.com/servo/string-cache/blob/6c044c91bb3d8212dae931152a7895f498574f71/src/atom.rs#L204)
around the lock. Please note that the code was written eight years ago in 2015.

```rust
pub(crate) static DYNAMIC_SET: Lazy<Mutex<Set>> = Lazy::new(|| {
    Mutex::new({

// ... in another place
let ptr: std::ptr::NonNull<Entry> =
    DYNAMIC_SET.lock().insert(string_to_add, hash.g);
```

So this is straightforward. It locks the data structure `Set` every time a string is being inserted.
As this routine is called frequently within a parser, its performance is impacted negatively by synchronization.

Now let's take a look at the [`Set` data structure](https://github.com/servo/string-cache/blob/6c044c91bb3d8212dae931152a7895f498574f71/src/dynamic_set.rs#L53-L86)
and see what it does:

```rust
pub(crate) fn insert(&mut self, string: Cow<str>, hash: u32) -> NonNull<Entry> {
    let bucket_index = (hash & BUCKET_MASK) as usize;
    {
        let mut ptr: Option<&mut Box<Entry>> = self.buckets[bucket_index].as_mut();

        while let Some(entry) = ptr.take() {
            if entry.hash == hash && *entry.string == *string {
                if entry.ref_count.fetch_add(1, SeqCst) > 0 {
                    return NonNull::from(&mut **entry);
                }
                entry.ref_count.fetch_sub(1, SeqCst);
                break;
            }
            ptr = entry.next_in_bucket.as_mut();
        }
    }
    debug_assert!(mem::align_of::<Entry>() >= ENTRY_ALIGNMENT);
    let string = string.into_owned();
    let mut entry = Box::new(Entry {
        next_in_bucket: self.buckets[bucket_index].take(),
        hash,
        ref_count: AtomicIsize::new(1),
        string: string.into_boxed_str(),
    });
    let ptr = NonNull::from(&mut *entry);
    self.buckets[bucket_index] = Some(entry);

    ptr
}
```

It looks like it is looking for a bucket to store the string and it inserts the string if it is not in the bucket.

💡 Is this linear probing? If this is linear probing then this `Set` is just a `HashMap` without saying it is a `HashMap`.
💡 If this is a `HashMap`, then `Mutex<HashMap>` is a concurrent hashmap.

Although the solution may seem straightforward when we know what to look for, it took me a month to figure this out because I was unaware of the issue.
When it became evident that this is just a concurrent hashmap, applying the Mutex to the buckets instead of the entire hashmap was a clear and logical solution.
Within an hour of implementing this change, I submitted a pull request and was happy with the outcome 😃.

```
https://github.com/servo/string-cache/pull/268
```

It is worth mentioning that string interning is a battlefield within the Rust community.
For the example shown in [this blog post](https://dev.to/cad97/string-interners-in-rust-797),
there are single-threaded libraries such `string-interner`, `lasso`, `lalrpop-intern`, `intaglio` and `strena`.

Since we are parsing files in parallel, an option is to utilize a multi-threaded string interner library such as [`ustr`](https://crates.io/crates/ustr).
However, after profiling both `ustr` and the enhanced version of `string-cache`, it became apparent that the performance was still below expectations compared to the approach I am going to explain below.

Some preliminary guesses for the sub-par performance are:

* Hashing - the interners need to hash the string for deduplication
* Indirection - we need to read the string value from a "far away" heap, which is not cache friendly

### String Inlining

So we are back to the initial problem of having to allocate lots of strings.
Fortunately, there is a partial solution to this problem if we look at what kind of data we are dealing with:
short JavaScript variable names and some short strings.
There is a technique called string inlining,
where we store all of the bytes of a string on the stack.

In essence, we want the following enum to store our string.

```rust
enum Str {
    Static(&'static str),
    Inline(InlineReprensation),
    Heap(String),
}
```

To minimize the size of the enum, `InlineRepresentation` should have the same size as `String`.

```rust
#[cfg(all(target_arch = "x86_64", target_pointer_width = "64"))]
#[test]
fn test_size() {
    use std::mem::size_of;
    assert_eq!(size_of::<String>(), size_of::<InlineReprensation>());
}
```

Many crates in the Rust community aim to optimize memory usage. This is yet another battlefield within the community.
The most popular ones are

* [smol\_str](https://crates.io/crates/smol_str)
* [smartstring](https://crates.io/crates/smartstring)
* [compact\_str](https://crates.io/crates/compact_str)
* [flexstr](https://crates.io/crates/flexstr)

Each of these crates have unique characteristics and approaches to achieving memory optimization, leading to a variety of trade-offs and considerations when choosing which one to use.
For example `smol_str` and `flexstr` clones are O(1).
`flexstr` can store 22 bytes, `smol_str` and `smartstring` can store 23 bytes, and `compact_str` can store 24 bytes on 64-bit systems.

<https://fasterthanli.me> has a [deep dive](https://fasterthanli.me/articles/small-strings-in-rust) on this topic.

Changing `String` to `compact_str::CompactStr` reduced memory allocations by a large amount.

## Lexer

### Token

The job of the lexer (also known as tokenizer) is to turn source text into structured data called a token.

```rust
pub struct Token {
    pub kind: Kind,
}
```

To make it easier to work with, a token kind is typically defined as an enum in Rust. The variants of the enums hold the corresponding data for each token.

```rust
pub enum Kind {
    // Keywords
    For,
    While,
    ...
    // Literals
    String(String),
    Num(f64),
    ...
}
```

This enum currently uses 32 bytes, and a lexer often need to construct millions of this token `Kind`.
Every time it constructs a `Kind::For` or `Kind::While`, it has to allocate 32 bytes of memory on the stack.

A clever way to improve this is to break up the enum variant to keep `Kind` to a single byte and move the values into another enum,

```rust
pub struct Token<'a> {
    pub kind: Kind,
    pub value: TokenValue
}

pub enum TokenValue {
    None,
    String(String),
    Num(f64),
}
```

Since we control all the parsing code, it is our job to keep this safe by always declaring the corresponding token value to its kind.

While a `TokenValue` of 32 bytes is already quite small, it may still have a negative impact on performance because it is allocated frequently.

Let's take a look at the `String` type and see what we can find, by using the "go-to definition" in our code editors,
we'll go through `String` -> `Vec` -> `RawVec`:

```rust
pub struct String {
    vec: Vec<u8>,
}

pub struct Vec {
    buf: RawVec<T, A>,
    len: usize,
}

pub struct RawVec {
    ptr: Unique<T>,
    cap: usize,
    alloc: A,
}
```

As advertised, a `String` is just a `Vec` of `u8`s, and a `Vec` has a length and a capacity field.
Since we are never going to mutate this string, an optimization in terms of memory usage would be to drop the cap field and use a string slice (`&str`) instead.

```rust
pub enum TokenValue<'a> {
    None,
    String(&'a str),
    Num(f64),
}
```

`TokenValue` becomes 24 bytes.

While using a string slice instead of String in `TokenValue` would reduce memory usage, it does come with the downside of adding a lifetime annotation.
This can lead to issues with the borrow checker and the lifetime annotation will propagate to the rest of the codebase, making our code somewhat difficult to manage.
I lost the borrow checking game 8 months ago but [finally won](https://github.com/oxc-project/oxc/pull/174) when I revisited this.

When it makes sense, we can always go for the owned version of the immutable data instead of using references.
For example `Box<str>` for `String` and `Box<[u8]>` for `Vec<u8>`.

In summary, we can always come up with tricks to keep our data structures small,
and it will sometimes reward us performance improvement.

### Cow

I first encountered the term `Cow` when I was studying jsparagus's code,
it has an infrastructure called [`AutoCow`](https://github.com/mozilla-spidermonkey/jsparagus/blob/212f6bdbc2cae909e7d5cfebf36284560c3c4ef4/crates/parser/src/lexer.rs#L2256).

I vaguely understood what the code was doing.
When a JavaScript string is being tokenized,
it allocates a new string when it encounters an escaped sequence or it returns the original string slice if it doesn't:

```rust
fn finish(&mut self, lexer: &Lexer<'alloc>) -> &'alloc str {
    match self.value.take() {
        Some(arena_string) => arena_string.into_bump_str(),
        None => &self.start[..self.start.len() - lexer.chars.as_str().len()],
    }
}
```

This is clever because 99.9% of the time it will not allocate a new string because escaped strings are rare.

But the term `Cow` or "clone-on-write smart pointer" never made sense to me.

> The type Cow is a smart pointer providing clone-on-write functionality: it can enclose and provide immutable access to borrowed data, and clone the data lazily when mutation or ownership is required. The type is designed to work with general borrowed data via the Borrow trait.

If you are new to Rust (like I was), then this description just doesn't help (I still don't understand what it is talking about).

It was [pointed out to me](https://twitter.com/zack_overflow/status/1620387950264713216) that `clone-on-write` is
just a use case of this data structure. A better name should be called `RefOrOwned` because it is a type that contains either
owned data or a reference.

### SIMD

When I was going through the old Rust blogs, the [Announcing the Portable SIMD Project Group](https://blog.rust-lang.org/inside-rust/2020/09/29/Portable-SIMD-PG.html)
caught my attention.
I always wanted to play around with SIMD but never got the chance.
After some research, I found a use case that may apply to a parser:
[How quickly can you remove spaces from a string?](https://lemire.me/blog/2017/01/20/how-quickly-can-you-remove-spaces-from-a-string) by Daniel Lemire.
So it turns out this has been done before, in a JSON parser called RapidJSON,
which [uses SIMD to remove whitespaces](https://rapidjson.org/md_doc_internals.html#SkipwhitespaceWithSIMD).

So eventually with the help of portable-SIMD and RapidJSON's code,
not only did I manage to [skip whitespaces](https://github.com/oxc-project/oxc/pull/26),
I also managed to [skip multi-line comments](https://github.com/oxc-project/oxc/pull/23) as well.

Both changes improved the performance by a few percent.

### Keyword match

At the top of the performance profile,
there is a hot code path that takes about 1 - 2% of the total execution time.

It tries to match a string to a JavaScript keyword:

```rust
fn match_keyword(s: &str) -> Self {
    match s {
        "as" => As,
        "do" => Do,
        "if" => If,
        ...
        "constructor" => Constructor,
        _ => Ident,
    }
}
```

With the addition of TypeScript, there are 84 strings for us to match from.
After some research, I found a blog from V8 [Blazingly fast parsing, part 1: optimizing the scanner](https://v8.dev/blog/scanner),
it describes its [keyword matching code](https://source.chromium.org/chromium/chromium/src/+/main:v8/src/parsing/keywords-gen.h) in detail.

> Since the list of keywords is static, we can compute a perfect hash function that for each identifier gives us at most one candidate keyword. V8 uses gperf to compute this function. The result computes a hash from the length and first two identifier characters to find the single candidate keyword. We only compare the identifier with the keyword if the length of that keyword matches the input identifier length.

So a quick hash plus an integer comparison should be faster than 84 string comparisons.
But we tried [again](https://github.com/oxc-project/oxc/pull/140) and [again](https://github.com/oxc-project/oxc/pull/171) to no avail.

As it turns out, [LLVM already optimized our code](https://github.com/oxc-project/oxc/issues/151#issuecomment-1464818336).
By using `--emit=llvm-ir` on `rustc`, we find the relevant code:

```
switch i64 %s.1, label %bb6 [
  i64 2, label %"_ZN4core5slice3cmp81_$LT$impl$u20$core..cmp..PartialEq$LT$$u5b$B$u5d$$GT$$u20$for$u20$$u5b$A$u5d$$GT$2eq17h46d405acb5da4997E.exit.i"
  i64 3, label %"_ZN4core5slice3cmp81_$LT$impl$u20$core..cmp..PartialEq$LT$$u5b$B$u5d$$GT$$u20$for$u20$$u5b$A$u5d$$GT$2eq17h46d405acb5da4997E.exit280.i"
  i64 4, label %"_ZN4core5slice3cmp81_$LT$impl$u20$core..cmp..PartialEq$LT$$u5b$B$u5d$$GT$$u20$for$u20$$u5b$A$u5d$$GT$2eq17h46d405acb5da4997E.exit325.i"
  i64 5, label %"_ZN4core5slice3cmp81_$LT$impl$u20$core..cmp..PartialEq$LT$$u5b$B$u5d$$GT$$u20$for$u20$$u5b$A$u5d$$GT$2eq17h46d405acb5da4997E.exit380.i"
  i64 6, label %"_ZN4core5slice3cmp81_$LT$impl$u20$core..cmp..PartialEq$LT$$u5b$B$u5d$$GT$$u20$for$u20$$u5b$A$u5d$$GT$2eq17h46d405acb5da4997E.exit450.i"
  i64 7, label %"_ZN4core5slice3cmp81_$LT$impl$u20$core..cmp..PartialEq$LT$$u5b$B$u5d$$GT$$u20$for$u20$$u5b$A$u5d$$GT$2eq17h46d405acb5da4997E.exit540.i"
  i64 8, label %"_ZN4core5slice3cmp81_$LT$impl$u20$core..cmp..PartialEq$LT$$u5b$B$u5d$$GT$$u20$for$u20$$u5b$A$u5d$$GT$2eq17h46d405acb5da4997E.exit590.i"
  i64 9, label %"_ZN4core5slice3cmp81_$LT$impl$u20$core..cmp..PartialEq$LT$$u5b$B$u5d$$GT$$u20$for$u20$$u5b$A$u5d$$GT$2eq17h46d405acb5da4997E.exit625.i"
  i64 10, label %"_ZN4core5slice3cmp81_$LT$impl$u20$core..cmp..PartialEq$LT$$u5b$B$u5d$$GT$$u20$for$u20$$u5b$A$u5d$$GT$2eq17h46d405acb5da4997E.exit655.i"
  i64 11, label %"_ZN4core5slice3cmp81_$LT$impl$u20$core..cmp..PartialEq$LT$$u5b$B$u5d$$GT$$u20$for$u20$$u5b$A$u5d$$GT$2eq17h46d405acb5da4997E.exit665.i"
], !dbg !191362
```

`%s` is the string, `%s.1` is its length ... it is branching on the string length! The compiler is smarter than us 😃.

(Yes, we got so serious with this so we started looking at LLVM IR and assembly code.)

Later on, [@strager](https://twitter.com/strager) posted a very educational YouTube video [Faster than Rust and C++: the PERFECT hash table](https://www.youtube.com/watch?v=DMQ_HcNSOAI) on this topic.
The video taught us a systematic approach to reasoning about fine-tuning performance problems

In the end, we concluded that the simple keyword match is enough for us since it was only about 1 - 2% of the performance,
and the effort is not worth it after spending a few days on it - Rust does not have all the pieces we need to build this perfect hashmap.

## Linter

A linter is a program that analyzes the source code for problems.

The simplest linter visits each AST node and checks for rules.
[The visitor pattern](https://rust-unofficial.github.io/patterns/patterns/behavioural/visitor.html) can be used:

```rust
pub trait Visit<'a>: Sized {
    // ... lots of visit functions

    fn visit_debugger_statement(&mut self, stmt: &'a DebuggerStatement) {
        // report error
    }
}
```

### Parent Pointing Tree

It is easy to go down the AST by using visitors, but what if we want to go up the tree to collect some information?

This problem is particularly challenging to solve in Rust, because it is not possible to add a pointer to the nodes of the AST.

Let's forget about ASTs for a second and focus on generic trees with the property of a node having a pointer to its parent.
To build a generic tree, each tree node needs to be the same type `Node`, we can reference their parent by using `Rc`:

```rust
struct Node {
    parent: Option<Rc<Node>>,
}
```

It is tedious to work with this pattern if we need mutation, and
it is not performant because the nodes have to be dropped at different times.

A more efficient solution is to use a `Vec` as its backing storage and use indexes for pointers.

```rust
struct Tree {
    nodes: Vec<Node>
}

struct Node {
    parent: Option<usize> // index into `nodes`
}
```

[`indextree`](https://crates.io/crates/indextree) is a nice library for this task.

Back to our AST, we can build a `indextree` by having the nodes point to an enum that wraps every single kind of AST node.
We call this the untyped AST.

```rust
struct Node<'a> {
    kind: AstKind<'a>
}

enum AstKind<'a> {
    BlockStatement(&'a BlockStatement<'a>),
    // ...
    ArrayExpression(&'a ArrayExpression<'a>),
    // ...
    Class(&'a Class<'a>),
    // ...
}
```

The last missing piece is to have callbacks inside the visitor pattern that builds this tree.

```rust
pub trait Visit<'a> {
    fn enter_node(&mut self, _kind: AstKind<'a>) {}
    fn leave_node(&mut self, _kind: AstKind<'a>) {}

    fn visit_block_statement(&mut self, stmt: &'a BlockStatement<'a>) {
        let kind = AstKind::BlockStatement(stmt);
        self.enter_node(kind);
        self.visit_statements(&stmt.body);
        self.leave_node(kind);
    }
}

impl<'a> Visit<'a> for TreeBuilder<'a> {
    fn enter_node(&mut self, kind: AstKind<'a>) {
        self.push_ast_node(kind);
    }

    fn leave_node(&mut self, kind: AstKind<'a>) {
        self.pop_ast_node();
    }
}
```

The final data structure becomes `indextree::Arena<Node<'a>>` where each `Node` has a pointer to an `AstKind<'a>`.
`indextree::Node::parent` can be called to get the parent of any node.

The nice benefit of making this parent pointing tree is that it becomes convenient to visit AST nodes without having to implement any visitors.
A linter becomes a simple loop over all the nodes inside the `indextree`:

```rust
for node in nodes {
    match node.get().kind {
        AstKind::DebuggerStatement(stmt) => {
        // report error
        }
        _ => {}
    }
}
```

A full example is provided [here](https://github.com/oxc-project/oxc/blob/main/crates/oxc_linter/examples/linter.rs).

At first glance, this process may seem slow and inefficient.
However, visiting the typed AST through a memory arena and pushing a pointer into `indextree` are efficient linear memory access patterns.
The current benchmark indicates that this approach is 84 times faster than ESLint, so it is certainly fast enough for our purposes.

### Processing files in parallel

The linter uses the [ignore](https://crates.io/crates/ignore) crate for directory traversal,
it supports `.gitignore` and adds additional ignore files such as `.eslintignore`.

A small problem with this crate is that it does not have a parallel interface,
There is no `par_iter` for `ignore::Walk::new(".")`.

Instead, [primitives need to be used](https://github.com/oxc-project/oxc/blob/b51c2df3cc43b9f7d57380acc1552fac7db75fab/crates/oxc_cli/src/lint/runner.rs#L116-L139)

```rust
let walk = Walk::new(&self.options);
rayon::spawn(move || {
    walk.iter().for_each(|path| {
        tx_path.send(path).unwrap();
    });
});

let linter = Arc::clone(&self.linter);
rayon::spawn(move || {
    while let Ok(path) = rx_path.recv() {
        let tx_error = tx_error.clone();
        let linter = Arc::clone(&linter);
        rayon::spawn(move || {
            if let Some(diagnostics) = Self::lint_path(&linter, &path) {
                tx_error.send(diagnostics).unwrap();
            }
            drop(tx_error);
        });
    }
});
```

This unlocks a useful feature where we can print all diagnostics in a single thread, which leads us to the final topic of this article.

### Printing is slow

Printing the diagnostics was fast, but I have been working on this project for so long that it felt like an eternity to print thousands of diagnostic messages every time I run the linter on huge monorepos.
So I started searching through the Rust GitHub issues and eventually found the relevant ones:

* [io::Stdout should use block buffering when appropriate](https://github.com/rust-lang/rust/issues/60673)
* [stdin and stdout performance considerations are not documented](https://github.com/rust-lang/rust/issues/106133)

In summary, a `println!` call will lock `stdout` every time it encounters a newline, this is called line buffering.
To make things print faster, we need to opt-in for block buffering which is [documented here](https://rust-cli.github.io/book/tutorial/output.html#a-note-on-printing-performance).

```rust
use std::io::{self, Write};

let stdout = io::stdout(); // get the global stdout entity
let mut handle = io::BufWriter::new(stdout); // optional: wrap that handle in a buffer
writeln!(handle, "foo: {}", 42); // add `?` if you care about errors here
```

Or acquire the lock on stdout.

```rust
let stdout = io::stdout(); // get the global stdout entity
let mut handle = stdout.lock(); // acquire a lock on it
writeln!(handle, "foo: {}", 42); // add `?` if you care about errors here
```

---

---
url: /docs/contribute/rules.md
---

# PR Rules and Policies

## PR Rules

* We [prefer smaller PRs](https://graphite.dev/blog/how-large-prs-slow-down-development).
* Try stacked PRs with [graphite](https://graphite.dev) if you have write access, which will be given to you when you contribute a lot.
* Please create an issue or discussion if the PR contains architectural changes.

## Development Policy

* Embrace data-oriented design.
* Keep APIs simple and well-documented.
* Always provide a reference to the source if the implementation is from another project.

### Performance

* All performance issues are considered as bugs in this project, this includes all runtime and compilation performance issues.
  * Follow guidance from the [Rust performance book](https://nnethercote.github.io/perf-book/introduction.html).
  * Minimize the use of the `regex` crate. Use Rust iterators and string methods for better performance.
* Compile time must be minimized to reduce impact on development workflow and downstream tools.
  * Minimize third-party dependencies to reduce compilation speed and project complexity.
  * Avoid heavy macros, generics, or any Rust techniques that slow compilation or increase binary size.
  * Our [CI runs](https://github.com/oxc-project/oxc/actions/workflows/ci.yml?query=branch%3Amain) complete in 3 minutes, any regressions need to be fixed.

## Maintenance Policy

* Monitor code coverage for unused code. Aim for 99% code coverage.
* Actively monitor and work on reducing the CI time to speed up merging of PRs. The current CI time on GitHub actions is around 3 minutes.
* Documentation first - documentation should serve as the source of truth. Keep the documentation updated and share the link instead of repeatedly answering the same questions. See GitLab's [handbook-first](https://handbook.gitlab.com/handbook/company/culture/all-remote/handbook-first) approach.
* Consistent import orders: "furthest away" to "closest".
  * `std`
  * External crates
  * Oxc crates
  * Local crate (`crate`)
  * `super`
  * `mod`

## Conventional Commits

We follow [conventional commits](https://www.conventionalcommits.org/en/v1.0.0/):

The commit contains the following structural elements, to communicate intent to the consumers:

* `fix`: a commit of the type fix patches a bug in your codebase.
* `feat`: a commit of the type feat introduces a new feature to the codebase.
* BREAKING CHANGE: a appends a `!` after the type/scope, introduces a breaking API change, e.g. `feat(parser)!: new feature`.
* the scopes are crate names.
* the types are `feat:`, `fix:`, `chore:`, `ci:`, `docs:`, `style:`, `refactor:`, `perf:` and `test:`.

## Action Policy

Taken from [Astral's values](https://astral-sh.notion.site/Astral-s-Values-0ed6a642bcc84e91af6836b2373572f5):

> We bias towards action, even in the face of uncertainty. We favor *pragmatic doing* over **prolonged debating**; we favor asking for *forgiveness* over *permission*. We value **decisiveness — especially** when a decision isn’t clear cut, and **especially** when a decision is reversible.
>
> A bias towards action is *not* the same as recklessness. Rather, it’s a bias towards making *responsible* decisions and acting on them with *urgency*, even if we’re left with lingering ambiguity or known unknowns.

---

---
url: /docs/contribute/profiling.md
---

# Profiling

## Compiling `oxlint` in release mode with debug information

For profiling, you will need to compile the `oxlint` binary in release mode with debug information enabled. You can do that by passing `--profile release-with-debug` to `cargo build`:

```bash
cargo build --profile release-with-debug --bin oxlint
```

After building, the binary is located at `./target/release-with-debug/oxlint`. This is the binary that should be used for profiling.

## CPU - Samply

[Samply](https://github.com/mstange/samply) is a command line CPU profiler which uses the Firefox profiler as its UI. Works on macOS and Linux.

To use Samply with `oxlint`, run `samply record` followed by the `oxlint` command and arguments:

```bash
samply record ./target/release-with-debug/oxlint .
```

To improve the profiling experience, you might consider some of the following options:

* `oxlint`: `--silent` will suppress diagnostics output and keep the profile more focused.
* `oxlint`: `--threads 1` will run the linter single threaded, which is slower, but makes it easier to analyze the profile for single-threaded performance.
* `samply record`: `--rate <number>` will sample the profile at a higher rate. The default is 1000Hz (1ms), but increasing this will provide more detailed information at the cost of a larger profile file.

For example, running `oxlint` single-threaded with a 0.1ms sample rate:

```bash
samply record --rate 10000 ./target/release-with-debug/oxlint --silent --threads 1 .
```

## CPU - Mac Xcode Instruments

[`cargo instruments`](https://github.com/cmyr/cargo-instruments) is the tool of choice to bridge Mac Xcode instruments.

The following instruction replicates the procedure of `cargo instruments`.

First, install Xcode Instruments command-line tools:

```bash
xcode-select --install
```

Then, if you haven't already, [ensure that the `oxlint` binary is compiled](#compiling-oxlint-in-release-mode-with-debug-information).

Under the hood, `cargo instruments` invokes the `xcrun xctrace` command, which is equivalent to

```bash
xcrun xctrace record --template 'Time Profile' --output . --launch -- /path/to/oxc/target/release-with-debug/oxlint
```

Running the command above produces the following output

```
Starting recording with the Time Profiler template. Launching process: oxlint.
Ctrl-C to stop the recording
Target app exited, ending recording...
Recording completed. Saving output file...
Output file saved as: Launch_oxlint_2023-09-03_4.41.45 PM_EB179B85.trace
```

Open the trace file `open Launch_oxlint_2023-09-03_4.41.45\ PM_EB179B85.trace`.

To see a top down trace:

1. On the top panel, click CPUs
2. On the left input box, click `x` then select `Time Profiler`
3. At the bottom panel, click "Call Tree", turn on "Invert Call Tree" and turn off separate by thread.

For memory and disk operations, use `--template 'Allocations'` and `--template 'File Activity'`.

For more detailed CPU profiling, such as L1/L2 cache misses, cycle and instruction counts, and branch prediction info, you need to use a custom "CPU Counters" template:

1. Open Instruments and select the "CPU Counters" template.
2. In the "CPU Counters" settings:
   1. Turn on the "High Frequency Sampling" option.
   2. Below the "High Frequency Sampling" option, click the plus icon and select an event type. Some suggested event types:
      * Cycles - for getting a rough idea of how many CPU cycles are spent in each function.
      * Instructions - for getting a rough idea of how many CPU instructions are executed in each function and how many cycles that takes
      * `L1D_CACHE_MISS_LD` - count of L1 cache misses from loading data from memory
3. Once you have enabled the events you are interested in, save the template in "File > Save as Template ..." and give it a name.
4. Now you can use this with `xctrace` by passing the template name to the `--template` option: `xcrun xctrace record --template 'My Custom CPU Counters' --output . --launch -- /path/to/oxc/target/release-with-debug/oxlint`

## Heap Allocation - dhat

[dhat](https://docs.rs/dhat/latest/dhat) is a heap profiler that can help identify memory leaks and analyze heap allocation patterns.

### Setup

Add dhat as a dependency to your `Cargo.toml`:

```toml
[dependencies]
dhat = "0.3"
```

Then add a global allocator at the top of your binary crate:

```rust
#[global_allocator]
static ALLOC: dhat::Alloc = dhat::Alloc;
```

### Profiling

Create a profiler in the scope you want to profile. The profiler will track allocations from when it's created until it's dropped:

```rust
fn main() {
    let _profiler = dhat::Profiler::new_heap();
    // Your code here - all heap allocations will be tracked
}
```

You can also add `_profiler` to any function to track memory only for that specific function:

```rust
fn my_function() {
    let _profiler = dhat::Profiler::new_heap();
    // Only allocations within this function scope will be tracked
}
```

The profiler will automatically generate a `dhat-heap.json` file when it's dropped.

### Loading and Reading the Profile

After running your program, a `dhat-heap.json` file will be created in your working directory.

To analyze the profile:

1. Open the dhat viewer at https://nnethercote.github.io/dh\_view/dh\_view.html
2. Load the `dhat-heap.json` file
3. Select a metric in "Sort metrics" to analyze different aspects of memory usage:
   * **"At t-gmax (bytes)"**: Shows allocations at the point of peak memory usage. Use this to identify what's consuming the most memory when your program reaches its maximum heap size.
   * **"At t-end (bytes)"**: Shows memory that was not dropped before the profiler was destroyed. This is particularly useful for identifying memory leaks, as it reveals allocations that remain at the end of the profiled scope.
   * **"Total (bytes)"**: Shows the total number of bytes allocated over the entire execution. Use this to identify which parts of your code are performing the most allocations, even if the memory is later freed.

### Advanced: Controlling Profiler Lifetime

For more control over when profiling stops, you can explicitly manage the profiler's lifetime. For example, to profile only the core logic and exclude cleanup:

```rust
struct MyApp {
    profiler: Option<dhat::Profiler>,
    // other fields
}

impl MyApp {
    fn close(&mut self) {
        // Drop the profiler here to capture the heap state before cleanup
        self.profiler = None;
        // cleanup code
    }
}
```

This pattern helps identify which data structures are holding memory at a specific point in your program's execution.

---

---
url: /docs/guide/projects.md
---

# Projects Using Oxc

## Oxlint / Oxfmt / Both

* [Google Neuroglancer](https://github.com/google/neuroglancer) (Oxlint) - WebGL volumetric data visualization tool
* [Shopify](https://www.shopify.com/news/performance%F0%9F%91%86-complexity%F0%9F%91%87-killer-updates-from-shopify-engineering) (Oxlint) - Reduced hour of workload to seconds
* [Cloudflare Agents](https://github.com/cloudflare/agents) (Both) - Cloudflare Agents SDK
* [BBC Simorgh](https://github.com/bbc/simorgh) (Oxlint) - BBC online rendering platform
* [Turborepo](https://github.com/vercel/turborepo) (Both) - High-performance build system for JavaScript and TypeScript codebases
* [Sentry JavaScript](https://github.com/getsentry/sentry-javascript) (Both) - Official Sentry SDKs for JavaScript
* [Vue.js](https://github.com/vuejs/core) (Both) - The progressive JavaScript framework
* [Hugging Face JS](https://github.com/huggingface/huggingface.js) (Oxfmt) - Hugging Face JS libraries
* [Bun](https://github.com/oven-sh/bun) (Oxlint) - JavaScript runtime and toolkit
* [Mastodon](https://github.com/mastodon/mastodon) (Oxfmt) - Decentralized social networking server
* [Preact](https://github.com/preactjs/preact) (Oxlint) - Fast 3kB React alternative with the same modern API
* [PostHog](https://github.com/PostHog/posthog) (Oxlint) - Open-source product analytics platform
* [Lichess](https://github.com/lichess-org/lila) (Both) - Lichess chess server/frontend
* [Rolldown](https://github.com/rolldown/rolldown) (Both) - Rust bundler in the VoidZero/Vite ecosystem
* [Renovate](https://github.com/renovatebot/renovate) (Oxlint) - Dependency update automation bot
* [Vue Pinia](https://github.com/vuejs/pinia) (Oxfmt) - Vue's official state management library
* [AFFiNE](https://github.com/toeverything/affine) (Oxlint) - Next-gen knowledge base
* [FormatJS](https://github.com/formatjs/formatjs) (Both) - JavaScript internationalization libraries
* [napi-rs](https://github.com/napi-rs/napi-rs) (Oxlint) - A framework for building compiled Node.js add-ons in Rust via Node-API
* [ComfyUI Frontend](https://github.com/Comfy-Org/ComfyUI_frontend) (Oxfmt) - Frontend for ComfyUI
* [Actual](https://github.com/actualbudget/actual) (Both) - Open-source budgeting app
* [Hey API](https://heyapi.dev/) (Oxlint) - OpenAPI to TypeScript codegen ecosystem
* [nuxt-auth](https://github.com/sidebase/nuxt-auth) (Oxlint) - Authentication built for Nuxt 3
* [OpenClaw](https://github.com/openclaw/openclaw) (Both) - Open source personal AI assistant
* [npmx.dev](https://github.com/npmx-dev/npmx.dev) (Both) - npm package explorer
* [Bluesky](https://github.com/bluesky-social/social-app) (Oxlint) - Social media network
* [Electron](https://github.com/electron/electron) (Both) - Framework for cross-platform apps
* [SWR](https://github.com/vercel/swr) (Both) - Library for data fetching in React

## Resolver

* [swc-node](https://github.com/swc-project/swc-node) - Faster ts-node without typecheck
* [Biome](https://biomejs.dev) - for loading configuration
* [turborepo](https://github.com/vercel/turborepo/pull/9134) - for `turbo-trace`
* [dts-resolver](https://npmx.dev/package/dts-resolver) - Resolves TypeScript declaration files for dependencies
* [codemod](https://github.com/codemod/codemod) - For module resolution in jssg codemods
* [Storybook](https://github.com/storybookjs/storybook) - for module resolution as part of change detection

## Parser

* [todoctor](https://github.com/azat-io/todoctor) - CLI tool to track and visualize TODO comments in Git repositories and make report
* [nuxt](https://nuxt.com) - Uses `oxc-parser` to [parse code in plugins](https://github.com/nuxt/nuxt/pull/30066)
* [Elide](https://elide.dev) - Uses `oxc` to strip TypeScript types before execution
* [Storybook](https://github.com/storybookjs/storybook) - for parsing as part of change detection

## Transformer

* [unplugin-isolated-decl](https://npmx.dev/package/unplugin-isolated-decl) - A blazing-fast tool for generating isolated declarations
* [stc](https://github.com/long-woo/stc) - A tool for converting OpenApi/Swagger/Apifox into code

## Crates

* [Andromeda](https://github.com/tryandromeda/andromeda) - A modern, and secure JavaScript & TypeScript runtime built with The Nova Engine and oxc crates
* [Rolldown](https://rolldown.rs) - Uses all compiler components
* [sovra](https://github.com/oblador/sovra) - Test decider for large JavaScript projects
* [Tauri](https://github.com/tauri-apps/tauri/blob/8c6d1e8e6c852667bb223b5f4823948868c26d98/crates/tauri-cli/src/migrate/migrations/v1/frontend.rs) - Uses the parser for its codemod
* [tree-shaker](https://github.com/KermanX/tree-shaker) - An experimental tree shaker for JavaScript
* [Tyvm](https://github.com/zackradisic/tyvm) - An experimental bytecode interpreter for type-level TypeScript

---

---
url: /docs/guide/usage/linter/rules/promise/always-return.md
---

### What it does

Require returning inside each `then()` to create readable and reusable Promise chains.
We also allow someone to throw inside a `then()` which is essentially the same as return `Promise.reject()`.

### Why is this bad?

Broken Promise Chain.
Inside the first `then()` callback, a function is called but not returned.
This causes the next `then()` in the chain to execute immediately without waiting for the called function to complete.

### Examples

Examples of **incorrect** code for this rule:

```javascript
myPromise.then(function (val) {});
myPromise.then(() => {
  doSomething();
});
myPromise.then((b) => {
  if (b) {
    return "yes";
  } else {
    forgotToReturn();
  }
});
```

Examples of **correct** code for this rule:

```javascript
myPromise.then((val) => val * 2);
myPromise.then(function (val) {
  return val * 2;
});
myPromise.then(doSomething); // could be either
myPromise.then((b) => {
  if (b) {
    return "yes";
  } else {
    return "no";
  }
});
```

## Configuration

This rule accepts a configuration object with the following properties:

### ignoreAssignmentVariable

type: `string[]`

default: `["globalThis"]`

You can pass an `{ ignoreAssignmentVariable: [] }` as an option to this rule
with a list of variable names so that the last `then()` callback in a promise
chain does not warn if it does an assignment to a global variable. Default is
`["globalThis"]`.

```javascript
/* promise/always-return: ["error", { ignoreAssignmentVariable: ["globalThis"] }] */

// OK
promise.then((x) => {
  globalThis = x;
});

promise.then((x) => {
  globalThis.x = x;
});

// OK
promise.then((x) => {
  globalThis.x.y = x;
});

// NG
promise.then((x) => {
  anyOtherVariable = x;
});

// NG
promise.then((x) => {
  anyOtherVariable.x = x;
});

// NG
promise.then((x) => {
  x();
});
```

### ignoreLastCallback

type: `boolean`

default: `false`

You can pass an `{ ignoreLastCallback: true }` as an option to this rule so that
the last `then()` callback in a promise chain does not warn if it does not have
a `return`. Default is `false`.

```javascript
// OK
promise.then((x) => {
  console.log(x);
});
// OK
void promise.then((x) => {
  console.log(x);
});
// OK
await promise.then((x) => {
  console.log(x);
});

promise
  // NG
  .then((x) => {
    console.log(x);
  })
  // OK
  .then((x) => {
    console.log(x);
  });

// NG
const v = promise.then((x) => {
  console.log(x);
});
// NG
const v = await promise.then((x) => {
  console.log(x);
});
function foo() {
  // NG
  return promise.then((x) => {
    console.log(x);
  });
}
```

## How to use

## Version

This rule was added in v1.13.0.

## References

---

---
url: /docs/guide/usage/linter/rules/promise/avoid-new.md
---

### What it does

Disallow creating promises with `new Promise()`.

### Why is this bad?

Many cases that use `new Promise()` could be refactored to use an
`async` function. `async` is considered more idiomatic in modern JavaScript.

### Examples

Examples of **incorrect** code for this rule:

```javascript
function foo() {
  return new Promise((resolve, reject) => {
    /* ... */
  });
}
```

Examples of **correct** code for this rule:

```javascript
async function foo() {
  // ...
}
const bar = await Promise.all([baz(), bang()]);
```

## How to use

## Version

This rule was added in v0.6.1.

## References

---

---
url: /docs/guide/usage/linter/rules/promise/catch-or-return.md
---

### What it does

Ensure that each time a `then()` is applied to a promise, a `catch()`
must be applied as well. Exceptions are made for promises returned from
a function.

### Why is this bad?

Not catching errors in a promise can cause hard to debug problems or
missing handling of error conditions. In the worst case, unhandled
promise rejections can cause your application to crash.

### Examples

Examples of **incorrect** code for this rule:

```javascript
myPromise.then(doSomething);
myPromise.then(doSomething, catchErrors); // catch() may be a little better
```

Examples of **correct** code for this rule:

```javascript
myPromise.then(doSomething).catch(errors);
function doSomethingElse() {
  return myPromise.then(doSomething);
}
const arrowFunc = () => myPromise.then(doSomething);
```

## Configuration

This rule accepts a configuration object with the following properties:

### allowFinally

type: `boolean`

default: `false`

Whether to allow `finally()` as a termination method.

### allowThen

type: `boolean`

default: `false`

Whether to allow `then()` with two arguments as a termination method.

### allowThenStrict

type: `boolean`

default: `false`

Whether to allow `then(null, handler)` as a termination method.

### terminationMethod

type: `array | string`

#### terminationMethod\[n]

type: `string`

## How to use

## Version

This rule was added in v0.9.2.

## References

---

---
url: /docs/guide/usage/linter/rules/promise/no-callback-in-promise.md
---

### What it does

Disallows calling a callback function (`cb()`) inside a `Promise.prototype.then()`
or `Promise.prototype.catch()`.

### Why is this bad?

Directly invoking a callback inside a `then()` or `catch()` method can lead to
unexpected behavior, such as the callback being called multiple times. Additionally,
mixing the callback and promise paradigms in this way can make the code confusing
and harder to maintain.

### Examples

Examples of **incorrect** code for this rule:

```js
function callback(err, data) {
  console.log("Callback got called with:", err, data);
  throw new Error("My error");
}

Promise.resolve()
  .then(() => callback(null, "data"))
  .catch((err) => callback(err.message, null));
```

Examples of **correct** code for this rule:

```js
Promise.resolve()
  .then((data) => {
    console.log(data);
  })
  .catch((err) => {
    console.error(err);
  });
```

## Configuration

This rule accepts a configuration object with the following properties:

### exceptions

type: `string[]`

default: `[]`

List of callback function names to allow within Promise `then` and `catch` methods.

### timeoutsErr

type: `boolean`

default: `false`

Boolean as to whether callbacks in timeout functions like `setTimeout` will err.

## How to use

## Version

This rule was added in v0.10.0.

## References

---

---
url: /docs/guide/usage/linter/rules/promise/no-multiple-resolved.md
---

### What it does

This rule warns of paths that resolve multiple times in executor functions of Promise constructors.

### Why is this bad?

Multiple resolve/reject calls:

* Violate the Promise/A+ specification
* Have no effect on the Promise's behavior
* Make the code's intent unclear
* May indicate logical errors in the implementation

### Examples

Examples of **incorrect** code for this rule:

```javascript
new Promise((resolve, reject) => {
  fn((error, value) => {
    if (error) {
      reject(error);
    }

    resolve(value); // Both `reject` and `resolve` may be called.
  });
});
```

Examples of **correct** code for this rule:

```javascript
new Promise((resolve, reject) => {
  fn((error, value) => {
    if (error) {
      reject(error);
    } else {
      resolve(value);
    }
  });
});
```

## How to use

## Version

This rule was added in v1.19.0.

## References

---

---
url: /docs/guide/usage/linter/rules/promise/no-nesting.md
---

### What it does

Disallow nested `then()` or `catch()` statements.

### Why is this bad?

Nesting promises makes code harder to read and understand.

### Examples

Examples of **incorrect** code for this rule:

```javascript
doThing().then(() => a.then());

doThing().then(function () {
  a.then();
});

doThing().then(() => {
  b.catch();
});

doThing().catch((val) => doSomething(val).catch(errors));
```

Examples of **correct** code for this rule:

```javascript
doThing().then(() => 4);

doThing().then(function () {
  return 4;
});

doThing().catch(() => 4);
```

```javascript
doThing()
  .then(() => Promise.resolve(1))
  .then(() => Promise.resolve(2));
```

This example is not a rule violation as unnesting here would
result in `a` being undefined in the expression `getC(a, b)`.

```javascript
doThing().then((a) => getB(a).then((b) => getC(a, b)));
```

## How to use

## Version

This rule was added in v0.15.13.

## References

---

---
url: /docs/guide/usage/linter/rules/promise/no-new-statics.md
---

### What it does

Disallows calling new on static `Promise` methods.

### Why is this bad?

Calling a static `Promise` method with `new` is invalid and will result
in a `TypeError` at runtime.

### Examples

Examples of **incorrect** code for this rule:

```javascript
const x = new Promise.resolve(value);
```

Examples of **correct** code for this rule:

```javascript
const x = Promise.resolve(value);
```

## How to use

## Version

This rule was added in v0.6.1.

## References

---

---
url: /docs/guide/usage/linter/rules/promise/no-promise-in-callback.md
---

### What it does

Disallows the use of Promises within error-first callback functions.

### Why is this bad?

Mixing Promises and callbacks can lead to unclear and inconsistent code.
Promises and callbacks are different patterns for handling asynchronous code.
Mixing them makes the logic flow harder to follow and complicates error handling,
as callbacks rely on an error-first pattern, while Promises use `catch`.

### Examples

Examples of **incorrect** code for this rule:

```js
doSomething((err, val) => {
  if (err) console.error(err);
  else doSomethingElse(val).then(console.log);
});
```

Examples of **correct** code for this rule:

```js
promisify(doSomething)().then(doSomethingElse).then(console.log).catch(console.error);
```

## Configuration

### exemptDeclarations

type: `boolean`

default: `false`

Whether or not to exempt function declarations. Defaults to `false`.

## How to use

## Version

This rule was added in v0.13.1.

## References

---

---
url: /docs/guide/usage/linter/rules/promise/no-return-in-finally.md
---

### What it does

Disallow return statements in a `finally()` callback of a promise.

### Why is this bad?

Disallow return statements inside a callback passed to finally(), since nothing would
consume what's returned.

### Examples

Examples of **incorrect** code for this rule:

```javascript
myPromise.finally(function (val) {
  return val;
});
```

Examples of **correct** code for this rule:

```javascript
Promise.resolve(1).finally(() => {
  console.log(2);
});
```

## How to use

## Version

This rule was added in v0.7.1.

## References

---

---
url: /docs/guide/usage/linter/rules/promise/no-return-wrap.md
---

### What it does

Prevents unnecessary wrapping of return values in promises with either `Promise.resolve`
or `Promise.reject`.

This rule enforces the following stances:

1. When a promise is to be resolved, instead of returning `Promise.resolve(value)` it is
   better to return the raw value with `return value` instead.

2. When a promise is to be rejected, instead of returning `Promise.reject(error)`, instead
   the raw error value should be thrown as in `throw error`.

There is an option to turn off the enforcing of 2, see the options section below.

### Why is this bad?

It is unnecessary to use `Promise.resolve` and `Promise.reject` for converting raw values
to promises in the return statements of `then` and `catch` callbacks. Using these
operations to convert raw values to promises is unnecessary as simply returning the raw
value for the success case and throwing the raw error value in the failure case have the
same effect. This is why some take the opinion that returning values such as
`Promise.resolve(1)` or `Promise.reject(err)` is syntactic noise.

### Examples

Examples of **incorrect** code for this rule:

```js
myPromise().then(() => Promise.resolve(4));
myPromise().then(function () {
  return Promise.resolve(4);
});

myPromise().then(() => Promise.reject("err"));
myPromise().then(function () {
  return Promise.reject("err");
});
```

```js
myPromise().catch(function () {
  return Promise.reject("err");
});
```

```js
myPromise().finally(function () {
  return Promise.reject("err");
});
```

```js
myPromise().finally(() => Promise.resolve(4));
```

Examples of **correct** code for this rule:

```js
myPromise().then(() => 4);
myPromise().then(function () {
  return 4;
});

myPromise().then(() => throw "err");
myPromise().then(function () {
  throw "err";
});
```

```js
myPromise().catch(function () {
  throw "err";
});
```

```js
myPromise().finally(() => 4);
```

## Configuration

This rule accepts a configuration object with the following properties:

### allowReject

type: `boolean`

default: `false`

`allowReject` allows returning `Promise.reject` inside a promise handler.

With `allowReject` set to `true` the following are examples of correct code:

```js
myPromise().then(function () {
  return Promise.reject(0);
});
```

```js
myPromise()
  .then()
  .catch(() => Promise.reject("err"));
```

## How to use

## Version

This rule was added in v0.15.14.

## References

---

---
url: /docs/guide/usage/linter/rules/promise/param-names.md
---

### What it does

Enforce standard parameter names for Promise constructors.

### Why is this bad?

Ensures that new Promise() is instantiated with the parameter names resolve, reject to
avoid confusion with order such as reject, resolve. The Promise constructor uses the
RevealingConstructor pattern. Using the same parameter names as the language specification
makes code more uniform and easier to understand.

### Examples

Examples of **incorrect** code for this rule:

```javascript
new Promise(function (reject, resolve) {
  /* ... */
}); // incorrect order
new Promise(function (ok, fail) {
  /* ... */
}); // non-standard parameter names
```

Examples of **correct** code for this rule:

```javascript
new Promise(function (resolve, reject) {});
```

## Configuration

This rule accepts a configuration object with the following properties:

### rejectPattern

type: `string`

Regex pattern used to validate the `reject` parameter name. If provided, this pattern
is used instead of the default `^_?reject$` check.

### resolvePattern

type: `string`

Regex pattern used to validate the `resolve` parameter name. If provided, this pattern
is used instead of the default `^_?resolve$` check.

## How to use

## Version

This rule was added in v0.6.1.

## References

---

---
url: /docs/guide/usage/linter/rules/promise/prefer-await-to-callbacks.md
---

### 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) => {});
```

## How to use

## Version

This rule was added in v0.9.10.

## References

---

---
url: /docs/guide/usage/linter/rules/promise/prefer-await-to-then.md
---

### What it does

Prefer `await` to `then()`/`catch()`/`finally()` for reading Promise values.

### Why is this bad?

Async/await syntax can be seen as more readable.

### Examples

Examples of **incorrect** code for this rule:

```javascript
function foo() {
  hey.then((x) => {});
}
```

Examples of **correct** code for this rule:

```javascript
async function hi() {
  await thing();
}
```

### Example with strict mode

Examples of **incorrect** code with `{ strict: true }`:

```javascript
async function hi() {
  await thing().then((x) => {});
}
```

## Configuration

This rule accepts a configuration object with the following properties:

### strict

type: `boolean`

default: `false`

If true, enforces the rule even after an `await` or `yield` expression.

## How to use

## Version

This rule was added in v0.7.1.

## References

---

---
url: /docs/guide/usage/linter/rules/promise/prefer-catch.md
---

### What it does

Prefer `catch` to `then(a, b)` and `then(null, b)`. This rule disallows the passing of an
argument into the second parameter of `then` calls for handling promise errors.

### Why is this bad?

A `then` call with two arguments can make it more difficult to recognize that a catch error
handler is present. Another issue with using the second argument in `then` calls is that
the ordering of promise error handling is less obvious.

For example on first glance it may appear that `prom.then(fn1, fn2)` is equivalent to
`prom.then(fn1).catch(fn2)`. However they aren't equivalent. In fact
`prom.catch(fn2).then(fn1)` is the equivalent. This kind of confusion is a good reason for
preferring explicit `catch` calls over passing an argument to the second parameter of
`then` calls.

### Examples

Examples of **incorrect** code for this rule:

```js
prom.then(fn1, fn2);

prom.then(null, fn2);
```

Examples of **correct** code for this rule:

```js
prom.catch(fn2).then(fn1);

prom.catch(fn2);
```

## How to use

## Version

This rule was added in v0.15.14.

## References

---

---
url: /docs/guide/usage/linter/rules/promise/spec-only.md
---

### What it does

Disallow use of non-standard Promise static methods.

### Why is this bad?

Non-standard Promises may cost more maintenance work.

### Examples

Examples of **incorrect** code for this rule:

```js
Promise.done();
```

Examples of **correct** code for this rule:

```js
Promise.resolve();
```

## Configuration

This rule accepts a configuration object with the following properties:

### allowedMethods

type: `string[]`

default: `null`

List of Promise static methods that are allowed to be used.

## How to use

## Version

This rule was added in v0.9.2.

## References

---

---
url: /docs/guide/usage/linter/rules/promise/valid-params.md
---

### What it does

Enforces the proper number of arguments are passed to Promise functions.

This rule is generally unnecessary if using TypeScript.

### Why is this bad?

Calling a Promise function with the incorrect number of arguments can lead to unexpected
behavior or hard to spot bugs.

### Examples

Examples of **incorrect** code for this rule:

```javascript
Promise.resolve(1, 2);
```

Examples of **correct** code for this rule:

```javascript
Promise.resolve(1);
```

## How to use

## Version

This rule was added in v0.7.1.

## References

---

---
url: /docs/guide/usage/formatter/quickstart.md
description: Install Oxfmt and learn the common workflows.
---

# Quickstart

Recommended setup and common workflows.

## Install

Install `oxfmt` as a dev dependency:

::: code-group

```sh [npm]
$ npm add -D oxfmt
```

```sh [pnpm]
$ pnpm add -D oxfmt
```

```sh [yarn]
$ yarn add -D oxfmt
```

```sh [bun]
$ bun add -D oxfmt
```

:::

::: warning Standalone binary
Oxfmt is also available as a standalone binary. It works as a pure CLI without Node.js, but does not support [Prettier-backed formats](./language-support#prettier-backed) (these files are skipped), dynamic config files (`oxfmt.config.ts`), [Tailwind CSS class sorting](./sorting#sort-tailwind-css-classes), [LSP](./editors) mode, etc.

The npm package is the recommended way to install Oxfmt and supports all features for now.
:::

Add scripts to `package.json`:

```json [package.json]
{
  "scripts": {
    "fmt": "oxfmt",
    "fmt:check": "oxfmt --check"
  }
}
```

Format files:

::: code-group

```sh [npm]
npm run fmt
```

```sh [pnpm]
pnpm run fmt
```

```sh [yarn]
yarn run fmt
```

```sh [bun]
bun run fmt
```

:::

Check formatting without writing files:

::: code-group

```sh [npm]
npm run fmt:check
```

```sh [pnpm]
pnpm run fmt:check
```

```sh [yarn]
yarn run fmt:check
```

```sh [bun]
bun run fmt:check
```

:::

## Usage

```sh
oxfmt [OPTIONS] [PATH]...
```

Running `oxfmt` without arguments formats the current directory (equivalent to `prettier --write .`).

CLI options like `--no-semi` are not supported. Use the configuration file instead to ensure consistent settings across CLI and editor integrations.

To use glob patterns in positional paths, be sure to quote them. Otherwise, they may or may not be expanded depending on your environment.

For the complete list of options, see the [CLI reference](/docs/guide/usage/formatter/cli.html).

## Common workflows

### Pre-commit with lint-staged

```json [package.json]
{
  "lint-staged": {
    "*": "oxfmt --no-error-on-unmatched-pattern"
  }
}
```

`--no-error-on-unmatched-pattern` prevents errors when no files match the pattern.

### Create a config file

Initialize `.oxfmtrc.json` with defaults:

```sh
oxfmt --init
```

### Migrate from Prettier

```sh
oxfmt --migrate prettier
```

See [migrate from prettier](./migrate-from-prettier) for details.

### List files that differ

```sh
oxfmt --list-different
```

This is useful for configuring [files to ignore](./ignore-files).

### Piping file contents

```sh
echo 'const   x   =   1' | oxfmt --stdin-filepath test.ts
```

Prints `const x = 1;`

### Node.js API

```ts
import { format, type FormatOptions } from "oxfmt";

const input = `let a=42;`;
const options: FormatOptions = {
  semi: false,
};

const { code } = await format("a.js", input, options);
console.log(code); // "let a = 42"
```

## Next steps

* [Change configuration](./config)
* [Setup editors](./editors)
* [Setup CI](./ci)
* Learn advanced features: [sorting](./sorting), [embedded formatting](./embedded-formatting)
* [Compatibility matrix](/compatibility)
* Check [CLI reference](./cli)

---

---
url: /docs/guide/usage/linter/quickstart.md
description: Install Oxlint and learn the common workflows.
---

# Quickstart

This page shows the recommended setup for Oxlint and the most common workflows, with copy-paste commands.

## Install

Install `oxlint` as a dev dependency:

::: code-group

```sh [npm]
$ npm add -D oxlint
```

```sh [pnpm]
$ pnpm add -D oxlint
```

```sh [yarn]
$ yarn add -D oxlint
```

```sh [bun]
$ bun add -D oxlint
```

:::

Add lint commands to `package.json`:

```json [package.json]
{
  "scripts": {
    "lint": "oxlint",
    "lint:fix": "oxlint --fix"
  }
}
```

Run it:

::: code-group

```sh [npm]
npm run lint
```

```sh [pnpm]
pnpm run lint
```

```sh [yarn]
yarn run lint
```

```sh [bun]
bun run lint
```

:::

Apply fixes:

::: code-group

```sh [npm]
npm run lint:fix
```

```sh [pnpm]
pnpm run lint:fix
```

```sh [yarn]
yarn run lint:fix
```

```sh [bun]
bun run lint:fix
```

:::

## Usage

For the complete list of options, see the [CLI reference](/docs/guide/usage/linter/cli.html).

```sh
oxlint [OPTIONS] [PATH]...
```

If `PATH` is omitted, Oxlint lints the current working directory.

## Common workflows

### Pre-commit with [lint-staged](https://npmx.dev/package/lint-staged)

::: code-group

```json [npm]
{
  "lint-staged": {
    "*.{js,jsx,ts,tsx,mjs,cjs}": "npm run lint"
  }
}
```

```json [pnpm]
{
  "lint-staged": {
    "*.{js,jsx,ts,tsx,mjs,cjs}": "pnpm run lint"
  }
}
```

```json [yarn]
{
  "lint-staged": {
    "*.{js,jsx,ts,tsx,mjs,cjs}": "yarn run lint"
  }
}
```

```json [bun]
{
  "lint-staged": {
    "*.{js,jsx,ts,tsx,mjs,cjs}": "bun run lint"
  }
}
```

:::

### Create a config file

Initialize the `.oxlintrc.json` config with default values:

```sh
oxlint --init
```

Then customize `.oxlintrc.json` as needed. See [Configuration](/docs/guide/usage/linter/config).

Alternatively, Oxlint supports a TypeScript config file named `oxlint.config.ts` or `oxlint.config.mts`. See [Configuration](/docs/guide/usage/linter/config#typescript-config) for details.

Then run Oxlint:

```sh
oxlint
```

::: tip
If you are migrating from ESLint, see [the "Migrate from ESLint" page](/docs/guide/usage/linter/migrate-from-eslint) for detailed guidance on migrating.
:::

### Fix problems

Apply safe fixes:

```sh
oxlint --fix
```

Apply suggestions (may change program behavior):

```sh
oxlint --fix-suggestions
```

Apply dangerous fixes and suggestions:

```sh
oxlint --fix-dangerously
```

See [Automatic fixes](/docs/guide/usage/linter/automatic-fixes) for guidance on when to use each mode.

### Ignore files

Use an explicit ignore file:

```sh
oxlint --ignore-path .oxlintignore
```

Add ignore patterns from the command line:

```sh
oxlint --ignore-pattern "dist/**" --ignore-pattern "*.min.js"
```

Disable ignore handling:

```sh
oxlint --no-ignore
```

See [Ignore files](/docs/guide/usage/linter/ignore-files).

### Fail CI reliably

Only report errors:

```sh
oxlint --quiet
```

Fail if any warnings are found:

```sh
oxlint --deny-warnings
```

Fail if warnings exceed a threshold:

```sh
oxlint --max-warnings 0
```

See [CI setup](/docs/guide/usage/linter/ci).

### Use machine-readable output

Select an output format:

```sh
oxlint -f json
```

Available formats include: `default`, `json`, `unix`, `checkstyle`, `github`, `gitlab`, `junit`, and `stylish`. See [Output formats](/docs/guide/usage/linter/output-formats) for more info.

### Inspect the effective configuration

Print the configuration that would be used for a file:

```sh
oxlint --print-config path/to/file.ts
```

### List available rules

List registered rules, including those enabled by your current Oxlint config:

```sh
oxlint --rules
```

The full list is in the [Rules reference](/docs/guide/usage/linter/rules).

## Next steps

* Configure rules, plugins, and ignores: [Configuration](/docs/guide/usage/linter/config)
* [Setup editors](/docs/guide/usage/linter/editors)
* [Setup CI](/docs/guide/usage/linter/ci)
* Learn advanced features: [Multi-file analysis](/docs/guide/usage/linter/multi-file-analysis), [Type-aware linting](/docs/guide/usage/linter/type-aware), [JS plugins](/docs/guide/usage/linter/js-plugins)
* Migrate: [From ESLint](/docs/guide/usage/linter/migrate-from-eslint)&#x20;
* [Compatibility matrix](/compatibility)
* [CLI reference](/docs/guide/usage/linter/cli)

---

---
url: /docs/guide/usage/transformer/react-compiler.md
---
# React Compiler

Oxc has experimental support for the [React Compiler](https://react.dev/learn/react-compiler), which automatically memoizes React components and hooks.

::: warning
This feature is experimental and under active development. Options and behaviour may change.
:::

Under the hood, Oxc integrates the [Rust port of the React Compiler](https://github.com/facebook/react/pull/36173) rather than the Babel-based `babel-plugin-react-compiler`. Because that port is an merged React PR, but unpublished, Oxc vendors it as releasable crates at [oxc-project/forked-react-compiler](https://github.com/oxc-project/forked-react-compiler).

## General Usage

```js
import { transform } from "oxc-transform";

// Enable with default options.
const result = await transform("App.jsx", sourceCode, {
  reactCompiler: true,
});

// Or enable with options.
const result = await transform("App.jsx", sourceCode, {
  reactCompiler: {
    // React runtime version target. `'17'` and `'18'` require the
    // `react-compiler-runtime` package; `'19'` ships the runtime in `react`.
    target: "19", // '17' | '18' | '19'
  },
});
```

Pass `false` or omit the option to disable the React Compiler.

## When the React Compiler won't work

The React Compiler [requires the original source](https://react.dev/learn/react-compiler/installation): it must see JSX before any other transform. Plugins that rewrite JSX first break this. Examples:

* [`@emotion/babel-plugin`](https://emotion.sh/docs/@emotion/babel-plugin) and other `css` prop / JSX pragma transforms.
* [`@babel/plugin-transform-react-constant-elements`](https://babeljs.io/docs/babel-plugin-transform-react-constant-elements) and `-inline-elements`, which hoist or inline JSX.

This is why Oxc runs the React Compiler before its own JSX transform.

Code that breaks the [Rules of React](https://react.dev/reference/rules) is also skipped rather than optimized — for example interior mutability, or libraries built on observable mutation such as MobX's `observer()`.

To find that code, Oxlint has an experimental [`react/react-compiler`](../linter/rules/react/react-compiler) rule that runs the same analysis in lint-only mode and reports the violations.

---

---
url: /docs/guide/usage/linter/rules/react_perf/jsx-no-jsx-as-prop.md
---

### What it does

Prevent JSX elements that are local to the current method from being
used as values of JSX props.

### Why is this bad?

Using locally defined JSX elements as values for props can lead to
unintentional re-renders and performance issues. Every time the parent
renders, a new instance of the JSX element is created, causing unnecessary
re-renders of child components. This also leads to harder-to-maintain code
as the component's props are not passed consistently.

### Examples

Examples of **incorrect** code for this rule:

```jsx
<Item jsx={<SubItem />} />
<Item jsx={this.props.jsx || <SubItem />} />
<Item jsx={this.props.jsx ? this.props.jsx : <SubItem />} />
```

Examples of **correct** code for this rule:

```jsx
<Item callback={this.props.jsx} />
```

## Configuration

This rule accepts a configuration object with the following properties:

### nativeAllowList

type: `array | "all"`

#### nativeAllowList\[n]

type: `string`

## How to use

## Version

This rule was added in v0.2.3.

## References

---

---
url: /docs/guide/usage/linter/rules/react_perf/jsx-no-new-array-as-prop.md
---

### What it does

Prevent arrays that are local to the current method from being used
as values of JSX props.

### Why is this bad?

Using locally defined arrays as values for props can lead to unintentional
re-renders and performance issues. Every time the parent component renders,
a new instance of the Array is created, causing unnecessary re-renders of
child components. This also leads to harder-to-maintain code as the
component's props are not passed consistently.

### Examples

Examples of **incorrect** code for this rule:

```jsx
<Item list={[]} />
<Item list={new Array()} />
<Item list={Array()} />
<Item list={this.props.list || []} />
<Item list={this.props.list ? this.props.list : []} />
```

Examples of **correct** code for this rule:

```jsx
<Item list={this.props.list} />
```

## Configuration

This rule accepts a configuration object with the following properties:

### nativeAllowList

type: `array | "all"`

#### nativeAllowList\[n]

type: `string`

## How to use

## Version

This rule was added in v0.2.3.

## References

---

---
url: /docs/guide/usage/linter/rules/react_perf/jsx-no-new-function-as-prop.md
---

### What it does

Prevent functions that are local to the current method from being used
as values of JSX props.

### Why is this bad?

Using locally defined functions as values for props can lead to unintentional
re-renders and performance issues. Every time the parent component renders,
a new instance of the function is created, causing unnecessary re-renders
of child components. This also leads to harder-to-maintain code as the
component's props are not passed consistently.

### Examples

Examples of **incorrect** code for this rule:

```jsx
<Item callback={new Function(...)} />
<Item callback={this.props.callback || function() {}} />
```

Examples of **correct** code for this rule:

```jsx
<Item callback={this.props.callback} />
```

## Configuration

This rule accepts a configuration object with the following properties:

### nativeAllowList

type: `array | "all"`

#### nativeAllowList\[n]

type: `string`

## How to use

## Version

This rule was added in v0.2.3.

## References

---

---
url: /docs/guide/usage/linter/rules/react_perf/jsx-no-new-object-as-prop.md
---

### What it does

Prevent objects that are local to the current method from being used
as values of JSX props.

### Why is this bad?

Using locally defined objects as values for props can lead to unintentional
re-renders and performance issues. Every time the parent component renders,
a new instance of the Object is created, causing unnecessary re-renders of
child components. This also leads to harder-to-maintain code as the
component's props are not passed consistently.

### Examples

Examples of **incorrect** code for this rule:

```jsx
<Item config={{}} />
<Item config={new Object()} />
<Item config={Object()} />
<Item config={this.props.config || {}} />
<Item config={this.props.config ? this.props.config : {}} />
<div style={{display: 'none'}} />
```

Examples of **correct** code for this rule:

```jsx
<Item config={staticConfig} />
```

## Configuration

This rule accepts a configuration object with the following properties:

### nativeAllowList

type: `array | "all"`

#### nativeAllowList\[n]

type: `string`

## How to use

## Version

This rule was added in v0.2.3.

## References

---

---
url: /docs/guide/usage/linter/rules/react/button-has-type.md
---

### What it does

Enforces an explicit `type` attribute for all HTML `button` elements.

### Why is this bad?

The default value of `type` attribute for `button` HTML element is
`"submit"` which is often not the desired behavior and may lead to
unexpected page reloads.

### Examples

Examples of **incorrect** code for this rule:

```jsx
<button />
<button type="foo" />
```

Examples of **correct** code for this rule:

```jsx
<button type="button" />
<button type="submit" />
```

## Configuration

This rule accepts a configuration object with the following properties:

### button

type: `boolean`

default: `true`

If true, allow `type="button"`.

### reset

type: `boolean`

default: `true`

If true, allow `type="reset"`.

### submit

type: `boolean`

default: `true`

If true, allow `type="submit"`.

## How to use

## Version

This rule was added in v0.1.1.

## References

---

---
url: /docs/guide/usage/linter/rules/react/checked-requires-onchange-or-readonly.md
---

### What it does

This rule enforces `onChange` or `readOnly` attribute for checked property of input elements.
It also warns when `checked` and `defaultChecked` properties are used together.

### Why is this bad?

`checked` should generally always be used with one of `onChange` or `readOnly`.

And using `checked` and `defaultChecked` together is likely an error as they are mutually
exclusive ways to control the checked state of an input element.

### Examples

Examples of **incorrect** code for this rule:

```jsx
<input type="checkbox" checked />
<input type="checkbox" checked defaultChecked />
<input type="radio" checked defaultChecked />

React.createElement('input', { checked: false });
React.createElement('input', { type: 'checkbox', checked: true });
React.createElement('input', { type: 'checkbox', checked: true, defaultChecked: true });
```

Examples of **correct** code for this rule:

```jsx
<input type="checkbox" checked onChange={() => {}} />
<input type="checkbox" checked readOnly />
<input type="checkbox" checked onChange readOnly />
<input type="checkbox" defaultChecked />

React.createElement('input', { type: 'checkbox', checked: true, onChange() {} });
React.createElement('input', { type: 'checkbox', checked: true, readOnly: true });
React.createElement('input', { type: 'checkbox', checked: true, onChange() {}, readOnly: true });
React.createElement('input', { type: 'checkbox', defaultChecked: true });
```

## Configuration

This rule accepts a configuration object with the following properties:

### ignoreExclusiveCheckedAttribute

type: `boolean`

default: `false`

Ignore the restriction that `checked` and `defaultChecked` should not be used together.

### ignoreMissingProperties

type: `boolean`

default: `false`

Ignore the requirement to provide either `onChange` or `readOnly` when the `checked` prop is present.

## How to use

## Version

This rule was added in v0.2.15.

## References

---

---
url: /docs/guide/usage/linter/rules/react/display-name.md
---

### What it does

Enforces that React components have a `displayName` property.

### Why is this bad?

React DevTools uses `displayName` to show component names in the component tree.
Without `displayName`, components will show up as "Unknown" in DevTools.

### Examples

Examples of **incorrect** code for this rule:

```jsx
const MyComponent = () => <div>Hello</div>;
```

Examples of **correct** code for this rule:

```jsx
const MyComponent = () => <div>Hello</div>;
MyComponent.displayName = "MyComponent";
```

## Configuration

This rule accepts a configuration object with the following properties:

### checkContextObjects

type: `boolean`

default: `false`

When `true`, this rule will warn on context objects
without a `displayName`.

`displayName` allows you to [name your context](https://reactjs.org/docs/context.html#contextdisplayname) object.
This name is used in the React DevTools for the context's `Provider` and `Consumer`.

### ignoreTranspilerName

type: `boolean`

default: `false`

When `true`, the rule will ignore the name set by the transpiler
and require a `displayName` property in this case.

## How to use

## Version

This rule was added in v1.42.0.

## References

---

---
url: /docs/guide/usage/linter/rules/react/exhaustive-deps.md
---

### What it does

Verifies the list of dependencies for Hooks like `useEffect` and similar.

### Why is this bad?

React Hooks like `useEffect` and similar require a list of dependencies to be passed as an argument. This list is used to determine when the effect should be re-run. If the list is missing or incomplete, the effect may run more often than necessary, or not at all.

### Examples

Examples of **incorrect** code for this rule:

```javascript
function MyComponent(props) {
  useEffect(() => {
    console.log(props.foo);
  }, []);
  // `props` is missing from the dependencies array
  return <div />;
}
```

Examples of **correct** code for this rule:

```javascript
function MyComponent(props) {
  useEffect(() => {
    console.log(props.foo);
  }, [props]);
  return <div />;
}
```

## Configuration

This rule accepts a configuration object with the following properties:

### additionalHooks

type: `string`

Optionally provide a regex of additional hooks to check.

## How to use

## Version

This rule was added in v0.12.0.

## References

---

---
url: /docs/guide/usage/linter/rules/react/forbid-component-props.md
---

### What it does

This rule prevents passing of props to components. This rule only applies to Components (e.g. `<Foo />`) and not DOM nodes (e.g. `<div />`).
By default this rule prevents passing of props that add lots of complexity (`className`, `style`) to Components.
The list of forbidden props can be customized with the forbid option.

### Why is this bad?

This rule checks all JSX elements and verifies that no forbidden props are used on components. This rule is off by default.

### Examples

Examples of **incorrect** code for this rule:

```jsx
<Hello className='foo' />
<Hello style={{color: 'red'}} />
```

Examples of **correct** code for this rule:

```jsx
<Hello name='Joe' />
<div className='foo' />
<div style={{color: 'red'}} />
```

## Configuration

This rule accepts a configuration object with the following properties:

### forbid

type: `array`

An array specifying the names of props that are forbidden.

The default value is `["className", "style"]`.

Each array element can be a string with the property name, or an object with `propName` / `propNamePattern`,
`allowedFor` / `allowedForPatterns`, `disallowedFor` / `disallowedForPatterns`, optional custom `message`

**Pattern matching**: Uses glob patterns to match prop names and component names.
For example, a `propNamePattern` of `"**-**"` would match any prop name that contains a hyphen, and an `allowedForPatterns` entry of `"*Icon"` would match component names like `SomeIcon` and `AnotherIcon`.
Note that the pattern matching is done in Rust with the fast-glob library, and so may differ
from the JavaScript glob library used by the original ESLint rule.

Examples:

* `["error", { "forbid": ["className", "style"] }]`
* `["error", { "forbid": [{ "propName": "className", "message": "Use variant instead" }] }]`
* `["error", { "forbid": [{ "propName": "className", "allowedFor": ["ReactModal"] }] }]`
* `["error", { "forbid": [{ "propNamePattern": "**-**", "disallowedFor": ["Foo"] }] }]`

#### forbid\[n]

type: `object | string`

A forbidden prop, either as a plain prop name string or with options.

##### forbid\[n].allowedFor

type: `string[]`

default: `[]`

Component names for which this prop is **allowed** (all others are
forbidden).

##### forbid\[n].allowedForPatterns

type: `string[]`

default: `[]`

Glob patterns for component names where the prop is **allowed**.

##### forbid\[n].disallowedFor

type: `string[]`

default: `[]`

Component names for which this prop is **disallowed** (all others are
allowed).

##### forbid\[n].disallowedForPatterns

type: `string[]`

default: `[]`

Glob patterns for component names where the prop is **disallowed**.

##### forbid\[n].message

type: `string`

Custom message to display.

##### forbid\[n].propName

type: `string`

Exact prop name to forbid.

##### forbid\[n].propNamePattern

type: `string`

Glob pattern to match prop names against.

## How to use

## Version

This rule was added in v1.62.0.

## References

---

---
url: /docs/guide/usage/linter/rules/react/forbid-dom-props.md
---

### What it does

This rule prevents passing of props to elements. This rule only applies to DOM Nodes (e.g. `<div />`) and not Components (e.g. `<Component />`). The list of forbidden props can be customized with the forbid option.

### Why is this bad?

This rule checks all JSX elements and verifies that no forbidden props are used on DOM Nodes. This rule is off by default.

### Examples

Examples of **incorrect** code for this rule:

```jsx
// [1, { "forbid": ["id"] }]
<div id='Joe' />

// [1, { "forbid": ["style"] }]
<div style={{color: 'red'}} />
```

Examples of **correct** code for this rule:

```jsx
// [1, { "forbid": ["id"] }]
<Hello id='foo' />

// [1, { "forbid": ["id"] }]
<Hello id={{color: 'red'}} />
```

## Configuration

Configuration for the `forbid-dom-props` rule.

This rule accepts a configuration object with the following properties:

### forbid

type: `array`

An array of prop names or objects that are forbidden on DOM elements.

Each array element can be a string with the property name, or an object
with `propName`, optional `disallowedFor` and `disallowedValues` arrays,
and an optional custom `message`.

Examples:

* `["error", { "forbid": ["id", "style"] }]`
* `["error", { "forbid": [{ "propName": "className", "message": "Use class instead" }] }]`
* `["error", { "forbid": [{ "propName": "style", "disallowedFor": ["div", "span"] }] }]`
* `["error", { "forbid": [{ "propName": "type", "disallowedValues": ["button"] }] }]`

#### forbid\[n]

type: `object | string`

A forbidden prop, either as a plain prop name string or with options.

##### forbid\[n].disallowedFor

type: `string[]`

A list of DOM element names (e.g. `["div", "span"]`) on which this
prop is forbidden. If empty or omitted, the prop is forbidden on all
DOM elements.

##### forbid\[n].disallowedValues

type: `string[]`

A list of string literal values for which this prop is forbidden. If
omitted, the prop is forbidden for all values.

##### forbid\[n].message

type: `string`

A custom message to display when this prop is used.

##### forbid\[n].propName

type: `string`

The name of the prop to forbid.

## How to use

## Version

This rule was added in v1.24.0.

## References

---

---
url: /docs/guide/usage/linter/rules/react/forbid-elements.md
---

### What it does

Allows you to configure a list of forbidden elements and to specify their desired replacements.

### Why is this bad?

You may want to forbid usage of certain elements in favor of others, e.g.
forbid all `<div />` and use `<Box />` instead.

### Examples

Examples of **incorrect** code for this rule:

```jsx
// ["error", { "forbid": ["button"] }]
<button />;
React.createElement("button");

// ["error", { "forbid": ["Modal"] }]
<Modal />;
React.createElement(Modal);

// ["error", { "forbid": ["Namespaced.Element"] }]
<Namespaced.Element />;
React.createElement(Namespaced.Element);

// ["error", { "forbid": [{ "element": "button", "message": "use <Button> instead" }, "input"] }]
<div>
  <button />
  <input />
</div>;
React.createElement("div", {}, React.createElement("button", {}, React.createElement("input")));
```

Examples of **correct** code for this rule:

```jsx
// ["error", { "forbid": ["button"] }]
<Button />

// ["error", { "forbid": [{ "element": "button" }] }]
<Button />
```

## Configuration

This rule accepts a configuration object with the following properties:

### forbid

type: `array`

List of forbidden elements, with optional messages for display with lint violations.

Examples:

* `["error, { "forbid": ["button"] }]`
* `["error, { "forbid": [{ "element": "button", "message": "Use <Button> instead." }] }]`
* `["error, { "forbid": [{ "element": "input" }] }]`

#### forbid\[n]

type: `object | string`

A forbidden element, either as a plain element name or with a custom message.

##### forbid\[n].element

type: `string`

The element name to forbid.

##### forbid\[n].message

type: `string`

The message to display when this element is found

## How to use

## Version

This rule was added in v0.16.11.

## References

---

---
url: /docs/guide/usage/linter/rules/react/forward-ref-uses-ref.md
---

### What it does

Requires that components wrapped with `forwardRef` must have a `ref` parameter.
Omitting the `ref` argument is usually a bug,
and components not using `ref` don't need to be wrapped by `forwardRef`.

### Why is this bad?

Omitting the `ref` argument makes the `forwardRef` wrapper unnecessary,
and can lead to confusion.

### Examples

Examples of **incorrect** code for this rule:

```jsx
var React = require("react");

var Component = React.forwardRef((props) => <div />);
```

Examples of **correct** code for this rule:

```jsx
var React = require("react");

var Component = React.forwardRef((props, ref) => <div ref={ref} />);

var Component = React.forwardRef((props, ref) => <div />);

function Component(props) {
  return <div />;
}
```

## How to use

## Version

This rule was added in v0.16.9.

## References

---

---
url: /docs/guide/usage/linter/rules/react/function-component-definition.md
---

### What it does

Enforces a consistent function form for React function components.

### Why is this bad?

Mixing declarations, function expressions, and arrow functions makes component definitions
less predictable and harder to scan.

### Examples

Examples of **incorrect** code for this rule:

```jsx
const Component = () => <div />;
```

Examples of **correct** code for this rule:

```jsx
function Component() {
  return <div />;
}
```

## Configuration

### namedComponents

type: `array | "function-declaration" | "arrow-function" | "function-expression"`

#### namedComponents\[n]

type: `"function-declaration" | "arrow-function" | "function-expression"`

### unnamedComponents

type: `array | "arrow-function" | "function-expression"`

#### unnamedComponents\[n]

type: `"arrow-function" | "function-expression"`

## How to use

## Version

This rule was added in v1.75.0.

## References

---

---
url: /docs/guide/usage/linter/rules/react/hook-use-state.md
---

### What it does

Ensure destructuring and symmetric naming of useState hook value and setter variables.

### Why is this bad?

This rule checks whether the value and setter variables destructured from a React.useState() call are named symmetrically

### Examples

Examples of **incorrect** code for this rule:

```jsx
import React from "react";
export default function useColor() {
  // useState call is not destructured into value + setter pair
  const useStateResult = React.useState();
  return useStateResult;
}
```

```jsx
import React from "react";
export default function useColor() {
  // useState call is destructured into value + setter pair, but identifier
  // names do not follow the [thing, setThing] naming convention
  const [color, updateColor] = React.useState();
  return [color, updateColor];
}
```

Examples of **correct** code for this rule:

```jsx
import React from "react";
export default function useColor() {
  // useState call is destructured into value + setter pair whose identifiers
  // follow the [thing, setThing] naming convention
  const [color, setColor] = React.useState();
  return [color, setColor];
}
```

## Configuration

### allowDestructuredState

type: `boolean`

default: `false`

When true the rule will ignore the name of the destructured value.

## How to use

## Version

This rule was added in v1.59.0.

## References

---

---
url: /docs/guide/usage/linter/rules/react/iframe-missing-sandbox.md
---

### What it does

Enforce the `sandbox` attribute on `iframe` elements.

### Why is this bad?

The sandbox attribute enables an extra set of restrictions for the
content in the iframe. Using sandbox attribute is considered a good
security practice. To learn more about sandboxing, see [MDN's
documentation on the `sandbox`
attribute](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/iframe#sandbox).

This rule checks all React `<iframe>` elements and verifies that there
is `sandbox` attribute and that it's value is valid. In addition to that
it also reports cases where attribute contains `allow-scripts` and
`allow-same-origin` at the same time as this combination allows the
embedded document to remove the sandbox attribute and bypass the
restrictions.

### Examples

Examples of **incorrect** code for this rule:

```jsx
<iframe />;
<iframe sandbox="invalid-value" />;
<iframe sandbox="allow-same-origin allow-scripts" />;
```

Examples of **correct** code for this rule:

```jsx
<iframe sandbox="" />;
<iframe sandbox="allow-origin" />;
```

## How to use

## Version

This rule was added in v0.10.0.

## References

---

---
url: /docs/guide/usage/linter/rules/react/jsx-boolean-value.md
---

### What it does

Enforce a consistent boolean attribute style in your code.

### Why is this bad?

In JSX, you can set a boolean attribute to `true` or omit it.
This rule will enforce a consistent style for boolean attributes.

### Examples

Examples of **incorrect** code for this rule with default `"never"` mode:

```jsx
const Hello = <Hello personal={true} />;
```

Examples of **correct** code for this rule with default `"never"` mode:

```jsx
const Hello = <Hello personal />;

const Foo = <Foo isSomething={false} />;
```

Examples of **incorrect** code for this rule with `"always"` mode:

```jsx
const Hello = <Hello personal />;
```

Examples of **correct** code for this rule with `"always"` mode:

```jsx
const Hello = <Hello personal={true} />;
```

## Configuration

### The 1st option

type: `"always" | "never"`

#### `"always"`

All boolean attributes must have explicit values.

#### `"never"`

All boolean attributes must omit values that are set to `true`.

### The 2nd option

This option is an object with the following properties:

#### always

type: `string[]`

default: `[]`

List of attribute names that should always have explicit boolean values.
Only necessary when main mode is `"never"`.

#### assumeUndefinedIsFalse

type: `boolean`

default: `false`

If `true`, treats `prop={false}` as equivalent to the prop being `undefined`.
When combined with `"never"` mode, this will enforce that the attribute is omitted entirely.

```jsx
// With "assumeUndefinedIsFalse": true
<App foo={false} />; // Incorrect
<App />; // Correct
```

This option does nothing in `"always"` mode.

#### never

type: `string[]`

default: `[]`

List of attribute names that should never have explicit boolean values.
Only necessary when main mode is `"always"`.

## How to use

## Version

This rule was added in v0.7.0.

## References

---

---
url: /docs/guide/usage/linter/rules/react/jsx-curly-brace-presence.md
---

### What it does

Disallow unnecessary JSX expressions when literals alone are
sufficient or enforce JSX expressions on literals in JSX children or
attributes.

This rule allows you to enforce curly braces or disallow unnecessary
curly braces in JSX props and/or children.

For situations where JSX expressions are unnecessary, please refer to
[the React doc](https://react.dev/learn/writing-markup-with-jsx)
and [this page about JSX
gotchas](https://github.com/facebook/react/blob/v15.4.0-rc.3/docs/docs/02.3-jsx-gotchas.md#html-entities).

### Why is this bad?

Using different styles for your JSX code can make it harder to read and
less consistent.

Code consistency improves readability. By enforcing or disallowing
curly braces in JSX props and/or children, this rule helps maintain
consistent patterns across your application.

### Rule Details

By default, this rule will check for and warn about unnecessary curly
braces in both JSX props and children. For the sake of backwards
compatibility, prop values that are JSX elements are not considered by
default.

You can pass in options to enforce the presence of curly braces on JSX
props, children, JSX prop values that are JSX elements, or any
combination of the three. The same options are available for not
allowing unnecessary curly braces as well as ignoring the check.

**Note**: it is *highly recommended* that you configure this rule with
an object, and that you set "propElementValues" to "always". The ability
to omit curly braces around prop values that are JSX elements is
obscure, and intentionally undocumented, and should not be relied upon.

#### Example Configurations

```jsonc
{
  "rules": {
    "react/jsx-curly-brace-presence": ["error", { "props": <string>, "children": <string>, "propElementValues": <string> }]
  }
}
```

or alternatively

```jsonc
{
  "rules": {
    "react/jsx-curly-brace-presence": ["error", "always"], // or "never" or "ignore"
  },
}
```

### Fix Details

If passed in the option to fix, this is how a style violation will get fixed

* `always`: wrap a JSX attribute in curly braces/JSX expression and/or a JSX child the same way but also with double quotes

* `never`: get rid of curly braces from a JSX attribute and/or a JSX child

* All fixing operations use double quotes.

### Examples

Examples of **incorrect** code for this rule, when configured with `{ props: "always", children: "always" }`:

```jsx
<App>Hello world</App>;
<App prop="Hello world">{"Hello world"}</App>;
```

They can be fixed to:

```jsx
<App>{"Hello world"}</App>;
<App prop={"Hello world"}>{"Hello world"}</App>;
```

Examples of **incorrect** code for this rule, when configured with `{ props: "never", children: "never" }`:

```jsx
<App>{"Hello world"}</App>;
<App prop={"Hello world"} attr={"foo"} />;
```

They can be fixed to:

```jsx
<App>Hello world</App>;
<App prop="Hello world" attr="foo" />;
```

Examples of **incorrect** code for this rule, when configured with `{ props: "always", children: "always", "propElementValues": "always" }`:

```jsx
<App prop=<div /> />
```

They can be fixed to:

```jsx
<App prop={<div />} />
```

Examples of **incorrect** code for this rule, when configured with `{ props: "never", children: "never", "propElementValues": "never" }`:

```jsx
<App prop={<div />} />
```

They can be fixed to:

```jsx
<App prop=<div /> />
```

Examples of **incorrect** code for this rule, when configured with `"always"`:

```jsx
<App>Hello world</App>;
<App prop="Hello world" attr="foo">
  Hello world
</App>;
```

They can be fixed to:

```jsx
<App>{"Hello world"}</App>;
<App prop={"Hello world"} attr={"foo"}>
  {"Hello world"}
</App>;
```

Examples of **incorrect** code for this rule, when configured with `"never"`:

```jsx
<App prop={"foo"} attr={"bar"}>
  {"Hello world"}
</App>
```

It can fixed to:

```jsx
<App prop="foo" attr="bar">
  Hello world
</App>
```

### Edge cases

The fix also deals with template literals, strings with quotes, and
strings with escapes characters.

* If the rule is set to get rid of unnecessary curly braces and the
  template literal inside a JSX expression has no expression, it will
  throw a warning and be fixed with double quotes. For example:

```jsx
<App prop={`Hello world`}>{`Hello world`}</App>
```

will be warned and fixed to:

```jsx
<App prop="Hello world">Hello world</App>
```

* If the rule is set to enforce curly braces and the strings have
  quotes, it will be fixed with double quotes for JSX children and the
  normal way for JSX attributes. Also, double quotes will be escaped in
  the fix.

For example:

```jsx
<App prop='Hello "foo" world'>Hello 'foo' "bar" world</App>
```

will warned and fixed to:

```jsx
<App prop={'Hello "foo" world'}>{"Hello 'foo' \"bar\" world"}</App>
```

* If the rule is set to get rid of unnecessary curly braces(JSX
  expression) and there are characters that need to be escaped in its JSX
  form, such as quote characters, [forbidden JSX text
  characters](https://facebook.github.io/jsx/), escaped characters and
  anything that looks like HTML entity names, the code will not be warned
  because the fix may make the code less readable.

Examples of **correct** code for this rule, even when configured with `"never"`:

```jsx
<Color text={"\u00a0"} />
<App>{"Hello \u00b7 world"}</App>;
<style type="text/css">{'.main { margin-top: 0; }'}</style>;
/**
 * there's no way to inject a whitespace into jsx without a container so this
 * will always be allowed.
 */
<App>{' '}</App>
<App>{'     '}</App>
<App>{/* comment */ <Bpp />}</App> // the comment makes the container necessary
```

### When Not To Use It

You should turn this rule off if you are not concerned about maintaining
consistency regarding the use of curly braces in JSX props and/or
children as well as the use of unnecessary JSX expressions.

## Configuration

### children

type: `"always" | "never" | "ignore"`

default: `"never"`

Whether to enforce or disallow curly braces for child content of a JSX element.

* `never` will disallow unnecessary curly braces, e.g. this will be preferred: `<Foo>I love oxlint</Foo>`
* `always` will force the usage of curly braces like this, in all cases: `<Foo>{'I love oxlint'}</Foo>`
* `ignore` will allow either style for child content.

### propElementValues

type: `"always" | "never" | "ignore"`

default: `"ignore"`

When set to `ignore` or `never`, this JSX code is allowed (or enforced):
`<App prop=<div /> />;`

When set to `always`, the curly braces are required for prop values that are
JSX elements: `<App prop={<div />} />;`

**Note**: it is *highly* recommended that you set `propElementValues` to `always`.
The ability to omit curly braces around prop values that are JSX elements is obscure, and
intentionally undocumented, and should not be relied upon.

### props

type: `"always" | "never" | "ignore"`

default: `"never"`

Whether to enforce or disallow curly braces for props on JSX elements.

* `never` will disallow unnecessary curly braces, e.g. this will be preferred: `<Foo foo="bar" />`
* `always` will force the usage of curly braces like this, in all cases: `<Foo foo={'bar'} />`
* `ignore` will allow either style for prop values.

## How to use

## Version

This rule was added in v0.7.0.

## References

---

---
url: /docs/guide/usage/linter/rules/react/jsx-filename-extension.md
---

### What it does

Enforces consistent use of the `.jsx` file extension.

### Why is this bad?

Some bundlers or parsers need to know by the file extension that it contains JSX
in order to properly handle the files.

### Examples

Examples of **incorrect** code for this rule:

```jsx
// filename: MyComponent.js
function MyComponent() {
  return <div />;
}
```

Examples of **correct** code for this rule:

```jsx
// filename: MyComponent.jsx
function MyComponent() {
  return <div />;
}
```

## Configuration

This rule accepts a configuration object with the following properties:

### allow

type: `"always" | "as-needed"`

default: `"always"`

When to allow a JSX filename extension. By default all files may have a JSX extension.
Set this to `as-needed` to only allow JSX file extensions in files that contain JSX syntax.

#### `"always"`

Always allow a JSX filename extension.

#### `"as-needed"`

Only allow JSX filename extension for files that contain JSX syntax.

### extensions

type: `string[]`

default: `["jsx"]`

The set of allowed file extensions.
Can include or exclude the leading dot (e.g., "jsx" and ".jsx" are both valid).

### ignoreFilesWithoutCode

type: `boolean`

default: `false`

If enabled, files that do not contain code (i.e. are empty, contain only whitespaces or comments) will not be rejected.

## How to use

## Version

This rule was added in v0.15.14.

## References

---

---
url: /docs/guide/usage/linter/rules/react/jsx-fragments.md
---

### What it does

Enforces the shorthand or standard form for React Fragments.

### Why is this bad?

Makes code using fragments more consistent one way or the other.

## Configuration

This rule accepts one of the following string values:

### `"syntax"`

This is the default mode. It will enforce the shorthand syntax for React fragments, with one exception.
Keys or attributes are not supported by the shorthand syntax, so the rule will not warn on standard-form fragments that use those.

Examples of **incorrect** code for this rule:

```jsx
<React.Fragment>
  <Foo />
</React.Fragment>
```

Examples of **correct** code for this rule:

```jsx
<>
  <Foo />
</>
```

```jsx
<React.Fragment key="key">
  <Foo />
</React.Fragment>
```

### `"element"`

This mode enforces the standard form for React fragments.

Examples of **incorrect** code for this rule:

```jsx
<>
  <Foo />
</>
```

Examples of **correct** code for this rule:

```jsx
<React.Fragment>
  <Foo />
</React.Fragment>
```

```jsx
<React.Fragment key="key">
  <Foo />
</React.Fragment>
```

## How to use

## Version

This rule was added in v1.12.0.

## References

---

---
url: /docs/guide/usage/linter/rules/react/jsx-handler-names.md
---

### What it does

Ensures that any component or prop methods used to handle events are correctly prefixed.

### Why is this bad?

Inconsistent naming of event handlers and props can reduce code readability and maintainability.

### Examples

Examples of **incorrect** code for this rule:

```jsx
<MyComponent handleChange={this.handleChange} />
<MyComponent onChange={this.componentChanged} />
```

Examples of **correct** code for this rule:

```jsx
<MyComponent onChange={this.handleChange} />
<MyComponent onChange={this.props.onFoo} />
```

## Configuration

This rule accepts a configuration object with the following properties:

### checkInlineFunction

type: `boolean`

default: `false`

Whether to check for inline functions in JSX attributes.

### checkLocalVariables

type: `boolean`

default: `false`

Whether to check for local variables in JSX attributes.

### eventHandlerPrefix

type: `string | boolean`

default: `"handle"`

Event handler prefixes to check against.

### eventHandlerPropPrefix

type: `string | boolean`

default: `"on"`

Event handler prop prefixes to check against.

### ignoreComponentNames

type: `string[]`

default: `[]`

Component names to ignore when checking for event handler prefixes.

## How to use

## Version

This rule was added in v1.13.0.

## References

---

---
url: /docs/guide/usage/linter/rules/react/jsx-key.md
---

### What it does

Enforce `key` prop for elements in an array.

### Why is this bad?

React [requires a `key` prop](https://react.dev/learn/rendering-lists#rendering-data-from-arrays)
for elements in an array to help identify which items have changed, are added, or are removed.

### Examples

Examples of **incorrect** code for this rule:

```jsx
[1, 2, 3].map((x) => <App />);
[1, 2, 3]?.map((x) => <ListItem />);
```

Examples of **correct** code for this rule:

```jsx
[1, 2, 3].map((x) => <App key={x} />);
[1, 2, 3]?.map((x) => <ListItem key={x} />);
```

NOTE: This rule's option defaults differ from the defaults in the original ESLint plugin. It is recommended to keep
all options set to `true` for correctness reasons, but you may want to set them back to `false` to get behavior
parity when migrating from ESLint.

## Configuration

This rule accepts a configuration object with the following properties:

### checkFragmentShorthand

type: `boolean`

default: `true`

When true, check fragment shorthand `<>` for keys

### checkKeyMustBeforeSpread

type: `boolean`

default: `true`

When true, require key prop to be placed before any spread props

### warnOnDuplicates

type: `boolean`

default: `true`

When true, warn on duplicate key values

## How to use

## Version

This rule was added in v0.0.14.

## References

---

---
url: /docs/guide/usage/linter/rules/react/jsx-max-depth.md
---

### What it does

Enforces a maximum depth for nested JSX elements and fragments.

### Why is this bad?

Excessively nested JSX makes components harder to read and maintain.

### Examples

Examples of **incorrect** code for this rule:

```jsx
const Component = () => (
  <div>
    <div>
      <div>
        <span />
      </div>
    </div>
  </div>
);
```

Examples of **correct** code for this rule:

```jsx
const Component = () => (
  <div>
    <div>
      <span />
    </div>
  </div>
);
```

## Configuration

This rule accepts a configuration object with the following properties:

### max

type: `integer`

default: `2`

The maximum allowed depth of nested JSX elements and fragments.

## How to use

## Version

This rule was added in v1.36.0.

## References

---

---
url: /docs/guide/usage/linter/rules/react/jsx-no-comment-textnodes.md
---

### What it does

This rule prevents comment strings (e.g. beginning with `//` or `/*`) from being
accidentally injected as a text node in JSX statements.

### Why is this bad?

In JSX, any text node that is not wrapped in curly braces is considered
a literal string to be rendered. This can lead to unexpected behavior
when the text contains a comment.

### Examples

Examples of **incorrect** code for this rule:

```jsx
const Hello = () => {
  return <div>// empty div</div>;
};

const Hello = () => {
  return <div>/* empty div */</div>;
};
```

Examples of **correct** code for this rule:

```jsx
const Hello = () => {
  return <div>{/* empty div */}</div>;
};
```

## How to use

## Version

This rule was added in v0.0.14.

## References

---

---
url: /docs/guide/usage/linter/rules/react/jsx-no-constructed-context-values.md
---

### What it does

Disallows JSX context provider values that cause needless re-renders.

### Why is this bad?

React Context and all its child nodes and Consumers are re-rendered whenever the value prop
changes. Because each JavaScript object carries its own identity, things like object
expressions (`{foo: 'bar'}`) or function expressions get a new identity on every render.
This makes the context think it has gotten a new object and can cause needless re-renders
and unintended consequences.

This can be a large performance hit because not only will it cause the context providers
and consumers to re-render with all the elements in its subtree, the processing for the
tree scan React does to render the provider and find consumers is also wasted.

### Examples

Examples of **incorrect** code for this rule:

```jsx
return <SomeContext.Provider value={{ foo: "bar" }}>...</SomeContext.Provider>;
```

```jsx
function Component() {
  function foo() {}
  return <MyContext.Provider value={foo} />;
}
```

Examples of **correct** code for this rule:

```jsx
const foo = useMemo(() => ({ foo: "bar" }), []);
return <SomeContext.Provider value={foo}>...</SomeContext.Provider>;
```

```jsx
const MyContext = createContext();
const Component = () => <MyContext.Provider value="Some string" />;
```

## How to use

## Version

This rule was added in v1.48.0.

## References

---

---
url: /docs/guide/usage/linter/rules/react/jsx-no-duplicate-props.md
---

### What it does

This rule prevents duplicate props in JSX elements.

### Why is this bad?

Having duplicate props in a JSX element is most likely a mistake.
Creating JSX elements with duplicate props can cause unexpected behavior in your application.

### Examples

Examples of **incorrect** code for this rule:

```jsx
<App a a />;
<App foo={2} bar baz foo={3} />;
```

Examples of **correct** code for this rule:

```jsx
<App a />;
<App bar baz foo={3} />;
```

### Differences from eslint-plugin-react

This rule does not support the `ignoreCase` option. Props with different cases are
considered distinct and will not be flagged as duplicates (e.g., `<App foo Foo />`
is allowed). This is intentional, as props are case-sensitive in JSX.

## How to use

## Version

This rule was added in v0.0.14.

## References

---

---
url: /docs/guide/usage/linter/rules/react/jsx-no-literals.md
---

### What it does

Disallows usage of unwrapped string literals inside JSX, such as text
children of a JSX element or string-valued props.

### Why is this bad?

Hard-coded string literals in JSX make it difficult to support
internationalization (i18n). By requiring literals to be wrapped in a
JSX expression container (for example, a call to a translation
function), this rule helps ensure all user-facing text flows through a
single, auditable mechanism rather than being scattered as inline
strings throughout the markup.

### Examples

Examples of **incorrect** code for this rule:

```jsx
<div>Hello world</div>
```

Examples of **correct** code for this rule:

```jsx
<div>{"Hello world"}</div>
```

## Configuration

The options shared between the top-level config and each `elementOverrides` entry.

This rule accepts a configuration object with the following properties:

### allowedStrings

type: `string[]`

default: `[]`

An array of unique string values that would otherwise warn, but will be ignored.

### elementOverrides

type: `Record<string, object>`

An object where the keys are the element names and the values are objects with the same options as above. This allows you to specify different options for different elements.

### ignoreProps

type: `boolean`

default: `false`

(default: false) - When true the rule ignores literals used in props, wrapped or unwrapped.

### noAttributeStrings

type: `boolean`

default: `false`

(default: false) - Enforces no string literals used in attributes when set to true.

### noStrings

type: `boolean`

default: `false`

(default: false) - Enforces no string literals used as children, wrapped or unwrapped.

### restrictedAttributes

type: `string[]`

default: `[]`

An array of unique attribute names where string literals should be restricted. Only the specified attributes will be checked for string literals when this option is used. Note: When noAttributeStrings is true, this option is ignored at the root level.

## How to use

## Version

This rule was added in v1.70.0.

## References

---

---
url: /docs/guide/usage/linter/rules/react/jsx-no-script-url.md
---

### What it does

Disallow usage of `javascript:` URLs.

### Why is this bad?

URLs starting with `javascript:` are a dangerous attack surface because it’s easy to accidentally
include unsanitized output in a tag like `<a href>` and create a security hole.

Starting in React 16.9, any URLs starting with `javascript:` log a warning.

In React 19, `javascript:` URLs are
[disallowed entirely](https://react.dev/blog/2024/04/25/react-19-upgrade-guide#other-breaking-changes).

### Examples

Examples of **incorrect** code for this rule:

```jsx
<a href="javascript:void(0)">Test</a>
```

Examples of **correct** code for this rule:

```jsx
<Foo test="javascript:void(0)" />
```

## Configuration

### \[0]

type: `array`

#### \[0]\[n]

type: `object`

##### \[0]\[n].name

type: `string`

Component name.

##### \[0]\[n].props

type: `string[]`

List of properties that should be validated.

### \[1]

type: `object`

#### \[1].includeFromSettings

type: `boolean`

default: `false`

Whether to include components from settings.

## How to use

## Version

This rule was added in v0.13.2.

## References

---

---
url: /docs/guide/usage/linter/rules/react/jsx-no-target-blank.md
---

### What it does

This rule aims to prevent user-generated link hrefs and form actions from creating security vulnerabilities by
requiring `rel='noreferrer'` for external link hrefs and form actions, and optionally any dynamically generated
link hrefs and form actions.

### Why is this bad?

When creating a JSX element that has an `a` tag, it is often desired to have the link open in a new tab using the
`target='_blank'` attribute. Using this attribute unaccompanied by `rel='noreferrer'`, however, is a severe security
vulnerability (see [`noreferrer` docs] and [`noopener` docs] for more details).
This rules requires that you accompany `target='_blank'` attributes with `rel='noreferrer'`.

### Examples

Examples of **incorrect** code for this rule:

```jsx
var Hello = <a target="_blank" href="https://example.com/"></a>;
var Hello = <a target="_blank" href={dynamicLink}></a>;
```

Examples of **correct** code for this rule:

```jsx
/// correct
var Hello = <p target="_blank"></p>;
var Hello = <a target="_blank" rel="noreferrer" href="https://example.com"></a>;
var Hello = <a target="_blank" rel="noopener noreferrer" href="https://example.com"></a>;
var Hello = <a target="_blank" href="relative/path/in/the/host"></a>;
var Hello = <a target="_blank" href="/absolute/path/in/the/host"></a>;
var Hello = <a></a>;
```

[`noreferrer` docs]: https://html.spec.whatwg.org/multipage/links.html#link-type-noreferrer

[`noopener` docs]: https://html.spec.whatwg.org/multipage/links.html#link-type-noopener

## Configuration

This rule accepts a configuration object with the following properties:

### allowReferrer

type: `boolean`

default: `false`

Whether to allow referrers.

### enforceDynamicLinks

type: `"always" | "never"`

default: `"always"`

Whether to enforce dynamic links or enforce static links.

#### `"always"`

Always enforce dynamic links.

#### `"never"`

Always enforce static links.

### forms

type: `boolean`

default: `false`

Whether to check form elements.

### links

type: `boolean`

default: `true`

Whether to check link elements.

### warnOnSpreadAttributes

type: `boolean`

default: `false`

Whether to warn when spread attributes are used.

## How to use

## Version

This rule was added in v0.2.5.

## References

---

---
url: /docs/guide/usage/linter/rules/react/jsx-no-undef.md
---

### What it does

Disallow undeclared variables in JSX.

Note that this rule is generally unnecessary if you are using TypeScript, as
TypeScript will catch undeclared variables for you.

### Why is this bad?

It is most likely a potential ReferenceError caused by a misspelling of a variable or parameter name.

### Examples

Examples of **incorrect** code for this rule:

```jsx
const A = () => <App />;
const C = <B />;
```

## How to use

## Version

This rule was added in v0.1.1.

## References

---

---
url: /docs/guide/usage/linter/rules/react/jsx-no-useless-fragment.md
---

### What it does

Disallow unnecessary fragments.

### Why is this bad?

Fragments are a useful tool when you need to group multiple children without adding a
node to the DOM tree. However, sometimes you might end up with a fragment with a single
child. When this child is an element, string, or expression, it's not necessary to
use a fragment.

### Examples

Examples of **incorrect** code for this rule:

```jsx
<>foo</>
<div><>foo</></div>
```

Examples of **correct** code for this rule:

```jsx
<>foo <div></div></>
<div>foo</div>
```

## Configuration

This rule accepts a configuration object with the following properties:

### allowExpressions

type: `boolean`

default: `false`

Allow fragments with a single expression child.

## How to use

## Version

This rule was added in v0.0.14.

## References

---

---
url: /docs/guide/usage/linter/rules/react/jsx-pascal-case.md
---

### What it does

Enforce PascalCase for user-defined JSX components.

### Why is this bad?

It enforces coding style that user-defined JSX components are defined and referenced in PascalCase. Note that since React's JSX uses the upper vs. lower case convention
to distinguish between local component classes and HTML tags this rule will not warn on components that start with a lower case letter.

### Examples

Examples of **incorrect** code for this rule:

```jsx
<Test_component />
<TEST_COMPONENT />
```

Examples of **correct** code for this rule:

```jsx
<div />

<TestComponent />

<TestComponent>
    <div />
</TestComponent>

<CSSTransitionGroup />
```

Examples of **correct** code for the "allowAllCaps" option:

```jsx
<ALLOWED />

<TEST_COMPONENT />
```

Examples of **correct** code for the "allowNamespace" option:

```jsx
<Allowed.div />

<TestComponent.p />
```

Examples of **correct** code for the "allowLeadingUnderscore" option:

```jsx
<_AllowedComponent />

<_AllowedComponent>
    <div />
</_AllowedComponent>
```

## Configuration

This rule accepts a configuration object with the following properties:

### allowAllCaps

type: `boolean`

default: `false`

Whether to allow all-caps component names.

### allowLeadingUnderscore

type: `boolean`

default: `false`

Whether to allow leading underscores in component names.

### allowNamespace

type: `boolean`

default: `false`

Whether to allow namespaced component names.

### ignore

type: `string[]`

default: `[]`

List of component names to ignore.

## How to use

## Version

This rule was added in v1.19.0.

## References

---

---
url: /docs/guide/usage/linter/rules/react/jsx-props-no-spread-multi.md
---

### What it does

Enforces that any unique expression is only spread once.

### Why is this bad?

Generally spreading the same expression twice is an indicator of a mistake since any attribute between the spreads may be overridden when the intent was not to.
Even when that is not the case this will lead to unnecessary computations being performed.

### Examples

Examples of **incorrect** code for this rule:

```jsx
<App {...props} myAttr="1" {...props} />
```

Examples of **correct** code for this rule:

```jsx
<App myAttr="1" {...props} />
<App {...props} myAttr="1" />
```

## How to use

## Version

This rule was added in v0.7.2.

## References

---

---
url: /docs/guide/usage/linter/rules/react/jsx-props-no-spreading.md
---

### What it does

Disallow JSX prop spreading.

### Why is this bad?

Enforces that there is no spreading for any JSX attribute. This enhances readability of code by being more explicit about what props are received by the component.
It is also good for maintainability by avoiding passing unintentional extra props and allowing react to emit warnings when invalid HTML props are passed to HTML elements.

### Examples

Examples of **incorrect** code for this rule:

```jsx
<App {...props} />
<MyCustomComponent {...props} some_other_prop={some_other_prop} />
<img {...props} />
```

Examples of **correct** code for this rule:

```jsx
const {src, alt} = props;
const {one_prop, two_prop} = otherProps;
<MyCustomComponent one_prop={one_prop} two_prop={two_prop} />
<img src={src} alt={alt} />
```

## Configuration

This rule accepts a configuration object with the following properties:

### custom

type: `"ignore" | "enforce"`

default: `"enforce"`

`custom` set to `ignore` will ignore all custom jsx tags like `App`, `MyCustomComponent` etc. Default is set to `enforce`.

### exceptions

type: `string[]`

default: `[]`

Exceptions flip the enforcement behavior for specific components.
For example:

* If `html` is set to `ignore`, an exception for `div` will enforce the rule on `<div>` elements.
* If `custom` is set to `enforce`, an exception for `Foo` will ignore the rule on `<Foo>` components.

This allows you to override the general setting for individual components.

### explicitSpread

type: `"ignore" | "enforce"`

default: `"enforce"`

`explicitSpread` set to `ignore` will ignore spread operators that are explicitly listing all object properties within that spread. Default is set to `enforce`.

### html

type: `"ignore" | "enforce"`

default: `"enforce"`

`html` set to `ignore` will ignore all html jsx tags like `div`, `img` etc. Default is set to `enforce`.

## How to use

## Version

This rule was added in v1.33.0.

## References

---

---
url: /docs/guide/usage/linter/rules/react/no-array-index-key.md
---

### What it does

Warn if an element uses an Array index in its key.

### Why is this bad?

It's a bad idea to use the array index since it doesn't uniquely identify your elements.
In cases where the array is sorted or an element is added to the beginning of the array,
the index will be changed even though the element representing that index may be the same.
This results in unnecessary renders.

### Examples

Examples of **incorrect** code for this rule:

```jsx
things.map((thing, index) => <Hello key={index} />);
```

Examples of **correct** code for this rule:

```jsx
things.map((thing, index) => <Hello key={thing.id} />);
```

## How to use

## Version

This rule was added in v0.13.0.

## References

---

---
url: /docs/guide/usage/linter/rules/react/no-children-prop.md
---

### What it does

Checks that children are not passed using a prop.

### Why is this bad?

Children should always be actual children, not passed in as a prop.
When using JSX, the children should be nested between the opening and closing tags.
When not using JSX, the children should be passed as additional arguments to `React.createElement`.

### Examples

Examples of **incorrect** code for this rule:

```jsx
<div children='Children' />

<MyComponent children={<AnotherComponent />} />
<MyComponent children={['Child 1', 'Child 2']} />
React.createElement("div", { children: 'Children' })
```

Examples of **correct** code for this rule:

```jsx
<div>Children</div>
<MyComponent>Children</MyComponent>

<MyComponent>
  <span>Child 1</span>
  <span>Child 2</span>
</MyComponent>

React.createElement("div", {}, 'Children')
React.createElement("div", 'Child 1', 'Child 2')
```

## How to use

## Version

This rule was added in v0.0.14.

## References

---

---
url: /docs/guide/usage/linter/rules/react/no-clone-element.md
---

### What it does

Prevents the usage of `React.cloneElement`, which is considered an anti-pattern in React.

### Why is this bad?

It is recommended not to use `React.cloneElement` because it can lead to code that is
harder to follow and understand. It is generally uncommon and fragile, and there are various
alternatives recommended by
[the React documentation](https://react.dev/reference/react/cloneElement#alternatives).

Note that this rule is based on [`@eslint-react/no-clone-element`](https://www.eslint-react.xyz/docs/rules/no-clone-element)
from `@eslint-react`, not a rule from `eslint-plugin-react`.

### Examples

Examples of **incorrect** code for this rule:

```jsx
import { cloneElement } from "react";

function List({ children }) {
  const [selectedIndex, setSelectedIndex] = useState(0);
  return (
    <div className="List">
      {Children.map(children, (child, index) =>
        cloneElement(child, {
          isHighlighted: index === selectedIndex,
        }),
      )}
    </div>
  );
}
```

Examples of **correct** code for this rule:

```jsx
// Using a map with a `renderItem` function prop instead.
function List({ items, renderItem }) {
  const [selectedIndex, setSelectedIndex] = useState(0);
  return (
    <div className="List">
      {items.map((item, index) => {
        const isHighlighted = index === selectedIndex;
        return renderItem(item, isHighlighted);
      })}
    </div>
  );
}
```

## How to use

## Version

This rule was added in v1.53.0.

## References

---

---
url: /docs/guide/usage/linter/rules/react/no-danger.md
---

### What it does

This rule prevents the use of `dangerouslySetInnerHTML` prop.

### Why is this bad?

`dangerouslySetInnerHTML` is a way to inject HTML into your React
component. This is dangerous because it can easily lead to XSS
vulnerabilities.

### Examples

Examples of **incorrect** code for this rule:

```jsx
import React from "react";

const Hello = <div dangerouslySetInnerHTML={{ __html: "Hello World" }}></div>;
```

Examples of **correct** code for this rule:

```jsx
import React from "react";

const Hello = <div>Hello World</div>;
```

## How to use

## Version

This rule was added in v0.0.14.

## References

---

---
url: /docs/guide/usage/linter/rules/react/no-danger-with-children.md
---

### What it does

Disallows DOM elements from using both `children` and `dangerouslySetInnerHTML` properties.

### Why is this bad?

React will throw a warning if this rule is ignored and both `children` and `dangerouslySetInnerHTML` are used.

### Examples

Examples of **incorrect** code for this rule:

```jsx
<div dangerouslySetInnerHTML={{ __html: "HTML" }}>Children</div>;
React.createElement("div", { dangerouslySetInnerHTML: { __html: "HTML" } }, "Children");
```

Examples of **correct** code for this rule:

```jsx
<div>Children</div>
<div dangerouslySetInnerHTML={{ __html: "HTML" }} />
```

## How to use

## Version

This rule was added in v0.9.6.

## References

---

---
url: /docs/guide/usage/linter/rules/react/no-did-mount-set-state.md
---

### What it does

Disallows using `setState` in the `componentDidMount` lifecycle method.

This rule is not relevant for function components, and so can potentially be
disabled for modern React codebases.

### Why is this bad?

Updating the state after a component mount will trigger a second `render()` call and can lead to property/layout thrashing.
This can cause performance issues and unexpected behavior.

### Examples

Examples of **incorrect** code for this rule:

```jsx
var Hello = createReactClass({
  componentDidMount: function () {
    this.setState({
      name: this.props.name.toUpperCase(),
    });
  },
  render: function () {
    return <div>Hello {this.state.name}</div>;
  },
});
```

Examples of **correct** code for this rule:

```jsx
var Hello = createReactClass({
  componentDidMount: function () {
    this.onMount(function callback(newName) {
      this.setState({
        name: newName,
      });
    });
  },
  render: function () {
    return <div>Hello {this.state.name}</div>;
  },
});
```

## Configuration

This rule accepts one of the following string values:

type: `"allowed" | "disallow-in-func"`

## How to use

## Version

This rule was added in v1.36.0.

## References

---

---
url: /docs/guide/usage/linter/rules/react/no-did-update-set-state.md
---

### What it does

Disallow usage of `setState` in `componentDidUpdate`.

### Why is this bad?

Updating the state after a component update will trigger a second `render()` call and can lead to property/layout thrashing.

### Examples

Examples of **incorrect** code for this rule:

```jsx
var Hello = createReactClass({
  componentDidUpdate: function () {
    this.setState({
      name: this.props.name.toUpperCase(),
    });
  },
  render: function () {
    return <div>Hello {this.state.name}</div>;
  },
});
```

Examples of **correct** code for this rule:

```jsx
var Hello = createReactClass({
  componentDidUpdate: function () {
    this.props.onUpdate();
  },
  render: function () {
    return <div>Hello {this.props.name}</div>;
  },
});
```

```jsx
var Hello = createReactClass({
  componentDidUpdate: function () {
    this.onUpdate(function callback(newName) {
      this.setState({
        name: newName,
      });
    });
  },
  render: function () {
    return <div>Hello {this.props.name}</div>;
  },
});
```

## Configuration

This rule accepts one of the following string values:

type: `"allowed" | "disallow-in-func"`

## How to use

## Version

This rule was added in v1.62.0.

## References

---

---
url: /docs/guide/usage/linter/rules/react/no-direct-mutation-state.md
---

### What it does

This rule forbids the direct mutation of `this.state` in React components.

Note that this rule only applies to class components, it does not apply to function
components. For modern React codebases, this rule may not be necessary or relevant.

### Why is this bad?

React components should *never* mutate `this.state` directly, as
calling `setState()` afterwards may replace the mutation you made.

`this.state` should be treated as if it were immutable.

### Examples

Examples of **incorrect** code for this rule:

```jsx
var Hello = createReactClass({
  componentDidMount: function () {
    this.state.name = this.props.name.toUpperCase();
  },
  render: function () {
    return <div>Hello {this.state.name}</div>;
  },
});

class Hello extends React.Component {
  constructor(props) {
    super(props);

    doSomethingAsync(() => {
      this.state = "bad";
    });
  }
}
```

Examples of **correct** code for this rule:

```jsx
var Hello = createReactClass({
  componentDidMount: function() {
    this.setState({
      name: this.props.name.toUpperCase();
    });
  },
  render: function() {
    return <div>Hello {this.state.name}</div>;
  }
});

class Hello extends React.Component {
  constructor(props) {
    super(props)

    this.state = {
      foo: 'bar',
    }
  }
}
```

## How to use

## Version

This rule was added in v0.2.0.

## References

---

---
url: /docs/guide/usage/linter/rules/react/no-find-dom-node.md
---

### What it does

This rule disallows the use of `findDOMNode`, which was deprecated in 2018 and removed in React 19.

### Why is this bad?

`findDOMNode` is an escape hatch used to access the underlying DOM node.
In most cases, use of this escape hatch is discouraged because it pierces the component abstraction.
It has been deprecated for years, and was
[removed from React entirely in React 19](https://react.dev/blog/2024/04/25/react-19-upgrade-guide#removed-reactdom-finddomnode).

It should not be used.

### Examples

Examples of **incorrect** code for this rule:

```jsx
class MyComponent extends Component {
  componentDidMount() {
    findDOMNode(this).scrollIntoView();
  }
  render() {
    return <div />;
  }
}
```

## How to use

## Version

This rule was added in v0.0.15.

## References

---

---
url: /docs/guide/usage/linter/rules/react/no-is-mounted.md
---

### What it does

This rule prevents using `isMounted` in class components.

### Why is this bad?

`isMounted` is an anti-pattern, and is not available
when using classes or function components.

### Examples

Examples of **incorrect** code for this rule:

```jsx
class Hello extends React.Component {
  someMethod() {
    if (!this.isMounted()) {
      return;
    }
  }
  render() {
    return <div onClick={this.someMethod.bind(this)}>Hello</div>;
  }
}
```

## How to use

## Version

This rule was added in v0.0.19.

## References

---

---
url: /docs/guide/usage/linter/rules/react/no-multi-comp.md
---

### What it does

Prevents multiple React components from being defined in the same file.

### Why is this bad?

Declaring multiple components in a single file can make it harder to navigate
and maintain the codebase. Each component should ideally be in its own file
for better organization and reusability.

### Examples

Examples of **incorrect** code for this rule:

```jsx
function Foo({ name }) {
  return <div>Hello {name}</div>;
}

function Bar({ name }) {
  return <div>Hello again {name}</div>;
}
```

Examples of **correct** code for this rule:

```jsx
function Foo({ name }) {
  return <div>Hello {name}</div>;
}
```

## Configuration

### ignoreStateless

type: `boolean`

default: `false`

When `true`, the rule will ignore stateless components and will allow you to have multiple
stateless components in the same file. Or one stateful component and one-or-more stateless
components in the same file.

Stateless basically just means function components, including those created via
`memo` and `forwardRef`.

## How to use

## Version

This rule was added in v1.43.0.

## References

---

---
url: /docs/guide/usage/linter/rules/react/no-namespace.md
---

### What it does

Enforce that namespaces are not used in React elements.

### Why is this bad?

Namespaces in React elements, such as svg:circle, are not supported by React.

### Examples

Examples of **incorrect** code for this rule:

```jsx
<ns:TestComponent />
<Ns:TestComponent />
```

Examples of **correct** code for this rule:

```jsx
<TestComponent />
<testComponent />
```

## How to use

## Version

This rule was added in v0.15.13.

## References

---

---
url: /docs/guide/usage/linter/rules/react/no-object-type-as-default-prop.md
---

### What it does

Disallows using object, array, function, class, regex, JSX, or `new`-constructed
values as default values for destructured React component props.

### Why is this bad?

Default values of destructured parameters are evaluated on every render. When the
default is an object literal, array literal, function expression, class expression,
regular expression, `new` expression, or JSX element, a new reference is created on
every render. Passing that fresh reference to child components or hook dependency
arrays defeats memoization and causes unnecessary re-renders.

Note: you do not need to enable this rule when using React Compiler, since React
Compiler memoizes default values automatically.

### Examples

Examples of **incorrect** code for this rule:

```jsx
function Foo({ items = [] }) {
  return <List items={items} />;
}

const Bar = ({ config = {} }) => <div data-config={config} />;

function Baz({ onClick = () => {} }) {
  return <button onClick={onClick} />;
}
```

Examples of **correct** code for this rule:

```jsx
const DEFAULT_ITEMS = [];
function Foo({ items = DEFAULT_ITEMS }) {
  return <List items={items} />;
}

const Bar = ({ name = "world" }) => <div>{name}</div>;

function Baz({ onClick }) {
  return <button onClick={onClick} />;
}
```

## How to use

## Version

This rule was added in v1.66.0.

## References

---

---
url: /docs/guide/usage/linter/rules/react/no-react-children.md
---

### What it does

Disallows the usage of `React.Children`, as it is considered a bad practice.

### Why is this bad?

Using `React.Children` is
[discouraged by the React documentation](https://react.dev/reference/react/Children).
It is an uncommon pattern and can lead to fragile code.

It is recommended to use alternative approaches for handling children. See the
[React documentation](https://react.dev/reference/react/Children#alternatives) for
more information.

::: tip
Don't confuse `React.Children` with using the `children` prop (lowercase `c`), which is
good and encouraged.
:::

Note that this rule is based on a combination of multiple rules from `@eslint-react/eslint-plugin`,
including [`@eslint-react/no-children-count`](https://www.eslint-react.xyz/docs/rules/no-children-count)
and [`@eslint-react/no-children-for-each`](https://www.eslint-react.xyz/docs/rules/no-children-for-each).

### Examples

Examples of **incorrect** code for this rule:

```jsx
import { Children } from "react";

Children.toArray(children);
Children.map(children, (child) => <div>{child}</div>);
Children.only(children);
Children.count(children);
Children.forEach(children, (child, index) => {});
```

```jsx
import React from "react";

function Table({ children }) {
  const mappedChildren = React.Children.map(children, (child) => <tr>{child}</tr>);

  return <table>{mappedChildren}</table>;
}
```

```jsx
import { Children } from "react";

function RowList({ children }) {
  return (
    <>
      <h1>Total rows: {Children.count(children)}</h1>
    </>
  );
}
```

Examples of **correct** code for this rule:

```jsx
function Card({ children }) {
  return <div className="card">{children}</div>;
}
```

## How to use

## Version

This rule was added in v1.53.0.

## References

---

---
url: /docs/guide/usage/linter/rules/react/no-redundant-should-component-update.md
---

### What it does

Disallow usage of `shouldComponentUpdate` when extending `React.PureComponent`.

Note that usage of `PureComponent` is
[not recommended in modern React](https://react.dev/reference/react/PureComponent).

### Why is this bad?

`React.PureComponent` automatically implements `shouldComponentUpdate` with a shallow prop and state comparison.
Defining `shouldComponentUpdate` in a class that extends `React.PureComponent` is redundant and defeats the purpose
of using `React.PureComponent`. If you need custom comparison logic, extend `React.Component` instead.

### Examples

Examples of **incorrect** code for this rule:

```jsx
class Foo extends React.PureComponent {
  shouldComponentUpdate() {
    // do check
  }

  render() {
    return <div>Radical!</div>;
  }
}

function Bar() {
  return class Baz extends React.PureComponent {
    shouldComponentUpdate() {
      // do check
    }

    render() {
      return <div>Groovy!</div>;
    }
  };
}
```

Examples of **correct** code for this rule:

```jsx
class Foo extends React.Component {
  shouldComponentUpdate() {
    // do check
  }

  render() {
    return <div>Radical!</div>;
  }
}

function Bar() {
  return class Baz extends React.Component {
    shouldComponentUpdate() {
      // do check
    }

    render() {
      return <div>Groovy!</div>;
    }
  };
}

class Qux extends React.PureComponent {
  render() {
    return <div>Tubular!</div>;
  }
}
```

## How to use

## Version

This rule was added in v1.33.0.

## References

---

---
url: /docs/guide/usage/linter/rules/react/no-render-return-value.md
---

### What it does

This rule will warn you if you try to use the `ReactDOM.render()` return value.

### Why is this bad?

Using the return value from `ReactDOM.render()` is a legacy
feature and should not be used.

Note that `ReactDOM.render`
[has been removed entirely in React 19](https://react.dev/blog/2024/04/25/react-19-upgrade-guide#removed-reactdom-render)
and so should generally not be used.

### Examples

Examples of **incorrect** code for this rule:

```jsx
var inst = ReactDOM.render(<App />, document.body);
function render() {
  return ReactDOM.render(<App />, document.body);
}
```

Examples of **correct** code for this rule:

```jsx
ReactDOM.render(<App />, document.body);
```

## How to use

## Version

This rule was added in v0.0.15.

## References

---

---
url: /docs/guide/usage/linter/rules/react/no-set-state.md
---

### What it does

Disallow the usage of `this.setState` in React components.

### Why is this bad?

When using an architecture that separates your application state from your UI components
(e.g. Flux), it may be desirable to forbid the use of local component state. This rule is
especially helpful in read-only applications (that don't use forms), since local component
state should rarely be necessary in such cases.

### Examples

Examples of **incorrect** code for this rule:

```jsx
var Hello = createReactClass({
  getInitialState: function () {
    return {
      name: this.props.name,
    };
  },
  handleClick: function () {
    this.setState({
      name: this.props.name.toUpperCase(),
    });
  },
  render: function () {
    return <div onClick={this.handleClick.bind(this)}>Hello {this.state.name}</div>;
  },
});
```

## How to use

## Version

This rule was added in v0.5.2.

## References

---

---
url: /docs/guide/usage/linter/rules/react/no-string-refs.md
---

### What it does

This rule prevents using the deprecated behavior of string literals in ref attributes.

### Why is this bad?

Using string literals in ref attributes has been deprecated since React 16.3.0.

String refs are [removed entirely in React 19](https://react.dev/blog/2024/04/25/react-19-upgrade-guide#removed-string-refs),
and so this rule can be disabled if on React 19+.

### Examples

Examples of **incorrect** code for this rule:

```jsx
var Hello = createReactClass({
  render: function () {
    return <div ref="hello">Hello, world.</div>;
  },
});

var Hello = createReactClass({
  componentDidMount: function () {
    var component = this.refs.hello;
    // ...do something with component
  },
  render: function () {
    return <div ref="hello">Hello, world.</div>;
  },
});
```

Examples of **correct** code for this rule:

```jsx
var Hello = createReactClass({
  componentDidMount: function () {
    var component = this.hello;
    // ...do something with component
  },
  render() {
    return (
      <div
        ref={(c) => {
          this.hello = c;
        }}
      >
        Hello, world.
      </div>
    );
  },
});
```

## Configuration

This rule accepts a configuration object with the following properties:

### noTemplateLiterals

type: `boolean`

default: `false`

Disallow template literals in addition to string literals.

## How to use

## Version

This rule was added in v0.0.15.

## References

---

---
url: /docs/guide/usage/linter/rules/react/no-this-in-sfc.md
---

### What it does

Prevents using `this` in stateless functional components.

### Why is this bad?

In React, stateless functional components (SFCs) receive props and context as function parameters,
not through `this`. Using `this` in an SFC typically indicates a mistake when converting from
class components or unfamiliarity with the two component styles.

### Examples

Examples of **incorrect** code for this rule:

```jsx
function Foo(props) {
  return <div>{this.props.bar}</div>;
}

function Foo(props) {
  const { bar } = this.props;
  return <div>{bar}</div>;
}

const Foo = (props) => (this.props.foo ? <span>{props.bar}</span> : null);
```

Examples of **correct** code for this rule:

```jsx
function Foo(props) {
  return <div>{props.bar}</div>;
}

function Foo({ bar }) {
  return <div>{bar}</div>;
}

class Foo extends React.Component {
  render() {
    return <div>{this.props.bar}</div>;
  }
}
```

## How to use

## Version

This rule was added in v1.37.0.

## References

---

---
url: /docs/guide/usage/linter/rules/react/no-unescaped-entities.md
---

### What it does

This rule prevents characters that you may have meant as JSX escape characters from being accidentally injected as a text node in JSX statements.

### Why is this bad?

JSX escape characters are used to inject characters into JSX statements that would otherwise be interpreted as code.

### Example

Incorrect

```jsx
<div> > </div>
```

Correct

```jsx
<div> &gt; </div>
```

```jsx
<div> {">"} </div>
```

## How to use

## Version

This rule was added in v0.0.15.

## References

---

---
url: /docs/guide/usage/linter/rules/react/no-unknown-property.md
---

### What it does

Disallow usage of unknown DOM properties.

### Why is this bad?

DOM properties should only be used if they are valid for a given HTML element.

### Examples

Examples of **incorrect** code for this rule:

```jsx
// Unknown properties
const Hello = <div class="hello">Hello World</div>;
const Alphabet = <div abc="something">Alphabet</div>;

// Invalid aria-* attribute
const IconButton = <div aria-foo="bar" />;
```

Examples of **correct** code for this rule:

```jsx
// Unknown properties
const Hello = <div className="hello">Hello World</div>;
const Alphabet = <div>Alphabet</div>;

// Invalid aria-* attribute
const IconButton = <div aria-label="bar" />;
```

## Configuration

This rule accepts a configuration object with the following properties:

### ignore

type: `string[]`

default: `[]`

List of properties to ignore.

### requireDataLowercase

type: `boolean`

default: `false`

Require `data-*` attributes to be lowercase, e.g. `data-foobar` instead of `data-fooBar`.

## How to use

## Version

This rule was added in v0.2.0.

## References

---

---
url: /docs/guide/usage/linter/rules/react/no-unsafe.md
---

### What it does

This rule identifies and restricts the use of unsafe React lifecycle methods.

### Why is this bad?

Certain lifecycle methods (`componentWillMount`, `componentWillReceiveProps`, and `componentWillUpdate`)
are considered unsafe and have been deprecated since React 16.9. They are frequently misused and cause
problems in async rendering. Using their `UNSAFE_` prefixed versions or the deprecated names themselves
should be avoided.

### Examples

Examples of **incorrect** code for this rule:

```jsx
// By default, UNSAFE_ prefixed methods are flagged
class Foo extends React.Component {
  UNSAFE_componentWillMount() {}
  UNSAFE_componentWillReceiveProps() {}
  UNSAFE_componentWillUpdate() {}
}

// With checkAliases: true, non-prefixed versions are also flagged
class Bar extends React.Component {
  componentWillMount() {}
  componentWillReceiveProps() {}
  componentWillUpdate() {}
}
```

Examples of **correct** code for this rule:

```jsx
class Foo extends React.Component {
  componentDidMount() {}
  componentDidUpdate() {}
  render() {}
}
```

## Configuration

This rule accepts a configuration object with the following properties:

### checkAliases

type: `boolean`

default: `false`

Whether to check for the non-prefixed lifecycle methods.
If `true`, this means `componentWillMount`, `componentWillReceiveProps`,
and `componentWillUpdate` will also be flagged, rather than just the
UNSAFE\_ versions. It is recommended to set this to `true` to fully
avoid unsafe lifecycle methods.

## How to use

## Version

This rule was added in v1.35.0.

## References

---

---
url: /docs/guide/usage/linter/rules/react/no-unstable-nested-components.md
---

### What it does

Disallows defining React components inside other components.

### Why is this bad?

React compares element types by reference during reconciliation. A component defined during
render gets a new identity on every render, so React remounts the entire nested subtree and
destroys its DOM nodes and state.

### Examples

Examples of **incorrect** code for this rule:

```jsx
function Component() {
  function UnstableNestedComponent() {
    return <div />;
  }

  return <UnstableNestedComponent />;
}
```

Examples of **correct** code for this rule:

```jsx
function StableComponent() {
  return <div />;
}

function Component() {
  return <StableComponent />;
}
```

## Configuration

This rule accepts a configuration object with the following properties:

### allowAsProps

type: `boolean`

default: `false`

Allow component definitions in props.

### customValidators

type: `string[]`

default: `[]`

Optional custom propTypes validators accepted for eslint-plugin-react compatibility.

### propNamePattern

type: `string`

default: `"render*"`

Glob pattern for render-prop names that may receive inline component definitions.

## How to use

## Version

This rule was added in v1.66.0.

## References

---

---
url: /docs/guide/usage/linter/rules/react/no-will-update-set-state.md
---

### What it does

Disallows using `setState` in the `componentWillUpdate` lifecycle method.

### Why is this bad?

Updating the state during the component update step can lead to indeterminate component state and is not allowed.
This can cause unexpected behavior and bugs in your React application.

### Examples

Examples of **incorrect** code for this rule:

```jsx
var Hello = createReactClass({
  componentWillUpdate: function () {
    this.setState({
      name: this.props.name.toUpperCase(),
    });
  },
  render: function () {
    return <div>Hello {this.state.name}</div>;
  },
});
```

Examples of **correct** code for this rule:

```jsx
var Hello = createReactClass({
  componentWillUpdate: function () {
    this.props.prepareHandler();
  },
  render: function () {
    return <div>Hello {this.state.name}</div>;
  },
});
```

## Configuration

This rule accepts one of the following string values:

type: `"allowed" | "disallow-in-func"`

## How to use

## Version

This rule was added in v1.37.0.

## References

---

---
url: /docs/guide/usage/linter/rules/react/only-export-components.md
---

### What it does

Ensures that modules only **export React components (and related HMR-safe items)** so
that Fast Refresh (a.k.a. hot reloading) can safely preserve component state.
Concretely, it validates the shape of your module’s exports and common entrypoints
(e.g. `createRoot(...).render(<App />)`) to match what integrations like
`react-refresh` expect.

This rule is based on the rule from `eslint-plugin-react-refresh`.

### Why is this bad?

Fast Refresh can only reliably retain state if a module exports components and
avoids patterns that confuse the refresh runtime. Problematic patterns (like
`export *`, anonymous default functions, exporting arrays of JSX, or mixing
non-component exports in unsupported ways) can cause:

* Components to remount and lose state on edit
* Missed updates (no refresh) or overly broad reloads
* Fragile HMR behavior that differs between bundlers

By enforcing predictable exports, edits stay fast and stateful during development.

### Examples

Examples of **incorrect** code for this rule:

```jsx
// 1) Mixing util exports with components in unsupported ways
export const foo = () => {}; // util, not a component
export const Bar = () => <></>; // component
```

```jsx
// 2) Anonymous default export (name is required)
export default function () {}
```

```jsx
// 3) Re-exporting everything hides what’s exported
export * from "./foo";
```

```jsx
// 4) Exporting JSX collections makes components non-discoverable
const Tab = () => null;
export const tabs = [<Tab />, <Tab />];
```

```jsx
// 5) Bootstrapping a root within the same module that defines components
const App = () => null;
createRoot(document.getElementById("root")).render(<App />);
```

Examples of **correct** code for this rule:

```jsx
// Named or default component exports are fine
export default function Foo() {
  return null;
}
```

```jsx
// Utilities may coexist if allowed by options or naming conventions
const foo = () => {};
export const Bar = () => null;
```

```jsx
// Entrypoint files may render an imported component
import { App } from "./App";
createRoot(document.getElementById("root")).render(<App />);
```

## Configuration

This rule accepts a configuration object with the following properties:

### allowConstantExport

type: `boolean`

default: `false`

Allow exporting primitive constants (string/number/boolean/template literal)
alongside component exports without triggering a violation. Recommended when your
bundler’s Fast Refresh integration supports this (enabled by the plugin’s `vite`
preset).

```jsx
// Allowed when allowConstantExport: true
export const VERSION = "3";
export const Foo = () => null;
```

### allowExportNames

type: `string[]`

default: `[]`

Treat specific named exports as HMR-safe (useful for frameworks that hot-replace
certain exports). For example, in Remix:
`{ "allowExportNames": ["meta", "links", "headers", "loader", "action"] }`

### checkJS

type: `boolean`

default: `false`

Check `.js` files that contain JSX (in addition to `.tsx`/`.jsx`). To reduce
false positives, only files that import React are checked when this is enabled.

### customHOCs

type: `string[]`

default: `[]`

If you export components wrapped in custom higher-order components, list their
identifiers here to avoid false positives.

## How to use

## Version

This rule was added in v1.23.0.

## References

---

---
url: /docs/guide/usage/linter/rules/react/prefer-es6-class.md
---

### What it does

React offers you two ways to create traditional components: using the
`create-react-class` package or the newer ES2015 class system.

Note that function components are preferred over class components in modern React,
and it is *especially* discouraged to use `createReactClass` in modern React.

### Why is this bad?

This rule enforces a consistent React class style.

### Examples

Examples of **incorrect** code for this rule by default:

```jsx
var Hello = createReactClass({
  render: function () {
    return <div>Hello {this.props.name}</div>;
  },
});
```

## Configuration

This rule accepts one of the following string values:

type: `"always" | "never"`

## How to use

## Version

This rule was added in v0.5.0.

## References

---

---
url: /docs/guide/usage/linter/rules/react/prefer-function-component.md
---

### What it does

Enforces that React components are written as function components
instead of class components.

### Why is this bad?

Function components are simpler, easier to read, and support React
hooks. Class components are a legacy pattern that is discouraged in
modern React.

This rule is based on the rule from
[eslint-plugin-react-prefer-function-component](https://www.npmjs.com/package/eslint-plugin-react-prefer-function-component).

### Examples

Examples of **incorrect** code for this rule:

```jsx
class Foo extends React.Component {
  render() {
    return <div>{this.props.foo}</div>;
  }
}

class Bar extends React.PureComponent {
  render() {
    return <div>{this.props.bar}</div>;
  }
}
```

Examples of **correct** code for this rule:

```jsx
const Foo = function (props) {
  return <div>{props.foo}</div>;
};

const Bar = ({ bar }) => <div>{bar}</div>;
```

## Configuration

This rule accepts a configuration object with the following properties:

### allowErrorBoundary

type: `boolean`

default: `true`

If `true`, error boundary classes (those implementing `componentDidCatch`
or `static getDerivedStateFromError`) are allowed as class components.

This is because these classes are not easily converted to function components,
and so they are exempted from this rule by default.

### allowJsxUtilityClass

type: `boolean`

default: `false`

If `true`, classes that contain JSX but do not extend `Component` or
`PureComponent` are allowed.

## How to use

## Version

This rule was added in v1.59.0.

## References

---

---
url: /docs/guide/usage/linter/rules/react/react-compiler.md
---

### What it does

Runs the React Compiler's analysis in lint-only mode and reports code
that violates the Rules of React — for example calling hooks
conditionally, calling setState during render, accessing refs during
render, or mutating props and state.

This rule surfaces the same diagnostics as `eslint-plugin-react-compiler`.

::: warning
This rule is experimental, and will change to fit in better with Oxlint.
:::

### Why is this bad?

Code that breaks the Rules of React can behave unpredictably at runtime
(stale UI, infinite re-render loops, lost state) and prevents React
Compiler from optimizing the component. Following these rules keeps
components correct and allows them to be automatically memoized.

### Examples

Examples of **incorrect** code for this rule:

```jsx
function Component(props) {
  if (props.cond) {
    useState(0); // hooks may not be called conditionally
  }
  return <div>{props.text}</div>;
}
```

```jsx
function Component() {
  const ref = useRef(null);
  return <div>{ref.current}</div>; // refs may not be read during render
}
```

Examples of **correct** code for this rule:

```jsx
function Component(props) {
  const [state, setState] = useState(0);
  return <button onClick={() => setState(state + 1)}>{props.text}</button>;
}
```

## Configuration

This rule accepts a configuration object with the following properties:

### reportAllBailouts

type: `boolean`

default: `false`

Also report compiler bail-outs — places where React Compiler skipped a
component or hook (for example because of unsupported syntax) without
finding a rule violation. These do not indicate incorrect code, only
code that the compiler declined to optimize.

## How to use

## Version

This rule was added in v1.70.0.

## References

---

---
url: /docs/guide/usage/linter/rules/react/react-in-jsx-scope.md
---

### What it does

Enforces that React is imported and in-scope when using JSX syntax.

Note that this rule is **not necessary** on React 17+ if you are using
the new JSX Transform, and you can disable this rule and skip importing
`React` in files with JSX syntax.

If your `tsconfig.json` has `jsx` set to `react-jsx` or `react-jsxdev`, you are using the new JSX Transform.
For JavaScript projects using Babel, you are using the new JSX Transform if your React preset configuration
(in `.babelrc` or `babel.config.js`) has `runtime: "automatic"`.

For more information, see
[the React blog post on JSX Transform](https://legacy.reactjs.org/blog/2020/09/22/introducing-the-new-jsx-transform.html#eslint).

### Why is this bad?

When using JSX, `<a />` expands to `React.createElement("a")`. Therefore
the `React` variable must be in scope.

### Examples

Examples of **incorrect** code for this rule:

```jsx
const a = <a />;
```

Examples of **correct** code for this rule:

```jsx
import React from "react";
const a = <a />;
```

## How to use

## Version

This rule was added in v0.0.20.

## References

---

---
url: /docs/guide/usage/linter/rules/react/require-render-return.md
---

### What it does

Require render methods in ES5 and ES2015 React components to return a value.

This rule is not relevant for function components, and so can potentially be
disabled for modern React codebases.

### Why is this bad?

When writing the `render` method in a component it is easy to forget to return the
JSX content. This rule will warn if the `return` statement is missing.

### Examples

Examples of **incorrect** code for this rule:

```jsx
var Hello = createReactClass({
  render() {
    <div>Hello</div>;
  },
});

class Hello extends React.Component {
  render() {
    <div>Hello</div>;
  }
}
```

Examples of **correct** code for this rule:

```jsx
var Hello = createReactClass({
  render() {
    return <div>Hello</div>;
  },
});

class Hello extends React.Component {
  render() {
    return <div>Hello</div>;
  }
}
```

## How to use

## Version

This rule was added in v0.2.0.

## References

---

---
url: /docs/guide/usage/linter/rules/react/rules-of-hooks.md
---

### What it does

Enforces the Rules of Hooks, ensuring that React Hooks are only called
in valid contexts and in the correct order.

### Why is this bad?

React Hooks must follow specific rules to ensure they work correctly:

1. Only call Hooks at the top level (never inside loops, conditions,
   or nested functions)
2. Only call Hooks from React function components or custom Hooks
3. Hooks must be called in the same order every time a component renders

Breaking these rules can lead to bugs where state gets corrupted or
component behavior becomes unpredictable.

### Examples

Examples of **incorrect** code for this rule:

```javascript
// Don't call Hooks inside loops, conditions, or nested functions
function BadComponent() {
  if (condition) {
    const [state, setState] = useState(); // ❌ Hook in condition
  }

  for (let i = 0; i < 10; i++) {
    useEffect(() => {}); // ❌ Hook in loop
  }
}

// Don't call Hooks from regular JavaScript functions
function regularFunction() {
  const [state, setState] = useState(); // ❌ Hook in regular function
}
```

Examples of **correct** code for this rule:

```javascript
// ✅ Call Hooks at the top level of a React component
function GoodComponent() {
  const [state, setState] = useState();

  useEffect(() => {
    // Effect logic here
  });

  return <div>{state}</div>;
}

// ✅ Call Hooks from custom Hooks
function useCustomHook() {
  const [state, setState] = useState();
  return state;
}
```

## How to use

## Version

This rule was added in v0.3.3.

## References

---

---
url: /docs/guide/usage/linter/rules/react/self-closing-comp.md
---

### What it does

Detects components without children which can be self-closed to avoid
unnecessary extra closing tags.

### Why is this bad?

Components without children don't need explicit closing tags. Using
self-closing syntax makes code more concise and reduces visual clutter.
It also follows common React and JSX conventions for empty elements.

A self-closing component which contains whitespace is allowed except
when it also contains a newline.

### Examples

Examples of **incorrect** code for this rule:

```jsx
const elem = <Component linter="oxlint"></Component>;
const dom_elem = <div id="oxlint"></div>;
const welem = <div id="oxlint"></div>;
```

Examples of **correct** code for this rule:

```jsx
const elem = <Component linter="oxlint" />;
const welem = <Component linter="oxlint"> </Component>;
const dom_elem = <div id="oxlint" />;
```

## Configuration

This rule accepts a configuration object with the following properties:

### component

type: `boolean`

default: `true`

Whether to enforce self-closing for custom components.

### html

type: `boolean`

default: `true`

Whether to enforce self-closing for native HTML elements.

## How to use

## Version

This rule was added in v0.9.3.

## References

---

---
url: /docs/guide/usage/linter/rules/react/state-in-constructor.md
---

### What it does

Enforces the state initialization style to be either in a
constructor or with a class property.

This rule is not relevant for function components, and so can potentially be
disabled for modern React codebases.

### Why is this bad?

Inconsistent state initialization styles can make the codebase harder to maintain and understand.
This rule enforces a consistent pattern across React class components.

### Examples

Examples of **incorrect** code for this rule by default, with `"always"` mode:

```jsx
class Foo extends React.Component {
  state = { bar: 0 };
  render() {
    return <div>Foo</div>;
  }
}
```

Examples of **correct** code for this rule by default, with `"always"` mode:

```jsx
class Foo extends React.Component {
  constructor(props) {
    super(props);
    this.state = { bar: 0 };
  }
  render() {
    return <div>Foo</div>;
  }
}
```

#### `"never"` mode

Will enforce the state initialization style to be with a class property.

Examples of **incorrect** code for this rule with `"never"` mode:

```jsx
class Foo extends React.Component {
  constructor(props) {
    super(props);
    this.state = { bar: 0 };
  }
  render() {
    return <div>Foo</div>;
  }
}
```

Examples of **correct** code for this rule with `"never"` mode:

```jsx
class Foo extends React.Component {
  state = { bar: 0 };
  render() {
    return <div>Foo</div>;
  }
}
```

## Configuration

This rule accepts one of the following string values:

type: `"always" | "never"`

## How to use

## Version

This rule was added in v1.26.0.

## References

---

---
url: /docs/guide/usage/linter/rules/react/style-prop-object.md
---

### What it does

Require that the value of the prop `style` be an object or a variable that is an object.

### Why is this bad?

The `style` prop expects an object mapping from style properties to values when using JSX.

### Examples

Examples of **incorrect** code for this rule:

```jsx
<div style="color: 'red'" />
<div style={true} />
<Hello style={true} />
const styles = true;
<div style={styles} />

React.createElement("div", { style: "color: 'red'" });
React.createElement("div", { style: true });
React.createElement("Hello", { style: true });
const styles = true;
React.createElement("div", { style: styles });
```

Examples of **correct** code for this rule:

```jsx
<div style={{ color: "red" }} />
<Hello style={{ color: "red" }} />
const styles = { color: "red" };
<div style={styles} />

React.createElement("div", { style: { color: 'red' }});
React.createElement("Hello", { style: { color: 'red' }});
const styles = { height: '100px' };
React.createElement("div", { style: styles });
```

## Configuration

This rule accepts a configuration object with the following properties:

### allow

type: `string[]`

default: `[]`

List of component names on which to allow `style` prop values of any type.

## How to use

## Version

This rule was added in v0.11.0.

## References

---

---
url: /docs/guide/usage/linter/rules/react/void-dom-elements-no-children.md
---

### What it does

Disallow void DOM elements (e.g. `<img />`, `<br />`) from receiving children.

### Why is this bad?

There are some HTML elements that are only self-closing (e.g. img, br, hr). These are collectively known as void DOM elements.
This rule checks that children are not passed to void DOM elements.

### Examples

Examples of **incorrect** code for this rule:

```jsx
<br>Children</br>
<br children='Children' />
<br dangerouslySetInnerHTML={{ __html: 'HTML' }} />
React.createElement('br', undefined, 'Children')
React.createElement('br', { children: 'Children' })
React.createElement('br', { dangerouslySetInnerHTML: { __html: 'HTML' } })
```

Examples of **correct** code for this rule:

```jsx
<div>Children</div>
<div children='Children' />
<div dangerouslySetInnerHTML={{ __html: 'HTML' }} />
React.createElement('div', undefined, 'Children')
React.createElement('div', { children: 'Children' })
React.createElement('div', { dangerouslySetInnerHTML: { __html: 'HTML' } })
```

## How to use

## Version

This rule was added in v0.2.11.

## References

---

---
url: /docs/learn/references.md
---

# References and Learning Resources

## Performance Programming

* [The Rust Performance Book](https://nnethercote.github.io/perf-book/introduction.html)
* [MIT Open Course Ware - Performance Engineering Of Software Systems](https://ocw.mit.edu/courses/6-172-performance-engineering-of-software-systems-fall-2018/video_galleries/lecture-videos)
* [Andrew Kelley - Practical DOD](https://vimeo.com/649009599)
* [Mike Acton - Data-Oriented Design and C++](https://youtu.be/rX0ItVEVjHc)

## JavaScript Parsers

* Rust: [swc](https://swc.rs), [biome](https://biomejs.dev), [jsparagus](https://github.com/mozilla-spidermonkey/jsparagus), [ratel](https://github.com/ratel-rust/ratel-core), [boa](https://github.com/boa-dev/boa),
* JavaScript: [acorn](https://github.com/acornjs/acorn), [babel](https://babeljs.io)
* Go: [esbuild](https://esbuild.github.io)
* C++: [quick-lint-js](https://github.com/quick-lint/quick-lint-js)
* ASTs: [estree](https://github.com/estree/estree), [swc\_ecma\_ast](https://github.com/swc-project/swc/tree/main/crates/swc_ecma_ast/src), [babel ast](https://github.com/babel/babel/blob/main/packages/babel-types/src/ast-types/generated/index.ts), [jsparagus](https://gist.github.com/Boshen/0b481a058cd715576aaf1624d2c6d469)

### Learn

* [Blazingly fast parsing, part 1: optimizing the scanner](https://v8.dev/blog/scanner)
* [Blazingly fast parsing, part 2: lazy parsing](https://v8.dev/blog/preparser)
* [Understanding ECMAScript](https://v8.dev/blog/tags/understanding-ecmascript)
* [Simple but Powerful Pratt Parsing](https://matklad.github.io/2020/04/13/simple-but-powerful-pratt-parsing.html)
* [JS syntactic quirks](https://github.com/mozilla-spidermonkey/jsparagus/blob/master/js-quirks.md)
* [Crafting Interpreters](https://craftinginterpreters.com)

### Specifications

* [ECMAScript Spec](https://tc39.es/ecma262/)
* [TypeScript 1.8 Spec](https://github.com/Boshen/TypeScript-Language-Specification/blob/main/TypeScript%20Language%20Specification.pdf)
* [JSX Spec](https://facebook.github.io/jsx/)

### Media

---

---
url: /docs/contribute/resolver.md
---

# Resolver

The Oxc resolver is a high-performance Node.js module resolution implementation that's compatible with webpack's enhanced-resolve. It's maintained in [its own GitHub repository](https://github.com/oxc-project/oxc_resolver).

## Architecture

The resolver is designed as a direct port of [enhanced-resolve](https://github.com/webpack/enhanced-resolve) with significant performance improvements:

* **28x faster** than enhanced-resolve
* **Zero-copy string operations** where possible
* **Optimized path traversal** algorithms
* **Efficient caching** strategies

---

---
url: /docs/guide/usage/resolver.md
---

# Resolver

A high-performance module resolver that primarily supports the Node.js resolution algorithm and is configurable.

## Features

* All configurations are aligned with [webpack/enhanced-resolve][url-enhanced-resolve].
* 28x faster than [webpack/enhanced-resolve][url-enhanced-resolve] ([benchmark](https://github.com/oxc-project/bench-resolver)).
* See [README](https://github.com/oxc-project/oxc-resolver)

## Installation

### Node.js

* Use the node binding [oxc-resolver][url-oxc-resolver-npm].
* Try on [stackblitz](https://stackblitz.com/fork/github/oxc-project/website/tree/main/stackblitz-templates/oxc-resolver).

### Rust

See [https://crates.io/crates/oxc\_resolver][url-oxc-resolver-crate] and its documentation [https://docs.rs/oxc\_resolver][url-oxc-resolver-docs].

[url-oxc-resolver-crate]: https://crates.io/crates/oxc_resolver

[url-oxc-resolver-docs]: https://docs.rs/oxc_resolver

[url-oxc-resolver-npm]: https://npmx.dev/package/oxc-resolver

[url-enhanced-resolve]: https://github.com/webpack/enhanced-resolve

---

---
url: /docs/guide/usage/linter/rules.md
---

# Rules

The progress of all rule implementations is tracked [here](https://github.com/oxc-project/oxc/issues/481).

* Total number of rules: {{ rulesCount }}
* Rules turned on by default: {{ defaultCount }}
* Rules with fixes available: {{ fixableCount }}

::: details Rule categories

Categories group rules by intent and can be enabled together in configuration. See [Enable groups of rules with categories](/docs/guide/usage/linter/config.html#enable-groups-of-rules-with-categories) for details.

:::

::: details Legend for 'Fixable?' column

* 🛠️: an auto-fix is available for this rule
* 💡: a suggestion is available for this rule
* ⚠️🛠️: a dangerous auto-fix is available for this rule
* ⚠️💡: a dangerous suggestion is available for this rule
* 🚧: an auto-fix or suggestion is possible, but currently not implemented

:::

***

---

---
url: /docs/contribute/security.md
---

# Security Policy

The following security policies are applied to all projects within the [oxc-project](https://github.com/oxc-project) organization.

Please inform [@boshen](https://github.com/Boshen) if you notice any oversights.

https://www.npmjs.com/~boshen and https://crates.io/users/Boshen are the only accounts with publish access to our packages and crates.

## github.com

* Required two-factor authentication for everyone in the organization
  * Only secure two-factor methods are allowed
* Enabled GitHub Security Scanning, including secret scanning
* GitHub Actions: Required all actions to be pinned to a full-length commit SHA
* Enabled release immutability — assets and tags cannot be modified once a release is published
* Required signed commits: https://docs.github.com/en/authentication/managing-commit-signature-verification/signing-commits
  * Not enforced in repository settings; otherwise external contributors would not be able to contribute
* Long-lived tokens are not stored for publishing — see trusted publishing for [npmjs.com](http://npmjs.com) and [crates.io](http://crates.io) below
* Enabled Renovate Bot for security updates
* Using https://docs.zizmor.sh to lint GitHub Actions for common security issues

## npmjs.com

* Enforced 2FA for login
* Published with `npm publish --provenance`: https://docs.npmjs.com/generating-provenance-statements
* Published with trusted publishing: https://docs.npmjs.com/trusted-publishers
* Installed Socket Security
* Enabled Renovate Bot's `"minimumReleaseAge": "3 days"` to avoid updating packages released within the past 3 days
* Uses pnpm: https://pnpm.io/supply-chain-security
  * No automatic `postinstall` scripts

## crates.io

* Published with trusted publishing: https://crates.io/docs/trusted-publishing
* Using `cargo deny` to check dependencies against the Rust advisory database (https://rustsec.org).

---

---
url: /docs/learn/parser_in_rust/semantic_analysis.md
---

# Semantic Analysis

Semantic analysis is the process of checking whether our source code is correct or not.
We need to check against all the "Early Error" rules in the ECMAScript specification.

## Context

For grammar contexts such as `[Yield]` or `[Await]`, an error need to be raised when the grammar forbids them, for example:

```
BindingIdentifier[Yield, Await] :
  Identifier
  yield
  await

13.1.1 Static Semantics: Early Errors

BindingIdentifier[Yield, Await] : yield
* It is a Syntax Error if this production has a [Yield] parameter.

* BindingIdentifier[Yield, Await] : await
It is a Syntax Error if this production has an [Await] parameter.
```

need to raise an error for

```javascript
async function* foo() {
  var yield, await;
}
```

because `AsyncGeneratorDeclaration` has `[+Yield]` and `[+Await]` for `AsyncGeneratorBody`:

```
AsyncGeneratorBody :
  FunctionBody[+Yield, +Await]
```

An example in Biome checking for the `yield` keyword:

```rust
// https://github.com/rome/tools/blob/5a059c0413baf1d54436ac0c149a829f0dfd1f4d/crates/rome_js_parser/src/syntax/expr.rs#L1368-L1377

pub(super) fn parse_identifier(p: &mut Parser, kind: JsSyntaxKind) -> ParsedSyntax {
    if !is_at_identifier(p) {
        return Absent;
    }

    let error = match p.cur() {
        T![yield] if p.state.in_generator() => Some(
            p.err_builder("Illegal use of `yield` as an identifier in generator function")
                .primary(p.cur_range(), ""),
        ),
```

## Scope

For declaration errors:

```
14.2.1 Static Semantics: Early Errors

Block : { StatementList }
* It is a Syntax Error if the LexicallyDeclaredNames of StatementList contains any duplicate entries.
* It is a Syntax Error if any element of the LexicallyDeclaredNames of StatementList also occurs in the VarDeclaredNames of StatementList.
```

We need to add a scope tree. A scope tree has all the `var`s and `let`s declared inside it.
It is also a parent pointing tree where we want to navigate up the tree and search for binding identifiers in parent scopes.
The data structure we can use is a [`indextree`](https://docs.rs/indextree/latest/indextree/).

```rust
use indextree::{Arena, Node, NodeId};
use bitflags::bitflags;

pub type Scopes = Arena<Scope>;
pub type ScopeId = NodeId;

bitflags! {
    #[derive(Default)]
    pub struct ScopeFlags: u8 {
        const TOP = 1 << 0;
        const FUNCTION = 1 << 1;
        const ARROW = 1 << 2;
        const CLASS_STATIC_BLOCK = 1 << 4;
        const VAR = Self::TOP.bits | Self::FUNCTION.bits | Self::CLASS_STATIC_BLOCK.bits;
    }
}

#[derive(Debug, Clone)]
pub struct Scope {
    /// [Strict Mode Code](https://tc39.es/ecma262/#sec-strict-mode-code)
    /// [Use Strict Directive Prologue](https://tc39.es/ecma262/#sec-directive-prologues-and-the-use-strict-directive)
    pub strict_mode: bool,

    pub flags: ScopeFlags,

    /// [Lexically Declared Names](https://tc39.es/ecma262/#sec-static-semantics-lexicallydeclarednames)
    pub lexical: IndexMap<Atom, SymbolId, FxBuildHasher>,

    /// [Var Declared Names](https://tc39.es/ecma262/#sec-static-semantics-vardeclarednames)
    pub var: IndexMap<Atom, SymbolId, FxBuildHasher>,

    /// Function Declarations
    pub function: IndexMap<Atom, SymbolId, FxBuildHasher>,
}
```

The scope tree can either be built inside the parser for performance reasons, or built-in a separate AST pass.

Generally, a `ScopeBuilder` is needed:

```rust
pub struct ScopeBuilder {
    scopes: Scopes,
    root_scope_id: ScopeId,
    current_scope_id: ScopeId,
}

impl ScopeBuilder {
    pub fn current_scope(&self) -> &Scope {
        self.scopes[self.current_scope_id].get()
    }

    pub fn enter_scope(&mut self, flags: ScopeFlags) {
        // Inherit strict mode for functions
        // https://tc39.es/ecma262/#sec-strict-mode-code
        let mut strict_mode = self.scopes[self.root_scope_id].get().strict_mode;
        let parent_scope = self.current_scope();
        if !strict_mode
            && parent_scope.flags.intersects(ScopeFlags::FUNCTION)
            && parent_scope.strict_mode
        {
            strict_mode = true;
        }

        let scope = Scope::new(flags, strict_mode);
        let new_scope_id = self.scopes.new_node(scope);
        self.current_scope_id.append(new_scope_id, &mut self.scopes);
        self.current_scope_id = new_scope_id;
    }

    pub fn leave_scope(&mut self) {
      self.current_scope_id = self.scopes[self.current_scope_id].parent().unwrap();
    }
}
```

We then call `enter_scope` and `leave_scope` accordingly inside the parse functions, for example in acorn:

```javascript reference
https://github.com/acornjs/acorn/blob/11735729c4ebe590e406f952059813f250a4cbd1/acorn/src/statement.js#L425-L437
```

:::info
One of the downsides of this approach is that for arrow functions,
we may need to create a temporary scope and then drop it afterwards if it is not an arrow function but a sequence expression.
This is detailed in [cover grammar](/docs/learn/ecmascript/grammar#cover-grammar).
:::

### The Visitor Pattern

If we decide to build the scope tree in another pass for simplicity,
then every node in the AST need to be visited in depth-first preorder and build the scope tree.

We can use the [Visitor Pattern](https://rust-unofficial.github.io/patterns/patterns/behavioural/visitor.html)
to separate out the traversal process from the operations performed on each object.

Upon visit, we can call `enter_scope` and `leave_scope` accordingly to build the scope tree.

---

---
url: /docs/guide/usage/formatter/ci.md
description: Run Oxfmt in CI or as a git hook.
---

# Setup CI and other integrations

You can - and should - set up your CI pipeline to run Oxfmt and fail the build on formatting differences.

This page also covers other integrations you may want to include, like git pre-commit hooks.

## CI

### GitHub Actions

First, add a `fmt:check` script to your `package.json` if you don't have one already:

```json [package.json]
{
  "scripts": {
    "fmt:check": "oxfmt --check"
  }
}
```

And then add a job to your GitHub Actions workflow:

```yaml [.github/workflows/ci.yml]
name: CI

on:
  pull_request:
  push:
    branches: [main]

permissions: {}

jobs:
  format:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7

      - uses: pnpm/action-setup@v4

      - uses: actions/setup-node@v6
        with:
          node-version: lts/*
          cache: pnpm

      # Or yarn, npm, etc.
      - run: pnpm install --frozen-lockfile
      - run: pnpm run fmt:check
```

#### Autofix formatting issues

If you find that you often forget to run Oxfmt before opening PRs, and don't or can't use pre-commit hooks, you can add an autofix step to your CI workflow using [autofix.ci](https://autofix.ci).

See <https://autofix.ci/setup> for more details, you will need to install the relevant GitHub App as well.

Below is an example GitHub Actions workflow you can use:

```yaml [.github/workflows/autofix.yml]
name: autofix.ci # needs to use this name

on:
  pull_request:
  push:
    branches: ["main"]

permissions:
  contents: read

jobs:
  autofix:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7

      - uses: pnpm/action-setup@v4

      - uses: actions/setup-node@v6
        with:
          node-version: lts/*
          cache: pnpm

      # Or yarn, npm, etc.
      - run: pnpm install --frozen-lockfile

      # Run oxfmt to write changes, autofix.ci will commit them if there are any differences.
      # Be sure to add a `fmt` script to your `package.json` if you haven't already.
      - run: pnpm run fmt

      # NOTE: It is strongly recommended to use the latest SHA hash for this action instead of the version number. (See https://autofix.ci/setup for more details.)
      - uses: autofix-ci/action@1.3.2
```

### GitLab CI

If you use GitLab CI, you can set up Oxfmt to enforce code formatting as part of your CI pipeline.

First, add a `fmt:check` script to your `package.json` if you don't have one already:

```json [package.json]
{
  "scripts": {
    "fmt:check": "oxfmt --check"
  }
}
```

And then add a job to your `.gitlab-ci.yml`, to check that all code is formatted correctly:

```yml [.gitlab-ci.yml]
oxfmt:
  image: node:lts
  stage: test
  before_script:
    # Or pnpm, yarn, etc.
    - npm install
  script:
    - npm run fmt:check
```

You may also want to add caching for your package manager to speed up installs.

## Pre-commit hook

To auto-format staged files, use `oxfmt --no-error-on-unmatched-pattern`. This formats all supported files and avoids errors when no files match (e.g., only Ruby files are staged).

Use `--check` to verify formatting without writing files.

For [lint-staged](https://npmx.dev/package/lint-staged), add to `package.json`:

```json [package.json]
{
  "lint-staged": {
    "*": "oxfmt --no-error-on-unmatched-pattern"
  }
}
```

To automatically install the git hook when installing dependencies, considering also using [husky](https://typicode.github.io/husky/get-started.html).

---

---
url: /docs/guide/usage/linter/ci.md
description: Run Oxlint in CI or as a git hook.
---

# Setup CI and other integrations

You can - and should - setup your CI pipeline to run Oxlint and fail the build on lint errors.

This page also covers other integrations you may want to include, like git pre-commit hooks.

## CI

These instructions assume you have already set up Oxlint in your project by adding `oxlint` to your devDependencies in your `package.json`, and already have an oxlint configuration file in the repo.

### GitHub Actions

First, add a `lint` script to your `package.json` if you don't have one already:

```json [package.json]
{
  "scripts": {
    "lint": "oxlint"
  }
}
```

Then create `.github/workflows/oxlint.yml`:

```yaml [.github/workflows/oxlint.yml]
name: Lint

on:
  pull_request:
  push:
    branches: [main]

permissions: {}

jobs:
  oxlint:
    runs-on: ubuntu-latest
    steps:
      # NOTE: For security, it is strongly recommended to pin all
      # actions to a specific SHA hash instead of using a version
      # tag like this.
      - uses: actions/checkout@v7
        with:
          persist-credentials: false
      - uses: pnpm/action-setup@v4
      - uses: actions/setup-node@v6
        with:
          node-version: lts/*
          cache: pnpm

      # alternatively use npm install / yarn install here
      - run: pnpm install --frozen-lockfile
      - run: pnpm run lint
```

By default, Oxlint will enable [better warning/error annotations](https://docs.github.com/en/actions/reference/workflows-and-actions/workflow-commands#setting-an-error-message) when it detects that it is running in a GitHub Actions environment. You can override this behavior by providing the `--format` flag with a different formatter option.

### GitLab CI

If you use GitLab CI, you can set up Oxlint with `--format=gitlab` and [GitLab's Code Quality feature](https://docs.gitlab.com/ci/testing/code_quality/#code-quality-report-format) to get inline annotations for lint violations in merge requests.

To set this up, you can add a script to your `package.json` to output the gitlab format and save it to a file, like so:

```json [package.json]
{
  "scripts": {
    "lint:gitlab": "oxlint --format=gitlab > gitlab-oxlint-report.json"
  }
}
```

And then add a job to your `.gitlab-ci.yml`, to run the script and upload the report as a Code Quality artifact:

```yml [.gitlab-ci.yml]
oxlint:
  image: node:lts
  stage: test
  before_script:
    # alternatively use pnpm install / yarn install here
    - npm install
  script:
    - npm run lint:gitlab
  artifacts:
    reports:
      codequality:
        # This is relative to your repository root, so adjust if your repo has a different structure or you put the report in a different location
        - gitlab-oxlint-report.json
```

If you do not want to use the Code Quality feature, you can simply run oxlint without `--format=gitlab` in the CI job instead.

You should ensure type-aware rules are enabled if you want to use them, and consider caching `node_modules` to speed up the installation of dependencies.

## Git hooks

### lint-staged

For JS/TS projects using [lint-staged](https://npmx.dev/package/lint-staged), you can set up oxlint to run as a pre-commit hook as follows:

```json [package.json]
{
  "lint-staged": {
    "*.{js,jsx,ts,tsx,mjs,cjs}": "pnpm run lint"
  }
}
```

To automatically install the git hook when installing dependencies, considering also using [husky](https://typicode.github.io/husky/get-started.html).

### pre-commit

If you use [pre-commit](https://pre-commit.com/) to manage git hooks, you can set up Oxlint as follows:

```yaml [.pre-commit-config.yaml]
repos:
  - repo: https://github.com/oxc-project/mirrors-oxlint
    rev: v0.0.0
    hooks:
      - id: oxlint
        verbose: true
```

Replace `v0.0.0` with the latest version.

## Other integrations

### Unplugin

Unplugin is supported via a [third-party package](https://npmx.dev/package/unplugin-oxlint)

### Vite plugin

A Vite plugin is supported via a [third-party package](https://npmx.dev/package/vite-plugin-oxlint)

---

---
url: /docs/guide/usage/formatter/editors.md
description: Configure Oxfmt in VS Code, Zed, JetBrains, and other editors.
---

# Setup editors

Editor extensions use `oxfmt --lsp` from your project, so `oxfmt` must be installed locally.

See [Quickstart](./quickstart) to install Oxfmt.

## Supported editors

* [VS Code](#vs-code) (and Cursor, etc.)
* [Zed](#zed)
* [JetBrains](#jetbrains)
* [Neovim](#neovim)
* [Other editors](#other-editors)

## VS Code

### Install

Download the official Oxc VS Code extension from:

* [Visual Studio Marketplace](https://marketplace.visualstudio.com/items?itemName=oxc.oxc-vscode)
* [Open VSX Registry](https://open-vsx.org/extension/oxc/oxc-vscode)

**The extension is compatible with other VS Code-based editors**, including Cursor.

### Team setup

1. Recommend the extension for contributors:

`.vscode/extensions.json`:

```json [.vscode/extensions.json]
{
  "recommendations": ["oxc.oxc-vscode"]
}
```

2. Enable format on save in `.vscode/settings.json`:

```json [.vscode/settings.json]
{
  "editor.defaultFormatter": "oxc.oxc-vscode",
  "editor.formatOnSave": true
}
```

To set per language:

```json [.vscode/settings.json]
{
  "[javascript]": {
    "editor.defaultFormatter": "oxc.oxc-vscode",
    "editor.formatOnSave": true
  },
  "[typescript]": {
    "editor.defaultFormatter": "oxc.oxc-vscode",
    "editor.formatOnSave": true
  }
}
```

### Reference

* [oxc-project/oxc-vscode](https://github.com/oxc-project/oxc-vscode)

## Zed

### Install

* [Oxc Zed Extension](https://zed.dev/extensions/oxc)

### Reference

* [oxc-project/oxc-zed](https://github.com/oxc-project/oxc-zed)

## JetBrains

IntelliJ IDEA and WebStorm.

### Install

* [Oxc in JetBrains Marketplace](https://plugins.jetbrains.com/plugin/27061-oxc)

### Reference

* [oxc-project/oxc-intellij-plugin](https://github.com/oxc-project/oxc-intellij-plugin)

## Neovim

### nvim-lspconfig

```sh
npm i -g oxfmt
```

```lua
vim.lsp.enable('oxfmt')
```

* [nvim-lspconfig: oxfmt](https://github.com/neovim/nvim-lspconfig/blob/master/doc/configs.md#oxfmt)

### conform.nvim

```lua
require("conform").setup({
  formatters_by_ft = {
    javascript = { "oxfmt" },
    javascriptreact = { "oxfmt" },
    typescript = { "oxfmt" },
    typescriptreact = { "oxfmt" },
    json = { "oxfmt" },
    vue = { "oxfmt" },
  },
})
```

* [conform.nvim](https://github.com/stevearc/conform.nvim)

### coc.nvim

```vim
:CocInstall coc-oxc
```

* [oxc-project/coc-oxc](https://github.com/oxc-project/coc-oxc)

## Other editors

For editors with LSP support (Emacs, Helix, Sublime), configure:

```sh
oxfmt --lsp
```

Or, for editors without LSP support:

```sh
cat foo/bar.js | oxfmt --stdin-filepath dummy.js --config ./path/to/config.json
```

## Reference

* [oxc\_language\_server](https://github.com/oxc-project/oxc/tree/main/crates/oxc_language_server)

---

---
url: /docs/guide/usage/linter/editors.md
description: Configure Oxlint in VS Code, Zed, JetBrains, and other editors.
---

# Setup editors

Editor extensions use `oxlint --lsp` from your project, so `oxlint` must be installed locally.

See [Quickstart](./quickstart) to install Oxlint.

## Supported editors

* [VS Code](#vs-code) (and Cursor, etc.)
* [Zed](#zed)
* [JetBrains](#jetbrains)
* [Neovim](#neovim)
* [Other editors](#other-editors)

## VS Code

### Install

Download the official Oxc VS Code extension from:

* [Visual Studio Marketplace](https://marketplace.visualstudio.com/items?itemName=oxc.oxc-vscode)
* [Open VSX Registry](https://open-vsx.org/extension/oxc/oxc-vscode)

**The extension is compatible with other VS Code-based editors**, including Cursor.

### Team setup

1. Recommend the extension for contributors:

`.vscode/extensions.json`:

```json [.vscode/extensions.json]
{
  "recommendations": ["oxc.oxc-vscode"]
}
```

2. Enable fix-on-save in `.vscode/settings.json`:

```json [.vscode/settings.json]
{
  "editor.codeActionsOnSave": {
    "source.fixAll.oxc": "always"
  }
}
```

3. Enable type-aware linting (optional):

To enable it for the whole project, set it in the root Oxlint config:

::: code-group

```json [.oxlintrc.json]
{
  "options": {
    "typeAware": true
  }
}
```

```ts [oxlint.config.ts]
import { defineConfig } from "oxlint";

export default defineConfig({
  options: {
    typeAware: true,
  },
});
```

:::

Or set it in `.vscode/settings.json`:

```json [.vscode/settings.json]
{
  "oxc.typeAware": true
}
```

When `oxc.typeAware` is unset, the editor uses the root config's `options.typeAware` value. When set explicitly, it overrides the config value.

You also need to ensure `oxlint-tsgolint` is installed in your project. See [the type-aware linting docs](/docs/guide/usage/linter/type-aware) for more details.

### Reference

* [oxc-project/oxc-vscode](https://github.com/oxc-project/oxc-vscode)

## Zed

### Install

* [Oxc Zed Extension](https://zed.dev/extensions/oxc)

### Reference

* [oxc-project/oxc-zed](https://github.com/oxc-project/oxc-zed)

## JetBrains

IntelliJ IDEA and WebStorm.

### Install

* [Oxc in JetBrains Marketplace](https://plugins.jetbrains.com/plugin/27061-oxc)

### Reference

* [oxc-project/oxc-intellij-plugin](https://github.com/oxc-project/oxc-intellij-plugin)

## Neovim

### nvim-lspconfig

```sh
npm i -g oxlint
```

```lua
vim.lsp.enable('oxlint')
```

* [nvim-lspconfig: oxlint](https://github.com/neovim/nvim-lspconfig/blob/master/doc/configs.md#oxlint)

### coc.nvim

```vim
:CocInstall coc-oxc
```

* [oxc-project/coc-oxc](https://github.com/oxc-project/coc-oxc)

## Other editors

For editors with LSP support (Emacs, Helix, Sublime), you can use `oxlint --lsp` as your language server.
To configure it, refer to the [LSP configuration reference](./lsp-config-reference.md) for the supported options.

## Reference

* [oxc\_language\_server](https://github.com/oxc-project/oxc/tree/main/crates/oxc_language_server)
* [LSP configuration reference](/docs/guide/usage/linter/lsp-config-reference.md)

---

---
url: /docs/guide/usage/formatter/sorting.md
---

# Sorting

Oxfmt includes sorting features for imports, Tailwind classes, and package.json.

* [Sort imports](#sort-imports)
* [Sort Tailwind CSS classes](#sort-tailwind-css-classes)
* [Sort package.json fields](#sort-package-json-fields)

See [Configuration file reference](./config-file-reference) for full details.

## Sort imports

Based on [eslint-plugin-perfectionist/sort-imports](https://perfectionist.dev/rules/sort-imports).

Disabled by default.

### Example configuration

The same order as `eslint-plugin-perfectionist/sort-imports` default.

::: code-group

```json [.oxfmtrc.json]
{
  "sortImports": {
    "groups": [
      "type-import",
      ["value-builtin", "value-external"],
      "type-internal",
      "value-internal",
      ["type-parent", "type-sibling", "type-index"],
      ["value-parent", "value-sibling", "value-index"],
      "unknown"
    ]
  }
}
```

```ts [oxfmt.config.ts]
import { defineConfig } from "oxfmt";

export default defineConfig({
  sortImports: {
    groups: [
      "type-import",
      ["value-builtin", "value-external"],
      "type-internal",
      "value-internal",
      ["type-parent", "type-sibling", "type-index"],
      ["value-parent", "value-sibling", "value-index"],
      "unknown",
    ],
  },
});
```

:::

Use `"newlinesBetween": false` at the top level to disable newlines between groups, then use `{ "newlinesBetween": true }` within `groups` to insert a newline at a specific point.

::: code-group

```json [.oxfmtrc.json]
{
  "sortImports": {
    "newlinesBetween": false,
    "groups": [
      ["value-builtin", "value-external"],
      ["value-internal", "value-parent", "value-sibling", "value-index"],
      { "newlinesBetween": true },
      "type-import",
      "unknown"
    ]
  }
}
```

```ts [oxfmt.config.ts]
import { defineConfig } from "oxfmt";

export default defineConfig({
  sortImports: {
    newlinesBetween: false,
    groups: [
      ["value-builtin", "value-external"],
      ["value-internal", "value-parent", "value-sibling", "value-index"],
      { newlinesBetween: true },
      "type-import",
      "unknown",
    ],
  },
});
```

:::

Use `customGroups` to define your own groups for matching specific imports. Each custom group has a `groupName` that can be referenced in `groups`. The `elementNamePattern` accepts glob patterns to match import sources.

::: code-group

```json [.oxfmtrc.json]
{
  "sortImports": {
    "customGroups": [
      {
        "groupName": "react-libs",
        "elementNamePattern": ["react", "react-**"]
      }
    ],
    "groups": [
      "react-libs",
      ["value-builtin", "value-external"],
      "value-internal",
      ["value-parent", "value-sibling", "value-index"],
      "unknown"
    ]
  }
}
```

```ts [oxfmt.config.ts]
import { defineConfig } from "oxfmt";

export default defineConfig({
  sortImports: {
    customGroups: [
      {
        groupName: "react-libs",
        elementNamePattern: ["react", "react-**"],
      },
    ],
    groups: [
      "react-libs",
      ["value-builtin", "value-external"],
      "value-internal",
      ["value-parent", "value-sibling", "value-index"],
      "unknown",
    ],
  },
});
```

:::

## Sort Tailwind CSS classes

Sorts Tailwind utility classes.

Based on [prettier-plugin-tailwindcss](https://github.com/tailwindlabs/prettier-plugin-tailwindcss).

Disabled by default.

### Example configuration

::: code-group

```json [.oxfmtrc.json]
{
  "sortTailwindcss": {
    "stylesheet": "./path/to/stylesheet.css",
    "functions": ["clsx", "cn"],
    "preserveWhitespace": true
  }
}
```

```ts [oxfmt.config.ts]
import { defineConfig } from "oxfmt";

export default defineConfig({
  sortTailwindcss: {
    stylesheet: "./path/to/stylesheet.css",
    functions: ["clsx", "cn"],
    preserveWhitespace: true,
  },
});
```

:::

Regex patterns for `attributes` and `functions` are not supported.

## Sort package.json fields

Sorts keys in `package.json` using an opinionated order.

See [field ordering](https://github.com/oxc-project/sort-package-json?tab=readme-ov-file#field-ordering) for details.

Enabled by default.

### Example configuration

To disable:

::: code-group

```json [.oxfmtrc.json]
{
  "sortPackageJson": false
}
```

```ts [oxfmt.config.ts]
import { defineConfig } from "oxfmt";

export default defineConfig({
  sortPackageJson: false,
});
```

:::

To sort `scripts` alphabetically:

::: code-group

```json [.oxfmtrc.json]
{
  "sortPackageJson": {
    "sortScripts": true
  }
}
```

```ts [oxfmt.config.ts]
import { defineConfig } from "oxfmt";

export default defineConfig({
  sortPackageJson: {
    sortScripts: true,
  },
});
```

:::

---

---
url: /docs/learn/ecmascript/spec.md
---

# Specification

[The ECMAScript® Language Specification](https://tc39.es/ecma262/) (a living standard) details everything about the JavaScript language, so anyone can implement their own JavaScript engine.

The following chapters need to be studied for our parser:

* Chapter 5: Notational Conventions
* Chapter 11: ECMAScript Language: Source Text
* Chapter 12: ECMAScript Language: Lexical Grammar
* Chapter 13 - 16: Expressions, Statements, Functions, Classes, Scripts and Modules
* Annex B: Additional ECMAScript Features for Web Browsers
* Annex C: The Strict Mode of ECMAScript

For navigation inside the specification:

* Anything clickable has a permanent link, they are shown on the URL as anchors, for example `#sec-identifiers`
* Hovering over things may show a tooltip, clicking on `References` shows all its references

## Notational Conventions

[Chapter 5.1.5 Grammar Notation](https://tc39.es/ecma262/#sec-grammar-notation) is the section we need to read.

The things to note here are:

### Recursion

This is how lists are presented in the grammar.

```
ArgumentList :
  AssignmentExpression
  ArgumentList , AssignmentExpression
```

means

```javascript
a, b = 1, c = 2
^_____________^ ArgumentList
   ^__________^ ArgumentList, AssignmentExpression,
          ^___^ AssignmentExpression
```

### Optional

The `_opt_` suffix for optional syntax. For example,

```
VariableDeclaration :
  BindingIdentifier Initializer_opt
```

means

```javascript
var binding_identifier;
var binding_identifier = Initializer;
                       ______________ Initializer_opt
```

### Parameters

The `[Return]` and `[In]` are parameters of the grammar.

For example

```
ScriptBody :
    StatementList[~Yield, ~Await, ~Return]
```

means top-level yield, await and return are not allowed in scripts, but

```
ModuleItem :
  ImportDeclaration
  ExportDeclaration
  StatementListItem[~Yield, +Await, ~Return]
```

allows for top-level await.

## Source Text

[Chapter 11.2 Types of Source Code](https://tc39.es/ecma262/#sec-types-of-source-code) tells us that
there is a huge distinction between script code and module code.
And there is a `use strict` mode that makes the grammar saner by disallowing old JavaScript behaviors.

**Script Code** is not strict, `use strict` need to be inserted at the top of the file to make script code strict.
In HTML we write `<script src="javascript.js"></script>`.

**Module Code** is automatically strict.
In HTML we write `<script type="module" src="main.mjs"></script>`.

## ECMAScript Language: Lexical Grammar

For more in-depth explanation, read the V8 blog on [Understanding the ECMAScript spec](https://v8.dev/blog/understanding-ecmascript-part-3).

### [Automatic Semicolon Insertion](https://tc39.es/ecma262/#sec-automatic-semicolon-insertion)

This section describes all the rules where we can omit a semicolon while writing JavaScript.
All the explanation boils down to

```rust
    pub fn asi(&mut self) -> Result<()> {
        if self.eat(Kind::Semicolon) || self.can_insert_semicolon() {
            return Ok(());
        }
        let range = self.prev_node_end..self.cur_token().start;
        Err(SyntaxError::AutoSemicolonInsertion(range.into()))
    }

    pub const fn can_insert_semicolon(&self) -> bool {
        self.cur_token().is_on_new_line || matches!(self.cur_kind(), Kind::RCurly | Kind::Eof)
    }
```

The `asi` function need to be manually called where applicable, for example in the end of statement:

```rust
fn parse_debugger_statement(&mut self) -> Result<Statement<'a>> {
    let node = self.start_node();
    self.expect(Kind::Debugger)?;
    self.asi()?; // [!code highlight]
    self.ast.debugger_statement(self.finish_node(node))
}
```

:::info

This section on asi is written with a parser in mind,
it explicitly states that the source text is parsed from left to right,
which makes it almost impossible to write the parser in any other way.
The author of jsparagus made a rant about this [here](https://github.com/mozilla-spidermonkey/jsparagus/blob/master/js-quirks.md#automatic-semicolon-insertion-).

> The specification for this feature is both very-high-level and weirdly procedural (“When, as the source text is parsed from left to right, a token is encountered...”, as if the specification is telling a story about a browser. As far as I know, this is the only place in the spec where anything is assumed or implied about the internal implementation details of parsing.) But it would be hard to specify ASI any other way.

:::

## Expressions, Statements, Functions, Classes, Scripts and Modules

It takes a while to understand the syntactic grammar, then apply them to writing a parser.

---

---
url: /docs/guide/usage/transformer/lowering.md
---
# Syntax Lowering

Oxc transformer supports lowering ESNext to ES2015 syntax.

## Target

Oxc transformer receives a `target` option to specify the target runtime. This will determine which syntaxes are lowered and which warnings are emitted.

Each target environment is an environment name followed by a version number. The following environment names are currently supported:

* `chrome`
* `deno`
* `edge`
* `firefox`
* `hermes`
* `ie`
* `ios`
* `node`
* `opera`
* `rhino`
* `safari`
* `samsung`
* `es`

The values that are supported by [esbuild's target option](https://esbuild.github.io/api/#target) are supported, excluding ES5.

You can pass a single string or an array of strings:

```js
import { transform } from "oxc-transform";

const result = await transform("lib.js", "const foo = a ?? b;", {
  target: "es2020",
  // or multiple targets:
  // target: ["chrome87", "es2022"],
});
```

## Transformations

Oxc supports lowering the syntaxes below. Note that RegExp related transformations only transforms the RegExp literal (`/foo/v`) to use a RegExp constructor (`new RegExp('foo', 'v')`). You will need to use a polyfill together to support older browsers.

### ES2026

* Explicit Resource Management (`using a = foo()`)

### ES2024

* RegExp v flag with set notation + properties of strings (`/\p{Emoji}--\p{ASCII}/v`)

### ES2022

* Class Static Block (`class A { static { foo() } }`)
* Class Fields (`class A { foo = 1; #bar = 2; static baz = 3; static qux = 4; foobar(a) { return #bar in a } }`)
* RegExp Match Indices (`/foo/d`)

### ES2021

* Logical Assignment Operators (`foo ||= bar`)
* Numeric separators (Note: this is not implemented as a transform, but the codegen always removes the separators)

### ES2020

* Nullish coalescing operator (`foo ?? bar`)
* Optional Chaining (`foo?.bar`)
* Export namespace from (`export * as foo from "bar"`)

### ES2019

* Optional `catch` binding (`try {} catch {}`)

### ES2018

* Rest/Spread Properties (`const foo = { a, b, ...c }`, `const { x, y, ...z } = foo;`)
* Asynchronous Iteration (`for await (const x of y) {}`, `async function* foo() {}`)
* RegExp Unicode Property Escapes (`/\p{Script=Greek}/u`)
* RegExp Lookbehind Assertions (`/(?<=foo)bar/`)
* RegExp named capture groups (`/(?<foo>bar)/`)
* `s` (`dotAll`) flag for regular expressions (`/foo./s`)

### ES2017

* Async functions (`async function foo() {}`)

### ES2016

* Exponentiation operator (`foo ** bar`)

### ES2015

* Arrow functions (`const foo = () => {}`)
* RegExp sticky flag (`/foo/y`)
* RegExp unicode flag (`/foo/u`)

## Warnings

Oxc transformer emits warnings for the syntaxes below if the target runtime does not support them.

### ES2022

* Top level await (`await foo()`)
* Arbitrary module namespace identifiers (`import * as "f o o" from "bar"`)

### ES2020

* BigInt (`1n`)

## Compiler assumptions

You can specify assumptions for the compiler to make the output more smaller.

```js
import { transform } from "oxc-transform";

const result = await transform("lib.js", "const foo = a ?? b;", {
  target: ["chrome87", "es2022"],
  assumptions: {
    noDocumentAll: true,
  },
});
```

The following assumptions are supported.

### `ignoreFunctionLength`

Assume that no code relies on the `.length` property of function objects.

::: info Note
This assumption is not fully implemented yet. In particular, enabling it with object rest/spread currently produces a transform error.
:::

### `noDocumentAll`

Assume that the deprecated `document.all` with its special behavior is not used.

### `objectRestNoSymbols`

Assume that object rest/spread properties do not include Symbol keys.

::: info Note
This assumption is not fully implemented yet. In particular, enabling it with object rest/spread currently produces a transform error.
:::

### `pureGetters`

Assume that getters does not have side effects.

### `setPublicClassFields`

When using public class fields, assume that they don't shadow any getter in the current class,
in its subclasses or in its superclass. Thus, it's safe to assign them rather than using `Object.defineProperty`.

::: tip Note
For TypeScript, if you wanted behavior is equivalent to `useDefineForClassFields: false`,
you should set both `setPublicClassFields` and `removeClassFieldsWithoutInitializer` to `true`.
See [the TypeScript page](./typescript#useDefineForClassFields) for more information.
:::

## Not supported syntaxes

The following syntaxes are not lowered by Oxc transformer.

* ESNext
  * Decorators (tracked at [#9170](https://github.com/oxc-project/oxc/issues/9170)) (Note that [experimental decorators in TypeScript are supported](./typescript#decorators))
* ES2025
  * RegExp Modifiers (tracked at [#11826](https://github.com/oxc-project/oxc/issues/11826))
  * Duplicate named capture groups (tracked at [#11827](https://github.com/oxc-project/oxc/issues/11827))

---

---
url: /docs/guide/usage/minifier/syntax-normalization.md
---
# Syntax Normalization

Oxc minifier supports transforming syntaxes to make the output shorter and repetitive.

This feature is enabled by default and can be disabled by setting the `compress` option to `false`.

## Target

Oxc minifier uses some syntaxes that are only supported in newer environments. You can specify the target environment by setting the `target` option. The default value is `esnext`, which allows the use of any syntaxes that are supported by the latest ECMAScript standard. The supported value is same as [the `target` option in the transformer](/docs/guide/usage/transformer/lowering#target).

```js
import { minify } from "oxc-minify";

const result = await minify("lib.js", code, {
  compress: {
    target: "chrome87",
  },
});
```

## Join Variables

By default, consecutive variable declarations are merged into a single declaration. You can disable this behavior by setting the `compress.joinVars` option to `false`.

```js
// input
var foo = 1;
var bar = 2;

// output
var foo = 1,
  bar = 2;
```

```js
// Example
import { minify } from "oxc-minify";

const result = await minify("lib.js", code, {
  compress: {
    joinVars: false,
  },
});
```

## Sequences

By default, consecutive statements are merged into a single statement using the comma operator. You can disable this behavior by setting the `compress.sequences` option to `false`.

```js
// input
foo();
bar();

// output
(foo(), bar());
```

```js
// Example
import { minify } from "oxc-minify";

const result = await minify("lib.js", code, {
  compress: {
    sequences: false,
  },
});
```

---

---
url: /docs/learn/terminology.md
---

# Terminology

## Binding

A value being assigned/bound within a scope.

## Binding type

The type of the binding: imported value, assigned value (let/const/var), exported value, func/class declaration, func/method arguments, etc.

## Scope

A block in which bindings can exist. A block is any code surrounded with {}, such as classes, functions, methods, callbacks, if/else, etc. Scopes have a hierarchy, with parents having children (not always), and children belonging to a parent. Bindings in a child shadow those in a parent if they have the same name.

## Scope flags

Metadata about the current scope (not inherited hierarchy scope): function, constructor, top-level (program), etc.

## Symbol

A binding wrapper with references to each usage/call site of the bound variable within the current source text. A symbol is assigned an ID in the order they are scanned, and reach reference points to the symbol by that ID.

## Symbol flags

Metadata about the symbol/binding.

## Reference

A symbol reference is the usage of a symbol (and in turn a binding), and is assigned an ID in the order they are scanned. Each reference is flagged as read, write, or both.

## Span

The start/end offset of the node within the source text.

---

---
url: /docs/learn/architecture/test.md
---
# Test Infrastructure

::: info

This article serves as an invitation for sharing ideas to improve our test infrastructure,
feel free to contact us on [Discord][discord-url].

:::

In Oxc, correctness and reliability are taken extremely seriously.

We spend a great deal of time strengthening the test infrastructure to prevent problems from propagating to downstream tools.

## Parser

### Conformance

Parser tests from [Test262](https://github.com/tc39/test262), [Babel](https://github.com/babel/babel), and [TypeScript](https://github.com/microsoft/TypeScript) are used to test JavaScript, TypeScript, and JSX syntax.

For Test262, all stage 4 and regular expression tests are included.

All conformance results are stored in a snapshot file for tracking changes:

* [test262.snap](https://github.com/oxc-project/oxc/blob/main/tasks/coverage/snapshots/parser_test262.snap).
* [babel.snap](https://github.com/oxc-project/oxc/blob/main/tasks/coverage/snapshots/parser_babel.snap).
* [typescript.snap](https://github.com/oxc-project/oxc/blob/main/tasks/coverage/snapshots/parser_typescript.snap).

All syntax errors are written to these snapshot files for diffing changes.

### Fuzzing

To ensure that the parser does not panic when encountering random data, three fuzzers are used:

1. [cargo fuzz](https://github.com/rust-fuzz/cargo-fuzz) for [sending random bytes](https://github.com/oxc-project/oxc-fuzz-parser/blob/main/fuzz/fuzz_targets/parser.rs) to the parser.
2. [shift-fuzzer-js](https://github.com/shapesecurity/shift-fuzzer-js) by [bakkot](https://github.com/bakkot) for producing random but valid ASTs.
3. [Automated-Fuzzer](https://github.com/qarmin/Automated-Fuzzer) by [qarmin](https://github.com/qarmin), which [actively reports](https://github.com/oxc-project/oxc/issues?q=is%3Aissue+author%3Aqarmin+) crashes.

### Memory Safety

Oxc uses an arena allocator based around [`bumpalo`](https://docs.rs/bumpalo/latest/bumpalo) as the memory allocator for its AST, and other data.
None of the AST node types have a `Drop` implementation.
This is enforced at compile time by Oxc's allocator, which causes a compile-time error if any code attempts to allocate types in the arena which are `Drop`.This statically ensures that types which own heap-allocated data cannot be stored in the arena, which would result in memory leaks.

### Unsafe code

Oxc uses `unsafe` code for performance optimizations. We aim to contain `unsafe` to within self-contained data structures which present safe APIs externally. Miri [is run](https://github.com/oxc-project/oxc/actions/workflows/miri.yml) on the crates containing these structures on every PR.

## Linter

### Snapshot Diagnostics

All linter diagnostics are written to a [snapshot file](https://github.com/oxc-project/oxc/tree/main/crates/oxc_linter/src/snapshots) for testing against regressions.

For example:

```javascript
 ⚠ typescript-eslint(adjacent-overload-signatures): All "foo" signatures should be adjacent.
  ╭─[adjacent_overload_signatures.tsx:3:18]
2 │         function foo(s: string);
3 │         function foo(n: number);
  ·                  ───
4 │         type bar = number;
5 │         function foo(sn: string | number) {}
  ·                  ───
6 │       }
  ╰────
```

### Ecosystem CI

[oxc-ecosystem-ci](https://github.com/oxc-project/oxc-ecosystem-ci) runs `oxlint` against large repositories to check for false positives, regressions, and panics. The repositories tested include:

* [rolldown/rolldown](https://github.com/rolldown-rs/rolldown)
* [napi-rs/napi-rs](https://github.com/napi-rs/napi-rs)
* [toeverything/affine](https://github.com/toeverything/affine)
* [preactjs/preact](https://github.com/preactjs/preact)
* [microsoft/vscode](https://github.com/microsoft/vscode)
* [bbc/simorgh](https://github.com/bbc/simorgh)
* [elastic/kibana](https://github.com/elastic/kibana)
* [DefinitelyTyped/DefinitelyTyped](https://github.com/DefinitelyTyped/DefinitelyTyped)

## Idempotency

Idempotency testing is used for integration tests and end-to-end tests on all tools.

An idempotency test follows this procedure:

```javascript
let sourceText = "foo";
let printed = tool(sourceText);
let printed2 = tool(printed);
assert(printed == printed2);
```

For example, idempotently minifying a piece of code should yield the same result.

All tools (parser, transformer, minifer, etc.) are idempotently tested on Test262, Babel and TypeScript test files.

## Integration Tests

Integration tests are preferred over unit tests.

[codecov](https://app.codecov.io/gh/oxc-project/oxc) currently reports
[![Code Coverage][code-coverage-badge]][code-coverage-url]
line coverage.

## End to End

The repository [monitor-oxc](https://github.com/oxc-project/monitor-oxc) performs end-to-end tests against the top 3000 npm packages from [npm-high-impact](https://github.com/wooorm/npm-high-impact).

Its `package.json` has 3000 dependencies:

```json
"devDependencies": {
  "@aashutoshrathi/word-wrap": "latest",
  "@actions/http-client": "latest",
  "@adobe/css-tools": "latest",
  "@alloc/quick-lru": "latest",
 ...
  "zip-stream": "latest",
  "zod": "latest",
  "zone.js": "latest",
  "zustand": "latest"
}
```

And a test file that imports these packages and asserts the import:

`src/dynamic.test.mjs`

```javascript
import test from "node:test";
import assert from "node:assert";
test("@aashutoshrathi/word-wrap", () => import("@aashutoshrathi/word-wrap").then(assert.ok));
test("@actions/http-client", () => import("@actions/http-client").then(assert.ok));
test("@adobe/css-tools", () => import("@adobe/css-tools").then(assert.ok));
test("@alloc/quick-lru", () => import("@alloc/quick-lru").then(assert.ok));
...
test("zod", () => import("zod").then(assert.ok));
test("zone.js", () => import("zone.js").then(assert.ok));
test("zustand", () => import("zustand").then(assert.ok));
test("zwitch", () => import("zwitch").then(assert.ok));
```

This test file is run after each of the tools (codegen, transformer, minifier, etc.) rewrites all the files in `node_modules`.

The packages are updated to their latest versions daily.

This setup has caught many obscure bugs that the conformance test suites missed.

***

If you any ideas on how to improve our test infrastructure,
feel free to contact us on [Discord][discord-url].

[discord-url]: https://discord.gg/9uXCAwqQZW

[code-coverage-badge]: https://codecov.io/github/oxc-project/oxc/branch/main/graph/badge.svg

[code-coverage-url]: https://codecov.io/gh/oxc-project/oxc

---

---
url: /docs/contribute/transformer.md
---

# Transformer

The Oxc transformer is responsible for converting higher versions of ECMAScript and TypeScript to lower versions that can run in older browsers and environments.

### Repository Structure

```
crates/oxc_transformer/
├── src/
│   ├── lib.rs                    # Main transformer interface
│   ├── transformer.rs            # Core transformation logic
│   ├── typescript/               # TypeScript transformations
│   ├── jsx/                      # JSX transformations
│   ├── es2015/                   # ES2015+ transformations
│   ├── isolated_declarations/    # .d.ts generation
│   └── helpers/                  # Utility functions
├── tests/                        # Integration tests
├── examples/                     # Usage examples
└── benches/                      # Performance benchmarks
```

---

---
url: /docs/guide/usage/transformer.md
---
# Transformer

A high-performance transformer that rewrites unsupported syntax into forms supported by target runtimes.

## Features

The features below run in a fixed order, regardless of the order of the options:

1. **[React Compiler](./transformer/react-compiler)** — runs first, on the original source.
2. **[TypeScript](./transformer/typescript)** — type stripping.
3. **[Decorators](./transformer/typescript#decorators)**.
4. **[Plugins](./transformer/plugins)** — e.g. styled-components.
5. **[React Refresh](./transformer/jsx#react-refresh)** — component instrumentation, runs just before the JSX transform.
6. **[JSX](./transformer/jsx)** — JSX to JavaScript.
7. **[Lowering](./transformer/lowering)** — ES2026 down to ES2015.
8. **[Inject](./transformer/global-variable-replacement#inject)** — global variable injection.
9. **[Define](./transformer/global-variable-replacement#define)** — global variable replacement.

Oxc also supports [TypeScript Isolated Declarations emit](./transformer/isolated-declarations) without using the TypeScript compiler.

## General Options

The `transform` function accepts a filename, source code, and an options object:

```js
import { transform } from "oxc-transform";

const result = await transform("lib.ts", sourceCode, {
  // Force the source language. Inferred from filename by default.
  lang: "tsx", // "js" | "jsx" | "ts" | "tsx" | "dts"

  // Treat the source as script, module, or CommonJS. Inferred by default.
  sourceType: "module", // "script" | "module" | "commonjs" | "unambiguous"

  // The current working directory. Used to resolve relative paths.
  cwd: "/path/to/project",

  // Enable source map generation.
  sourcemap: true,

  // Configure runtime helper strategy.
  helpers: {
    mode: "Runtime", // "Runtime" (import from @oxc-project/runtime) or "External" (use global babelHelpers)
  },

  // See sub-pages for more options:
  // typescript, jsx, target, assumptions, define, inject, decorator, plugins
});
```

The `transform` function is async. A synchronous `transformSync` variant is also available with the same signature.

## Installation

### Node.js

* Use the node binding [oxc-transform][url-oxc-transform-npm].
* Try on [stackblitz](https://stackblitz.com/fork/github/oxc-project/website/tree/main/stackblitz-templates/oxc-transform).

### Rust

Use the umbrella crate [oxc][url-oxc-crate] with the `transformer` feature.

Rust usage example can be found [here](https://github.com/oxc-project/oxc/blob/main/crates/oxc_transformer/examples/transformer.rs).

## Integrations

* [`unplugin-oxc`](https://npmx.dev/package/unplugin-oxc)
* [`unplugin-isolated-decl`](https://npmx.dev/package/unplugin-isolated-decl)
* [`oxc-webpack-loader`](https://npmx.dev/package/oxc-webpack-loader)

[url-oxc-crate]: https://docs.rs/oxc

[url-oxc-transform-npm]: https://npmx.dev/package/oxc-transform

---

---
url: /docs/guide/troubleshooting.md
---
# Troubleshooting

## Cannot find native binding. npm has a bug related to optional dependencies

This is a npm (< v11.3.0) bug, things you can try:

* use latest npm
* use pnpm
* `rm -rf node_modules; npm i`
* Install one of these bindings explicitly in your package.json because package manager is not picking up the optional dependency:

```
@{app}/binding-win32-x64-msvc
@{app}/binding-win32-arm64-msvc
@{app}/binding-linux-x64-gnu
@{app}/binding-linux-x64-musl
@{app}/binding-freebsd-x64
@{app}/binding-linux-arm64-gnu
@{app}/binding-linux-arm64-musl
@{app}/binding-linux-arm-gnueabihf
@{app}/binding-linux-arm-musleabihf
@{app}/binding-linux-s390x-gnu
@{app}/binding-linux-riscv64-gnu
@{app}/binding-darwin-x64
@{app}/binding-darwin-arm64
@{app}/binding-android-arm64
@{app}/binding-wasm32-wasi
```

where app is `oxlint`, `oxfmt`, `oxc-parser`, `oxc-transform`, `oxc-minify`, `oxc-resolver`

---

---
url: /docs/guide/usage/linter/type-aware.md
description: Linting with type information.
---

# Type-Aware Linting

Type-aware linting enables rules that rely on TypeScript’s type system, such as detecting unhandled promises or unsafe assignments. In Oxlint, type-aware linting is provided by [`tsgolint`](https://github.com/oxc-project/tsgolint) and is integrated into the Oxlint CLI and configuration system.

Type-aware linting currently supports [59 out of 61](https://github.com/oxc-project/tsgolint/tree/main?tab=readme-ov-file#implemented-rules) type-aware rules from typescript-eslint. Rule coverage, performance, and compatibility continue to improve.

## Overview

Oxlint separates responsibilities between two components:

* **Oxlint (Rust)**
  Handles file traversal, ignore logic, configuration, non-type-aware rules, and reporting.

* **tsgolint (Go)**
  Builds TypeScript programs using [`typescript-go`](https://github.com/microsoft/typescript-go) and executes type-aware rules, returning structured diagnostics to Oxlint.

## Installation

Type-aware linting requires an additional dependency:

::: code-group

```sh [npm]
npm add -D oxlint-tsgolint@latest
```

```sh [pnpm]
pnpm add -D oxlint-tsgolint@latest
```

```sh [yarn]
yarn add -D oxlint-tsgolint@latest
```

```sh [bun]
bun add -D oxlint-tsgolint@latest
```

:::

## Running type-aware linting

You can enable type-aware linting in either place:

* CLI flag: `--type-aware`
* Root config: `options.typeAware: true`

CLI:

```bash
oxlint --type-aware
```

Root config:

::: code-group

```json [.oxlintrc.json]
{
  "options": {
    "typeAware": true
  }
}
```

```ts [oxlint.config.ts]
import { defineConfig } from "oxlint";

export default defineConfig({
  options: {
    typeAware: true,
  },
});
```

:::

When enabled, Oxlint runs standard rules and type-aware rules in the `typescript/*` namespace.

`--type-aware` takes precedence over config files. For example, `oxlint --type-aware -c .oxlintrc.json` enables type-aware linting even if that config sets `options.typeAware` to `false`.

`options.typeAware` and `options.typeCheck` are only supported in the root config file. Nested configs should not set these fields.

In editor and LSP-based integrations like VS Code, type-aware linting can be enabled by setting the `typeAware` option to `true`, see the [Editors](./editors) page for more information.

### Monorepos and build outputs

Type-aware linting requires resolved type information.

In monorepos:

* Build dependent packages so `.d.ts` files are available
* Ensure dependencies are installed before running

```bash
pnpm install
pnpm -r build
oxlint --type-aware
```

### Type checking diagnostics

Enable type checking to report TypeScript errors alongside lint results:

```bash
oxlint --type-aware --type-check
```

Or enable it in the root config:

::: code-group

```json [.oxlintrc.json]
{
  "options": {
    "typeAware": true,
    "typeCheck": true
  }
}
```

```ts [oxlint.config.ts]
import { defineConfig } from "oxlint";

export default defineConfig({
  options: {
    typeAware: true,
    typeCheck: true,
  },
});
```

:::

`--type-check` takes precedence over config files. For example, `oxlint --type-check -c .oxlintrc.json` enables type checking even if that config sets `options.typeCheck` to `false`.

This mode can replace a separate `tsc --noEmit` step in CI:

```bash
# before
tsc --noEmit
oxlint

# after
oxlint --type-aware --type-check
```

## Configuring type-aware rules

Type-aware rules are configured like other Oxlint rules.

::: code-group

```json [.oxlintrc.json]
{
  "plugins": ["typescript"],
  "rules": {
    "typescript/no-floating-promises": "error",
    "typescript/no-unsafe-assignment": "warn"
  }
}
```

```ts [oxlint.config.ts]
import { defineConfig } from "oxlint";

export default defineConfig({
  plugins: ["typescript"],
  rules: {
    "typescript/no-floating-promises": "error",
    "typescript/no-unsafe-assignment": "warn",
  },
});
```

:::

Rules support the same options as their `typescript-eslint` equivalents.

::: code-group

```json [.oxlintrc.json]
{
  "plugins": ["typescript"],
  "rules": {
    "typescript/no-floating-promises": ["error", { "ignoreVoid": true }]
  }
}
```

```ts [oxlint.config.ts]
import { defineConfig } from "oxlint";

export default defineConfig({
  plugins: ["typescript"],
  rules: {
    "typescript/no-floating-promises": ["error", { ignoreVoid: true }],
  },
});
```

:::

## Rule timings

Use `--debug timings` to find the most expensive rules in your configuration:

```bash
oxlint --type-aware --debug timings
```

The report orders rules by total time and includes their relative share, call count, and execution source:

```text
Rule timings:
Rule                                                         Time (ms)  Relative  Calls  Source
----------------------------------------------------------  ----------  --------  -----  ----------
typescript/unbound-method                                      108.620     46.5%  12450  type-aware
typescript/no-floating-promises                                 65.606     28.1%   7327  type-aware
eslint/no-unused-vars                                            2.187      0.9%    372  native
typescript/no-duplicate-type-constituents                        1.505      0.6%    870  type-aware
typescript/no-meaningless-void-operator                          1.445      0.6%    383  type-aware
vitest/no-standalone-expect                                      0.978      0.4%    372  native
vitest/expect-expect                                             0.951      0.4%   4682  native
typescript/no-implied-eval                                       0.401      0.2%  13809  type-aware
oxc/no-map-spread                                                0.383      0.2%  12545  native
react/no-did-update-set-state                                    0.382      0.2%  12545  native
eslint/no-misleading-character-class                             0.380      0.2%  13524  native
typescript/no-redundant-type-constituents                        0.371      0.2%    870  type-aware
unicorn/no-single-promise-in-promise-methods                     0.362      0.2%  12545  native
eslint/no-useless-backreference                                  0.360      0.2%  13524  native
typescript/no-useless-default-assignment                         0.258      0.1%   3110  type-aware
eslint/no-console                                                0.256      0.1%  12484  native
eslint/no-caller                                                 0.253      0.1%  11603  native
...
```

`native` rules run inside Oxlint, while rules run by tsgolint are labelled `type-aware`. Timing collection has no overhead unless it is enabled. When enabled, it adds measurement overhead, so use the report to compare rules within the same run rather than as an end-to-end benchmark.

## Disable comments

Type-aware rules support inline disable comments:

```ts
// oxlint-disable-next-line typescript/no-floating-promises
doSomethingAsync();
```

Report unused disable comments with:

```bash
oxlint --type-aware --report-unused-disable-directives
```

## TypeScript compatibility

Type-aware linting is powered by `typescript-go`.

* TypeScript **7.0+** is required
* Some legacy `tsconfig` options are not supported (like `baseUrl` in `tsconfig.json`)
* If you're using config options/features that were deprecated in TypeScript 6.0 or removed in TypeScript 7.0, you'll need to migrate your codebase first
* Invalid options are reported when `--type-check` is enabled

See the [TypeScript migration guide](https://github.com/microsoft/TypeScript/issues/62508#issuecomment-3348649259) for more details, and consider using [ts5to6](https://github.com/andrewbranch/ts5to6) to upgrade your tsconfig file.

## Stability notes

Type-aware linting:

* Rule coverage is incomplete (but very close)
* Very large codebases may encounter high memory usage
* Performance continues to improve

## Troubleshooting

### Performance and debugging

If type-aware linting is slow or uses excessive memory:

1. Update both tools:

* `oxlint`
* `oxlint-tsgolint`

2. Enable debug logging:

```bash
OXC_LOG=debug oxlint --type-aware
```

Example output (showing key timing milestones):

```
2026/01/01 12:00:00.000000 Starting tsgolint
2026/01/01 12:00:00.001000 Starting to assign files to programs. Total files: 259
2026/01/01 12:00:01.000000 Done assigning files to programs. Total programs: 8. Unmatched files: 75
2026/01/01 12:00:01.001000 Starting linter with 12 workers
2026/01/01 12:00:01.001000 Workload distribution: 8 programs
2026/01/01 12:00:01.002000 [1/8] Running linter on program: /path/to/project/jsconfig.json
...
2026/01/01 12:00:01.100000 [4/8] Running linter on program: /path/to/project/tsconfig.json
2026/01/01 12:00:02.500000 Program created with 26140 source files
2026/01/01 12:00:14.000000 /path/to/project/oxlint-plugin.mts
...
2026/01/01 12:00:14.100000 [5/8] Running linter on program: /path/to/project/apps/tsconfig.json
...
2026/01/01 12:00:15.000000 Linting Complete
Finished in 16.4s on 259 files with 161 rules using 12 threads.
```

**How to interpret the log:**

* **File assignment phase** (`Starting to assign files...` → `Done assigning files...`): Maps source files to their tsconfig projects. This phase should be fast. If slow, please file an issue.
* **Program linting** (`[N/M] Running linter on program...`): Each TypeScript project is linted separately. Programs that take significantly longer may indicate expensive type resolution or an overly large project.
  * Look for programs with an unusually high number of source files (e.g., `Program created with 26140 source files`). This may indicate misconfigured tsconfig `includes`/`excludes` pulling in unnecessary files like `node_modules`.
  * Each file path logged indicates when that file is being linted. Large time gaps between files may indicate expensive type resolution for certain files.

### Common performance issues

#### Root tsconfig includes too many files

A root `tsconfig.json` with overly broad `include` patterns can inadvertently include all files in the repository, causing significant slowdowns:

```json [tsconfig.json]
{
  "include": ["**/*"] // ❌ Catches everything
}
```

This configuration pulls in build outputs and other files that shouldn't be type-checked.

**Fix:** Explicitly scope the `include` patterns and add appropriate `exclude` entries:

```json [tsconfig.json]
{
  "include": ["src/**/*"], // ✅ Only source files
  "exclude": ["dist", "build", "coverage"] // node_modules are excluded by default
}
```

For monorepos, ensure the root `tsconfig.json` does not include source files directly:

```json [tsconfig.json]
{
  "files": []
}
```

**Diagnosing the issue:** Enable debug logging and look for programs with an unusually high number of source files:

```
2026/01/01 12:00:02.500000 Program created with 26140 source files
```

If you see thousands of files in a single program, check that tsconfig's `include`/`exclude` settings.

## Next steps

* Check [implemented rules](https://github.com/oxc-project/tsgolint/tree/main?tab=readme-ov-file#implemented-rules)
* Report issues to <https://github.com/oxc-project/tsgolint>

---

---
url: /docs/guide/usage/transformer/typescript.md
---
# TypeScript

Oxc transformer supports transforming TypeScript to JavaScript.

```js
import { transform } from "oxc-transform";

const result = await transform("lib.ts", sourceCode, {
  typescript: {
    jsxPragma: "React.createElement",
    jsxPragmaFrag: "React.Fragment",
    onlyRemoveTypeImports: false,
    allowNamespaces: true,
    removeClassFieldsWithoutInitializer: false,
    rewriteImportExtensions: false,
    optimizeConstEnums: false,
    optimizeEnums: false,
  },
});
```

## `verbatimModuleSyntax`

By default, TypeScript removes unused imports in a different semantics than the JavaScript specification.
The [`verbatimModuleSyntax`](https://www.typescriptlang.org/tsconfig/#verbatimModuleSyntax) option tells TypeScript to align with the JavaScript specification.

If you are using this option, make sure to set `typescript.onlyRemoveTypeImports` option to `true`.

```js
import { transform } from "oxc-transform";

const result = await transform("lib.ts", sourceCode, {
  typescript: {
    onlyRemoveTypeImports: true,
  },
});
```

## `useDefineForClassFields`

TypeScript used to have a different semantics for class fields than the JavaScript specification. The [`useDefineForClassFields`](https://www.typescriptlang.org/tsconfig/#useDefineForClassFields) option tells TypeScript to align with the JavaScript specification. This options is enabled by default if the `target` option in the tsconfig is set to `es2022` or higher.

If you are disabling this option, make sure to set `typescript.removeClassFieldsWithoutInitializer` option and `assumptions.setPublicClassFields` to `true`.

```js
import { transform } from "oxc-transform";

const result = await transform("lib.ts", sourceCode, {
  typescript: {
    removeClassFieldsWithoutInitializer: true,
  },
  assumptions: {
    setPublicClassFields: true,
  },
});
```

## Decorators

Oxc transformer supports transforming legacy decorators. This is called experimental decorators in TypeScript.

If you are using the [`experimentalDecorators`](https://www.typescriptlang.org/tsconfig/#experimentalDecorators) option in the tsconfig, you can use the `decorator.legacy` option.
If you are using the [`emitDecoratorMetadata`](https://www.typescriptlang.org/tsconfig/#emitDecoratorMetadata) option in the tsconfig, you can use the `decorator.emitDecoratorMetadata` option.

```js
import { transform } from "oxc-transform";

const result = await transform("lib.ts", sourceCode, {
  decorator: {
    legacy: true,
    emitDecoratorMetadata: true,
  },
});
```

:::: warning Decorator Metadata: Types that requires type inference will fallback to `Object`

Due to the lack of full type inference feature, Oxc transformer will fallback to `Object` type if it cannot calculate the type of the decorator metadata.

For example, the following code will be transformed to the following code:

::: code-group

```ts [input.ts]
import { Something1 } from "./somewhere";

type Something2 = Exclude<string | number, string>;

export class Foo {
  @test
  foo(input1: Something1, input2: Something2) {}
}
```

```js [output(oxc).js]
// omit helper functions
import { Something1 } from "./somewhere";
var _ref;
export class Foo {
  foo(input1, input2) {}
}
_decorate(
  [
    test,
    _decorateMetadata("design:type", Function),
    _decorateMetadata("design:paramtypes", [
      typeof (_ref = typeof Something1 !== "undefined" && Something1) === "function"
        ? _ref
        : Object,
      Object, // [!code highlight]
    ]),
    _decorateMetadata("design:returntype", void 0),
  ],
  Foo.prototype,
  "foo",
  null,
);
```

```js [output(typescript_compiler).js]
// omit helper functions
var _a;
import { Something1 } from "./somewhere";
export class Foo {
  foo(input1, input2) {}
}
__decorate(
  [
    test,
    __metadata("design:type", Function),
    __metadata("design:paramtypes", [
      typeof (_a = typeof Something1 !== "undefined" && Something1) === "function" ? _a : Object,
      Number, // [!code highlight]
    ]),
    __metadata("design:returntype", void 0),
  ],
  Foo.prototype,
  "foo",
  null,
);
```

:::

This behavior aligns with TypeScript's behavior when using a type that is external.

You can explicitly set the types by calling `Reflect.metadata`:

::: code-group

```ts [input.ts]
import { Something1 } from "./somewhere";

type Something2 = Exclude<string | number, string>;

export class Foo {
  @test
  @Reflect.metadata("design:paramtypes", [Something1, Number])
  foo(input1: Something1, input2: Something2) {}
}
```

```js [output.js]
// omit helper functions
import { Something1 } from "./somewhere";
var _ref;
export class Foo {
  foo(input1, input2) {}
}
_decorate(
  [
    test,
    Reflect.metadata("design:paramtypes", [Something1, Number]),
    _decorateMetadata("design:type", Function),
    _decorateMetadata("design:paramtypes", [
      typeof (_ref = typeof Something1 !== "undefined" && Something1) === "function"
        ? _ref
        : Object,
      Object,
    ]),
    _decorateMetadata("design:returntype", void 0),
  ],
  Foo.prototype,
  "foo",
  null,
);
```

:::

::::

## TSX

Transforming TSX files is supported as well.
See [JSX transform](./jsx) for more information.

## Rewriting import extensions

If you are using the [`rewriteRelativeImportExtensions`](https://www.typescriptlang.org/tsconfig/#rewriteRelativeImportExtensions) option in the tsconfig, you can use the `typescript.rewriteImportExtensions` option.

* `"rewrite"` or `true`: rewrites `.ts` and `.tsx` to `.js`, `.mts` to `.mjs`, and `.cts` to `.cjs`.
* `"remove"`: removes `.ts`/`.tsx`/`.mts`/`.cts` extensions entirely.
* `false` (default): no changes.

```js
import { transform } from "oxc-transform";

const result = await transform("lib.ts", sourceCode, {
  typescript: {
    rewriteImportExtensions: "rewrite", // or "remove", true, false
  },
});
```

## Optimize Enums

Oxc transformer can optimize enums by inlining their member values at usage sites.

* `optimizeConstEnums`: inlines `const enum` values and removes the declaration.
* `optimizeEnums`: inlines regular (non-const) enum member accesses when all members satisfy const enum constraints (i.e., their values are statically evaluable). Non-exported enum declarations are also removed when all members are evaluable and no references to the enum as a runtime value exist.

```js
import { transform } from "oxc-transform";

const result = await transform("lib.ts", sourceCode, {
  typescript: {
    optimizeConstEnums: true,
    optimizeEnums: true,
  },
});
```

## Declaration

Generate `.d.ts` declaration files alongside the transform output. The source file must be compliant with all [`isolatedDeclarations`](https://www.typescriptlang.org/docs/handbook/release-notes/typescript-5-5.html#isolated-declarations) requirements.

```js
import { transform } from "oxc-transform";

const result = await transform("lib.ts", sourceCode, {
  typescript: {
    declaration: {
      stripInternal: false,
    },
  },
});

console.log(result.declaration); // the .d.ts content
console.log(result.declarationMap); // the declaration source map (if sourcemap is enabled)
```

## Caveats

### Isolated Modules

Because Oxc transformer transforms each files independently, some TypeScript features are not supported.
To avoid using unsupported features, you should enable the [`isolatedModules`](https://www.typescriptlang.org/tsconfig/#isolatedModules) option in your `tsconfig.json` file.

### Partial Namespace Support

TypeScript has a legacy feature called [namespaces](https://www.typescriptlang.org/docs/handbook/namespaces.html). While [it is recommended to use ES modules for new projects](https://www.typescriptlang.org/docs/handbook/namespaces-and-modules.html#using-modules), Oxc transformer has a partial support for namespaces.

#### Exporting a variable using `var` or `let` is not supported

Exporting a variable using `var` or `let` is not supported.

```ts
namespace Foo {
  export let bar = 1; // [!code highlight]
}
console.log(Foo.bar);
```

A workaround is to use `const`. If you need the variable to be mutable, use an object with internal mutability:

```ts
namespace Foo {
  export const bar = { value: 1 }; // [!code highlight]
}
console.log(Foo.bar.value);
```

#### Namespaces does not share the scope between namespaces with the same name

::: code-group

```ts [input.ts]
namespace Foo {
  export const bar = 1;
}
namespace Foo {
  export const baz = bar;
}
```

```js [output(oxc).js]
let foo;
(function (_Foo) {
  const bar = (_Foo.bar = 1);
})(Foo || (Foo = {}));
(function (_Foo2) {
  const baz = (_Foo2.baz = bar); // [!code highlight]
})(Foo || (Foo = {}));
```

```js [output(typescript_compiler).js]
var Foo;
(function (Foo) {
  Foo.bar = 1;
})(Foo || (Foo = {}));
(function (Foo) {
  Foo.baz = Foo.bar; // [!code highlight]
})(Foo || (Foo = {}));
```

:::

In this example, the `bar` reference in the second namespace points to the `bar` variable in the first namespace for the TypeScript compiler output, but it does not for the Oxc transformer output.

A workaround is to explicitly reference via the namespace object:

```ts
namespace Foo {
  export const bar = 1;
}
namespace Foo {
  export const baz = Foo.bar; // [!code highlight]
}
```

---

---
url: /docs/guide/usage/oxc-node.md
description: Run TypeScript and JSX directly in Node.js with Oxc.
---

# TypeScript Runner

::: info Experimental
The TypeScript runner is experimental and under active development. APIs and behavior may change between releases.
:::

[`oxc-node`](https://github.com/oxc-project/oxc-node) is Oxc's TypeScript runner. It runs TypeScript and JSX without a separate build step while preserving the standard Node.js command-line workflow.

The runner provides:

* The `oxnode` command for running scripts and starting a REPL.
* A Node.js register hook for use with `node --import`.
* Synchronous and asynchronous transformation APIs.
* ESM and CommonJS support.
* Source maps for stack traces.
* `tsconfig.json` integration.

## CLI

Install [`@oxc-node/cli`](https://npmx.dev/package/@oxc-node/cli) as a development dependency:

::: code-group

```sh [npm]
$ npm add -D @oxc-node/cli
```

```sh [pnpm]
$ pnpm add -D @oxc-node/cli
```

```sh [yarn]
$ yarn add -D @oxc-node/cli
```

```sh [bun]
$ bun add -D @oxc-node/cli
```

:::

::: tip
A project-local installation keeps the runner version consistent across your team. You can instead install `@oxc-node/cli` globally if you want to invoke `oxnode` outside a project or package script.
:::

Run a TypeScript entry point:

```sh
oxnode ./src/index.ts
```

Arguments are passed through to Node.js, so Node.js features such as watch mode remain available:

```sh
oxnode --watch ./src/index.ts
```

Running `oxnode` without a script starts the Node.js REPL. Use `oxnode --node-help` to display Node.js command-line help.

For a repeatable project command, add a script to `package.json`:

```json [package.json]
{
  "scripts": {
    "dev": "oxnode ./src/index.ts"
  }
}
```

## Node.js register hook

Install [`@oxc-node/core`](https://npmx.dev/package/@oxc-node/core) when you want to keep using the `node` command directly:

::: code-group

```sh [npm]
$ npm add -D @oxc-node/core
```

```sh [pnpm]
$ pnpm add -D @oxc-node/core
```

```sh [yarn]
$ yarn add -D @oxc-node/core
```

```sh [bun]
$ bun add -D @oxc-node/core
```

:::

Register Oxc before loading the entry point:

```sh
node --import @oxc-node/core/register ./src/index.ts
```

Because this uses Node.js's register hook, it composes with other Node.js commands and flags. For example, run TypeScript tests with the built-in test runner:

```sh
node --import @oxc-node/core/register --test ./test.ts
```

## Supported files

The register hook transforms the following extensions:

```
.js .jsx .ts .tsx .mjs .mts .cjs .cts .es6 .es
```

Module format is inferred from the file extension, the nearest `package.json`, and `tsconfig.json`. Files in `node_modules` are not transformed by default. Set `OXC_TRANSFORM_ALL=1` to transform them as well.

## TypeScript configuration

The runner reads `tsconfig.json` from the current working directory. Set `OXC_TSCONFIG_PATH` or `TS_NODE_PROJECT` to use a different file:

```sh
OXC_TSCONFIG_PATH=./config/tsconfig.dev.json oxnode ./src/index.ts
```

The transformer uses relevant compiler options for module format, JSX, decorators, class fields, and rewriting relative import extensions. TypeScript types are stripped during transformation; the runner does not type-check your program.

## Links

* [`oxc-node` repository](https://github.com/oxc-project/oxc-node)
* [`@oxc-node/cli`](https://npmx.dev/package/@oxc-node/cli)
* [`@oxc-node/core`](https://npmx.dev/package/@oxc-node/core)

---

---
url: /docs/guide/usage/linter/rules/typescript/adjacent-overload-signatures.md
---

### What it does

Require that function overload signatures be consecutive.

### Why is this bad?

Function overload signatures represent multiple ways
a function can be called, potentially with different return types.
It's typical for an interface or type alias describing a function to place all overload signatures next to each other.
If Signatures placed elsewhere in the type are easier to be missed by future developers reading the code.

### Examples

Examples of **incorrect** code for this rule:

```typescript
declare namespace Foo {
  export function foo(s: string): void;
  export function foo(n: number): void;
  export function bar(): void;
  export function foo(sn: string | number): void;
}

type Foo = {
  foo(s: string): void;
  foo(n: number): void;
  bar(): void;
  foo(sn: string | number): void;
};

interface Foo {
  foo(s: string): void;
  foo(n: number): void;
  bar(): void;
  foo(sn: string | number): void;
}

class Foo {
  foo(s: string): void;
  foo(n: number): void;
  bar(): void {}
  foo(sn: string | number): void {}
}

export function foo(s: string): void;
export function foo(n: number): void;
export function bar(): void;
export function foo(sn: string | number): void;
```

## How to use

## Version

This rule was added in v0.0.7.

## References

---

---
url: /docs/guide/usage/linter/rules/typescript/array-type.md
---

### What it does

Require consistently using either `T[]` or `Array<T>` for arrays.

### Why is this bad?

Using the `Array` type directly is not idiomatic. Instead, use the array type `T[]` or `Array<T>`.

### Examples

Examples of **incorrect** code for this rule (with default configuration):

```typescript
const arr: Array<number> = new Array<number>();
const readonlyArr: ReadonlyArray<number> = [1, 2, 3];
```

Examples of **correct** code for this rule (with default configuration):

```typescript
const arr: number[] = new Array<number>();
const readonlyArr: readonly number[] = [1, 2, 3];
```

## Configuration

This rule accepts a configuration object with the following properties:

### default

type: `"array" | "array-simple" | "generic"`

default: `"array"`

The array type expected for mutable cases.

#### `"array"`

Enforce using `T[]` for all array types.

Example of **incorrect** code for this option:

```ts
const arr: Array<number> = new Array<number>();
```

Example of **correct** code for this option:

```ts
const arr: number[] = new Array<number>();
```

#### `"array-simple"`

Enforce using `T[]` for simple types, and `Array<T>` for complex types.

Example of **incorrect** code for this option:

```ts
const a: (string | number)[] = ["a", "b"];
const b: { prop: string }[] = [{ prop: "a" }];
const c: Array<MyType> = ["a", "b"];
const d: Array<string> = ["a", "b"];
```

Example of **correct** code for this option:

```ts
const a: Array<string | number> = ["a", "b"];
const b: Array<{ prop: string }> = [{ prop: "a" }];
const c: string[] = ["a", "b"];
const d: MyType[] = ["a", "b"];
```

#### `"generic"`

Enforce using `Array<T>` for all array types.

Example of **incorrect** code for this option:

```ts
const arr: number[] = new Array<number>();
```

Example of **correct** code for this option:

```ts
const arr: Array<number> = new Array<number>();
```

### readonly

type: `"array" | "array-simple" | "generic"`

default: `null`

The array type expected for readonly cases. If omitted, the value for `default` will be used.

## How to use

## Version

This rule was added in v0.2.8.

## References

---

---
url: /docs/guide/usage/linter/rules/typescript/await-thenable.md
---

### What it does

This rule disallows awaiting a value that is not a Thenable.

### Why is this bad?

While it is valid JavaScript to await a non-Promise-like value (it will resolve immediately), this practice can be confusing for readers who are not aware of this behavior. It can also be a sign of a programmer error, such as forgetting to add parentheses to call a function that returns a Promise.

### Examples

Examples of **incorrect** code for this rule:

```
await 12;
await (() => {});

// non-Promise values
await Math.random;
await { then() {} };

// this is not a Promise - it's a function that returns a Promise
declare const getPromise: () => Promise<string>;
await getPromise;
```

Examples of **correct** code for this rule:

```
await Promise.resolve('value');
await Promise.reject(new Error());

// Promise-like values
await {
  then(onfulfilled, onrejected) {
    onfulfilled('value');
  },
};

// this is a Promise - produced by calling a function
declare const getPromise: () => Promise<string>;
await getPromise();
```

## How to use

## Version

This rule was added in v1.12.0.

## References

---

---
url: /docs/guide/usage/linter/rules/typescript/ban-ts-comment.md
---

### What it does

This rule lets you set which directive comments you want to allow in your codebase.

### Why is this bad?

Using TypeScript directives to suppress TypeScript compiler errors
reduces the effectiveness of TypeScript overall.

### Examples

Examples of **incorrect** code for this rule:

```ts
if (false) {
  // @ts-ignore: Unreachable code error
  console.log("hello");
}
```

## Configuration

This rule allows you to specify how different TypeScript directive comments
should be handled.

For each directive (`@ts-expect-error`, `@ts-ignore`, `@ts-nocheck`, `@ts-check`), you can choose one of the following options:

* `true`: Disallow the directive entirely, preventing its use in the entire codebase.
* `false`: Allow the directive without any restrictions.
* `"allow-with-description"`: Allow the directive only if it is followed by a description explaining its use. The description must meet the minimum length specified by `minimumDescriptionLength`.
* `{ "descriptionFormat": "<regex>" }`: Allow the directive only if the description matches the specified regex pattern.

For example:

```json
{
  "ts-expect-error": "allow-with-description",
  "ts-ignore": true,
  "ts-nocheck": { "descriptionFormat": "^: TS\\d+ because .+$" },
  "ts-check": false,
  "minimumDescriptionLength": 3
}
```

This rule accepts a configuration object with the following properties:

### minimumDescriptionLength

type: `integer`

default: `3`

Minimum description length required when using directives with `allow-with-description`.

### ts-check

type: `object | boolean | "allow-with-description"`

#### ts-check.descriptionFormat

type: `string`

### ts-expect-error

type: `object | boolean | "allow-with-description"`

#### ts-expect-error.descriptionFormat

type: `string`

### ts-ignore

type: `object | boolean | "allow-with-description"`

#### ts-ignore.descriptionFormat

type: `string`

### ts-nocheck

type: `object | boolean | "allow-with-description"`

#### ts-nocheck.descriptionFormat

type: `string`

## How to use

## Version

This rule was added in v0.0.8.

## References

---

---
url: /docs/guide/usage/linter/rules/typescript/ban-tslint-comment.md
---

### What it does

This rule disallows `tslint:<rule-flag>` comments.

### Why is this bad?

Useful when migrating from TSLint to ESLint. Once TSLint has been
removed, this rule helps locate TSLint annotations

### Examples

Examples of **incorrect** code for this rule:

```ts
// tslint:disable-next-line
someCode();
```

Examples of **correct** code for this rule:

```ts
someCode();
```

## How to use

## Version

This rule was added in v0.2.9.

## References

---

---
url: /docs/guide/usage/linter/rules/typescript/ban-types.md
---

### What it does

This rule bans specific types and can suggest alternatives. Note that it does not ban the corresponding runtime objects from being used.

::: warning
This rule is deprecated and will be removed in a future release.

Prefer these replacement rules:

* `typescript/no-empty-object-type`
* `typescript/no-unsafe-function-type`
* `typescript/no-wrapper-object-types`
* `typescript/no-restricted-types` (for custom type bans)
  :::

### Why is this bad?

Some built-in types have aliases, while some types are considered dangerous or harmful. It's often a good idea to ban certain types to help with consistency and safety.

### Examples

Examples of **incorrect** code for this rule:

```typescript
let foo: String = "foo";

let bar: Boolean = true;
```

Examples of **correct** code for this rule:

```typescript
let foo: string = "foo";

let bar: boolean = true;
```

## How to use

## Version

This rule was added in v0.0.14.

## References

---

---
url: /docs/guide/usage/linter/rules/typescript/class-literal-property-style.md
---

### What it does

Enforces a consistent style for exposing literal values on classes.

### Why is this bad?

Mixing readonly fields and trivial literal getters for the same kind of value
makes class APIs inconsistent and harder to scan.

### Examples

Examples of **incorrect** code for this rule (default `"fields"`):

```ts
class C {
  get name() {
    return "oxc";
  }
}
```

Examples of **correct** code for this rule:

```ts
class C {
  readonly name = "oxc";
}
```

## Configuration

This rule accepts one of the following string values:

### `"fields"`

Enforce using readonly fields for literal values.

Examples of **incorrect** code with this option:

```ts
class C {
  get name() {
    return "oxc";
  }
}
```

Examples of **correct** code with this option:

```ts
class C {
  readonly name = "oxc";
}
```

### `"getters"`

Enforce using getters for literal values.

Examples of **incorrect** code with this option:

```ts
class C {
  readonly name = "oxc";
}
```

Examples of **correct** code with this option:

```ts
class C {
  get name() {
    return "oxc";
  }
}
```

## How to use

## Version

This rule was added in v1.47.0.

## References

---

---
url: /docs/guide/usage/linter/rules/typescript/consistent-generic-constructors.md
---

### What it does

When constructing a generic class, you can specify the type arguments on either the left-hand side (as a type annotation) or the right-hand side (as part of the constructor call).

This rule enforces consistency in the way generic constructors are used.

### Why is this bad?

Inconsistent usage of generic constructors can make the code harder to read and maintain.

### Examples

Examples of **incorrect** code for this rule:

```ts
const a: Foo<string> = new Foo();
const a = new Foo<string>(); // prefer type annotation
```

Examples of **correct** code for this rule:

```ts
const a = new Foo<string>();
const a: Foo<string> = new Foo(); // prefer type annotation
```

## Configuration

This rule accepts one of the following string values:

### `"constructor"`

Type arguments that only appear on the type annotation are disallowed.

### `"type-annotation"`

Type arguments that only appear on the constructor are disallowed.

## How to use

## Version

This rule was added in v0.14.0.

## References

---

---
url: /docs/guide/usage/linter/rules/typescript/consistent-indexed-object-style.md
---

### What it does

Choose between requiring either `Record` type or indexed signature types.

These two types are equivalent, this rule enforces consistency in picking one style over the other:

```ts
type Foo = Record<string, unknown>;

type Foo = {
  [key: string]: unknown;
};
```

### Why is this bad?

Inconsistent style for indexed object types can harm readability in a project.

### Examples

Examples of **incorrect** code for this rule with
`consistent-indexed-object-style: ["error", "record"]` (default):

```ts
interface Foo {
  [key: string]: unknown;
}
type Foo = {
  [key: string]: unknown;
};
```

Examples of **correct** code for this rule with
`consistent-indexed-object-style: ["error", "record"]` (default):

```ts
type Foo = Record<string, unknown>;
```

Examples of **incorrect** code for this rule with
`consistent-indexed-object-style: ["error", "index-signature"]`:

```ts
type Foo = Record<string, unknown>;
```

Examples of **correct** code for this rule with
`consistent-indexed-object-style: ["error", "index-signature"]`:

```ts
interface Foo {
  [key: string]: unknown;
}
type Foo = {
  [key: string]: unknown;
};
```

## Configuration

This rule accepts one of the following string values:

### `"record"`

When set to `record`, enforces the use of a `Record` for indexed object types, e.g. `Record<string, unknown>`.

### `"index-signature"`

When set to `index-signature`, enforces the use of indexed signature types, e.g. `{ [key: string]: unknown }`.

## How to use

## Version

This rule was added in v0.4.2.

## References

---

---
url: /docs/guide/usage/linter/rules/typescript/consistent-return.md
---

### What it does

Enforce consistent return behavior in functions.

### Why is this bad?

Mixing value-returning and non-value-returning code paths makes control flow harder to
reason about and frequently indicates a bug.

::: warning
If possible, prefer TypeScript's `noImplicitReturns` compiler option over this rule.
`noImplicitReturns` uses TypeScript's type information and control-flow analysis,
so it can catch more implicit return paths than this rule.
:::

### Examples

Examples of **incorrect** code for this rule:

```ts
function maybe(flag: boolean): number {
  if (flag) {
    return 1;
  }
  return;
}
```

Examples of **correct** code for this rule:

```ts
function maybe(flag: boolean): number {
  if (flag) {
    return 1;
  }
  return 0;
}
```

## Configuration

This rule accepts a configuration object with the following properties:

### treatUndefinedAsUnspecified

type: `boolean`

default: `false`

Treat explicit `return undefined` as equivalent to an unspecified return.

## How to use

## Version

This rule was added in v0.0.8.

## References

---

---
url: /docs/guide/usage/linter/rules/typescript/consistent-type-assertions.md
---

### What it does

Enforce consistent usage of TypeScript type assertions.

### Why is this bad?

Mixing assertion styles (`as` vs angle-bracket) makes code harder to read and maintain.
In some codebases, type assertions are banned in favor of safer alternatives like
type annotations or `satisfies`.

### Examples

Examples of **incorrect** code for this rule (default: `assertionStyle: "as"`):

```ts
const value = <Foo>bar;
```

Examples of **correct** code for this rule (default: `assertionStyle: "as"`):

```ts
const value = bar as Foo;
```

When `objectLiteralTypeAssertions` or `arrayLiteralTypeAssertions` are set to `never`, then the preferred syntax
for type assertions on object and array literals is to use a type annotation or the `satisfies` operator instead of a type assertion.

Examples of **incorrect** code when `objectLiteralTypeAssertions: "never"` and `arrayLiteralTypeAssertions: "never"`:

```ts
const obj = { a: 1 } as Foo;
const arr = [1, 2] as Foo[];
```

Examples of **correct** code when `objectLiteralTypeAssertions: "never"` and `arrayLiteralTypeAssertions: "never"`:

```ts
const obj: Foo = { a: 1 };
const obj = { a: 1 } satisfies Foo;
```

## Configuration

This rule accepts a configuration object with the following properties:

### arrayLiteralTypeAssertions

type: `"allow" | "allow-as-parameter" | "never"`

Whether array literal type assertions are allowed, allowed only as parameters, or disallowed.

#### `"allow"`

Allow type assertions on array literals.

Examples of **correct** code with this option:

```ts
const x = [1, 2] as number[];
const x = ["a"] as Array<string>;
```

#### `"allow-as-parameter"`

Allow type assertions on array literals only when used as a function parameter,
`throw` target, or default value.

Examples of **incorrect** code with this option:

```ts
const x = [1, 2] as Foo;
const foo = () => [5] as Foo;
```

Examples of **correct** code with this option:

```ts
print([5] as Foo);
throw [1, 2] as Bar;
function f(x = [5] as Foo.Bar) {}
```

#### `"never"`

Disallow type assertions on array literals entirely.

Examples of **incorrect** code with this option:

```ts
const x = [1, 2] as Foo;
print([5] as Foo);
```

Examples of **correct** code with this option:

```ts
const x: Foo = [1, 2];
const x = [1, 2] satisfies Foo;
```

### assertionStyle

type: `"as" | "angle-bracket" | "never"`

Which assertion syntax is enforced.

#### `"as"`

Enforce `as` syntax for type assertions.

Examples of **incorrect** code with this option:

```ts
const value = <Foo>bar;
```

Examples of **correct** code with this option:

```ts
const value = bar as Foo;
```

#### `"angle-bracket"`

Enforce angle-bracket syntax for type assertions.

Examples of **incorrect** code with this option:

```ts
const value = bar as Foo;
```

Examples of **correct** code with this option:

```ts
const value = <Foo>bar;
```

#### `"never"`

Disallow type assertions entirely.

Examples of **incorrect** code with this option:

```ts
const value = bar as Foo;
const value = <Foo>bar;
```

Examples of **correct** code with this option:

```ts
const value: Foo = bar;
const value = bar satisfies Foo;
```

### objectLiteralTypeAssertions

type: `"allow" | "allow-as-parameter" | "never"`

Whether object literal type assertions are allowed, allowed only as parameters, or disallowed.

#### `"allow"`

Allow type assertions on object literals.

Examples of **correct** code with this option:

```ts
const x = { a: 1 } as Foo;
const x = {} as Foo<int>;
```

#### `"allow-as-parameter"`

Allow type assertions on object literals only when used as a function parameter,
`throw` target, or default value.

Examples of **incorrect** code with this option:

```ts
const x = { a: 1 } as Foo;
const x = {} as Foo<int>;
```

Examples of **correct** code with this option:

```ts
print({ a: 1 } as Foo);
throw { bar: 5 } as Foo;
function f(x = {} as Foo) {}
```

#### `"never"`

Disallow type assertions on object literals entirely.

Examples of **incorrect** code with this option:

```ts
const x = { a: 1 } as Foo;
print({ a: 1 } as Foo);
```

Examples of **correct** code with this option:

```ts
const x: Foo = { a: 1 };
const x = { a: 1 } satisfies Foo;
```

## How to use

## Version

This rule was added in v1.44.0.

## References

---

---
url: /docs/guide/usage/linter/rules/typescript/consistent-type-definitions.md
---

### What it does

Enforce type definitions to consistently use either `interface` or `type`.

### Why is this bad?

TypeScript provides two common ways to define an object type: `interface` and `type`.
The two are generally very similar, and can often be used interchangeably.
Using the same type declaration style consistently helps with code readability.

### Examples

By default this rule enforces the use of `interface` for defining object types.

Examples of **incorrect** code for this rule:

```typescript
type T = { x: number };
```

Examples of **correct** code for this rule:

```typescript
type T = string;
type Foo = string | {};

interface T {
  x: number;
}
```

## Configuration

This rule accepts one of the following string values:

### `"interface"`

Prefer `interface` over `type` for object type definitions:

```typescript
interface T {
  x: number;
}
```

### `"type"`

Prefer `type` over `interface` for object type definitions:

```typescript
type T = { x: number };
```

## How to use

## Version

This rule was added in v0.2.17.

## References

---

---
url: /docs/guide/usage/linter/rules/typescript/consistent-type-exports.md
---

### What it does

Enforce using `export type` for exports that are only used as types.

### Why is this bad?

Mixing type-only exports with value exports without `export type` makes module intent
harder to read and can cause unnecessary runtime export surface.

### Examples

Examples of **incorrect** code for this rule:

```ts
type Foo = { bar: string };
export { Foo };

export { TypeOnly, value } from "./mod";
```

Examples of **correct** code for this rule:

```ts
type Foo = { bar: string };
export type { Foo };

export type { TypeOnly } from "./mod";
export { value } from "./mod";
```

## Configuration

This rule accepts a configuration object with the following properties:

### fixMixedExportsWithInlineTypeSpecifier

type: `boolean`

default: `false`

Enables an autofix strategy that rewrites mixed exports using inline `type` specifiers.

## How to use

## Version

This rule was added in v0.0.8.

## References

---

---
url: /docs/guide/usage/linter/rules/typescript/consistent-type-imports.md
---

### What it does

Enforce consistent usage of type imports by adding or removing the
`type` keyword from imports.

The `fixStyle` option controls where newly added `type` keywords are
placed when this rule auto-fixes imports. It does not enforce the
placement of `type` keywords that are already present in the code. To
enforce consistent placement, use
[`import/consistent-type-specifier-style`](https://oxc.rs/docs/guide/usage/linter/rules/import/consistent-type-specifier-style.html).

#### Ignored Files

This rule ignores `.astro`, `.svelte` and `.vue` files entirely. Since Oxlint does
not support parsing template syntax, this rule cannot tell if a variable
is used or unused in a Vue / Svelte / Astro file.

### Why is this bad?

Inconsistent usage of type imports can make the code harder to read and understand.

### Examples

Examples of **incorrect** code for this rule:

```ts
import { Foo } from "Foo";
type T = Foo;

type S = import("Foo");
```

Examples of **correct** code for this rule:

```ts
import type { Foo } from "Foo";
```

#### Examples with `"prefer": "type-imports"` (default)

Examples of **incorrect** code:

```ts
import { Foo } from "foo";
let foo: Foo;
```

Examples of **correct** code:

```ts
import type { Foo } from "foo";
let foo: Foo;
```

#### Examples with `"prefer": "no-type-imports"`

Examples of **incorrect** code:

```ts
import type { Foo } from "foo";
let foo: Foo;
```

Examples of **correct** code:

```ts
import { Foo } from "foo";
let foo: Foo;
```

#### Examples with `"fixStyle": "inline-type-imports"`

When fixing type imports, this option will use inline `type` modifiers:

```ts
// Before fixing
import { A, B } from "foo";
type T = A;
const b = B;

// After fixing
import { type A, B } from "foo";
type T = A;
const b = B;
```

#### Examples with `"disallowTypeAnnotations": false`

When set to `false`, allows `import()` type annotations:

```ts
type T = import("foo").Bar;
```

## Configuration

This rule accepts a configuration object with the following properties:

### disallowTypeAnnotations

type: `boolean`

default: `true`

Disallow using `import()` in type annotations, like `type T = import('foo')`

### fixStyle

type: `"separate-type-imports" | "inline-type-imports"`

default: `"separate-type-imports"`

Control how type imports are added when auto-fixing.

#### `"separate-type-imports"`

Will add the type keyword after the import keyword `import type { A } from '...'`

#### `"inline-type-imports"`

Will inline the type keyword `import { type A } from '...'` (only available in TypeScript 4.5+)

### prefer

type: `"type-imports" | "no-type-imports"`

default: `"type-imports"`

Control whether to enforce type imports or value imports.

#### `"type-imports"`

Enforces that you always use `import type Foo from '...'`, except when referenced by decorator metadata.

#### `"no-type-imports"`

Will enforce that you always use `import Foo from '...'`

## How to use

## Version

This rule was added in v0.5.2.

## References

---

---
url: /docs/guide/usage/linter/rules/typescript/dot-notation.md
---

### What it does

Enforce dot notation whenever property access can be written safely as `obj.prop`.

### Why is this bad?

Dot notation is generally more readable and concise than bracket notation for static
property names.

### Examples

Examples of **incorrect** code for this rule:

```ts
obj["name"];
foo["bar"];
```

Examples of **correct** code for this rule:

```ts
obj.name;
foo.bar;

obj[key];
obj["not-an-identifier"];
```

## Configuration

This rule accepts a configuration object with the following properties:

### allowIndexSignaturePropertyAccess

type: `boolean`

default: `false`

Allow bracket notation for properties covered by an index signature.

### allowKeywords

type: `boolean`

default: `true`

Allow bracket notation for ES3 keyword property names (for example `obj["class"]`).

### allowPattern

type: `string`

default: `""`

Regex pattern for property names that are allowed to use bracket notation.

### allowPrivateClassPropertyAccess

type: `boolean`

default: `false`

Allow bracket notation for private class members.

### allowProtectedClassPropertyAccess

type: `boolean`

default: `false`

Allow bracket notation for protected class members.

## How to use

## Version

This rule was added in v1.49.0.

## References

---

---
url: /docs/guide/usage/linter/rules/typescript/explicit-function-return-type.md
---

### What it does

This rule enforces that functions have an explicit return type annotation.

### Why is this bad?

Explicit return types make it clearer what type is returned by a function. Making the
type returned by a function obvious allows the reader to infer what the function does
and how it can be used from a quick glance.

Another benefit of explicit return types is the potential for a speed up of type
checking in large codebases with many large functions.

### Examples

Examples of **incorrect** code for this rule:

```ts
// Should indicate that no value is returned (void)
function test() {
  return;
}

// Should indicate that a number is returned
var fn = function () {
  return 1;
};

// Should indicate that a string is returned
var arrowFn = () => "test";

class Test {
  // Should indicate that no value is returned (void)
  method() {
    return;
  }
}
```

Examples of **correct** code for this rule:

```ts
// No return value should be expected (void)
function test(): void {
  return;
}

// A return value of type number
var fn = function (): number {
  return 1;
};

// A return value of type string
var arrowFn = (): string => "test";

class Test {
  // No return value should be expected (void)
  method(): void {
    return;
  }
}
```

## Configuration

This rule accepts a configuration object with the following properties:

### allowConciseArrowFunctionExpressionsStartingWithVoid

type: `boolean`

default: `false`

Whether to allow concise arrow functions that start with the `void` keyword.

### allowDirectConstAssertionInArrowFunctions

type: `boolean`

default: `true`

Whether to allow arrow functions that use `as const` assertion on their return value.

### allowExpressions

type: `boolean`

default: `false`

Whether to allow expressions as function return types. When `true`, allows functions that immediately return an expression without a return type annotation.

### allowFunctionsWithoutTypeParameters

type: `boolean`

default: `false`

Whether to allow functions that do not have generic type parameters.

### allowHigherOrderFunctions

type: `boolean`

default: `true`

Whether to allow higher-order functions (functions that return another function) without return type annotations.

### allowIIFEs

type: `boolean`

default: `false`

Whether to allow immediately invoked function expressions (IIFEs) without return type annotations.

### allowTypedFunctionExpressions

type: `boolean`

default: `true`

Whether to allow typed function expressions. When `true`, allows function expressions that are assigned to a typed variable or parameter.

### allowedNames

type: `string[]`

default: `[]`

Array of function names that are exempt from requiring return type annotations.

## How to use

## Version

This rule was added in v0.4.4.

## References

---

---
url: /docs/guide/usage/linter/rules/typescript/explicit-member-accessibility.md
---

### What it does

Require explicit accessibility modifiers on class properties and methods.

### Why is this bad?

TypeScript allows placing explicit `public`, `protected`, and `private`
accessibility modifiers in front of class members. The modifiers exist
solely in the type system and serve to describe who is allowed to access
those members.

Leaving off accessibility modifiers makes for less code to read and
write. Members are `public` by default. However, adding explicit
modifiers can make code more readable and explicit about who can use
which properties.

### Examples

#### `{ "accessibility": "explicit" }` (default)

Examples of **incorrect** code:

```ts
class Animal {
  constructor(name: string) {}
  animalName: string;
  get name(): string {
    return this.animalName;
  }
}
```

Examples of **correct** code:

```ts
class Animal {
  public constructor(name: string) {}
  private animalName: string;
  public get name(): string {
    return this.animalName;
  }
}
```

#### `{ "accessibility": "no-public" }`

Examples of **incorrect** code:

```ts
class Animal {
  public constructor(
    public breed: string,
    name: string,
  ) {}
  public animalName: string;
  public get name(): string {
    return this.animalName;
  }
}
```

Examples of **correct** code:

```ts
class Animal {
  constructor(
    protected breed: string,
    name: string,
  ) {}
  private animalName: string;
  get name(): string {
    return this.animalName;
  }
}
```

#### `{ "overrides": { "constructors": "no-public" } }`

Disallow the use of `public` on constructors while requiring explicit
modifiers everywhere else.

Examples of **incorrect** code:

```ts
class Animal {
  public constructor(protected animalName: string) {}
}
```

Examples of **correct** code:

```ts
class Animal {
  constructor(protected animalName: string) {}
  public get name(): string {
    return this.animalName;
  }
}
```

#### `{ "accessibility": "no-public", "overrides": { "properties": "explicit" } }`

Require explicit modifiers on properties while disallowing `public`
everywhere else.

Examples of **incorrect** code:

```ts
class Animal {
  legs: number;
  private hasFleas: boolean;
}
```

Examples of **correct** code:

```ts
class Animal {
  public legs: number;
  private hasFleas: boolean;
}
```

## Configuration

This rule accepts a configuration object with the following properties:

### accessibility

type: `"explicit" | "no-public" | "off"`

Which accessibility modifier is required to exist or not exist.

#### `"explicit"`

Always require an accessibility modifier.

#### `"no-public"`

Require an accessibility modifier except when public.

#### `"off"`

Never check whether there is an accessibility modifier.

### ignoredMethodNames

type: `string[]`

default: `[]`

Specific method names that may be ignored.

### overrides

type: `object`

Changes to required accessibility modifiers for specific kinds of class members.

#### overrides.accessors

type: `"explicit" | "no-public" | "off"`

Which member accessibility modifier requirements to apply for accessors (getters/setters).

#### overrides.constructors

type: `"explicit" | "no-public" | "off"`

Which member accessibility modifier requirements to apply for constructors.

#### overrides.methods

type: `"explicit" | "no-public" | "off"`

Which member accessibility modifier requirements to apply for methods.

#### overrides.parameterProperties

type: `"explicit" | "no-public" | "off"`

Which member accessibility modifier requirements to apply for parameter properties.

#### overrides.properties

type: `"explicit" | "no-public" | "off"`

Which member accessibility modifier requirements to apply for properties.

## How to use

## Version

This rule was added in v1.61.0.

## References

---

---
url: /docs/guide/usage/linter/rules/typescript/explicit-module-boundary-types.md
---

### What it does

Require explicit return and argument types on exported functions' and classes' public class methods.

### Why is this bad?

Explicit types for function return values and arguments makes it clear
to any calling code what is the module boundary's input and output.
Adding explicit type annotations for those types can help improve code
readability. It can also improve TypeScript type checking performance on
larger codebases.

### Examples

Examples of **incorrect** code for this rule:

```ts
// Should indicate that no value is returned (void)
export function test() {
  return;
}

// Should indicate that a string is returned
export var arrowFn = () => "test";

// All arguments should be typed
export var arrowFn = (arg): string => `test ${arg}`;
export var arrowFn = (arg: any): string => `test ${arg}`;

export class Test {
  // Should indicate that no value is returned (void)
  method() {
    return;
  }
}
```

Examples of **correct** code for this rule:

```ts
// A function with no return value (void)
export function test(): void {
  return;
}

// A return value of type string
export var arrowFn = (): string => "test";

// All arguments should be typed
export var arrowFn = (arg: string): string => `test ${arg}`;
export var arrowFn = (arg: unknown): string => `test ${arg}`;

export class Test {
  // A class method with no return value (void)
  method(): void {
    return;
  }
}

// The function does not apply because it is not an exported function.
function test() {
  return;
}
```

## Configuration

This rule accepts a configuration object with the following properties:

### allowArgumentsExplicitlyTypedAsAny

type: `boolean`

default: `false`

Whether to ignore arguments that are explicitly typed as `any`.

### allowDirectConstAssertionInArrowFunctions

type: `boolean`

default: `true`

Whether to ignore return type annotations on body-less arrow functions
that return an `as const` type assertion. You must still type the
parameters of the function.

### allowHigherOrderFunctions

type: `boolean`

default: `true`

Whether to ignore return type annotations on functions immediately
returning another function expression. You must still type the
parameters of the function.

### allowOverloadFunctions

type: `boolean`

default: `false`

Whether to ignore return type annotations on functions with overload
signatures.

### allowTypedFunctionExpressions

type: `boolean`

default: `true`

Whether to ignore type annotations on the variable of a function
expression.

### allowedNames

type: `string[]`

default: `[]`

An array of function/method names that will not have their arguments or
return values checked.

## How to use

## Version

This rule was added in v1.9.0.

## References

---

---
url: /docs/guide/usage/linter/rules/typescript/method-signature-style.md
---

### What it does

Enforce using a particular method signature syntax.

### Why is this bad?

TypeScript provides two ways to define an object/interface function property:

```ts
interface Example {
  // method shorthand syntax
  func(arg: string): number;

  // regular property with function type
  func: (arg: string) => number;
}
```

The two are very similar; most of the time it doesn't matter which one you use.
However, when TypeScript's `strictFunctionTypes` option is enabled, there is an important difference: methods are always bivariant in their arguments, while function properties are contravariant.
This means that switching from method syntax to property syntax (or vice versa) can cause TypeScript to report new type errors or stop reporting existing ones.

A good practice is to use the TypeScript's `strict` option (which implies `strictFunctionTypes`) which enables correct typechecking for function properties only (method signatures get old behavior).

TypeScript FAQ:

> A method and a function property of the same type behave differently.
> Methods are always bivariant in their argument, while function properties are contravariant in their argument under `strictFunctionTypes`.

See the reasoning behind that in the [TypeScript PR for the compiler option](https://github.com/microsoft/TypeScript/pull/18654).

### Examples

Examples of **incorrect** code for this rule with `property` option:

```ts
interface T1 {
  func(arg: string): number;
}
type T2 = {
  func(arg: boolean): void;
};
interface T3 {
  func(arg: number): void;
  func(arg: string): void;
  func(arg: boolean): void;
}
```

Examples of **correct** code for this rule with `property` option:

```ts
interface T1 {
  func: (arg: string) => number;
}
type T2 = {
  func: (arg: boolean) => void;
};
// this is equivalent to the overload
interface T3 {
  func: ((arg: number) => void) & ((arg: string) => void) & ((arg: boolean) => void);
}
```

Examples of **incorrect** code for this rule with `method` option:

```ts
interface T1 {
  func: (arg: string) => number;
}
type T2 = {
  func: (arg: boolean) => void;
};
```

Examples of **correct** code for this rule with `method` option:

```ts
interface T1 {
  func(arg: string): number;
}
type T2 = {
  func(arg: boolean): void;
};
```

## Configuration

This rule accepts one of the following string values:

### `"property"`

Enforce using property signature for functions. Use this to enforce maximum correctness together with TypeScript's strict mode.

### `"method"`

Enforce using method signature for functions. Use this if you aren't using TypeScript's strict mode and prefer this style.

## How to use

## Version

This rule was added in v1.68.0.

## References

---

---
url: /docs/guide/usage/linter/rules/typescript/no-array-delete.md
---

### What it does

This rule disallows using the delete operator on array values.

### Why is this bad?

When using the delete operator on an array, the element is not actually removed, but instead the array slot is turned into `undefined`. This is usually not the intended behavior. Instead, you should use methods like `Array.prototype.splice()` to properly remove elements from an array.

### Examples

Examples of **incorrect** code for this rule:

```ts
declare const arr: number[];
delete arr[0];
```

Examples of **correct** code for this rule:

```ts
declare const arr: number[];
arr.splice(0, 1);

// or with a filter
const filteredArr = arr.filter((_, index) => index !== 0);

// delete on object is allowed
declare const obj: { a?: number };
delete obj.a;
```

## How to use

## Version

This rule was added in v1.12.0.

## References

---

---
url: /docs/guide/usage/linter/rules/typescript/no-base-to-string.md
---

### What it does

This rule requires `toString()` and `toLocaleString()` calls to only be called on objects which provide useful information when stringified.

### Why is this bad?

JavaScript's `toString()` method returns '\[object Object]' on plain objects, which is not useful information. This rule prevents `toString()` and `toLocaleString()` from being called on objects that return less useful strings.

### Examples

Examples of **incorrect** code for this rule:

```ts
// These will evaluate to '[object Object]'
({}).toString();
({ foo: "bar" }).toString();
({ foo: "bar" }).toLocaleString();

// This will evaluate to 'Symbol()'
Symbol("foo").toString();
```

Examples of **correct** code for this rule:

```ts
const someString = "Hello world";
someString.toString();

const someNumber = 42;
someNumber.toString();

const someBoolean = true;
someBoolean.toString();

class CustomToString {
  toString() {
    return "CustomToString";
  }
}
new CustomToString().toString();
```

## Configuration

This rule accepts a configuration object with the following properties:

### checkUnknown

type: `boolean`

default: `false`

Whether to also check values of type `unknown`.
When `true`, calling toString on `unknown` values will be flagged.
Default is `false`.

### ignoredTypeNames

type: `string[]`

default: `["Error", "RegExp", "URL", "URLSearchParams"]`

A list of type names to ignore when checking for unsafe toString usage.
These types are considered safe to call toString on even if they don't
provide a custom implementation.

## How to use

## Version

This rule was added in v1.12.0.

## References

---

---
url: /docs/guide/usage/linter/rules/typescript/no-confusing-non-null-assertion.md
---

### What it does

Disallow non-null assertion in locations that may be confusing.

### Why is this bad?

Using a non-null assertion (`!`) next to an assignment or equality check (`=` or `==` or
`===`) creates code that is confusing as it looks similar to an inequality check (`!=` or
`!==`). Using one next to an `in` or `instanceof` check is also confusing because it may
look like the operator is negated.

### Examples

Examples of **incorrect** code for this rule:

```ts
a! == b; // a non-null assertions(`!`) and an equals test(`==`)
a !== b; // not equals test(`!==`)
a! === b; // a non-null assertions(`!`) and an triple equals test(`===`)
a! in b;
a! instanceof b;
```

Examples of **correct** code for this rule:

```ts
a == b;
a !== b;
a === b;
```

## How to use

## Version

This rule was added in v0.6.1.

## References

---

---
url: /docs/guide/usage/linter/rules/typescript/no-confusing-void-expression.md
---

### What it does

This rule forbids using void expressions in confusing locations such as arrow function returns.

### Why is this bad?

The void operator is useful when you want to execute an expression while evaluating to `undefined`. However, it can be confusing when used in places where the return value is meaningful, particularly in arrow functions and conditional expressions.

### Examples

Examples of **incorrect** code for this rule:

```ts
// arrow function returning void expression
const foo = () => void bar();

// conditional expression
const result = condition ? void foo() : bar();

// void in conditional
if (void foo()) {
  // ...
}
```

Examples of **correct** code for this rule:

```ts
// proper use of void
void foo();

// explicit return statement
const foo = () => {
  bar();
  return;
};

// statement expression
foo();

// IIFE with void
void (function () {
  console.log("immediately invoked");
})();
```

## Configuration

This rule accepts a configuration object with the following properties:

### ignoreArrowShorthand

type: `boolean`

default: `false`

Whether to ignore arrow function shorthand that returns void.
When true, allows expressions like `() => someVoidFunction()`.

### ignoreVoidOperator

type: `boolean`

default: `false`

Whether to ignore expressions using the void operator.
When true, allows `void someExpression`.

### ignoreVoidReturningFunctions

type: `boolean`

default: `false`

Whether to ignore calling functions that are declared to return void.
When true, allows expressions like `x = voidReturningFunction()`.

## How to use

## Version

This rule was added in v1.12.0.

## References

---

---
url: /docs/guide/usage/linter/rules/typescript/no-deprecated.md
---

### What it does

Disallow using code marked as `@deprecated`.

### Why is this bad?

The JSDoc `@deprecated` tag can be used to document some piece of code
being deprecated. It's best to avoid using code marked as deprecated.
This rule reports on any references to code marked as `@deprecated`.

TypeScript recognizes the `@deprecated` tag, allowing editors to visually
indicate deprecated code — usually with a strikethrough. However, TypeScript
doesn't report type errors for deprecated code on its own.

### Examples

Examples of **incorrect** code for this rule:

```ts
/** @deprecated Use apiV2 instead. */
declare function apiV1(): Promise<string>;
declare function apiV2(): Promise<string>;

await apiV1(); // Using deprecated function

import { parse } from "node:url";
// 'parse' is deprecated. Use the WHATWG URL API instead.
const url = parse("/foo");
```

Examples of **correct** code for this rule:

```ts
/** @deprecated Use apiV2 instead. */
declare function apiV1(): Promise<string>;
declare function apiV2(): Promise<string>;

await apiV2(); // Using non-deprecated function

// Modern Node.js API, uses `new URL()`
const url2 = new URL("/foo", "http://www.example.com");
```

## Configuration

This rule accepts a configuration object with the following properties:

### allow

type: `array`

default: `[]`

An array of type or value specifiers that are allowed to be used even if deprecated.
Use this to allow specific deprecated APIs that you intentionally want to continue using.

#### allow\[n]

type: `object | string`

Type or value specifier for matching specific declarations

Supports four types of specifiers:

1. **String specifier** (deprecated): Universal match by name

```json
"Promise"
```

2. **File specifier**: Match types/values declared in local files

```json
{ "from": "file", "name": "MyType" }
{ "from": "file", "name": ["Type1", "Type2"] }
{ "from": "file", "name": "MyType", "path": "./types.ts" }
```

3. **Lib specifier**: Match TypeScript built-in lib types

```json
{ "from": "lib", "name": "Promise" }
{ "from": "lib", "name": ["Promise", "PromiseLike"] }
```

4. **Package specifier**: Match types/values from npm packages

```json
{ "from": "package", "name": "Observable", "package": "rxjs" }
{ "from": "package", "name": ["Observable", "Subject"], "package": "rxjs" }
```

##### allow\[n].from

type: `"file"`

Must be "file"

##### allow\[n].name

type: `array | string`

The name(s) of the type or value to match

Name specifier that can be a single string or array of strings

###### allow\[n].name\[n]

type: `string`

##### allow\[n].path

type: `string`

Optional file path to specify where the types or values must be declared.
If omitted, all files will be matched.

## How to use

## Version

This rule was added in v1.26.0.

## References

---

---
url: /docs/guide/usage/linter/rules/typescript/no-duplicate-enum-values.md
---

### What it does

Disallow duplicate enum member values.

### Why is this bad?

Although TypeScript supports duplicate enum member values, people
usually expect members to have unique values within the same enum.
Duplicate values can lead to bugs that are hard to track down.

### Examples

This rule disallows defining an enum with multiple members initialized
to the same value. Members without initializers will not be checked.

Example of **incorrect** code:

```ts
enum E {
  A = 0,
  B = 0,
}
```

```ts
enum E {
  A = "A",
  B = "A",
}
```

Example of **correct** code:

```ts
enum E {
  A = 0,
  B = 1,
}
```

```ts
enum E {
  A = "A",
  B = "B",
}
```

```ts
enum E {
  A,
  B,
}
```

## How to use

## Version

This rule was added in v0.0.8.

## References

---

---
url: /docs/guide/usage/linter/rules/typescript/no-duplicate-type-constituents.md
---

### What it does

This rule disallows duplicate constituents of union or intersection types.

### Why is this bad?

Duplicate constituents in union and intersection types serve no purpose and can make code harder to read. They are likely a mistake.

### Examples

Examples of **incorrect** code for this rule:

```ts
type T1 = "A" | "A";

type T2 = A | A | B;

type T3 = { a: string } & { a: string };

type T4 = [A, A];

type T5 = "foo" | "bar" | "foo";
```

Examples of **correct** code for this rule:

```ts
type T1 = "A" | "B";

type T2 = A | B | C;

type T3 = { a: string } & { b: string };

type T4 = [A, B];

type T5 = "foo" | "bar" | "baz";
```

## Configuration

This rule accepts a configuration object with the following properties:

### ignoreIntersections

type: `boolean`

default: `false`

Whether to ignore duplicate types in intersection types.
When true, allows `type T = A & A`.

### ignoreUnions

type: `boolean`

default: `false`

Whether to ignore duplicate types in union types.
When true, allows `type T = A | A`.

## How to use

## Version

This rule was added in v1.12.0.

## References

---

---
url: /docs/guide/usage/linter/rules/typescript/no-dynamic-delete.md
---

### What it does

Disallow using the delete operator on computed key expressions.

### Why is this bad?

Deleting dynamically computed keys can be dangerous and in some cases not well optimized.
Using the delete operator on keys that aren't runtime constants could be a sign that you're using the wrong data structures.
Consider using a Map or Set if you’re using an object as a key-value collection.

### Examples

Examples of **incorrect** code for this rule:

```ts
const container: { [i: string]: 0 } = {};
delete container["aa" + "b"];
```

Examples of **correct** code for this rule:

```ts
const container: { [i: string]: 0 } = {};
delete container.aab;
```

## How to use

## Version

This rule was added in v0.5.2.

## References

---

---
url: /docs/guide/usage/linter/rules/typescript/no-empty-interface.md
---

### What it does

Disallow the declaration of empty interfaces.

### Why is this bad?

An empty interface in TypeScript does very little: any non-nullable value is assignable to {}.
Using an empty interface is often a sign of programmer error, such as misunderstanding the concept of {} or forgetting to fill in fields.
This rule aims to ensure that only meaningful interfaces are declared in the code.

### Examples

Examples of **incorrect** code for this rule:

```ts
interface Foo {}
interface Bar extends Foo {}
```

Examples of **correct** code for this rule:

```ts
interface Foo {
  member: string;
}
interface Bar extends Foo {
  member: string;
}
```

## Configuration

This rule accepts a configuration object with the following properties:

### allowSingleExtends

type: `boolean`

default: `false`

When set to `true`, allows empty interfaces that extend a single interface.

## How to use

## Version

This rule was added in v0.0.6.

## References

---

---
url: /docs/guide/usage/linter/rules/typescript/no-empty-object-type.md
---

### What it does

To avoid confusion around the `{}` type allowing any non-nullish value, this rule bans usage of the `{}` type. That includes interfaces and object type aliases with no fields.

### Why is this bad?

The `{}`, or "empty object" type in TypeScript is a common source of confusion for developers unfamiliar with TypeScript's structural typing. `{}` represents any non-nullish value, including literals like 0 and "".
Often, developers writing `{}` actually mean either:

* object: representing any object value
* unknown: representing any value at all, including `null` and `undefined`
  In other words, the "empty object" type {}\` really means "any value that is defined". That includes arrays, class instances, functions, and primitives such as string and symbol.

Note that this rule does not report on:

* `{}` as a type constituent in an intersection type (e.g. types like TypeScript's built-in `type NonNullable<T> = T & {}`), as this can be useful in type system operations.
* Interfaces that extend from multiple other interfaces.

### Examples

Examples of **incorrect** code for this rule:

```ts
let anyObject: {};
let anyValue: {};
interface AnyObjectA {}
interface AnyValueA {}
type AnyObjectB = {};
type AnyValueB = {};
```

Examples of **correct** code for this rule:

```ts
let anyObject: object;
let anyValue: unknown;
type AnyObjectA = object;
type AnyValueA = unknown;
type AnyObjectB = object;
type AnyValueB = unknown;
let objectWith: { property: boolean };
interface InterfaceWith {
  property: boolean;
}
type TypeWith = { property: boolean };
```

## Configuration

This rule accepts a configuration object with the following properties:

### allowInterfaces

type: `"never" | "always" | "with-single-extends"`

default: `"never"`

Whether to allow empty interfaces.

#### `"never"`

Never allow interfaces with no fields.

#### `"always"`

Always allow interfaces with no fields.

#### `"with-single-extends"`

Allow empty interfaces that `extend` from a single base interface.

Examples of **correct** code for this rule with `{ allowInterfaces: 'with-single-extends' }`:

```ts
interface Base {
  value: boolean;
}
interface Derived extends Base {}
```

### allowObjectTypes

type: `"never" | "always"`

default: `"never"`

Whether to allow empty object type literals.

#### `"never"`

Never allow object type literals with no fields.

#### `"always"`

Always allow object type literals with no fields.

### allowWithName

type: `string`

A stringified regular expression to allow interfaces and object type aliases with the configured name.

This can be useful if your existing code style includes a pattern of declaring empty types with `{}` instead of `object`.

Example of **incorrect** code for this rule with `{ allowWithName: 'Props$' }`:

```ts
interface InterfaceValue {}
type TypeValue = {};
```

Example of **correct** code for this rule with `{ allowWithName: 'Props$' }`:

```ts
interface InterfaceProps {}
type TypeProps = {};
```

## How to use

## Version

This rule was added in v0.12.0.

## References

---

---
url: /docs/guide/usage/linter/rules/typescript/no-explicit-any.md
---

### What it does

Disallows explicit use of the `any` type.

### Why is this bad?

The `any` type in TypeScript is a dangerous "escape hatch" from the type system. Using
`any` disables many type checking rules and is generally best used only as a last resort or
when prototyping code. This rule reports on explicit uses of the `any` keyword as a type
annotation.

> TypeScript's `--noImplicitAny` compiler option prevents an implied `any`, but doesn't
> prevent `any` from being explicitly used the way this rule does.

### Examples

Examples of **incorrect** code for this rule:

```typescript
const age: any = "seventeen";
const ages: any[] = ["seventeen"];
const ages: Array<any> = ["seventeen"];
function greet(): any {}
function greet(): any[] {}
function greet(): Array<any> {}
function greet(): Array<Array<any>> {}
function greet(param: Array<any>): string {}
function greet(param: Array<any>): Array<any> {}
```

Examples of **correct** code for this rule:

```typescript
const age: number = 17;
const ages: number[] = [17];
const ages: Array<number> = [17];
function greet(): string {}
function greet(): string[] {}
function greet(): Array<string> {}
function greet(): Array<Array<string>> {}
function greet(param: Array<string>): string {}
function greet(param: Array<string>): Array<string> {}
```

## Configuration

This rule accepts a configuration object with the following properties:

### fixToUnknown

type: `boolean`

default: `false`

Whether to enable auto-fixing in which the `any` type is converted to the `unknown` type.

### ignoreRestArgs

type: `boolean`

default: `false`

Whether to ignore rest parameter arrays.

## How to use

## Version

This rule was added in v0.0.13.

## References

---

---
url: /docs/guide/usage/linter/rules/typescript/no-extra-non-null-assertion.md
---

### What it does

Disallow extra non-null assertions.

### Why is this bad?

The `!` non-null assertion operator in TypeScript is used to assert that a value's type
does not include `null` or `undefined`. Using the operator any more than once on a single value
does nothing.

### Examples

Examples of **incorrect** code for this rule:

```ts
const foo: { bar: number } | null = null;
const bar = foo!!!.bar;
```

```ts
function foo(bar: number | undefined) {
  const bar: number = bar!!!;
}
```

```ts
function foo(bar?: { n: number }) {
  return bar!?.n;
}
```

Examples of **correct** code for this rule:

```ts
const foo: { bar: number } | null = null;
const bar = foo!.bar;
```

```ts
function foo(bar: number | undefined) {
  const bar: number = bar!;
}
```

```ts
function foo(bar?: { n: number }) {
  return bar?.n;
}
```

## How to use

## Version

This rule was added in v0.0.6.

## References

---

---
url: /docs/guide/usage/linter/rules/typescript/no-extraneous-class.md
---

### What it does

This rule reports when a class has no non-static members, such as for a
class used exclusively as a static namespace. This rule also reports
classes that have only a constructor and no fields. Those classes can
generally be replaced with a standalone function.

### Why is this bad?

Users who come from a OOP paradigm may wrap their utility functions in
an extra class, instead of putting them at the top level of an
ECMAScript module. Doing so is generally unnecessary in JavaScript and
TypeScript projects.

* Wrapper classes add extra cognitive complexity to code without adding
  any structural improvements
  * Whatever would be put on them, such as utility functions, are already
    organized by virtue of being in a module.
  * As an alternative, you can `import * as ...` the module to get all of them
    in a single object.
* IDEs can't provide as good suggestions for static class or namespace
  imported properties when you start typing property names
* It's more difficult to statically analyze code for unused variables,
  etc. when they're all on the class (see: [Finding dead code (and dead
  types) in TypeScript](https://effectivetypescript.com/2020/10/20/tsprune/)).

This rule also reports classes that have only a constructor and no
fields. Those classes can generally be replaced with a standalone
function.

### Examples

Examples of **incorrect** code for this rule:

```ts
class StaticConstants {
  static readonly version = 42;

  static isProduction() {
    return process.env.NODE_ENV === "production";
  }
}

class HelloWorldLogger {
  constructor() {
    console.log("Hello, world!");
  }
}

abstract class Foo {}
```

Examples of **correct** code for this rule:

```ts
const version = 42;
const isProduction = () => process.env.NODE_ENV === "production";
```

## Configuration

This rule accepts a configuration object with the following properties:

### allowConstructorOnly

type: `boolean`

default: `false`

Allow classes that only have a constructor.

### allowEmpty

type: `boolean`

default: `false`

Allow empty classes.

### allowStaticOnly

type: `boolean`

default: `false`

Allow classes with only static members.

### allowWithDecorator

type: `boolean`

default: `false`

Allow classes with decorators.

## How to use

## Version

This rule was added in v0.7.0.

## References

---

---
url: /docs/guide/usage/linter/rules/typescript/no-floating-promises.md
---

### What it does

This rule disallows "floating" Promises in TypeScript code, which is a Promise that is created without any code to handle its resolution or rejection.

This rule will report Promise-valued statements that are not treated in one of the following ways:

* Calling its `.then()` with two arguments
* Calling its `.catch()` with one argument
* `await`ing it
* `return`ing it
* `void`ing it

This rule also reports when an Array containing Promises is created and not properly handled. The main way to resolve this is by using one of the Promise concurrency methods to create a single Promise, then handling that according to the procedure above. These methods include:

* `Promise.all()`
* `Promise.allSettled()`
* `Promise.any()`
* `Promise.race()`

### Why is this bad?

Floating Promises can cause several issues, such as improperly sequenced operations, ignored Promise rejections, and more.

### Examples

Examples of **incorrect** code for this rule:

```ts
const promise = new Promise((resolve, reject) => resolve("value"));
promise;

async function returnsPromise() {
  return "value";
}
returnsPromise().then(() => {});

Promise.reject("value").catch();

Promise.reject("value").finally();

[1, 2, 3].map(async (x) => x + 1);
```

Examples of **correct** code for this rule:

```ts
const promise = new Promise((resolve, reject) => resolve("value"));
await promise;

async function returnsPromise() {
  return "value";
}

void returnsPromise();

returnsPromise().then(
  () => {},
  () => {},
);

Promise.reject("value").catch(() => {});

await Promise.reject("value").finally(() => {});

await Promise.all([1, 2, 3].map(async (x) => x + 1));
```

## Configuration

This rule accepts a configuration object with the following properties:

### allowForKnownSafeCalls

type: `array`

default: `[]`

Allows specific calls to be ignored, specified as type or value specifiers.

#### allowForKnownSafeCalls\[n]

type: `object | string`

Type or value specifier for matching specific declarations

Supports four types of specifiers:

1. **String specifier** (deprecated): Universal match by name

```json
"Promise"
```

2. **File specifier**: Match types/values declared in local files

```json
{ "from": "file", "name": "MyType" }
{ "from": "file", "name": ["Type1", "Type2"] }
{ "from": "file", "name": "MyType", "path": "./types.ts" }
```

3. **Lib specifier**: Match TypeScript built-in lib types

```json
{ "from": "lib", "name": "Promise" }
{ "from": "lib", "name": ["Promise", "PromiseLike"] }
```

4. **Package specifier**: Match types/values from npm packages

```json
{ "from": "package", "name": "Observable", "package": "rxjs" }
{ "from": "package", "name": ["Observable", "Subject"], "package": "rxjs" }
```

##### allowForKnownSafeCalls\[n].from

type: `"file"`

Must be "file"

##### allowForKnownSafeCalls\[n].name

type: `array | string`

The name(s) of the type or value to match

Name specifier that can be a single string or array of strings

###### allowForKnownSafeCalls\[n].name\[n]

type: `string`

##### allowForKnownSafeCalls\[n].path

type: `string`

Optional file path to specify where the types or values must be declared.
If omitted, all files will be matched.

### allowForKnownSafePromises

type: `array`

default: `[]`

Allows specific Promise types to be ignored, specified as type or value specifiers.

#### allowForKnownSafePromises\[n]

type: `object | string`

Type or value specifier for matching specific declarations

Supports four types of specifiers:

1. **String specifier** (deprecated): Universal match by name

```json
"Promise"
```

2. **File specifier**: Match types/values declared in local files

```json
{ "from": "file", "name": "MyType" }
{ "from": "file", "name": ["Type1", "Type2"] }
{ "from": "file", "name": "MyType", "path": "./types.ts" }
```

3. **Lib specifier**: Match TypeScript built-in lib types

```json
{ "from": "lib", "name": "Promise" }
{ "from": "lib", "name": ["Promise", "PromiseLike"] }
```

4. **Package specifier**: Match types/values from npm packages

```json
{ "from": "package", "name": "Observable", "package": "rxjs" }
{ "from": "package", "name": ["Observable", "Subject"], "package": "rxjs" }
```

##### allowForKnownSafePromises\[n].from

type: `"file"`

Must be "file"

##### allowForKnownSafePromises\[n].name

type: `array | string`

The name(s) of the type or value to match

Name specifier that can be a single string or array of strings

###### allowForKnownSafePromises\[n].name\[n]

type: `string`

##### allowForKnownSafePromises\[n].path

type: `string`

Optional file path to specify where the types or values must be declared.
If omitted, all files will be matched.

### checkThenables

type: `boolean`

default: `false`

Check for thenable objects that are not necessarily Promises.

### ignoreIIFE

type: `boolean`

default: `false`

Ignore immediately invoked function expressions (IIFEs).

### ignoreVoid

type: `boolean`

default: `true`

Ignore Promises that are void expressions.

## How to use

## Version

This rule was added in v1.11.0.

## References

---

---
url: /docs/guide/usage/linter/rules/typescript/no-for-in-array.md
---

### What it does

This rule disallows iterating over an array with a for-in loop.

### Why is this bad?

A for-in loop iterates over the enumerable properties of an object, which includes the array indices, but also includes any enumerable properties added to the array prototype or the array instance. This is almost never what you want when iterating over an array.

### Examples

Examples of **incorrect** code for this rule:

```ts
const arr = [1, 2, 3];

for (const i in arr) {
  console.log(arr[i]);
}

for (const i in arr) {
  console.log(i, arr[i]);
}
```

Examples of **correct** code for this rule:

```ts
const arr = [1, 2, 3];

// Use for-of to iterate over array values
for (const value of arr) {
  console.log(value);
}

// Use regular for loop with index
for (let i = 0; i < arr.length; i++) {
  console.log(i, arr[i]);
}

// Use forEach
arr.forEach((value, index) => {
  console.log(index, value);
});

// for-in is fine for objects
const obj = { a: 1, b: 2 };
for (const key in obj) {
  console.log(key, obj[key]);
}
```

## How to use

## Version

This rule was added in v1.12.0.

## References

---

---
url: /docs/guide/usage/linter/rules/typescript/no-implied-eval.md
---

### What it does

This rule disallows the use of eval-like methods.

### Why is this bad?

It's considered a good practice to avoid using `eval()` in JavaScript. There are security and performance implications involved with doing so, which is why many linters recommend disallowing `eval()`. However, there are some other ways to pass a string and have it interpreted as JavaScript code that have similar concerns.

### Examples

Examples of **incorrect** code for this rule:

```ts
setTimeout('alert("Hi!");', 100);

setInterval('alert("Hi!");', 100);

setImmediate('alert("Hi!")');

window.setTimeout("count = 5", 10);

window.setInterval("foo = bar", 10);

const fn = new Function("a", "b", "return a + b");
```

Examples of **correct** code for this rule:

```ts
setTimeout(() => {
  alert("Hi!");
}, 100);

setInterval(() => {
  alert("Hi!");
}, 100);

setImmediate(() => {
  alert("Hi!");
});

const fn = (a: number, b: number) => a + b;
```

## How to use

## Version

This rule was added in v1.12.0.

## References

---

---
url: /docs/guide/usage/linter/rules/typescript/no-import-type-side-effects.md
---

### What it does

Enforce the use of top-level `import type` qualifier when an import only
has specifiers with inline type qualifiers.

### Why is this bad?

The `--verbatimModuleSyntax` compiler option causes TypeScript to do
simple and predictable transpilation on import declarations. Namely, it
completely removes import declarations with a top-level type qualifier,
and it removes any import specifiers with an inline type qualifier.

The latter behavior does have one potentially surprising effect in that
in certain cases TS can leave behind a "side effect" import at runtime:

```ts
import { type A, type B } from "mod";
```

is transpiled to

```ts
import {} from "mod";
// which is the same as
import "mod";
```

For the rare case of needing to import for side effects, this may be
desirable - but for most cases you will not want to leave behind an
unnecessary side effect import.

### Examples

Examples of **incorrect** code for this rule:

```ts
import { type A } from "mod";
import { type A as AA } from "mod";
import { type A, type B } from "mod";
import { type A as AA, type B as BB } from "mod";
```

Examples of **correct** code for this rule:

```ts
import type { A } from "mod";
import type { A as AA } from "mod";
import type { A, B } from "mod";
import type { A as AA, B as BB } from "mod";
```

## How to use

## Version

This rule was added in v0.5.0.

## References

---

---
url: /docs/guide/usage/linter/rules/typescript/no-inferrable-types.md
---

### What it does

Disallow explicit type declarations for variables or parameters initialized to a number, string, or boolean.

### Why is this bad?

Explicitly typing variables or parameters that are initialized to a literal value is unnecessary because TypeScript can infer the type from the value.

### Examples

Examples of **incorrect** code for this rule:

```ts
const a: number = 5;
const b: string = "foo";
const c: boolean = true;
const fn = (a: number = 5, b: boolean = true, c: string = "foo") => {};
```

Examples of **correct** code for this rule:

```ts
const a = 5;
const b = "foo";
const c = true;
const fn = (a = 5, b = true, c = "foo") => {};
```

## Configuration

This rule accepts a configuration object with the following properties:

### ignoreParameters

type: `boolean`

default: `false`

When set to `true`, ignores type annotations on function parameters.

### ignoreProperties

type: `boolean`

default: `false`

When set to `true`, ignores type annotations on class properties.

## How to use

## Version

This rule was added in v0.14.0.

## References

---

---
url: /docs/guide/usage/linter/rules/typescript/no-invalid-void-type.md
---

### What it does

Disallow `void` type usage outside return types and configured generic contexts.

### Why is this bad?

In TypeScript, `void` is primarily meaningful in return positions. Using `void` in other
type locations (parameters, properties, aliases, and most unions) is usually confusing and
often indicates a mistaken type design.

### Examples

Examples of **incorrect** code for this rule:

```ts
function takeVoid(arg: void) {}
type Alias = void;
type Union = string | void;
```

Examples of **correct** code for this rule:

```ts
function f(): void {}
type P = Promise<void>;
type U = void | never;
```

## Configuration

This rule accepts a configuration object with the following properties:

### allowAsThisParameter

type: `boolean`

default: `false`

Whether a `this` parameter of a function may be `void`.

### allowInGenericTypeArguments

type: `array | boolean`

#### allowInGenericTypeArguments\[n]

type: `string`

## How to use

## Version

This rule was added in v1.47.0.

## References

---

---
url: /docs/guide/usage/linter/rules/typescript/no-meaningless-void-operator.md
---

### What it does

This rule disallows the void operator when its argument is already of type void or `undefined`.

### Why is this bad?

The void operator is useful when you want to execute an expression and force it to evaluate to `undefined`. However, using void on expressions that are already of type void or `undefined` is meaningless and adds unnecessary complexity to the code.

### Examples

Examples of **incorrect** code for this rule:

```ts
function foo(): void {
  return;
}

void foo(); // meaningless, foo() already returns void

void undefined; // meaningless, undefined is already undefined

async function bar() {
  void (await somePromise); // meaningless if somePromise resolves to void
}
```

Examples of **correct** code for this rule:

```ts
function getValue(): number {
  return 42;
}

void getValue(); // meaningful, converts number to void

void console.log("hello"); // meaningful, console.log returns undefined but we want to be explicit

function processData() {
  // some processing
}

processData(); // no void needed since we don't care about return value
```

## Configuration

This rule accepts a configuration object with the following properties:

### checkNever

type: `boolean`

default: `false`

Whether to check `void` applied to expressions of type `never`.

## How to use

## Version

This rule was added in v1.12.0.

## References

---

---
url: /docs/guide/usage/linter/rules/typescript/no-misused-new.md
---

### What it does

Enforces valid definitions of `new` and `constructor`. This rule prevents classes from defining
a method named `new`, interfaces from defining a method named `constructor`, and interfaces
from defining a construct signature that returns the interface itself.

### Why is this bad?

JavaScript classes may define a constructor method that runs
when a class instance is newly created.

TypeScript allows interfaces that describe a static class object to
define a `new()` signature (though this is rarely used in real world code). That construct
signature should return the constructed instance type, not the interface for the constructor
object itself.
Developers new to JavaScript classes and/or TypeScript interfaces may
sometimes confuse when to use constructor or new.

### Examples

Examples of **incorrect** code for this rule:

```typescript
declare class C {
  new(): C;
}
```

```typescript
interface I {
  new (): I;
}
```

```typescript
interface I {
  constructor(): void;
}
```

Examples of **correct** code for this rule:

```typescript
declare class C {
  constructor();
}
```

```typescript
class C {}

interface I {
  new (): C;
}
```

## How to use

## Version

This rule was added in v0.0.7.

## References

---

---
url: /docs/guide/usage/linter/rules/typescript/no-misused-promises.md
---

### What it does

This rule forbids providing Promises to logical locations such as if statements in places where the TypeScript
compiler allows them but they are not handled properly. These situations can often arise due to a missing
`await` keyword or just a misunderstanding of the way async functions are handled/awaited.

### Why is this bad?

Misused promises can cause crashes or other unexpected behavior, unless there are possibly some global unhandled promise handlers registered.

### Examples

Examples of **incorrect** code for this rule:

```ts
// Promises in conditionals:
const promise = Promise.resolve("value");
if (promise) {
  // Do something
}

// Promises where `void` return was expected:
[1, 2, 3].forEach(async (value) => {
  await fetch(`/${value}`);
});

// Spreading Promises:
const getData = () => fetch("/");
console.log({ foo: 42, ...getData() });
```

Examples of **correct** code for this rule:

```ts
// Awaiting the Promise to get its value in a conditional:
const promise = Promise.resolve("value");
if (await promise) {
  // Do something
}

// Using a `for-of` with `await` inside (instead of `forEach`):
for (const value of [1, 2, 3]) {
  await fetch(`/${value}`);
}

// Spreading data returned from Promise, instead of the Promise itself:
const getData = () => fetch("/");
console.log({ foo: 42, ...(await getData()) });
```

## Configuration

This rule accepts a configuration object with the following properties:

### checksConditionals

type: `boolean`

default: `true`

Whether to check if Promises are used in conditionals.
When true, disallows using Promises in conditions where a boolean is expected.

### checksSpreads

type: `boolean`

default: `true`

Whether to check if Promises are used in spread syntax.
When true, disallows spreading Promise values.

### checksVoidReturn

type: `object | boolean`

#### checksVoidReturn.arguments

type: `boolean`

default: `true`

Whether to check Promise-returning functions passed as arguments to void-returning functions.

#### checksVoidReturn.attributes

type: `boolean`

default: `true`

Whether to check Promise-returning functions in JSX attributes expecting void.

#### checksVoidReturn.inheritedMethods

type: `boolean`

default: `true`

Whether to check Promise-returning methods that override void-returning inherited methods.

#### checksVoidReturn.properties

type: `boolean`

default: `true`

Whether to check Promise-returning functions assigned to object properties expecting void.

#### checksVoidReturn.returns

type: `boolean`

default: `true`

Whether to check Promise values returned from void-returning functions.

#### checksVoidReturn.variables

type: `boolean`

default: `true`

Whether to check Promise-returning functions assigned to variables typed as void-returning.

## How to use

## Version

This rule was added in v1.11.0.

## References

---

---
url: /docs/guide/usage/linter/rules/typescript/no-misused-spread.md
---

### What it does

This rule disallows spreading syntax in places where it doesn't make sense or could cause runtime errors.

### Why is this bad?

The spread operator can be misused in ways that might not be immediately obvious but can cause runtime errors or unexpected behavior. This rule helps catch common misuses.

### Examples

Examples of **incorrect** code for this rule:

```ts
// Spreading a non-iterable value in an array
const num = 42;
const arr = [...num]; // Runtime error: num is not iterable

// Spreading a Promise in an array
const promise = Promise.resolve([1, 2, 3]);
const arr2 = [...promise]; // Runtime error: Promise is not iterable

// Spreading non-object in object literal
const str = "hello";
const obj = { ...str }; // Creates { '0': 'h', '1': 'e', ... } which might be unexpected
```

Examples of **correct** code for this rule:

```ts
// Spreading arrays
const arr1 = [1, 2, 3];
const arr2 = [...arr1];

// Spreading objects
const obj1 = { a: 1, b: 2 };
const obj2 = { ...obj1 };

// Spreading resolved Promise
const promise = Promise.resolve([1, 2, 3]);
const arr3 = [...(await promise)];

// Using Array.from for non-iterables if needed
const str = "hello";
const arr4 = Array.from(str); // ['h', 'e', 'l', 'l', 'o']
```

## Configuration

This rule accepts a configuration object with the following properties:

### allow

type: `array`

default: `[]`

An array of type or value specifiers that are allowed to be spread
even if they would normally be flagged as misused.

#### allow\[n]

type: `object | string`

Type or value specifier for matching specific declarations

Supports four types of specifiers:

1. **String specifier** (deprecated): Universal match by name

```json
"Promise"
```

2. **File specifier**: Match types/values declared in local files

```json
{ "from": "file", "name": "MyType" }
{ "from": "file", "name": ["Type1", "Type2"] }
{ "from": "file", "name": "MyType", "path": "./types.ts" }
```

3. **Lib specifier**: Match TypeScript built-in lib types

```json
{ "from": "lib", "name": "Promise" }
{ "from": "lib", "name": ["Promise", "PromiseLike"] }
```

4. **Package specifier**: Match types/values from npm packages

```json
{ "from": "package", "name": "Observable", "package": "rxjs" }
{ "from": "package", "name": ["Observable", "Subject"], "package": "rxjs" }
```

##### allow\[n].from

type: `"file"`

Must be "file"

##### allow\[n].name

type: `array | string`

The name(s) of the type or value to match

Name specifier that can be a single string or array of strings

###### allow\[n].name\[n]

type: `string`

##### allow\[n].path

type: `string`

Optional file path to specify where the types or values must be declared.
If omitted, all files will be matched.

## How to use

## Version

This rule was added in v1.12.0.

## References

---

---
url: /docs/guide/usage/linter/rules/typescript/no-mixed-enums.md
---

### What it does

This rule disallows enums from having both string and numeric members.

### Why is this bad?

TypeScript enums can have string, numeric, or computed members. Having mixed string and numeric members in the same enum can lead to confusion and unexpected runtime behavior due to how TypeScript compiles enums.

### Examples

Examples of **incorrect** code for this rule:

```ts
enum Status {
  Open = 1,
  Closed = "closed",
}

enum Direction {
  Up = "up",
  Down = 2,
  Left = "left",
  Right = 4,
}
```

Examples of **correct** code for this rule:

```ts
// All numeric
enum Status {
  Open = 1,
  Closed = 2,
}

// All string
enum Direction {
  Up = "up",
  Down = "down",
  Left = "left",
  Right = "right",
}

// Auto-incremented numeric
enum Color {
  Red,
  Green,
  Blue,
}
```

## How to use

## Version

This rule was added in v1.12.0.

## References

---

---
url: /docs/guide/usage/linter/rules/typescript/no-namespace.md
---

### What it does

Disallow TypeScript namespaces.

### Why is this bad?

TypeScript historically allowed a form of code organization called "custom modules" (module Example {}),
later renamed to "namespaces" (namespace Example). Namespaces are an outdated way to organize TypeScript code.
ES2015 module syntax is now preferred (`import`/`export`).

### Examples

Examples of **incorrect** code for this rule:

```typescript
module foo {}
namespace foo {}
declare module foo {}
declare namespace foo {}
```

Examples of **correct** code for this rule:

```typescript
declare module "foo" {}
// anything inside a d.ts file
```

## Configuration

This rule accepts a configuration object with the following properties:

### allowDeclarations

type: `boolean`

default: `false`

Whether to allow declare with custom TypeScript namespaces.

Examples of **incorrect** code for this rule when `{ "allowDeclarations": true }`

```typescript
module foo {}
namespace foo {}
```

Examples of **correct** code for this rule when `{ "allowDeclarations": true }`

```typescript
declare module "foo" {}
declare module foo {}
declare namespace foo {}

declare global {
  namespace foo {}
}

declare module foo {
  namespace foo {}
}
```

Examples of **incorrect** code for this rule when `{ "allowDeclarations": false }`

```typescript
module foo {}
namespace foo {}
declare module foo {}
declare namespace foo {}
```

Examples of **correct** code for this rule when `{ "allowDeclarations": false }`

```typescript
declare module "foo" {}
```

### allowDefinitionFiles

type: `boolean`

default: `true`

Examples of **incorrect** code for this rule when `{ "allowDefinitionFiles": true }`

```typescript
// if outside a d.ts file
module foo {}
namespace foo {}

// if outside a d.ts file
module foo {}
namespace foo {}
declare module foo {}
declare namespace foo {}
```

Examples of **correct** code for this rule when `{ "allowDefinitionFiles": true }`

```typescript
declare module "foo" {}
// anything inside a d.ts file
```

## How to use

## Version

This rule was added in v0.0.8.

## References

---

---
url: >-
  /docs/guide/usage/linter/rules/typescript/no-non-null-asserted-nullish-coalescing.md
---

### What it does

Disallow non-null assertions in the left operand of a nullish coalescing operator.

### Why is this bad?

The ?? nullish coalescing runtime operator allows providing a default value when dealing
with `null` or `undefined`. Using a ! non-null assertion type operator in the left operand of
a nullish coalescing operator is redundant, and likely a sign of programmer error or
confusion over the two operators.

### Examples

Examples of **incorrect** code for this rule:

```ts
foo! ?? bar;
foo.bazz! ?? bar;
foo!.bazz! ?? bar;
foo()! ?? bar;

let x!: string;
x! ?? "";

let x: string;
x = foo();
x! ?? "";
```

Examples of **correct** code for this rule:

```ts
foo ?? bar;
foo ?? bar!;
foo!.bazz ?? bar;
foo!.bazz ?? bar!;
foo() ?? bar;
```

```ts
// This is considered correct code because there's no way for the user to satisfy it.
let x: string;
x! ?? "";
```

## How to use

## Version

This rule was added in v0.5.0.

## References

---

---
url: >-
  /docs/guide/usage/linter/rules/typescript/no-non-null-asserted-optional-chain.md
---

### What it does

Disallow non-null assertions after an optional chain expression.

### Why is this bad?

By design, optional chain expressions (`?.`) provide `undefined` as the expression's value, if the object being
accessed is `null` or `undefined`, instead of throwing an error. Using a non-null assertion (`!`) to assert the
result of an optional chain expression is contradictory and likely wrong, as it indicates the code is both expecting
the value to be potentially `null` or `undefined` and non-null at the same time.

In most cases, either:

1. The object is not nullable and did not need the `?.` for its property lookup
2. The non-null assertion is incorrect and introduces a type safety hole.

### Examples

Examples of **incorrect** code for this rule:

```ts
foo?.bar!;
foo?.bar()!;
```

Examples of **correct** code for this rule:

```ts
foo?.bar;
foo.bar!;
```

## How to use

## Version

This rule was added in v0.0.6.

## References

---

---
url: /docs/guide/usage/linter/rules/typescript/no-non-null-assertion.md
---

### What it does

Disallow non-null assertions using the `!` postfix operator.

### Why is this bad?

TypeScript's `!` non-null assertion operator asserts to the type system that an expression is non-nullable, as in not `null` or `undefined`. Using assertions to tell the type system new information is often a sign that code is not fully type-safe. It's generally better to structure program logic so that TypeScript understands when values may be nullable.

### Examples

Examples of **incorrect** code for this rule:

```ts
x!;
x!.y;
x.y!;
```

Examples of **correct** code for this rule:

```ts
x;
x?.y;
x.y;
```

## How to use

## Version

This rule was added in v0.5.0.

## References

---

---
url: /docs/guide/usage/linter/rules/typescript/no-redundant-type-constituents.md
---

### What it does

This rule disallows type constituents of unions and intersections that are redundant.

### Why is this bad?

Some constituents of union and intersection types can be redundant due to TypeScript's type system rules. These redundant constituents don't add any value and can make types harder to read and understand.

### Examples

Examples of **incorrect** code for this rule:

```ts
// unknown is redundant in unions
type T1 = string | unknown;

// any is redundant in unions
type T2 = string | any;

// never is redundant in unions
type T3 = string | never;

// Literal types that are wider than other types
type T4 = string | "hello";

// Object types that are subsets
type T5 = { a: string } | { a: string; b: number };
```

Examples of **correct** code for this rule:

```ts
type T1 = string | number;

type T2 = "hello" | "world";

type T3 = { a: string } | { b: number };

// unknown in intersections is meaningful
type T4 = string & unknown;

// never in intersections is meaningful
type T5 = string & never;
```

## How to use

## Version

This rule was added in v1.12.0.

## References

---

---
url: /docs/guide/usage/linter/rules/typescript/no-require-imports.md
---

### What it does

Forbids the use of CommonJS `require` calls.

### Why is this bad?

`require` imports, while functional in Node.js and older JavaScript environments, are generally
considered less desirable than ES modules (`import`) for several key reasons in modern JavaScript development:

1. **Static vs. Dynamic**: `require` is a **runtime** function. It executes when the code runs, which means errors related to missing modules or incorrect paths are only discovered during runtime. ES modules (`import`) are static imports. Their resolution and potential errors are checked during the compilation or bundling process, making them easier to catch during development.

2. **Code Organization and Readability**: `require` statements are scattered throughout the code, potentially making it harder to quickly identify the dependencies of a given module. `import` statements are typically grouped at the top of a file, improving code organization and readability.

3. **Tree Shaking and Optimization**: Modern bundlers like Webpack and Rollup use tree-shaking to remove unused code from the final bundle. Tree-shaking works significantly better with ES modules because their dependencies are declared statically and explicitly. `require` makes it harder for bundlers to accurately identify and remove unused code, resulting in larger bundle sizes and slower load times.

4. **Cyclic Dependencies**: Handling cyclic dependencies (where module A imports B, and B imports A) is significantly more challenging with `require`. ES modules, through their declarative nature and the use of dynamic imports (`import()`), provide better mechanisms to handle cyclic imports and manage asynchronous loading.

5. **Maintainability and Refactoring**: Changing module names or paths is simpler with ES modules because the changes are declared directly and the compiler or bundler catches any errors. With `require`, you might have to track down all instances of a specific `require` statement for a particular module, making refactoring more error-prone.

6. Modern JavaScript Standards: import is the standard way to import modules in modern JavaScript, aligned with current best practices and language specifications. Using require necessitates additional build steps or tools to translate it to a format that the browser or modern JavaScript environments can understand.

7. Error Handling: ES modules provide a more structured way to handle errors during module loading using `try...catch` blocks with dynamic imports, enhancing error management. `require` errors can be less predictable.

In summary, while `require` works, the benefits of ES modules in terms of static analysis, better bundling, improved code organization, and easier maintainability make it the preferred method for importing modules in modern JavaScript projects.

### Examples

Examples of **incorrect** code for this rule:

```ts
const lib1 = require("lib1");
const { lib2 } = require("lib2");
import lib3 = require("lib3");
```

Examples of **correct** code for this rule:

```ts
import * as lib1 from "lib1";
import { lib2 } from "lib2";
import * as lib3 from "lib3";
```

## Configuration

This rule accepts a configuration object with the following properties:

### allow

type: `string[]`

These strings will be compiled into regular expressions with the u flag and be used to test against the imported path.
A common use case is to allow importing `package.json`. This is because `package.json` commonly lives outside of the TS root directory,
so statically importing it would lead to root directory conflicts, especially with `resolveJsonModule` enabled.
You can also use it to allow importing any JSON if your environment doesn't support JSON modules, or use it for other cases where `import` statements cannot work.

With `{ allow: ['/package\\.json$'] }`:

Examples of **correct** code for this rule:

```ts
console.log(require("../package.json").version);
```

### allowAsImport

type: `boolean`

default: `false`

When set to `true`, `import ... = require(...)` declarations won't be reported.
This is useful if you use certain module options that require strict CommonJS interop semantics.

When set to `true`:

Examples of **incorrect** code for this rule:

```ts
var foo = require("foo");
const foo = require("foo");
let foo = require("foo");
```

Examples of **correct** code for this rule:

```ts
import foo = require("foo");
import foo from "foo";
```

## How to use

## Version

This rule was added in v0.13.0.

## References

---

---
url: /docs/guide/usage/linter/rules/typescript/no-restricted-types.md
---

### What it does

Disallow certain types from being used.

### Why is this bad?

Some built-in types have aliases, while some types are considered dangerous or harmful.
It's often a good idea to ban certain types to help with consistency and safety.

### Examples

Given `{ "types": { "Foo": { "message": "Use Bar instead", "fixWith": "Bar" } } }`:

Examples of **incorrect** code for this rule:

```ts
let value: Foo;
```

Examples of **correct** code for this rule:

```ts
let value: Bar;
```

Other examples of configuration option setups for this rule:

* Banning the `Foo` type with just a message, no fixes or suggestions:
  `{ "types": { "Foo": "Use `OtherType` instead." } }`

* Banning `Bar` type with suggestion:
  `{ "types": { "Bar": { "message": "Avoid using `Bar`.", "suggest": "BazQux" } } }`

* Banning `Object` type with a generic message:
  `{ "types": { "Object": true } }`

## Configuration

This rule accepts a configuration object with the following properties:

### types

type: `object`

default: `{}`

A mapping of type names to ban configurations.

## How to use

## Version

This rule was added in v1.31.0.

## References

---

---
url: /docs/guide/usage/linter/rules/typescript/no-this-alias.md
---

### What it does

Disallow aliasing of `this`.

### Why is this bad?

Assigning a variable to `this` instead of properly using
arrow lambdas may be a symptom of pre-ES2015 practices or not managing scope well.

### Examples

Examples of **incorrect** code for this rule:

```js
const self = this;

setTimeout(function () {
  self.doWork();
});
```

Examples of **correct** code for this rule:

```js
setTimeout(() => {
  this.doWork();
});
```

## Configuration

This rule accepts a configuration object with the following properties:

### allowDestructuring

type: `boolean`

default: `true`

Whether to allow destructuring of `this` to local variables.

### allowedNames

type: `string[]`

default: `[]`

An array of variable names that are allowed to alias `this`.

## How to use

## Version

This rule was added in v0.0.7.

## References

---

---
url: >-
  /docs/guide/usage/linter/rules/typescript/no-unnecessary-boolean-literal-compare.md
---

### What it does

This rule disallows unnecessary equality comparisons with boolean literals.

### Why is this bad?

Comparing boolean values to boolean literals is unnecessary when the comparison can be eliminated. These comparisons make code more verbose without adding value.

### Examples

Examples of **incorrect** code for this rule:

```ts
declare const someCondition: boolean;

if (someCondition === true) {
  // ...
}

if (someCondition === false) {
  // ...
}

if (someCondition !== true) {
  // ...
}

if (someCondition !== false) {
  // ...
}

const result = someCondition == true;
```

Examples of **correct** code for this rule:

```ts
declare const someCondition: boolean;

if (someCondition) {
  // ...
}

if (!someCondition) {
  // ...
}

// Comparisons with non-boolean types are allowed
declare const someValue: unknown;
if (someValue === true) {
  // ...
}
```

## Configuration

This rule accepts a configuration object with the following properties:

### allowComparingNullableBooleansToFalse

type: `boolean`

default: `true`

Whether to allow comparing nullable boolean expressions to `false`.
When false, `x === false` where x is `boolean | null` will be flagged.

### allowComparingNullableBooleansToTrue

type: `boolean`

default: `true`

Whether to allow comparing nullable boolean expressions to `true`.
When false, `x === true` where x is `boolean | null` will be flagged.

## How to use

## Version

This rule was added in v1.12.0.

## References

---

---
url: /docs/guide/usage/linter/rules/typescript/no-unnecessary-condition.md
---

### What it does

Disallow conditions that are always truthy, always falsy, or always nullish
based on TypeScript's type information.

### Why is this bad?

Conditions with no possible runtime variation make code harder to read and can
hide logic errors. They often leave dead branches and suggest that the declared
types do not match the intended behavior.

### Examples

Examples of **incorrect** code for this rule:

```ts
declare const value: null;
if (value) {
  doWork();
}

const items: string[] = [];
if (items) {
  doWork();
}

declare const status: "ready";
if (!status) {
  reportError();
}
```

Examples of **correct** code for this rule:

```ts
declare const maybeUser: User | undefined;
if (maybeUser) {
  doWork(maybeUser);
}

const items: string[] = [];
if (items.length > 0) {
  doWork();
}

declare const status: "ready" | "";
if (!status) {
  reportError();
}
```

## Configuration

This rule accepts a configuration object with the following properties:

### allowConstantLoopConditions

type: `boolean | "never" | "always" | "only-allowed-literals"`

Represents the different ways `allowConstantLoopConditions` can be specified in JSON.
Can be:

* `true` or `false`
* A string enum (`"never"`, `"always"`, `"only-allowed-literals"`)

### checkTypePredicates

type: `boolean`

default: `false`

Whether to check arguments passed to type predicate and assertion functions.

When enabled, the rule reports a call if the argument already satisfies the predicate or
if an assertion function receives an argument that is always truthy or always falsy.

For example, `narrow(value)` is unnecessary because `value` already has type `true`:

```ts
declare const narrow: (value: unknown) => value is true;
const value = true;
if (narrow(value)) {
  // ...
}
```

## How to use

## Version

This rule was added in v1.48.0.

## References

---

---
url: >-
  /docs/guide/usage/linter/rules/typescript/no-unnecessary-parameter-property-assignment.md
---

### What it does

Prevents unnecessary assignment of parameter properties.

### Why is this bad?

Constructor parameters marked with one of the visibility modifiers
public, private, protected, or readonly are automatically initialized.
Providing an explicit assignment is unnecessary and can be removed.

### Examples

Examples of **incorrect** code for this rule:

```js
class Foo {
  constructor(public name: unknown) {
    this.name = name;
  }
}
```

Examples of **correct** code for this rule:

```js
class Foo {
  constructor(public name: unknown) {}
}
```

## How to use

## Version

This rule was added in v0.15.13.

## References

---

---
url: /docs/guide/usage/linter/rules/typescript/no-unnecessary-qualifier.md
---

### What it does

Disallow namespace qualifiers when the referenced name is already in scope.

### Why is this bad?

Redundant qualifiers add noise and make type references harder to read.

### Examples

Examples of **incorrect** code for this rule:

```ts
namespace A {
  export type B = number;
  const value: A.B = 1;
}
```

Examples of **correct** code for this rule:

```ts
namespace A {
  export type B = number;
  const value: B = 1;
}
```

## How to use

## Version

This rule was added in v1.49.0.

## References

---

---
url: >-
  /docs/guide/usage/linter/rules/typescript/no-unnecessary-template-expression.md
---

### What it does

Disallows unnecessary template expressions (interpolations) that can be simplified.

### Why is this bad?

Template literals with substitution expressions that are unnecessary add complexity
without providing any benefit. Static string literal expressions or expressions that
are already strings can be simplified.

Note: This rule does not flag template literals without substitution expressions.
For example, `` `hello` `` is allowed even though it could be written as `'hello'`.

### Examples

Examples of **incorrect** code for this rule:

```ts
// Static values can be incorporated into the surrounding template
const ab1 = `${"a"}${"b"}`;
const ab2 = `a${"b"}`;

const stringWithNumber = `${"1 + 1 = "}${2}`;
const stringWithBoolean = `${"true is "}${true}`;

// Expressions that are already strings can be rewritten without a template
const text = "a";
const wrappedText = `${text}`;

declare const intersectionWithString: string & { _brand: "test-brand" };
const wrappedIntersection = `${intersectionWithString}`;
```

Examples of **correct** code for this rule:

```ts
// Static values incorporated into the template
const ab1 = `ab`;

// Template with non-trivial interpolation
const name = "world";
const greeting = `Hello ${name}!`;

// Template with expression
const result = `Result: ${1 + 2}`;

// Simple strings don't need templates
const text = "a";
const wrappedText = text;

// Multi-line strings are fine
const multiline = `
  Hello
  world
`;
```

## How to use

## Version

This rule was added in v1.12.0.

## References

---

---
url: /docs/guide/usage/linter/rules/typescript/no-unnecessary-type-arguments.md
---

### What it does

This rule disallows type arguments that are identical to the default type parameter.

### Why is this bad?

Explicit type arguments that are the same as their default values are unnecessary and add visual noise to the code. TypeScript will infer these types automatically.

### Examples

Examples of **incorrect** code for this rule:

```ts
function identity<T = string>(arg: T): T {
  return arg;
}

// Unnecessary type argument - string is the default
const result = identity<string>("hello");

interface Container<T = number> {
  value: T;
}

// Unnecessary type argument - number is the default
const container: Container<number> = { value: 42 };

class MyClass<T = boolean> {
  constructor(public value: T) {}
}

// Unnecessary type argument - boolean is the default
const instance = new MyClass<boolean>(true);
```

Examples of **correct** code for this rule:

```ts
function identity<T = string>(arg: T): T {
  return arg;
}

// Using default type
const result1 = identity("hello");

// Using different type
const result2 = identity<number>(42);

interface Container<T = number> {
  value: T;
}

// Using default type
const container1: Container = { value: 42 };

// Using different type
const container2: Container<string> = { value: "hello" };
```

## How to use

## Version

This rule was added in v1.12.0.

## References

---

---
url: /docs/guide/usage/linter/rules/typescript/no-unnecessary-type-assertion.md
---

### What it does

This rule disallows type assertions that do not change the type of an expression.

### Why is this bad?

Type assertions that don't actually change the type of an expression are unnecessary and can be safely removed. They add visual noise without providing any benefit and may indicate confusion about TypeScript's type system.

### Examples

Examples of **incorrect** code for this rule:

```ts
const str: string = "hello";
const redundant = str as string; // unnecessary, str is already string

function getString(): string {
  return "hello";
}
const result = getString() as string; // unnecessary, getString() already returns string

const num = 42;
const alsoRedundant = num as 42; // unnecessary if TypeScript can infer literal type

// Unnecessary assertion to wider type
const literal = "hello" as string;
```

Examples of **correct** code for this rule:

```ts
const unknown: unknown = "hello";
const str = unknown as string; // necessary to narrow type

const element = document.getElementById("myElement") as HTMLInputElement; // necessary for specific element type

const obj = { name: "John" };
const name = obj.name as const; // necessary for literal type

// No assertion needed
const str2: string = "hello";
const num: number = 42;
```

## Configuration

This rule accepts a configuration object with the following properties:

### checkLiteralConstAssertions

type: `boolean`

default: `false`

Whether to check literal const assertions like `'foo' as const`.
When `false` (default), const assertions on literal types are not flagged.
When `true`, these will be reported as unnecessary since the type is already a literal.

### typesToIgnore

type: `string[]`

default: `[]`

A list of type names to ignore when checking for unnecessary assertions.
Type assertions to these types will not be flagged even if they appear unnecessary.
Example: `["Foo", "Bar"]` to allow `x as Foo` or `x as Bar`.

## How to use

## Version

This rule was added in v1.12.0.

## References

---

---
url: /docs/guide/usage/linter/rules/typescript/no-unnecessary-type-constraint.md
---

### What it does

Disallow unnecessary constraints on generic types.

### Why is this bad?

Generic type parameters (`<T>`) in TypeScript may be "constrained" with an `extends`
keyword. When no `extends` is provided, type parameters default a constraint to `unknown`.
It is therefore redundant to `extend` from `any` or `unknown`.

### Examples

Examples of **incorrect** code for this rule:

```typescript
interface FooAny<T extends any> {}
interface FooUnknown<T extends unknown> {}

type BarAny<T extends any> = {};
type BarUnknown<T extends unknown> = {};

const QuuxAny = <T extends any>() => {};

function QuuzAny<T extends any>() {}
```

```typescript
class BazAny<T extends any> {
  quxAny<U extends any>() {}
}
```

Examples of **correct** code for this rule:

```typescript
interface Foo<T> {}

type Bar<T> = {};

const Quux = <T>() => {};

function Quuz<T>() {}
```

```typescript
class Baz<T> {
  qux<U>() {}
}
```

## How to use

## Version

This rule was added in v0.0.6.

## References

---

---
url: /docs/guide/usage/linter/rules/typescript/no-unnecessary-type-conversion.md
---

### What it does

Disallow unnecessary type conversion expressions.

### Why is this bad?

Type conversions that do not change a value's type or runtime behavior
add noise and can obscure intent.

### Examples

Examples of **incorrect** code for this rule:

```ts
const value = String("asdf");
```

Examples of **correct** code for this rule:

```ts
const value = "asdf";
```

## How to use

## Version

This rule was added in v1.49.0.

## References

---

---
url: /docs/guide/usage/linter/rules/typescript/no-unnecessary-type-parameters.md
---

### What it does

Disallow type parameters that are declared but not meaningfully used.

### Why is this bad?

Unnecessary type parameters make signatures noisier and harder to understand, and they
often hide opportunities to simplify APIs.

### Examples

Examples of **incorrect** code for this rule:

```ts
function parseYAML<T>(input: string): T {
  return input as any as T;
}
```

Examples of **correct** code for this rule:

```ts
function parseYAML(input: string): unknown {
  return input;
}

function identity<T>(value: T): T {
  return value;
}
```

## How to use

## Version

This rule was added in v1.49.0.

## References

---

---
url: /docs/guide/usage/linter/rules/typescript/no-unsafe-argument.md
---

### What it does

This rule disallows calling a function with an argument which is typed as `any`.

### Why is this bad?

The `any` type in TypeScript is a dangerous "escape hatch" from the type system. Using `any` disables most type checking rules and is generally unsafe. When you pass a value typed as `any` to a function, you lose type safety for that function call.

### Examples

Examples of **incorrect** code for this rule:

```ts
declare const anyValue: any;

function takesString(str: string): void {
  console.log(str.length);
}

takesString(anyValue); // unsafe

declare function takesNumber(num: number): number;
const result = takesNumber(anyValue); // unsafe
```

Examples of **correct** code for this rule:

```ts
declare const stringValue: string;
declare const numberValue: number;
declare const unknownValue: unknown;

function takesString(str: string): void {
  console.log(str.length);
}

takesString(stringValue); // safe

// Type guard to safely use unknown
if (typeof unknownValue === "string") {
  takesString(unknownValue); // safe after type guard
}

// Type assertion if you're sure about the type
takesString(unknownValue as string); // explicitly unsafe, but intentional
```

## How to use

## Version

This rule was added in v1.12.0.

## References

---

---
url: /docs/guide/usage/linter/rules/typescript/no-unsafe-assignment.md
---

### What it does

This rule disallows assigning a value with type `any` to variables and properties.

### Why is this bad?

The `any` type in TypeScript disables type checking and can lead to runtime errors. When you assign an `any` value to a typed variable, you're essentially bypassing TypeScript's type safety without any guarantees about the actual value.

### Examples

Examples of **incorrect** code for this rule:

```ts
declare const anyValue: any;

const str: string = anyValue; // unsafe assignment

let num: number;
num = anyValue; // unsafe assignment

const obj = {
  prop: anyValue as any, // unsafe assignment
};

interface User {
  name: string;
  age: number;
}

const user: User = anyValue; // unsafe assignment
```

Examples of **correct** code for this rule:

```ts
declare const stringValue: string;
declare const numberValue: number;
declare const unknownValue: unknown;

const str: string = stringValue; // safe

let num: number;
num = numberValue; // safe

// Use type guards with unknown
if (typeof unknownValue === "string") {
  const str2: string = unknownValue; // safe after type guard
}

// Explicit any assignment (still not recommended, but intentional)
const anything: any = unknownValue;
```

## How to use

## Version

This rule was added in v1.12.0.

## References

---

---
url: /docs/guide/usage/linter/rules/typescript/no-unsafe-call.md
---

### What it does

This rule disallows calling a value with type `any`.

### Why is this bad?

The `any` type in TypeScript disables type checking. When you call a value typed as `any`, TypeScript cannot verify that it's actually a function, what parameters it expects, or what it returns. This can lead to runtime errors.

### Examples

Examples of **incorrect** code for this rule:

```ts
declare const anyValue: any;

anyValue(); // unsafe call

anyValue(1, 2, 3); // unsafe call

const result = anyValue("hello"); // unsafe call

// Chained unsafe calls
anyValue().then().catch(); // unsafe
```

Examples of **correct** code for this rule:

```ts
declare const fn: () => void;
declare const fnWithParams: (a: number, b: string) => boolean;
declare const unknownValue: unknown;

fn(); // safe

const result = fnWithParams(1, "hello"); // safe

// Type guard for unknown
if (typeof unknownValue === "function") {
  unknownValue(); // safe after type guard
}

// Explicit type assertion if you're certain
(anyValue as () => void)(); // explicitly unsafe but intentional
```

## How to use

## Version

This rule was added in v1.12.0.

## References

---

---
url: /docs/guide/usage/linter/rules/typescript/no-unsafe-declaration-merging.md
---

### What it does

Disallow unsafe declaration merging.

### Why is this bad?

Declaration merging between classes and interfaces is unsafe.
The TypeScript compiler doesn't check whether properties are initialized, which can lead to TypeScript not detecting code that will cause runtime errors.

### Examples

Examples of **incorrect** code for this rule:

```ts
interface Foo {}
class Foo {}
```

Examples of **correct** code for this rule:

```ts
interface Foo {}
class Bar {}
```

## How to use

## Version

This rule was added in v0.0.11.

## References

---

---
url: /docs/guide/usage/linter/rules/typescript/no-unsafe-enum-comparison.md
---

### What it does

This rule disallows comparing an enum value with a non-enum value.

### Why is this bad?

Enum values should only be compared with other values of the same enum type or their underlying literal values in a type-safe manner. Comparing enums with unrelated values can lead to unexpected behavior and defeats the purpose of using enums for type safety.

### Examples

Examples of **incorrect** code for this rule:

```ts
enum Status {
  Open = "open",
  Closed = "closed",
}

enum Color {
  Red = "red",
  Blue = "blue",
}

declare const status: Status;
declare const color: Color;
declare const str: string;

// Comparing enum with different enum
if (status === color) {
} // unsafe

// Comparing enum with string (unless it's a literal that matches)
if (status === str) {
} // unsafe

// Comparing with arbitrary value
if (status === "unknown") {
} // unsafe
```

Examples of **correct** code for this rule:

```ts
enum Status {
  Open = "open",
  Closed = "closed",
}

declare const status: Status;

// Comparing with same enum values
if (status === Status.Open) {
} // safe

// Comparing with the correct literal type
if (status === "open") {
} // safe

// Using enum methods
if (Object.values(Status).includes(someValue)) {
} // safe way to check
```

## How to use

## Version

This rule was added in v1.12.0.

## References

---

---
url: /docs/guide/usage/linter/rules/typescript/no-unsafe-function-type.md
---

### What it does

Disallow using the unsafe built-in Function type.

### Why is this bad?

TypeScript's built-in Function type allows being called with any number of arguments and returns type any. Function also allows classes or plain objects that happen to possess all properties of the Function class. It's generally better to specify function parameters and return types with the function type syntax.

### Examples

Examples of **incorrect** code for this rule:

```ts
let noParametersOrReturn: Function;
noParametersOrReturn = () => {};

let stringToNumber: Function;
stringToNumber = (text: string) => text.length;

let identity: Function;
identity = (value) => value;
```

Examples of **correct** code for this rule:

```ts
let noParametersOrReturn: () => void;
noParametersOrReturn = () => {};

let stringToNumber: (text: string) => number;
stringToNumber = (text) => text.length;

let identity: <T>(value: T) => T;
identity = (value) => value;
```

## How to use

## Version

This rule was added in v0.11.1.

## References

---

---
url: /docs/guide/usage/linter/rules/typescript/no-unsafe-member-access.md
---

### What it does

This rule disallows member access on a value with type `any`.

### Why is this bad?

The `any` type in TypeScript disables type checking. When you access a member (property or method) on a value typed as `any`, TypeScript cannot verify that the member exists or what type it has. This can lead to runtime errors.

### Examples

Examples of **incorrect** code for this rule:

```ts
declare const anyValue: any;

anyValue.foo; // unsafe member access

anyValue.bar.baz; // unsafe nested member access

anyValue["key"]; // unsafe computed member access

const result = anyValue.method(); // unsafe method access
```

Examples of **correct** code for this rule:

```ts
declare const obj: { foo: string; bar: { baz: number } };
declare const unknownValue: unknown;

obj.foo; // safe

obj.bar.baz; // safe

obj["foo"]; // safe

// Type guard for unknown
if (typeof unknownValue === "object" && unknownValue !== null && "foo" in unknownValue) {
  console.log(unknownValue.foo); // safe after type guard
}

// Explicit type assertion if needed
(anyValue as { foo: string }).foo; // explicitly unsafe but intentional
```

## Configuration

This rule accepts a configuration object with the following properties:

### allowOptionalChaining

type: `boolean`

default: `false`

Whether to allow `?.` optional chains on `any` values.
When `true`, optional chaining on `any` values will not be flagged.
Default is `false`.

## How to use

## Version

This rule was added in v1.12.0.

## References

---

---
url: /docs/guide/usage/linter/rules/typescript/no-unsafe-return.md
---

### What it does

This rule disallows returning a value with type `any` from a function.

### Why is this bad?

The `any` type in TypeScript disables type checking. When you return a value typed as `any` from a function, you're essentially passing the type-safety problem to the caller without providing any guarantees about what the function actually returns.

### Examples

Examples of **incorrect** code for this rule:

```ts
declare const anyValue: any;

function getString(): string {
  return anyValue; // unsafe return
}

const getNumber = (): number => anyValue; // unsafe return

function processData(): { name: string; age: number } {
  return anyValue; // unsafe return
}
```

Examples of **correct** code for this rule:

```ts
declare const stringValue: string;
declare const numberValue: number;
declare const unknownValue: unknown;

function getString(): string {
  return stringValue; // safe
}

const getNumber = (): number => numberValue; // safe

function processUnknown(): unknown {
  return unknownValue; // safe - explicitly returning unknown
}

// Type guard to safely return
function safeGetString(): string | null {
  if (typeof unknownValue === "string") {
    return unknownValue; // safe after type guard
  }
  return null;
}
```

## How to use

## Version

This rule was added in v1.12.0.

## References

---

---
url: /docs/guide/usage/linter/rules/typescript/no-unsafe-type-assertion.md
---

### What it does

Disallows unsafe type assertions that narrow a type.

### Why is this bad?

Type assertions that narrow a type bypass TypeScript's type-checking and can lead to
runtime errors. Type assertions that broaden a type are safe because TypeScript
essentially knows *less* about a type. Instead of using type assertions to narrow a
type, it's better to rely on type guards, which help avoid potential runtime errors
caused by unsafe type assertions.

### Examples

Examples of **incorrect** code for this rule:

```ts
function f() {
  return Math.random() < 0.5 ? 42 : "oops";
}
const z = f() as number;

const items = [1, "2", 3, "4"];
const number = items[0] as number;
```

Examples of **correct** code for this rule:

```ts
function f() {
  return Math.random() < 0.5 ? 42 : "oops";
}
const z = f() as number | string | boolean;

const items = [1, "2", 3, "4"];
const number = items[0] as number | string | undefined;
```

## How to use

## Version

This rule was added in v1.12.0.

## References

---

---
url: /docs/guide/usage/linter/rules/typescript/no-unsafe-unary-minus.md
---

### What it does

This rule disallows using the unary minus operator on a value which is not of type 'number' | 'bigint'.

### Why is this bad?

The unary minus operator should only be used on numeric values. Using it on other types can lead to unexpected behavior due to JavaScript's type coercion rules.

### Examples

Examples of **incorrect** code for this rule:

```ts
declare const value: any;
const result1 = -value; // unsafe on any

declare const str: string;
const result2 = -str; // unsafe on string

declare const bool: boolean;
const result3 = -bool; // unsafe on boolean

declare const obj: object;
const result4 = -obj; // unsafe on object

declare const arr: any[];
const result5 = -arr; // unsafe on array
```

Examples of **correct** code for this rule:

```ts
declare const num: number;
const result1 = -num; // safe

declare const bigint: bigint;
const result2 = -bigint; // safe

const literal = -42; // safe

const bigintLiteral = -42n; // safe

declare const union: number | bigint;
const result3 = -union; // safe

// Convert to number first if needed
declare const str: string;
const result4 = -Number(str); // safe conversion
```

## How to use

## Version

This rule was added in v1.12.0.

## References

---

---
url: /docs/guide/usage/linter/rules/typescript/no-useless-default-assignment.md
---

### What it does

Disallow default assignments that can never be used.

### Why is this bad?

A default assignment is redundant when the value can never be `undefined`.
This adds runtime logic and noise without changing behavior.

### Examples

Examples of **incorrect** code for this rule:

```ts
[1, 2, 3].map((a = 0) => a + 1);
```

Examples of **correct** code for this rule:

```ts
[1, 2, 3].map((a) => a + 1);
```

## How to use

## Version

This rule was added in v1.49.0.

## References

---

---
url: /docs/guide/usage/linter/rules/typescript/no-useless-empty-export.md
---

### What it does

Disallow empty exports that don't change anything in a module file.

### Why is this bad?

An empty `export {}` statement is sometimes useful in TypeScript code to
turn a file that would otherwise be a script file into a module file.
Per the [TypeScript Handbook Modules page](https://www.typescriptlang.org/docs/handbook/modules/introduction.html):

In TypeScript, just as in ECMAScript 2015, any file containing a
top-level import or export is considered a module. Conversely, a file
without any top-level import or export declarations is treated as a
script whose contents are available in the global scope (and therefore
to modules as well).

However, an `export {}` statement does nothing if there are any other
top-level import or export statements in a file.

This rule reports an `export {}` that doesn't do anything in a file
already using ES modules.

### Examples

Examples of **incorrect** code for this rule:

```ts
export const value = "Hello, world!";
export {};
```

Examples of **correct** code for this rule:

```ts
export const value = "Hello, world!";
```

## How to use

## Version

This rule was added in v0.4.4.

## References

---

---
url: /docs/guide/usage/linter/rules/typescript/no-var-requires.md
---

### What it does

Disallow `require` statements except in import statements.

**NOTE**: This rule is intentionally missing the `allow` option from the original typescript-eslint rule.
This rule is deprecated in the upstream plugin and the `typescript/no-require-imports` rule should be
used instead.

### Why is this bad?

In other words, the use of forms such as var foo = require("foo") are banned. Instead use ES module imports or import foo = require("foo") imports.

```typescript
var foo = require("foo");
const foo = require("foo");
let foo = require("foo");
```

## How to use

## Version

This rule was added in v0.0.7.

## References

---

---
url: /docs/guide/usage/linter/rules/typescript/no-wrapper-object-types.md
---

### What it does

Disallow the use of wrapper object types.

### Why is this bad?

Wrapper object types are types that are defined in the global scope and are not primitive types. These types are not recommended to be used in TypeScript code.

### Examples

Examples of **incorrect** code for this rule:

```ts
let myBigInt: BigInt;
let myBoolean: Boolean;
let myNumber: Number;
let myString: String;
let mySymbol: Symbol;

let myObject: Object = "allowed by TypeScript";
```

Examples of **correct** code for this rule:

```ts
let myBigint: bigint;
let myBoolean: boolean;
let myNumber: number;
let myString: string;
let mySymbol: symbol;

let myObject: object = "Type 'string' is not assignable to type 'object'.";
```

## How to use

## Version

This rule was added in v0.8.0.

## References

---

---
url: /docs/guide/usage/linter/rules/typescript/non-nullable-type-assertion-style.md
---

### What it does

This rule prefers a non-null assertion over an explicit type cast for non-nullable types.

### Why is this bad?

When you know that a value cannot be `null` or `undefined`, you can use either a non-null assertion (`!`) or a type assertion (`as Type`). The non-null assertion is more concise and clearly communicates the intent that you're asserting the value is not `null`/`undefined`.

### Examples

Examples of **incorrect** code for this rule:

```ts
declare const value: string | null;

// Type assertion when non-null assertion would be clearer
const result1 = value as string;

declare const maybe: number | undefined;
const result2 = maybe as number;

// In function calls
function takesString(s: string) {
  console.log(s);
}

takesString(value as string);
```

Examples of **correct** code for this rule:

```ts
declare const value: string | null;

// Non-null assertion for non-nullable types
const result1 = value!;

declare const maybe: number | undefined;
const result2 = maybe!;

// In function calls
function takesString(s: string) {
  console.log(s);
}

takesString(value!);

// Type assertion for actual type changes is still fine
declare const unknown: unknown;
const str = unknown as string; // This is a different type, not just removing null
```

## How to use

## Version

This rule was added in v1.12.0.

## References

---

---
url: /docs/guide/usage/linter/rules/typescript/only-throw-error.md
---

### What it does

This rule disallows throwing non-Error values.

### Why is this bad?

It's considered good practice to only throw Error objects (or subclasses of Error). This is because Error objects automatically capture a stack trace, which is useful for debugging. Additionally, some tools and environments expect thrown values to be Error objects.

### Examples

Examples of **incorrect** code for this rule:

```ts
throw "error"; // throwing string

throw 42; // throwing number

throw true; // throwing boolean

throw { message: "error" }; // throwing plain object

throw null; // throwing null

throw undefined; // throwing undefined

const error = "Something went wrong";
throw error; // throwing non-Error variable
```

Examples of **correct** code for this rule:

```ts
throw new Error("Something went wrong");

throw new TypeError("Invalid type");

throw new RangeError("Value out of range");

// Custom Error subclasses
class CustomError extends Error {
  constructor(message: string) {
    super(message);
    this.name = "CustomError";
  }
}
throw new CustomError("Custom error occurred");

// Variables that are Error objects
const error = new Error("Error message");
throw error;
```

## Configuration

This rule accepts a configuration object with the following properties:

### allow

type: `array`

default: `[]`

An array of type or value specifiers for additional types that are allowed to be thrown.
Use this to allow throwing custom error types.

#### allow\[n]

type: `object | string`

Type or value specifier for matching specific declarations

Supports four types of specifiers:

1. **String specifier** (deprecated): Universal match by name

```json
"Promise"
```

2. **File specifier**: Match types/values declared in local files

```json
{ "from": "file", "name": "MyType" }
{ "from": "file", "name": ["Type1", "Type2"] }
{ "from": "file", "name": "MyType", "path": "./types.ts" }
```

3. **Lib specifier**: Match TypeScript built-in lib types

```json
{ "from": "lib", "name": "Promise" }
{ "from": "lib", "name": ["Promise", "PromiseLike"] }
```

4. **Package specifier**: Match types/values from npm packages

```json
{ "from": "package", "name": "Observable", "package": "rxjs" }
{ "from": "package", "name": ["Observable", "Subject"], "package": "rxjs" }
```

##### allow\[n].from

type: `"file"`

Must be "file"

##### allow\[n].name

type: `array | string`

The name(s) of the type or value to match

Name specifier that can be a single string or array of strings

###### allow\[n].name\[n]

type: `string`

##### allow\[n].path

type: `string`

Optional file path to specify where the types or values must be declared.
If omitted, all files will be matched.

### allowRethrowing

type: `boolean`

default: `true`

Whether to allow rethrowing caught values that are not Error objects.

### allowThrowingAny

type: `boolean`

default: `true`

Whether to allow throwing values typed as `any`.

### allowThrowingUnknown

type: `boolean`

default: `true`

Whether to allow throwing values typed as `unknown`.

## How to use

## Version

This rule was added in v1.12.0.

## References

---

---
url: /docs/guide/usage/linter/rules/typescript/parameter-properties.md
---

### What it does

Requires or disallows parameter properties in class constructors.

### Why is this bad?

Mixing parameter properties and class property declarations can make
class style inconsistent and harder to maintain.

### Examples

#### `{ "prefer": "class-property" }` (default)

Examples of **incorrect** code for this rule:

```ts
class Foo {
  constructor(private name: string) {}
}
```

Examples of **correct** code for this rule:

```ts
class Foo {
  name: string;
  constructor(name: string) {
    this.name = name;
  }
}
```

#### `{ "prefer": "parameter-property" }`

Examples of **incorrect** code for this rule:

```ts
class Foo {
  name: string;
  constructor(name: string) {
    this.name = name;
  }
}
```

Examples of **correct** code for this rule:

```ts
class Foo {
  constructor(private name: string) {}
}
```

## Configuration

This rule accepts a configuration object with the following properties:

### allow

type: `array`

default: `[]`

Modifiers that are allowed to be used with parameter properties or class properties, depending on the `prefer` option.

#### allow\[n]

type: `"private" | "private readonly" | "protected" | "protected readonly" | "public" | "public readonly" | "readonly"`

### prefer

type: `"class-property" | "parameter-property"`

default: `"class-property"`

Whether to prefer parameter properties or class properties.

## How to use

## Version

This rule was added in v1.48.0.

## References

---

---
url: /docs/guide/usage/linter/rules/typescript/prefer-as-const.md
---

### What it does

Enforce the use of `as const` over literal types.

### Why is this bad?

There are two common ways to tell TypeScript that a literal value should be interpreted as
its literal type (e.g. `2`) rather than general primitive type (e.g. `number`);

`as const`: telling TypeScript to infer the literal type automatically
`as` with the literal type: explicitly telling the literal type to TypeScript

`as const` is generally preferred, as it doesn't require re-typing the literal value.
This rule reports when an `as` with an explicit literal type can be replaced with an `as const`.

### Examples

Examples of **incorrect** code for this rule:

```ts
let bar: 2 = 2;
let foo = { bar: "baz" as "baz" };
```

Examples of **correct** code for this rule:

```ts
let foo = "bar";
let foo = "bar" as const;
let foo: "bar" = "bar" as const;
let bar = "bar" as string;
let foo = { bar: "baz" };
```

## How to use

## Version

This rule was added in v0.0.8.

## References

---

---
url: /docs/guide/usage/linter/rules/typescript/prefer-enum-initializers.md
---

### What it does

Require each enum member value to be explicitly initialized.

### Why is this bad?

In projects where the value of `enum` members are important, allowing implicit values for enums can cause bugs if enums are modified over time.

### Examples

Examples of **incorrect** code for this rule:

```typescript
// wrong, the value of `Close` is not constant
enum Status {
  Open = 1,
  Close,
}
```

Examples of **correct** code for this rule:

```typescript
enum Status {
  Open = 1,
  Close = 2,
}
```

## How to use

## Version

This rule was added in v0.3.2.

## References

---

---
url: /docs/guide/usage/linter/rules/typescript/prefer-find.md
---

### What it does

Prefer `.find(...)` over `.filter(...)[0]` for retrieving a single element.

### Why is this bad?

`.filter(...)[0]` builds an intermediate array and is less clear about intent.
`.find(...)` directly expresses that only the first matching element is needed.

### Examples

Examples of **incorrect** code for this rule:

```ts
const first = list.filter((item) => item.active)[0];
```

Examples of **correct** code for this rule:

```ts
const first = list.find((item) => item.active);
```

## How to use

## Version

This rule was added in v1.49.0.

## References

---

---
url: /docs/guide/usage/linter/rules/typescript/prefer-for-of.md
---

### What it does

Enforces the use of a `for...of` loop instead of a `for` loop with simple iteration.

### Why is this bad?

Using a `for` loop with a simple iteration over an array can be replaced with a more concise
and readable `for...of` loop. `for...of` loops are easier to read and less error-prone, as they
eliminate the need for an index variable and manual array access.

### Examples

Examples of **incorrect** code for this rule:

```typescript
for (let i = 0; i < arr.length; i++) {
  console.log(arr[i]);
}
```

Examples of **correct** code for this rule:

```typescript
for (const item of arr) {
  console.log(item);
}
```

## How to use

## Version

This rule was added in v0.2.16.

## References

---

---
url: /docs/guide/usage/linter/rules/typescript/prefer-function-type.md
---

### What it does

Enforce using function types instead of interfaces with call signatures.

### Why is this bad?

TypeScript allows for two common ways to declare a type for a function:

* Function type: `() => string`
* Object type with a signature: `{ (): string }`

The function type form is generally preferred when possible for being
more succinct and readable. Interfaces with only call signatures add
unnecessary verbosity without providing additional functionality.

### Examples

Examples of **incorrect** code for this rule:

```typescript
interface Example {
  (): string;
}

function foo(example: { (): number }): number {
  return example();
}

interface ReturnsSelf {
  (arg: string): this;
}
```

Examples of **correct** code for this rule:

```typescript
type Example = () => string;

function foo(example: () => number): number {
  return example();
}

// Returns the function itself, not the `this` argument
type ReturnsSelf = (arg: string) => ReturnsSelf;

// Multiple properties are allowed
function foo(bar: { (): string; baz: number }): string {
  return bar();
}

// Multiple call signatures (overloads) are allowed
interface Overloaded {
  (data: string): number;
  (id: number): string;
}

// this is equivalent to Overloaded interface.
type Intersection = ((data: string) => number) & ((id: number) => string);
```

## How to use

## Version

This rule was added in v0.2.11.

## References

---

---
url: /docs/guide/usage/linter/rules/typescript/prefer-includes.md
---

### What it does

Enforce using `.includes()` instead of `.indexOf() !== -1` or `/regex/.test()`.

### Why is this bad?

`.includes()` is more readable and expressive than checking `.indexOf() !== -1`.
It clearly communicates the intent to check for the presence of a value.
Additionally, for simple string searches, `.includes()` is often preferred over
regex `.test()` for better performance and clarity.

### Examples

Examples of **incorrect** code for this rule:

```ts
// Using indexOf
const str = "hello world";
if (str.indexOf("world") !== -1) {
  console.log("found");
}

if (str.indexOf("world") != -1) {
  console.log("found");
}

if (str.indexOf("world") > -1) {
  console.log("found");
}

// Using regex test for simple strings
if (/world/.test(str)) {
  console.log("found");
}

// Arrays
const arr = [1, 2, 3];
if (arr.indexOf(2) !== -1) {
  console.log("found");
}
```

Examples of **correct** code for this rule:

```ts
// Using includes for strings
const str = "hello world";
if (str.includes("world")) {
  console.log("found");
}

// Using includes for arrays
const arr = [1, 2, 3];
if (arr.includes(2)) {
  console.log("found");
}

// Complex regex patterns are allowed
if (/wo+rld/.test(str)) {
  console.log("found");
}

// Regex with flags
if (/world/i.test(str)) {
  console.log("found");
}
```

## How to use

## Version

This rule was added in v1.29.0.

## References

---

---
url: /docs/guide/usage/linter/rules/typescript/prefer-literal-enum-member.md
---

### What it does

Explicit enum values must only be literal values (string, number, boolean, etc.).

### Why is this bad?

TypeScript allows the value of an enum member to be many different kinds of valid JavaScript expressions.
However, because enums create their own scope whereby each enum member becomes a variable in that scope, developers are often surprised at the resultant values.

### Examples

Examples of **incorrect** code for this rule:

```ts
const imOutside = 2;
const b = 2;
enum Foo {
  outer = imOutside,
  a = 1,
  b = a,
  c = b,
}
```

## Configuration

This rule accepts a configuration object with the following properties:

### allowBitwiseExpressions

type: `boolean`

default: `false`

When set to `true`, allows bitwise expressions in enum member initializers.
This includes bitwise NOT (`~`), AND (`&`), OR (`|`), XOR (`^`), and shift operators (`<<`, `>>`, `>>>`).

## How to use

## Version

This rule was added in v0.3.2.

## References

---

---
url: /docs/guide/usage/linter/rules/typescript/prefer-namespace-keyword.md
---

### What it does

This rule reports when the module keyword is used instead of namespace.
This rule does not report on the use of TypeScript module declarations to describe external APIs (declare module 'foo' {}).

::: warning
This rule is deprecated and will be removed in a future release.

In a future version of TypeScript and Oxlint, this will be a hard error produced by the parser.

See: https://github.com/microsoft/TypeScript/issues/54500, https://github.com/microsoft/TypeScript/issues/62211 and https://github.com/microsoft/TypeScript/pull/62876.
:::

### Why is this bad?

Namespaces are an outdated way to organize TypeScript code. ES2015 module syntax is now preferred (`import`/`export`).
For projects still using custom modules / namespaces, it's preferred to refer to them as namespaces.

### Examples

Examples of **incorrect** code for this rule:

```typescript
module Example {}
```

Examples of **correct** code for this rule:

```typescript
namespace Example {}
```

## How to use

## Version

This rule was added in v0.7.0.

## References

---

---
url: /docs/guide/usage/linter/rules/typescript/prefer-nullish-coalescing.md
---

### What it does

Enforce using the nullish coalescing operator (`??`) instead of logical OR (`||`)
or conditional expressions when the left operand might be `null` or `undefined`.

### Why is this bad?

The `||` operator returns the right-hand side when the left-hand side is any
falsy value (`false`, `0`, `''`, `null`, `undefined`, `NaN`). This can lead
to unexpected behavior when you only want to provide a default for `null`
or `undefined`.

The nullish coalescing operator (`??`) only returns the right-hand side when
the left-hand side is `null` or `undefined`, making the intent clearer and
avoiding bugs with other falsy values.

### Examples

Examples of **incorrect** code for this rule:

```ts
declare const x: string | null;

// Using || when ?? would be more appropriate
const foo = x || "default";

// Ternary that could use ??
const bar = x !== null && x !== undefined ? x : "default";
const baz = x != null ? x : "default";

// If statement that could use ??
let value = "default";
if (x !== null && x !== undefined) {
  value = x;
}
```

Examples of **correct** code for this rule:

```ts
declare const x: string | null;

// Using nullish coalescing
const foo = x ?? "default";

// || is fine when you want falsy behavior
declare const y: string;
const bar = y || "default";

// Boolean coercion (can be ignored with ignoreBooleanCoercion)
const bool = Boolean(x || y);
```

## Configuration

This rule accepts a configuration object with the following properties:

### ignoreBooleanCoercion

type: `boolean`

default: `false`

Whether to ignore arguments to the `Boolean` constructor.

### ignoreConditionalTests

type: `boolean`

default: `true`

Whether to ignore cases that are located within a conditional test.

### ignoreIfStatements

type: `boolean`

default: `false`

Whether to ignore any if statements that could be simplified by using
the nullish coalescing operator.

### ignoreMixedLogicalExpressions

type: `boolean`

default: `false`

Whether to ignore any logical or expressions that are part of a mixed
logical expression (with `&&`).

### ignorePrimitives

type: `object | boolean`

Represents the different ways `ignorePrimitives` can be specified in JSON.
Can be:

* `true` - ignore all primitive types
* An object specifying which primitives to ignore

#### ignorePrimitives.bigint

type: `boolean`

default: `false`

Ignore bigint primitive types.

#### ignorePrimitives.boolean

type: `boolean`

default: `false`

Ignore boolean primitive types.

#### ignorePrimitives.number

type: `boolean`

default: `false`

Ignore number primitive types.

#### ignorePrimitives.string

type: `boolean`

default: `false`

Ignore string primitive types.

### ignoreTernaryTests

type: `boolean`

default: `false`

Whether to ignore any ternary expressions that could be simplified by
using the nullish coalescing operator.

## How to use

## Version

This rule was added in v1.33.0.

## References

---

---
url: /docs/guide/usage/linter/rules/typescript/prefer-optional-chain.md
---

### What it does

Enforce using concise optional chain expressions instead of chained logical AND
operators, negated logical OR operators, or empty objects.

Note that this rule is in the nursery category while we ensure it is working
correctly in as many edge-case scenarios as possible. The logic for this is
complex and the autofix may cause logic changes in some edge-cases.

### Why is this bad?

TypeScript 3.7 introduced optional chaining (`?.`) which provides a more concise
and readable way to access properties on potentially nullish values. Using optional
chaining instead of logical AND chains (`&&`) or other patterns improves code clarity.

### Examples

Examples of **incorrect** code for this rule:

```ts
foo && foo.bar;
foo && foo.bar && foo.bar.baz;
foo && foo["bar"];
foo && foo.bar && foo.bar.baz && foo.bar.baz.buzz;
foo && foo.bar && foo.bar.baz.buzz;
foo && foo.bar.baz && foo.bar.baz.buzz;
(foo || {}).bar;
```

Examples of **correct** code for this rule:

```ts
foo?.bar;
foo?.bar?.baz;
foo?.["bar"];
foo?.bar?.baz?.buzz;
foo?.bar?.baz.buzz;
foo?.bar.baz?.buzz;
foo?.bar;
```

## Configuration

This rule accepts a configuration object with the following properties:

### allowPotentiallyUnsafeFixesThatModifyTheReturnTypeIKnowWhatImDoing

type: `boolean`

default: `false`

Allow autofixers that will change the return type of the expression.
This option is considered unsafe as it may break the build.

### checkAny

type: `boolean`

default: `true`

Check operands that are typed as `any` when inspecting "loose boolean" operands.

### checkBigInt

type: `boolean`

default: `true`

Check operands that are typed as `bigint` when inspecting "loose boolean" operands.

### checkBoolean

type: `boolean`

default: `true`

Check operands that are typed as `boolean` when inspecting "loose boolean" operands.

### checkNumber

type: `boolean`

default: `true`

Check operands that are typed as `number` when inspecting "loose boolean" operands.

### checkString

type: `boolean`

default: `true`

Check operands that are typed as `string` when inspecting "loose boolean" operands.

### checkUnknown

type: `boolean`

default: `true`

Check operands that are typed as `unknown` when inspecting "loose boolean" operands.

### requireNullish

type: `boolean`

default: `false`

Skip operands that are not typed with `null` and/or `undefined` when inspecting
"loose boolean" operands.

## How to use

## Version

This rule was added in v1.39.0.

## References

---

---
url: /docs/guide/usage/linter/rules/typescript/prefer-promise-reject-errors.md
---

### What it does

This rule enforces passing an Error object to `Promise.reject()`.

### Why is this bad?

It's considered good practice to only reject promises with Error objects. This is because Error objects automatically capture a stack trace, which is useful for debugging. Additionally, some tools and environments expect rejection reasons to be Error objects.

### Examples

Examples of **incorrect** code for this rule:

```ts
Promise.reject("error"); // rejecting with string

Promise.reject(42); // rejecting with number

Promise.reject(true); // rejecting with boolean

Promise.reject({ message: "error" }); // rejecting with plain object

Promise.reject(null); // rejecting with null

Promise.reject(); // rejecting with undefined

const error = "Something went wrong";
Promise.reject(error); // rejecting with non-Error variable
```

Examples of **correct** code for this rule:

```ts
Promise.reject(new Error("Something went wrong"));

Promise.reject(new TypeError("Invalid type"));

Promise.reject(new RangeError("Value out of range"));

// Custom Error subclasses
class CustomError extends Error {
  constructor(message: string) {
    super(message);
    this.name = "CustomError";
  }
}
Promise.reject(new CustomError("Custom error occurred"));

// Variables that are Error objects
const error = new Error("Error message");
Promise.reject(error);
```

## Configuration

This rule accepts a configuration object with the following properties:

### allow

type: `array`

default: `[]`

An array of type or value specifiers for additional types that are allowed
as Promise rejection reasons.

#### allow\[n]

type: `object | string`

Type or value specifier for matching specific declarations

Supports four types of specifiers:

1. **String specifier** (deprecated): Universal match by name

```json
"Promise"
```

2. **File specifier**: Match types/values declared in local files

```json
{ "from": "file", "name": "MyType" }
{ "from": "file", "name": ["Type1", "Type2"] }
{ "from": "file", "name": "MyType", "path": "./types.ts" }
```

3. **Lib specifier**: Match TypeScript built-in lib types

```json
{ "from": "lib", "name": "Promise" }
{ "from": "lib", "name": ["Promise", "PromiseLike"] }
```

4. **Package specifier**: Match types/values from npm packages

```json
{ "from": "package", "name": "Observable", "package": "rxjs" }
{ "from": "package", "name": ["Observable", "Subject"], "package": "rxjs" }
```

##### allow\[n].from

type: `"file"`

Must be "file"

##### allow\[n].name

type: `array | string`

The name(s) of the type or value to match

Name specifier that can be a single string or array of strings

###### allow\[n].name\[n]

type: `string`

##### allow\[n].path

type: `string`

Optional file path to specify where the types or values must be declared.
If omitted, all files will be matched.

### allowEmptyReject

type: `boolean`

default: `false`

Whether to allow calling `Promise.reject()` with no arguments.

### allowThrowingAny

type: `boolean`

default: `false`

Whether to allow rejecting Promises with values typed as `any`.

### allowThrowingUnknown

type: `boolean`

default: `false`

Whether to allow rejecting Promises with values typed as `unknown`.

## How to use

## Version

This rule was added in v1.12.0.

## References

---

---
url: /docs/guide/usage/linter/rules/typescript/prefer-readonly.md
---

### What it does

Require class members that are never reassigned to be marked `readonly`.

### Why is this bad?

Members that never change should be declared `readonly` to make class invariants explicit
and prevent accidental mutation.

### Examples

Examples of **incorrect** code for this rule:

```ts
class Counter {
  private value = 0;

  getValue() {
    return this.value;
  }
}
```

Examples of **correct** code for this rule:

```ts
class Counter {
  private readonly value = 0;

  getValue() {
    return this.value;
  }
}
```

## Configuration

This rule accepts a configuration object with the following properties:

### onlyInlineLambdas

type: `boolean`

default: `false`

Restrict checks to members immediately initialized with inline lambda values.

## How to use

## Version

This rule was added in v0.0.8.

## References

---

---
url: /docs/guide/usage/linter/rules/typescript/prefer-readonly-parameter-types.md
---

### What it does

Require function and method parameters to use readonly-compatible types.

### Why is this bad?

Mutable parameter types make accidental mutation easier and weaken function contracts.
Readonly parameter types communicate intent and improve API safety.

### Examples

Examples of **incorrect** code for this rule:

```ts
function update(items: string[]) {
  items.push("x");
}

function consume(obj: { value: string }) {
  obj.value = obj.value.trim();
}
```

Examples of **correct** code for this rule:

```ts
function update(items: readonly string[]) {
  return items.length;
}

function consume(obj: Readonly<{ value: string }>) {
  return obj.value;
}
```

## Configuration

This rule accepts a configuration object with the following properties:

### allow

type: `array`

default: `[]`

Type/value specifiers that should be exempt from this rule.

#### allow\[n]

type: `object | string`

Type or value specifier for matching specific declarations

Supports four types of specifiers:

1. **String specifier** (deprecated): Universal match by name

```json
"Promise"
```

2. **File specifier**: Match types/values declared in local files

```json
{ "from": "file", "name": "MyType" }
{ "from": "file", "name": ["Type1", "Type2"] }
{ "from": "file", "name": "MyType", "path": "./types.ts" }
```

3. **Lib specifier**: Match TypeScript built-in lib types

```json
{ "from": "lib", "name": "Promise" }
{ "from": "lib", "name": ["Promise", "PromiseLike"] }
```

4. **Package specifier**: Match types/values from npm packages

```json
{ "from": "package", "name": "Observable", "package": "rxjs" }
{ "from": "package", "name": ["Observable", "Subject"], "package": "rxjs" }
```

##### allow\[n].from

type: `"file"`

Must be "file"

##### allow\[n].name

type: `array | string`

The name(s) of the type or value to match

Name specifier that can be a single string or array of strings

###### allow\[n].name\[n]

type: `string`

##### allow\[n].path

type: `string`

Optional file path to specify where the types or values must be declared.
If omitted, all files will be matched.

### checkParameterProperties

type: `boolean`

default: `true`

Whether to check constructor parameter properties.

### ignoreInferredTypes

type: `boolean`

default: `false`

Whether to ignore parameters without explicit type annotations.

### treatMethodsAsReadonly

type: `boolean`

default: `false`

Whether mutable methods should be treated as readonly members.

## How to use

## Version

This rule was added in v1.49.0.

## References

---

---
url: /docs/guide/usage/linter/rules/typescript/prefer-reduce-type-parameter.md
---

### What it does

This rule prefers using a type parameter for the accumulator in `Array#reduce()` instead of casting.

### Why is this bad?

`Array#reduce()` can be called with a generic type parameter to specify the type of the accumulator. This is preferred over casting the result because it provides better type safety and is more explicit about the intended type.

### Examples

Examples of **incorrect** code for this rule:

```ts
const numbers = [1, 2, 3];

// Casting the result
const sum = numbers.reduce((acc, val) => acc + val, 0) as number;

// Using type assertion on accumulator
const result = [1, 2, 3].reduce((acc: string[], curr) => {
  acc.push(curr.toString());
  return acc;
}, [] as string[]);
```

Examples of **correct** code for this rule:

```ts
const numbers = [1, 2, 3];

// Using type parameter
const sum = numbers.reduce<number>((acc, val) => acc + val, 0);

// Type parameter for complex types
const result = [1, 2, 3].reduce<string[]>((acc, curr) => {
  acc.push(curr.toString());
  return acc;
}, []);

// When TypeScript can infer the type, no parameter needed
const simpleSum = numbers.reduce((acc, val) => acc + val, 0);

// Object accumulator with type parameter
interface Count {
  [key: string]: number;
}

const counts = ["a", "b", "a"].reduce<Count>((acc, item) => {
  acc[item] = (acc[item] || 0) + 1;
  return acc;
}, {});
```

## How to use

## Version

This rule was added in v1.12.0.

## References

---

---
url: /docs/guide/usage/linter/rules/typescript/prefer-regexp-exec.md
---

### What it does

Prefer `RegExp#exec()` over `String#match()` when extracting a regex match.

### Why is this bad?

`exec()` is more explicit about matching with a regular expression and avoids the
overloaded behavior of `String#match()`.

### Examples

Examples of **incorrect** code for this rule:

```ts
const text = "value";
text.match(/v/);
```

Examples of **correct** code for this rule:

```ts
const text = "value";
/v/.exec(text);
```

## How to use

## Version

This rule was added in v1.49.0.

## References

---

---
url: /docs/guide/usage/linter/rules/typescript/prefer-return-this-type.md
---

### What it does

This rule enforces using `this` types for return types when possible.

### Why is this bad?

Classes that have methods which return the instance itself should use `this` as the return type instead of the class name. This provides better type safety for inheritance, as the return type will be the actual subclass type rather than the base class type.

### Examples

Examples of **incorrect** code for this rule:

```ts
class Builder {
  private value: string = "";

  setValue(value: string): Builder {
    // Should return 'this'
    this.value = value;
    return this;
  }

  build(): string {
    return this.value;
  }
}

class FluentAPI {
  method1(): FluentAPI {
    // Should return 'this'
    return this;
  }

  method2(): FluentAPI {
    // Should return 'this'
    return this;
  }
}
```

Examples of **correct** code for this rule:

```ts
class Builder {
  private value: string = "";

  setValue(value: string): this {
    this.value = value;
    return this;
  }

  build(): string {
    return this.value;
  }
}

class FluentAPI {
  method1(): this {
    return this;
  }

  method2(): this {
    return this;
  }
}

// Now inheritance works correctly
class ExtendedBuilder extends Builder {
  setPrefix(prefix: string): this {
    // The return type is 'this' (ExtendedBuilder), not Builder
    return this.setValue(prefix + this.getValue());
  }
}
```

## How to use

## Version

This rule was added in v1.12.0.

## References

---

---
url: /docs/guide/usage/linter/rules/typescript/prefer-string-starts-ends-with.md
---

### What it does

Prefer `startsWith` and `endsWith` over manual string boundary checks.

### Why is this bad?

Boundary checks written with `slice`, `indexOf`, regex anchors, or manual indexing are
harder to read and maintain than `startsWith`/`endsWith`.

### Examples

Examples of **incorrect** code for this rule:

```ts
value.slice(0, 3) === "foo";
value.slice(-3) === "bar";
```

Examples of **correct** code for this rule:

```ts
value.startsWith("foo");
value.endsWith("bar");
```

## Configuration

This rule accepts a configuration object with the following properties:

### allowSingleElementEquality

type: `"always" | "never"`

default: `"never"`

Whether equality checks against the first/last character are allowed.

#### `"always"`

Always allow equality checks against the first or last character.

#### `"never"`

Never allow equality checks against the first or last character.

## How to use

## Version

This rule was added in v0.0.8.

## References

---

---
url: /docs/guide/usage/linter/rules/typescript/prefer-ts-expect-error.md
---

### What it does

Enforce using @ts-expect-error over @ts-ignore.

### Why is this bad?

TypeScript allows you to suppress all errors on a line by placing a comment starting with @ts-ignore or @ts-expect-error immediately before the erroring line.
The two directives work the same, except @ts-expect-error causes a type error if placed before a line that's not erroring in the first place.

This means it's easy for @ts-ignores to be forgotten about, and remain in code even after the error they were suppressing is fixed.
This is dangerous, as if a new error arises on that line it'll be suppressed by the forgotten about @ts-ignore, and so be missed.

### Examples

Examples of **incorrect** code for this rule:

```ts
// @ts-ignore
const str: string = 1;

/**
 * Explaining comment
 *
 * @ts-ignore */
const multiLine: number = "value";
```

Examples of **correct** code for this rule:

```ts
/**
 * Explaining comment
 *
 * @ts-expect-error */
const multiLine: number = "value";
```

## How to use

## Version

This rule was added in v0.2.11.

## References

---

---
url: /docs/guide/usage/linter/rules/typescript/promise-function-async.md
---

### What it does

This rule requires any function or method that returns a Promise to be marked as async.

### Why is this bad?

Functions that return Promises should typically be marked as `async` to make their asynchronous nature clear and to enable the use of `await` within them. This makes the code more readable and helps prevent common mistakes with Promise handling.

### Examples

Examples of **incorrect** code for this rule:

```ts
// Function returning Promise without async
function fetchData(): Promise<string> {
  return fetch("/api/data").then((res) => res.text());
}

// Method returning Promise without async
class DataService {
  getData(): Promise<any> {
    return fetch("/api/data").then((res) => res.json());
  }
}

// Arrow function returning Promise without async
const processData = (): Promise<void> => {
  return Promise.resolve();
};
```

Examples of **correct** code for this rule:

```ts
// Async function
async function fetchData(): Promise<string> {
  const response = await fetch("/api/data");
  return response.text();
}

// Async method
class DataService {
  async getData(): Promise<any> {
    const response = await fetch("/api/data");
    return response.json();
  }
}

// Async arrow function
const processData = async (): Promise<void> => {
  await someAsyncOperation();
};

// Functions that don't return Promise are fine
function syncFunction(): string {
  return "hello";
}

// Functions returning Promise-like but not actual Promise
function createThenable(): { then: Function } {
  return { then: () => {} };
}
```

## Configuration

This rule accepts a configuration object with the following properties:

### allowAny

type: `boolean`

default: `true`

Whether to allow functions returning `any` type without requiring `async`.

### allowedPromiseNames

type: `string[]`

default: `[]`

A list of Promise type names that are allowed without requiring `async`.
Example: `["SpecialPromise"]` to allow functions returning `SpecialPromise` without `async`.

### checkArrowFunctions

type: `boolean`

default: `true`

Whether to check arrow functions for missing `async` keyword.

### checkFunctionDeclarations

type: `boolean`

default: `true`

Whether to check function declarations for missing `async` keyword.

### checkFunctionExpressions

type: `boolean`

default: `true`

Whether to check function expressions for missing `async` keyword.

### checkMethodDeclarations

type: `boolean`

default: `true`

Whether to check method declarations for missing `async` keyword.

## How to use

## Version

This rule was added in v1.12.0.

## References

---

---
url: /docs/guide/usage/linter/rules/typescript/related-getter-setter-pairs.md
---

### What it does

This rule enforces that getters and setters for the same property are defined together and have related types.

### Why is this bad?

When you define a getter and setter for the same property, they should typically be defined together and work with compatible types. Having mismatched types or defining them separately can lead to confusion and potential runtime errors.

### Examples

Examples of **incorrect** code for this rule:

```ts
class Example {
  // Getter and setter with incompatible types
  get value(): string {
    return this._value.toString();
  }

  set value(val: number) {
    // Incompatible with getter
    this._value = val;
  }

  private _value: number = 0;
}

// Getter without corresponding setter or vice versa might be flagged
class IncompleteProperty {
  get readOnlyValue(): string {
    return "constant";
  }
  // Missing setter - might be intended, but should be consistent
}
```

Examples of **correct** code for this rule:

```ts
class Example {
  // Getter and setter with compatible types
  get value(): string {
    return this._value;
  }

  set value(val: string) {
    this._value = val;
  }

  private _value: string = "";
}

// Read-only property with only getter
class ReadOnlyProperty {
  get constant(): string {
    return "constant value";
  }
}

// Write-only property with only setter (less common but valid)
class WriteOnlyProperty {
  set logger(message: string) {
    console.log(message);
  }
}
```

## How to use

## Version

This rule was added in v1.12.0.

## References

---

---
url: /docs/guide/usage/linter/rules/typescript/require-array-sort-compare.md
---

### What it does

This rule requires `Array#sort()` to be called with a comparison function.

### Why is this bad?

When `Array#sort()` is called without a comparison function, it converts elements to strings and sorts them lexicographically. This often leads to unexpected results, especially with numbers where `[1, 10, 2].sort()` returns `[1, 10, 2]` instead of `[1, 2, 10]`.

### Examples

Examples of **incorrect** code for this rule:

```ts
const numbers = [3, 1, 4, 1, 5];
numbers.sort(); // Lexicographic sort, not numeric

const mixedArray = ["10", "2", "1"];
mixedArray.sort(); // Might be intended, but explicit compareFn is clearer

[3, 1, 4].sort(); // Will sort as strings: ['1', '3', '4']
```

Examples of **correct** code for this rule:

```ts
const numbers = [3, 1, 4, 1, 5];

// Numeric sort
numbers.sort((a, b) => a - b);

// Reverse numeric sort
numbers.sort((a, b) => b - a);

// String sort (explicit)
const strings = ["banana", "apple", "cherry"];
strings.sort((a, b) => a.localeCompare(b));

// Custom object sorting
interface Person {
  name: string;
  age: number;
}

const people: Person[] = [
  { name: "Alice", age: 30 },
  { name: "Bob", age: 25 },
];

people.sort((a, b) => a.age - b.age);
people.sort((a, b) => a.name.localeCompare(b.name));
```

## Configuration

This rule accepts a configuration object with the following properties:

### ignoreStringArrays

type: `boolean`

default: `true`

Whether to ignore arrays in which all elements are strings.

## How to use

## Version

This rule was added in v1.12.0.

## References

---

---
url: /docs/guide/usage/linter/rules/typescript/require-await.md
---

### What it does

This rule disallows async functions which do not have an await expression.

### Why is this bad?

Async functions that don't use await are usually a mistake. They return a Promise unnecessarily and can often be converted to regular functions. This can improve performance and make the code clearer.

### Examples

Examples of **incorrect** code for this rule:

```ts
// Async function without await
async function fetchData() {
  return fetch("/api/data");
}

// Async arrow function without await
const processData = async () => {
  return someData.map((x) => x * 2);
};

// Async method without await
class DataService {
  async getData() {
    return this.data;
  }
}

// Async function that returns Promise but doesn't await
async function getPromise() {
  return Promise.resolve("value");
}
```

Examples of **correct** code for this rule:

```ts
// Async function with await
async function fetchData() {
  const response = await fetch("/api/data");
  return response.json();
}

// Regular function returning Promise
function fetchDataSync() {
  return fetch("/api/data");
}

// Async function with await in conditional
async function conditionalAwait(condition: boolean) {
  if (condition) {
    return await someAsyncOperation();
  }
  return "default";
}

// Async function with await in loop
async function processItems(items: string[]) {
  const results = [];
  for (const item of items) {
    results.push(await processItem(item));
  }
  return results;
}
```

## How to use

## Version

This rule was added in v1.12.0.

## References

---

---
url: /docs/guide/usage/linter/rules/typescript/restrict-plus-operands.md
---

### What it does

This rule requires both operands of addition to be the same type and be number, string, or any.

### Why is this bad?

JavaScript's + operator can be used for both numeric addition and string concatenation. When the operands are of different types, JavaScript's type coercion rules can lead to unexpected results. This rule helps prevent these issues by requiring both operands to be of compatible types.

### Examples

Examples of **incorrect** code for this rule:

```ts
declare const num: number;
declare const str: string;
declare const bool: boolean;
declare const obj: object;

// Mixed types
const result1 = num + str; // number + string
const result2 = str + bool; // string + boolean
const result3 = num + bool; // number + boolean
const result4 = obj + str; // object + string

// Literals with different types
const result5 = 42 + "hello"; // number literal + string literal
const result6 = true + 5; // boolean literal + number literal
```

Examples of **correct** code for this rule:

```ts
declare const num1: number;
declare const num2: number;
declare const str1: string;
declare const str2: string;

// Same types
const sum = num1 + num2; // number + number
const concat = str1 + str2; // string + string

// Explicit conversions
const result1 = num1 + String(num2); // Convert to string first
const result2 = String(num1) + str1; // Convert to string first
const result3 = Number(str1) + num1; // Convert to number first

// Template literals for string concatenation
const result4 = `${num1}${str1}`; // Clear intent to concatenate

// Literals of same type
const numResult = 42 + 58; // number + number
const strResult = "hello" + "world"; // string + string
```

## Configuration

This rule accepts a configuration object with the following properties:

### allowAny

type: `boolean`

default: `true`

Whether to allow `any` type in plus operations.

### allowBoolean

type: `boolean`

default: `true`

Whether to allow `boolean` types in plus operations.

### allowNullish

type: `boolean`

default: `true`

Whether to allow nullish types (`null` or `undefined`) in plus operations.

### allowNumberAndString

type: `boolean`

default: `true`

Whether to allow mixed number and string operands in plus operations.

### allowRegExp

type: `boolean`

default: `true`

Whether to allow `RegExp` types in plus operations.

### skipCompoundAssignments

type: `boolean`

default: `false`

Whether to skip compound assignments (e.g., `a += b`).

## How to use

## Version

This rule was added in v1.12.0.

## References

---

---
url: /docs/guide/usage/linter/rules/typescript/restrict-template-expressions.md
---

### What it does

This rule restricts the types allowed in template literal expressions.

### Why is this bad?

Template literals will call `toString()` on the interpolated values. Some types don't have meaningful string representations (like objects that become `"[object Object]"`) or may not have a `toString` method at all. This rule helps ensure that only appropriate types are used in template expressions.

### Examples

Examples of **incorrect** code for this rule:

```ts
declare const obj: object;
declare const sym: symbol;
declare const fn: () => void;
declare const arr: unknown[];

// Objects become "[object Object]"
const str1 = `Value: ${obj}`;

// Symbols might not be what you expect
const str2 = `Symbol: ${sym}`;

// Functions become their source code or "[Function]"
const str3 = `Function: ${fn}`;

// Arrays might not format as expected
const str4 = `Array: ${arr}`;

// undefined/null become "undefined"/"null" which might be confusing
declare const maybeValue: string | undefined;
const str5 = `Value: ${maybeValue}`; // Could be "Value: undefined"
```

Examples of **correct** code for this rule:

```ts
declare const str: string;
declare const num: number;
declare const bool: boolean;
declare const obj: object;

// Safe types
const result1 = `String: ${str}`;
const result2 = `Number: ${num}`;
const result3 = `Boolean: ${bool}`;

// Explicit conversions for complex types
const result4 = `Object: ${JSON.stringify(obj)}`;
const result5 = `Array: ${arr.join(", ")}`;

// Handle undefined/null explicitly
declare const maybeValue: string | undefined;
const result6 = `Value: ${maybeValue ?? "N/A"}`;
const result7 = `Value: ${maybeValue || "default"}`;

// Type guards for unknown values
declare const unknown: unknown;
const result8 = typeof unknown === "string" ? `Value: ${unknown}` : "Invalid";
```

## Configuration

This rule accepts a configuration object with the following properties:

### allow

type: `array`

default: `[{"from":"lib", "name":["Error", "URL", "URLSearchParams"]}]`

An array of type or value specifiers for additional types that are allowed in template expressions.
Defaults include Error, URL, and URLSearchParams from lib.

#### allow\[n]

type: `object | string`

Type or value specifier for matching specific declarations

Supports four types of specifiers:

1. **String specifier** (deprecated): Universal match by name

```json
"Promise"
```

2. **File specifier**: Match types/values declared in local files

```json
{ "from": "file", "name": "MyType" }
{ "from": "file", "name": ["Type1", "Type2"] }
{ "from": "file", "name": "MyType", "path": "./types.ts" }
```

3. **Lib specifier**: Match TypeScript built-in lib types

```json
{ "from": "lib", "name": "Promise" }
{ "from": "lib", "name": ["Promise", "PromiseLike"] }
```

4. **Package specifier**: Match types/values from npm packages

```json
{ "from": "package", "name": "Observable", "package": "rxjs" }
{ "from": "package", "name": ["Observable", "Subject"], "package": "rxjs" }
```

##### allow\[n].from

type: `"file"`

Must be "file"

##### allow\[n].name

type: `array | string`

The name(s) of the type or value to match

Name specifier that can be a single string or array of strings

###### allow\[n].name\[n]

type: `string`

##### allow\[n].path

type: `string`

Optional file path to specify where the types or values must be declared.
If omitted, all files will be matched.

### allowAny

type: `boolean`

default: `true`

Whether to allow `any` typed values in template expressions.

### allowArray

type: `boolean`

default: `false`

Whether to allow array types in template expressions.

### allowBoolean

type: `boolean`

default: `true`

Whether to allow boolean types in template expressions.

### allowNever

type: `boolean`

default: `false`

Whether to allow `never` type in template expressions.

### allowNullish

type: `boolean`

default: `true`

Whether to allow nullish types (`null` or `undefined`) in template expressions.

### allowNumber

type: `boolean`

default: `true`

Whether to allow number and bigint types in template expressions.

### allowRegExp

type: `boolean`

default: `true`

Whether to allow RegExp values in template expressions.

## How to use

## Version

This rule was added in v1.12.0.

## References

---

---
url: /docs/guide/usage/linter/rules/typescript/return-await.md
---

### What it does

This rule enforces consistent returning of awaited values from async functions.

### Why is this bad?

There are different patterns for returning awaited values from async functions.
Sometimes you want to await before returning (to handle errors in the current
function), and sometimes you want to return the Promise directly (for better
performance). This rule helps enforce consistency.

### Examples

Examples of **incorrect** code for this rule (depending on configuration):

```ts
// If configured to require await:
async function fetchData() {
  return fetch("/api/data"); // Should be: return await fetch('/api/data');
}

async function processData() {
  return someAsyncOperation(); // Should be: return await someAsyncOperation();
}

// If configured to disallow unnecessary await:
async function fetchData() {
  return await fetch("/api/data"); // Should be: return fetch('/api/data');
}

async function processData() {
  return await someAsyncOperation(); // Should be: return someAsyncOperation();
}
```

Examples of **correct** code for this rule:

```ts
// When await is required for error handling:
async function fetchData() {
  try {
    return await fetch("/api/data");
  } catch (error) {
    console.error("Fetch failed:", error);
    throw error;
  }
}

// When returning Promise directly for performance:
async function fetchData() {
  return fetch("/api/data");
}

// Processing before return requires await:
async function fetchAndProcess() {
  const response = await fetch("/api/data");
  return response.json();
}

// Multiple async operations:
async function multipleOperations() {
  const data1 = await fetchData1();
  const data2 = await fetchData2();
  return data1 + data2;
}
```

## Configuration

This rule accepts one of the following string values:

### `"in-try-catch"`

Require `await` when returning Promises inside try/catch/finally blocks.
This ensures proper error handling and stack traces.

### `"always"`

Require `await` before returning Promises in all cases.
Example: `return await Promise.resolve()` is required.

### `"error-handling-correctness-only"`

Require `await` only when it affects error handling correctness.
Only flags cases where omitting await would change error handling behavior.

### `"never"`

Disallow `await` before returning Promises in all cases.
Example: `return Promise.resolve()` is required (no await).

## How to use

## Version

This rule was added in v1.12.0.

## References

---

---
url: /docs/guide/usage/linter/rules/typescript/strict-boolean-expressions.md
---

### What it does

Disallow certain types in boolean expressions.

### Why is this bad?

Forbids usage of non-boolean types in expressions where a boolean is expected.
`boolean` and `never` types are always allowed. Additional types which are
considered safe in a boolean context can be configured via options.

The following nodes are checked:

* Arguments to the `!`, `&&`, and `||` operators
* The condition in a conditional expression (`cond ? x : y`)
* Conditions for `if`, `for`, `while`, and `do-while` statements.

### Examples

Examples of **incorrect** code for this rule:

```ts
const str = "hello";
if (str) {
  console.log("string");
}

const num = 42;
if (num) {
  console.log("number");
}

const obj = { foo: "bar" };
if (obj) {
  console.log("object");
}

declare const maybeString: string | undefined;
if (maybeString) {
  console.log(maybeString);
}

const result = str && num;
const ternary = str ? "yes" : "no";
```

Examples of **correct** code for this rule:

```ts
const str = "hello";
if (str !== "") {
  console.log("string");
}

const num = 42;
if (num !== 0) {
  console.log("number");
}

const obj = { foo: "bar" };
if (obj !== null) {
  console.log("object");
}

declare const maybeString: string | undefined;
if (maybeString !== undefined) {
  console.log(maybeString);
}

const bool = true;
if (bool) {
  console.log("boolean");
}
```

## Configuration

This rule accepts a configuration object with the following properties:

### allowAny

type: `boolean`

default: `false`

Whether to allow `any` type in boolean contexts.

### allowNullableBoolean

type: `boolean`

default: `false`

Whether to allow nullable boolean types (e.g., `boolean | null`) in boolean contexts.

### allowNullableEnum

type: `boolean`

default: `false`

Whether to allow nullable enum types in boolean contexts.

### allowNullableNumber

type: `boolean`

default: `false`

Whether to allow nullable number types (e.g., `number | null`) in boolean contexts.

### allowNullableObject

type: `boolean`

default: `true`

Whether to allow nullable object types in boolean contexts.

### allowNullableString

type: `boolean`

default: `false`

Whether to allow nullable string types (e.g., `string | null`) in boolean contexts.

### allowNumber

type: `boolean`

default: `true`

Whether to allow number types in boolean contexts (checks for non-zero numbers).

### allowString

type: `boolean`

default: `true`

Whether to allow string types in boolean contexts (checks for non-empty strings).

## How to use

## Version

This rule was added in v1.25.0.

## References

---

---
url: /docs/guide/usage/linter/rules/typescript/strict-void-return.md
---

### What it does

Disallow returning non-void values where a `void` return is expected.

### Why is this bad?

Returning values from `void` contexts can hide logic errors and make callback APIs
behave unexpectedly.

### Examples

Examples of **incorrect** code for this rule:

```ts
declare function run(cb: () => void): void;

run(() => "value");
run(async () => 123);
```

Examples of **correct** code for this rule:

```ts
declare function run(cb: () => void): void;

run(() => {
  doWork();
});

run(() => undefined);
```

## Configuration

This rule accepts a configuration object with the following properties:

### allowReturnAny

type: `boolean`

default: `false`

Allow callbacks that return `any` in places that expect a `void` callback.

## How to use

## Version

This rule was added in v0.0.8.

## References

---

---
url: /docs/guide/usage/linter/rules/typescript/switch-exhaustiveness-check.md
---

### What it does

This rule requires switch statements to be exhaustive when switching on union types.

### Why is this bad?

When switching on a union type, it's important to handle all possible cases to avoid runtime errors. TypeScript can help ensure exhaustiveness, but only if the switch statement is properly structured with a default case that TypeScript can analyze.

### Examples

Examples of **incorrect** code for this rule:

```ts
type Status = "pending" | "approved" | "rejected";

function handleStatus(status: Status) {
  switch (status) {
    case "pending":
      return "Waiting for approval";
    case "approved":
      return "Request approved";
    // Missing 'rejected' case
  }
}

enum Color {
  Red,
  Green,
  Blue,
}

function getColorName(color: Color) {
  switch (color) {
    case Color.Red:
      return "red";
    case Color.Green:
      return "green";
    // Missing Color.Blue case
  }
}
```

Examples of **correct** code for this rule:

```ts
type Status = "pending" | "approved" | "rejected";

function handleStatus(status: Status) {
  switch (status) {
    case "pending":
      return "Waiting for approval";
    case "approved":
      return "Request approved";
    case "rejected":
      return "Request rejected";
  }
}

// Or with default case for exhaustiveness checking
function handleStatusWithDefault(status: Status) {
  switch (status) {
    case "pending":
      return "Waiting for approval";
    case "approved":
      return "Request approved";
    case "rejected":
      return "Request rejected";
    default:
      const _exhaustiveCheck: never = status;
      return _exhaustiveCheck;
  }
}

enum Color {
  Red,
  Green,
  Blue,
}

function getColorName(color: Color) {
  switch (color) {
    case Color.Red:
      return "red";
    case Color.Green:
      return "green";
    case Color.Blue:
      return "blue";
    default:
      const _exhaustiveCheck: never = color;
      return _exhaustiveCheck;
  }
}
```

## Configuration

This rule accepts a configuration object with the following properties:

### allowDefaultCaseForExhaustiveSwitch

type: `boolean`

default: `true`

Whether to allow default cases on switches that are not exhaustive.
When false, requires exhaustive switch statements without default cases.

### considerDefaultExhaustiveForUnions

type: `boolean`

default: `false`

Whether to consider `default` cases exhaustive for union types.
When true, a switch statement with a `default` case is considered exhaustive
even if not all union members are handled explicitly.

### defaultCaseCommentPattern

type: `string`

Regular expression pattern that when matched in a default case comment,
will suppress the exhaustiveness check.
Example: `"@skip-exhaustive-check"` to allow `default: // @skip-exhaustive-check`

### requireDefaultForNonUnion

type: `boolean`

default: `false`

Whether to require default cases on switches over union types that are not exhaustive.
When true, switches with non-exhaustive union types must have a default case.

## How to use

## Version

This rule was added in v1.12.0.

## References

---

---
url: /docs/guide/usage/linter/rules/typescript/triple-slash-reference.md
---

### What it does

Disallow certain triple slash directives in favor of ES module import declarations.

### Why is this bad?

Use of triple-slash reference type directives is generally discouraged in favor of ECMAScript Module imports.

### Examples

Examples of **incorrect** code for this rule:

```ts
/// <reference lib="code" />
globalThis.value;
```

## Configuration

This rule accepts a configuration object with the following properties:

### lib

type: `"always" | "never"`

default: `"always"`

What to enforce for `/// <reference lib="..." />` references.

### path

type: `"always" | "never"`

default: `"never"`

What to enforce for `/// <reference path="..." />` references.

#### `"always"`

Allow triple-slash `path` references.

#### `"never"`

Disallow triple-slash `path` references.

### types

type: `"always" | "never" | "prefer-import"`

default: `"prefer-import"`

What to enforce for `/// <reference types="..." />` references.

#### `"always"`

Allow triple-slash `types` references.

#### `"never"`

Disallow triple-slash `types` references.

#### `"prefer-import"`

Prefer ES module import declarations over triple-slash `types` references.
This option only reports when there is an existing `import` declaration for the same module.

For example, this would be reported as a lint violation with `prefer-import`:

```ts
/// <reference types="foo" />
import { bar } from "foo";
```

## How to use

## Version

This rule was added in v0.2.0.

## References

---

---
url: /docs/guide/usage/linter/rules/typescript/unbound-method.md
---

### What it does

This rule enforces that unbound methods are called with their expected scope.

### Why is this bad?

When you extract a method from an object and call it separately, the `this` context is lost. This can lead to runtime errors or unexpected behavior, especially with methods that rely on `this` to access instance properties or other methods.

### Examples

Examples of **incorrect** code for this rule:

```ts
class MyClass {
  private value = 42;

  getValue() {
    return this.value;
  }

  processValue() {
    return this.value * 2;
  }
}

const instance = new MyClass();

// Unbound method - loses 'this' context
const getValue = instance.getValue;
getValue(); // Runtime error: cannot read property 'value' of undefined

// Passing unbound method as callback
[1, 2, 3].map(instance.processValue); // 'this' will be undefined

// Destructuring methods
const { getValue: unboundGetValue } = instance;
unboundGetValue(); // Runtime error
```

Examples of **correct** code for this rule:

```ts
class MyClass {
  private value = 42;

  getValue() {
    return this.value;
  }

  processValue() {
    return this.value * 2;
  }
}

const instance = new MyClass();

// Call method on instance
const value = instance.getValue(); // Correct

// Bind method to preserve context
const boundGetValue = instance.getValue.bind(instance);
boundGetValue(); // Correct

// Use arrow function to preserve context
[1, 2, 3].map(() => instance.processValue()); // Correct

// Use arrow function in class for auto-binding
class MyClassWithArrow {
  private value = 42;

  getValue = () => {
    return this.value;
  };
}

const instance2 = new MyClassWithArrow();
const getValue = instance2.getValue; // Safe - arrow function preserves 'this'
getValue(); // Correct
```

## Configuration

This rule accepts a configuration object with the following properties:

### ignoreStatic

type: `boolean`

default: `false`

Whether to ignore unbound methods that are static.
When true, static methods can be referenced without binding.

## How to use

## Version

This rule was added in v1.12.0.

## References

---

---
url: /docs/guide/usage/linter/rules/typescript/unified-signatures.md
---

### What it does

Disallow overload signatures that can be unified into one.

### Why is this bad?

Duplicate overload signatures that only differ by a single type, or by an optional/rest
parameter, are harder to maintain and read than a single unified signature.

### Examples

Examples of **incorrect** code for this rule:

```ts
function f(a: number): void;
function f(a: string): void;
```

Examples of **correct** code for this rule:

```ts
function f(a: number | string): void;
```

## Configuration

This rule accepts a configuration object with the following properties:

### ignoreDifferentlyNamedParameters

type: `boolean`

default: `false`

Whether to ignore parameter name differences when comparing signatures. If `false`, signatures
will not be considered unifiable if they have parameters in the same position with different
names, even if the parameter types are the same.

### ignoreOverloadsWithDifferentJSDoc

type: `boolean`

default: `false`

Whether to ignore JSDoc differences when comparing signatures. If `false`, signatures will not
be considered unifiable if the closest leading block comments for the signatures are different,
even if the signatures themselves are identical.

## How to use

## Version

This rule was added in v1.48.0.

## References

---

---
url: >-
  /docs/guide/usage/linter/rules/typescript/use-unknown-in-catch-callback-variable.md
---

### What it does

This rule enforces using `unknown` for catch clause variables instead of `any`.

### Why is this bad?

In TypeScript 4.0+, catch clause variables can be typed as `unknown` instead of `any`. Using `unknown` is safer because it forces you to perform type checking before using the error, preventing potential runtime errors.

### Examples

Examples of **incorrect** code for this rule:

```ts
try {
  somethingRisky();
} catch (error: any) {
  // Should use 'unknown'
  console.log(error.message); // Unsafe access
  error.someMethod(); // Unsafe call
}

// Default catch variable is 'any' in older TypeScript
try {
  somethingRisky();
} catch (error) {
  // Implicitly 'any'
  console.log(error.message); // Unsafe access
}
```

Examples of **correct** code for this rule:

```ts
try {
  somethingRisky();
} catch (error: unknown) {
  // Type guard for Error objects
  if (error instanceof Error) {
    console.log(error.message); // Safe access
    console.log(error.stack);
  } else {
    console.log("Unknown error:", error);
  }
}

// More comprehensive error handling
try {
  somethingRisky();
} catch (error: unknown) {
  if (error instanceof Error) {
    // Handle Error objects
    console.error("Error:", error.message);
  } else if (typeof error === "string") {
    // Handle string errors
    console.error("String error:", error);
  } else {
    // Handle unknown error types
    console.error("Unknown error type:", error);
  }
}

// Helper function for error handling
function isError(error: unknown): error is Error {
  return error instanceof Error;
}

try {
  somethingRisky();
} catch (error: unknown) {
  if (isError(error)) {
    console.log(error.message);
  }
}
```

## How to use

## Version

This rule was added in v1.12.0.

## References

---

---
url: /docs/guide/usage/linter/rules/unicorn/catch-error-name.md
---

### What it does

This rule enforces consistent and descriptive naming for error variables
in `catch` statements, preventing the use of vague names like `badName`
or `_` when the error is used.

### Why is this bad?

Using non-descriptive names like `badName` or `_` makes the code harder
to read and understand, especially when debugging. It's important to use
clear, consistent names to represent errors.

### Examples

Examples of **incorrect** code for this rule:

```javascript
try {
} catch (badName) {}

// `_` is not allowed if it's used
try {
} catch (_) {
  console.log(_);
}

promise.catch((badName) => {});

promise.then(undefined, (badName) => {});
```

Examples of **correct** code for this rule:

```javascript
try {
} catch (error) {}

// `_` is allowed if it's not used
try {
} catch (_) {
  console.log(123);
}

promise.catch((error) => {});

promise.then(undefined, (error) => {});
```

## Configuration

This rule accepts a configuration object with the following properties:

### ignore

type: `string[]`

A list of patterns to ignore when checking `catch` variable names. The pattern
can be a string or regular expression.

### name

type: `string`

default: `"error"`

The name to use for error variables in `catch` blocks. You can customize it
to something other than `'error'` (e.g., `'exception'`).

## How to use

## Version

This rule was added in v0.0.14.

## References

---

---
url: /docs/guide/usage/linter/rules/unicorn/consistent-assert.md
---

### What it does

Enforces consistent usage of the `assert` module.

### Why is this bad?

Inconsistent usage of the `assert` module can make code
harder to follow and understand.

`assert.ok(...)` is preferred as it makes the intent of
the assertion clearer.

### Examples

Examples of **incorrect** code for this rule:

```js
import assert from "node:assert";

assert(divide(10, 2) === 5);
```

Examples of **correct** code for this rule:

```js
import assert from "node:assert";

assert.ok(divide(10, 2) === 5);
```

## How to use

## Version

This rule was added in v0.16.9.

## References

---

---
url: /docs/guide/usage/linter/rules/unicorn/consistent-date-clone.md
---

### What it does

The Date constructor can clone a `Date` object directly when passed as an argument,
making timestamp conversion unnecessary. This rule enforces the use of the
direct `Date` cloning instead of using `.getTime()` for conversion.

### Why is this bad?

Using `.getTime()` to convert a `Date` object to a timestamp and then back to a
`Date` is redundant and unnecessary. Simply passing the `Date` object to the
`Date` constructor is cleaner and more efficient.

### Examples

Examples of **incorrect** code for this rule:

```js
new Date(date.getTime());
```

Examples of **correct** code for this rule:

```js
new Date(date);
```

## How to use

## Version

This rule was added in v0.15.13.

## References

---

---
url: /docs/guide/usage/linter/rules/unicorn/consistent-empty-array-spread.md
---

### What it does

When spreading a ternary in an array, we can use both `[]` and `''` as fallbacks,
but it's better to have consistent types in both branches.

### Why is this bad?

Having consistent types in both branches makes the code easier to read and understand.

### Examples

Examples of **incorrect** code for this rule:

```javascript
const array = [a, ...(foo ? [b, c] : "")];

const array = [a, ...(foo ? "bc" : [])];
```

Examples of **correct** code for this rule:

```javascript
const array = [a, ...(foo ? [b, c] : [])];

const array = [a, ...(foo ? "bc" : "")];
```

## How to use

## Version

This rule was added in v0.10.1.

## References

---

---
url: /docs/guide/usage/linter/rules/unicorn/consistent-existence-index-check.md
---

### What it does

Enforce consistent style for element existence checks with `indexOf()`,
`lastIndexOf()`, `findIndex()`, and `findLastIndex()`. This ensures
that comparisons are performed in a standard and clear way.

### Why is this bad?

This rule is meant to enforce a specific style and improve code clarity.
Using inconsistent comparison styles (e.g., `index < 0`, `index >= 0`)
can make the intention behind the code unclear, especially in large
codebases.

### Examples

Examples of **incorrect** code for this rule:

```javascript
const index = foo.indexOf("bar");
if (index < 0) {
}

const index = foo.indexOf("bar");
if (index >= 0) {
}
```

Examples of **correct** code for this rule:

```javascript
const index = foo.indexOf("bar");
if (index === -1) {
}

const index = foo.indexOf("bar");
if (index !== -1) {
}
```

## How to use

## Version

This rule was added in v0.12.0.

## References

---

---
url: /docs/guide/usage/linter/rules/unicorn/consistent-function-scoping.md
---

### What it does

Disallow functions that are declared in a scope which does not capture
any variables from the outer scope.

### Why is this bad?

Moving function declarations to the highest possible scope improves
readability, directly [improves performance](https://stackoverflow.com/questions/80802/does-use-of-anonymous-functions-affect-performance/81329#81329)
and allows JavaScript engines to better [optimize your performance](https://ponyfoo.com/articles/javascript-performance-pitfalls-v8#optimization-limit).

### Examples

Examples of **incorrect** code for this rule:

```js
export function doFoo(foo) {
  // Does not capture anything from the scope, can be moved to the outer scope
  function doBar(bar) {
    return bar === "bar";
  }
  return doBar;
}

function doFoo(foo) {
  const doBar = (bar) => {
    return bar === "bar";
  };
}
```

Examples of **correct** code for this rule:

```js
function doBar(bar) {
  return bar === "bar";
}

export function doFoo(foo) {
  return doBar;
}

export function doFoo(foo) {
  function doBar(bar) {
    return bar === "bar" && foo.doBar(bar);
  }
  return doBar;
}
```

### Limitations

This rule does not detect or remove extraneous code blocks inside of functions:

```js
function doFoo(foo) {
  {
    function doBar(bar) {
      return bar;
    }
  }

  return foo;
}
```

It also ignores functions that contain `JSXElement` references:

```jsx
function doFoo(FooComponent) {
  function Bar() {
    return <FooComponent />;
  }

  return Bar;
}
```

[Immediately invoked function expressions (IIFE)](https://en.wikipedia.org/wiki/Immediately_invoked_function_expression) are ignored:

```js
(function () {
  function doFoo(bar) {
    return bar;
  }
})();
```

## Configuration

This rule accepts a configuration object with the following properties:

### checkArrowFunctions

type: `boolean`

default: `true`

Whether to check scoping with arrow functions.

## How to use

## Version

This rule was added in v0.8.0.

## References

---

---
url: /docs/guide/usage/linter/rules/unicorn/consistent-template-literal-escape.md
---

### What it does

Enforce consistent style for escaping `${` in template literals.

### Why is this bad?

Using `\${` instead of `${` can improve readability and prevent confusion.

### Examples

Examples of **incorrect** code for this rule:

```js
const foo = `$\{a}`;
```

```js
const foo = `\$\{a}`;
```

Examples of **correct** code for this rule:

```js
const foo = `\${a}`;
```

## How to use

## Version

This rule was added in v1.60.0.

## References

---

---
url: /docs/guide/usage/linter/rules/unicorn/custom-error-definition.md
---

### What it does

Enforces the only valid way of Error subclassing. It works with any super class that ends in Error.

### Why is this bad?

Incorrectly defined custom errors can lead to unexpected behavior when
catching and identifying errors. Missing `super()` calls, wrong `name`
property values, or non-standard class names make error handling unreliable.

### Examples

Examples of **incorrect** code for this rule:

```js
class CustomError extends Error {
  constructor(message) {
    super(message);
    // The `this.message` assignment is useless as it's already set via the `super()` call.
    this.message = message;
    this.name = "CustomError";
  }
}

class CustomError extends Error {
  constructor(message) {
    super();
    // Pass the error message to `super()` instead of setting `this.message`.
    this.message = message;
    this.name = "CustomError";
  }
}

class CustomError extends Error {
  constructor(message) {
    super(message);
    // No `name` property set. The name property is needed so the
    // error shows up as `[CustomError: foo]` and not `[Error: foo]`.
  }
}

class CustomError extends Error {
  constructor(message) {
    super(message);
    // Use a string literal to set the `name` property as it will not change after minifying.
    this.name = this.constructor.name;
  }
}

class CustomError extends Error {
  constructor(message) {
    super(message);
    // The `name` property should be set to the class name.
    this.name = "MyError";
  }
}
```

Examples of **correct** code for this rule:

```js
class CustomError extends Error {
  constructor(message) {
    super(message);
    this.name = "CustomError";
  }
}

class CustomError extends Error {
  constructor() {
    super("My custom error");
    this.name = "CustomError";
  }
}

class CustomError extends TypeError {
  constructor() {
    super();
    this.name = "CustomError";
  }
}

class CustomError extends Error {
  name = "CustomError";
}
```

## How to use

## Version

This rule was added in v1.57.0.

## References

---

---
url: /docs/guide/usage/linter/rules/unicorn/empty-brace-spaces.md
---

### What it does

Removes the extra spaces or new line characters inside a pair of braces
that does not contain additional code. This ensures that braces are clean
and do not contain unnecessary spaces or newlines.

### Why is this bad?

Extra spaces inside braces can negatively impact the readability of the code.
Keeping braces clean and free of unnecessary characters improves consistency and
makes the code easier to understand and maintain.

### Examples

Examples of **incorrect** code for this rule:

```javascript
const a = {  };
class A {
}
```

Examples of **correct** code for this rule:

```javascript
const a = {};
class A {}
```

## How to use

## Version

This rule was added in v0.0.18.

## References

---

---
url: /docs/guide/usage/linter/rules/unicorn/error-message.md
---

### What it does

Enforces providing a `message` when creating built-in `Error` objects to
improve readability and debugging.

### Why is this bad?

Throwing an `Error` without a message, like `throw new Error()`, provides no context
on what went wrong, making debugging harder. A clear error message improves
code clarity and helps developers quickly identify issues.

### Examples

Examples of **incorrect** code for this rule:

```javascript
throw Error();
throw new TypeError();
```

Examples of **correct** code for this rule:

```javascript
throw new Error("Unexpected token");
throw new TypeError("Number expected");
```

## How to use

## Version

This rule was added in v0.0.14.

## References

---

---
url: /docs/guide/usage/linter/rules/unicorn/escape-case.md
---

### What it does

Enforces defining escape sequence values with uppercase characters rather than lowercase ones.
This promotes readability by making the escaped value more distinguishable from the identifier.

### Why is this bad?

Using lowercase characters in escape sequences makes them less readable and harder to distinguish
from surrounding code. Most style guides recommend uppercase for consistency and clarity.

### Examples

Examples of **incorrect** code for this rule:

```javascript
const foo = "\xa9";
const foo = "\ud834";
const foo = "\u{1d306}";
const foo = "\ca";
```

Examples of **correct** code for this rule:

```javascript
const foo = "\xA9";
const foo = "\uD834";
const foo = "\u{1D306}";
const foo = "\cA";
```

## How to use

## Version

This rule was added in v0.0.19.

## References

---

---
url: /docs/guide/usage/linter/rules/unicorn/explicit-length-check.md
---

### What it does

Enforce explicitly comparing the `length` or `size` property of a value.

### Why is this bad?

Using the explicit `length` or `size` properties can help make code clearer
and easier to understand, as it avoids relying on implicit truthy/falsy
evaluations.

### Examples

Examples of **incorrect** code for this rule:

```javascript
const isEmpty = foo.length == 0;
const isEmpty = foo.length < 1;
const isEmpty = 0 === foo.length;
const isEmpty = 0 == foo.length;
const isEmpty = 1 > foo.length;

const isEmpty = !foo.length;
const isEmpty = !(foo.length > 0);
const isEmptySet = !foo.size;
```

Examples of **correct** code for this rule:

```javascript
const isEmpty = foo.length === 0;

if (foo.length > 0 || bar.length > 0) {
}

const unicorn = foo.length > 0 ? 1 : 2;
```

## Configuration

This rule accepts a configuration object with the following properties:

### non-zero

type: `"greater-than" | "not-equal"`

default: `"greater-than"`

Configuration option to specify how non-zero length checks should be enforced.

#### `"greater-than"`

Enforces non-zero to be checked with `foo.length > 0`.

#### `"not-equal"`

Enforces non-zero to be checked with `foo.length !== 0`.

## How to use

## Version

This rule was added in v0.0.19.

## References

---

---
url: /docs/guide/usage/linter/rules/unicorn/explicit-timer-delay.md
---

### What it does

Enforce or disallow explicit `delay` argument for `setTimeout()` and
`setInterval()`.

### Why is this bad?

When using `setTimeout()` or `setInterval()`, the `delay` parameter is
optional and defaults to `0`. This rule allows you to enforce whether the
`delay` argument should always be explicitly provided or omitted when it's
`0`.

### Examples

Examples of **incorrect** code for this rule:

```javascript
setTimeout(() => console.log("Hello"));
setInterval(callback);
window.setTimeout(() => console.log("Hello"));
globalThis.setInterval(callback);
```

Examples of **correct** code for this rule:

```javascript
setTimeout(() => console.log("Hello"), 0);
setInterval(callback, 0);
window.setTimeout(() => console.log("Hello"), 0);
globalThis.setInterval(callback, 0);
setTimeout(() => console.log("Hello"), 1000);
setInterval(callback, 100);
```

With the `"never"` option, explicit `0` delays are disallowed and
non-zero delays are still allowed.

Examples of **incorrect** code for the `"never"` option:

```javascript
setTimeout(() => console.log("Hello"), 0);
setInterval(callback, 0);
window.setTimeout(() => console.log("Hello"), 0);
globalThis.setInterval(callback, 0);
```

Examples of **correct** code for the `"never"` option:

```javascript
setTimeout(() => console.log("Hello"));
setInterval(callback);
window.setTimeout(() => console.log("Hello"));
globalThis.setInterval(callback);
setTimeout(() => console.log("Hello"), 1000);
globalThis.setInterval(callback, 100);
```

## Configuration

This rule accepts one of the following string values:

### `"always"`

Require explicit `delay` argument for clarity.

### `"never"`

Disallow explicit `0` delay, prefer implicit default.

## How to use

## Version

This rule was added in v1.73.0.

## References

---

---
url: /docs/guide/usage/linter/rules/unicorn/filename-case.md
---

### What it does

Enforces a consistent case style for filenames to improve project organization and maintainability.
By default, `kebab-case` is enforced, but other styles can be configured.

Files named `index.js`, `index.ts`, etc. are exempt from this rule as they cannot reliably be
renamed to other casings (mainly just a problem with PascalCase).

### Why is this bad?

Inconsistent file naming conventions make it harder to locate files, navigate projects, and enforce
consistency across a codebase. Standardizing naming conventions improves readability, reduces cognitive
overhead, and aligns with best practices in large-scale development.

### Examples

Examples of **correct** filenames for each case:

#### `kebabCase`

* `some-file-name.js`
* `some-file-name.test.js`
* `some-file-name.test-utils.js`

#### `camelCase`

* `someFileName.js`
* `someFileName.test.js`
* `someFileName.testUtils.js`

#### `snakeCase`

* `some_file_name.js`
* `some_file_name.test.js`
* `some_file_name.test_utils.js`

#### `pascalCase`

* `SomeFileName.js`
* `SomeFileName.Test.js`
* `SomeFileName.TestUtils.js`

#### `lowercase`

Only rejects uppercase letters; separators are allowed.

* `somefilename.js`
* `some-file-name.js`
* `some_file_name.js`

#### `screamingSnakeCase`

* `SOME_FILE_NAME.js`
* `SOME_FILE_NAME.TEST.js`
* `SOME_FILE_NAME.TEST_UTILS.js`

## Configuration

This rule accepts a configuration object with the following properties:

### case

type: `"kebabCase" | "camelCase" | "snakeCase" | "pascalCase" | "lowercase" | "screamingSnakeCase"`

default: `null`

The case style to enforce for filenames.

You can set the `case` option like this:

```json
{
  "unicorn/filename-case": [
    "error",
    {
      "case": "kebabCase"
    }
  ]
}
```

### cases

type: `object`

default: `null`

The case style(s) to allow/enforce for filenames. `true` means the case style is allowed, `false` means it is banned.

You can set the `cases` option like this:

```json
{
  "unicorn/filename-case": [
    "error",
    {
      "cases": {
        "camelCase": true,
        "pascalCase": true
      }
    }
  ]
}
```

#### cases.camelCase

type: `boolean`

default: `false`

Whether camel case is allowed, e.g. `someFileName.js`.

#### cases.kebabCase

type: `boolean`

default: `false`

Whether kebab case is allowed, e.g. `some-file-name.js`.

#### cases.lowercase

type: `boolean`

default: `false`

Whether lowercase is allowed, e.g. `somefilename.js`.

#### cases.pascalCase

type: `boolean`

default: `false`

Whether pascal case is allowed, e.g. `SomeFileName.js`.

#### cases.screamingSnakeCase

type: `boolean`

default: `false`

Whether screaming snake case is allowed, e.g. `SOME_FILE_NAME.js`.

#### cases.snakeCase

type: `boolean`

default: `false`

Whether snake case is allowed, e.g. `some_file_name.js`.

### ignore

type: `string[]`

An array of regular expression patterns for filenames to ignore.

You can set the `ignore` option like this:

```json
{
  "unicorn/filename-case": [
    "error",
    {
      "ignore": ["^foo.*$"]
    }
  ]
}
```

### multipleFileExtensions

type: `boolean`

default: `true`

Whether to treat additional, `.`-separated parts of a filename as
parts of the extension rather than parts of the filename.

## How to use

## Version

This rule was added in v0.0.14.

## References

---

---
url: /docs/guide/usage/linter/rules/unicorn/import-style.md
---

### What it does

Enforce specific import styles per module.

### Why is this bad?

Some modules are easier to read when imported in a consistent way.
For example, utility modules often work better with named imports,
while modules that expose one primary interface are clearer as default imports.

### Examples

Examples of **incorrect** code for this rule:

```js
import util from "node:util";
```

Examples of **correct** code for this rule:

```js
import { promisify } from "node:util";
```

## Configuration

This rule accepts a configuration object with the following properties:

### checkDynamicImport

type: `boolean`

default: `true`

Whether dynamic import expressions are checked.

Set this to `false` to skip calls such as `await import("module")`.

With the default configuration, examples of **incorrect** code:

```js
async () => {
  const { red } = await import("chalk");
};
```

Examples of **correct** code:

```js
async () => {
  const { default: chalk } = await import("chalk");
};
```

### checkExportFrom

type: `boolean`

default: `false`

Whether export-from declarations are checked.

This is disabled by default. Set this to `true` to check declarations like
`export ... from "module"`.

With `{ "checkExportFrom": true }`, examples of **incorrect** code:

```js
export * from "node:util";
```

Examples of **correct** code:

```js
export { promisify } from "node:util";
```

### checkImport

type: `boolean`

default: `true`

Whether static import declarations are checked.

Set this to `false` to skip `import ... from "module"` and side-effect imports like
`import "module"`.

With the default configuration, examples of **incorrect** code:

```js
import { red } from "chalk";
```

Examples of **correct** code:

```js
import chalk from "chalk";
```

### checkRequire

type: `boolean`

default: `true`

Whether CommonJS `require()` calls are checked.

Set this to `false` to skip `require("module")` calls completely.

With the default configuration, examples of **incorrect** code:

```js
const util = require("node:util");
```

Examples of **correct** code:

```js
const { promisify } = require("node:util");
```

### extendDefaultStyles

type: `boolean`

default: `true`

Whether `styles` extends or replaces the built-in module preferences.

When this is `true`, entries in `styles` are merged with the default preferences. For
example, `{ "styles": { "path": { "named": true } } }` allows named imports from
`path` while leaving its default import style allowed. When this is `false`, only modules
configured in `styles` are checked.

With `{ "extendDefaultStyles": false, "styles": {} }`, examples of **correct** code:

```js
import { red } from "chalk";
```

### styles

type: `object`

default: `{}`

Per-module import style preferences.

Each key is a module specifier. Set the value to `false` to disable checking for the
module, or to an object that allows one or more import styles. The available styles are
`unassigned`, `default`, `namespace`, and `named`. When `extendDefaultStyles` is `true`,
these entries extend the built-in defaults instead of replacing them.

The default module preferences are default imports for `chalk`, `path`, and `node:path`,
and named imports for `util` and `node:util`.

With `{ "styles": { "node:util": { "named": true, "default": false } } }`,
examples of **incorrect** code:

```js
import util from "node:util";
```

Examples of **correct** code:

```js
import { promisify } from "node:util";
```

## How to use

## Version

This rule was added in v1.67.0.

## References

---

---
url: /docs/guide/usage/linter/rules/unicorn/max-nested-calls.md
---

### What it does

Limit the depth of nested calls.

This rule counts calls and constructor calls passed into other calls or
constructors. Fluent receiver chains and JSX wrappers are ignored.

### Why is this bad?

Deeply nested calls make code hard to read. Extracting intermediate
results into named variables improves readability.

### Examples

Examples of **incorrect** code for this rule:

```js
foo(bar(baz(qux())));
```

Examples of **correct** code for this rule:

```js
const value = baz(qux());
foo(bar(value));

// Fluent chains are ignored.
query().filter().map().toArray();
```

## Configuration

This rule accepts a configuration object with the following properties:

### max

type: `integer`

default: `3`

The maximum allowed nested call depth.

## How to use

## Version

This rule was added in v1.71.0.

## References

---

---
url: /docs/guide/usage/linter/rules/unicorn/new-for-builtins.md
---

### What it does

Enforces the use of `new` for the following builtins: `Object`, `Array`, `ArrayBuffer`, `BigInt64Array`,
`BigUint64Array`, `DataView`, `Date`, `Error`, `Float16Array`, `Float32Array`, `Float64Array`, `Function`, `Int8Array`,
`Int16Array`, `Int32Array`, `Map`, `WeakMap`, `Set`, `WeakSet`, `Promise`, `RegExp`, `Uint8Array`,
`Uint16Array`, `Uint32Array`, `Uint8ClampedArray`, `SharedArrayBuffer`, `Proxy`, `WeakRef`, `FinalizationRegistry`.

Disallows the use of `new` for the following builtins: `String`, `Number`, `Boolean`, `Symbol`, `BigInt`.

### Why is this bad?

Using `new` inconsistently can cause confusion. Constructors like `Array` and `RegExp` should always use `new`
to ensure the expected instance type. Meanwhile, `String`, `Number`, `Boolean`, `Symbol`, and `BigInt` should not use `new`,
as they create object wrappers instead of primitive values.

### Examples

Examples of **incorrect** code for this rule:

```javascript
const foo = new String("hello world");
const bar = Array(1, 2, 3);
const now = Date();
```

Examples of **correct** code for this rule:

```javascript
const foo = String("hello world");
const bar = new Array(1, 2, 3);
const now = String(new Date());
```

## How to use

## Version

This rule was added in v0.0.16.

## References

---

---
url: /docs/guide/usage/linter/rules/unicorn/no-abusive-eslint-disable.md
---

### What it does

Disallows `oxlint-disable` or `eslint-disable` comments without specifying rules.

### Why is this bad?

A general `oxlint-disable` or `eslint-disable` comment suppresses all lint errors, not just the intended one,
potentially hiding useful warnings and making debugging harder.

### Examples

Examples of **incorrect** code for this rule:

```javascript
/* eslint-disable */
console.log(message);

console.log(message); // eslint-disable-line

// eslint-disable-next-line
console.log(message);
```

```javascript
/* oxlint-disable */
console.log(message);

console.log(message); // oxlint-disable-line

// oxlint-disable-next-line
console.log(message);
```

Examples of **correct** code for this rule:

```javascript
/* eslint-disable no-console */
console.log(message);

console.log(message); // eslint-disable-line no-console

// eslint-disable-next-line no-console
console.log(message);
```

```javascript
/* oxlint-disable no-console */
console.log(message);

console.log(message); // oxlint-disable-line no-console

// oxlint-disable-next-line no-console
console.log(message);
```

## How to use

## Version

This rule was added in v0.0.18.

## References

---

---
url: /docs/guide/usage/linter/rules/unicorn/no-accessor-recursion.md
---

### What it does

Disallow recursive access to `this` within getters and setters.

### Why is this bad?

This rule prevents recursive access to `this` within getter and
setter methods in objects and classes, avoiding infinite recursion
and stack overflow errors.

### Examples

Examples of **incorrect** code for this rule:

```js
const foo = {
  get bar() {
    return this.bar;
  },
};

const baz = {
  set bar(value) {
    this.bar = value;
  },
};
```

Examples of **correct** code for this rule:

```js
const foo = {
  get bar() {
    return this.qux;
  },
};

const baz = {
  set bar(value) {
    this._bar = value;
  },
};
```

## How to use

## Version

This rule was added in v0.16.5.

## References

---

---
url: /docs/guide/usage/linter/rules/unicorn/no-anonymous-default-export.md
---

### What it does

Disallows anonymous functions and classes as default exports.

### Why is this bad?

Naming default exports improves searchability and ensures consistent
identifiers for a module’s default export in both declaration and import.

### Examples

Examples of **incorrect** code for this rule:

```javascript
export default class {}
export default function () {}
export default () => {};
module.exports = class {};
module.exports = function () {};
module.exports = () => {};
```

Examples of **correct** code for this rule:

```javascript
export default class Foo {}
export default function foo () {}

const foo = () => {};
export default foo;

module.exports = class Foo {};
module.exports = function foo () {};

const foo = () => {};
module.exports = foo;
```

## How to use

## Version

This rule was added in v0.3.3.

## References

---

---
url: /docs/guide/usage/linter/rules/unicorn/no-array-callback-reference.md
---

### What it does

Prevents passing a function reference directly to iterator methods.

### Why is this bad?

Passing functions to iterator methods can cause issues when the function is changed
without realizing that the iterator passes 2 more parameters to it (index and array).
This can lead to unexpected behavior when the function signature changes.

### Examples

Examples of **incorrect** code for this rule:

```js
const foo = array.map(callback);
array.forEach(callback);
const result = array.filter(lib.method);
```

Examples of **correct** code for this rule:

```js
const foo = array.map((element) => callback(element));
array.forEach((element) => {
  callback(element);
});
const result = array.filter((element) => lib.method(element));

// Built-in functions are allowed
const foo = array.map(String);
const bar = array.filter(Boolean);
```

## How to use

## Version

This rule was added in v1.19.0.

## References

---

---
url: /docs/guide/usage/linter/rules/unicorn/no-array-fill-with-reference-type.md
---

### What it does

Disallows using reference values as `Array#fill()` values.

### Why is this bad?

`Array#fill()` reuses the same value for every array element. When the
fill value is an object, array, class, or most constructed objects, all
elements point at the same reference and mutating one element mutates the
shared value observed by the others.

### Examples

Examples of **incorrect** code for this rule:

```js
const rows = new Array(3).fill({});
rows[0].selected = true; // Every row now has `selected`.
```

Examples of **correct** code for this rule:

```js
const rows = Array.from({ length: 3 }, () => ({}));
```

## How to use

## Version

This rule was added in v1.70.0.

## References

---

---
url: /docs/guide/usage/linter/rules/unicorn/no-array-for-each.md
---

### What it does

Forbids the use of `Array#forEach` in favor of a for loop.

### Why is this bad?

Benefits of [`for…of` statement](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/for...of) over the `forEach` method can include:

* Faster
* Better readability
* Ability to exit early with `break` or `return`

Additionally, using `for…of` has great benefits if you are using TypeScript, because it does not cause a function boundary to be crossed. This means that type-narrowing earlier on in the current scope will work properly while inside of the loop (without having to re-type-narrow). Furthermore, any mutated variables inside of the loop will picked up on for the purposes of determining if a variable is being used.

### Examples

Examples of **incorrect** code for this rule:

```javascript
const foo = [1, 2, 3];
foo.forEach((element) => {
  /* ... */
});
```

Examples of **correct** code for this rule:

```javascript
const foo = [1, 2, 3];
for (const element of foo) {
  /* ... */
}

for (const [index, element] of foo.entries()) {
  /* ... */
}
```

## How to use

## Version

This rule was added in v0.0.19.

## References

---

---
url: /docs/guide/usage/linter/rules/unicorn/no-array-method-this-argument.md
---

### What it does

Disallows the use of the `thisArg` parameter in array iteration methods such as
`map`, `filter`, `some`, `every`, and similar.

### Why is this bad?

The `thisArg` parameter makes code harder to understand and reason about. Instead,
prefer arrow functions or bind explicitly in a clearer way. Arrow functions inherit
`this` from the lexical scope, which is more intuitive and less error-prone.

### Examples

Examples of **incorrect** code for this rule:

```js
array.map(function (x) {
  return x + this.y;
}, this);
array.filter(function (x) {
  return x !== this.value;
}, this);
```

Examples of **correct** code for this rule:

```js
array.map((x) => x + this.y);
array.filter((x) => x !== this.value);
const self = this;
array.map(function (x) {
  return x + self.y;
});
```

## How to use

## Version

This rule was added in v0.16.12.

## References

---

---
url: /docs/guide/usage/linter/rules/unicorn/no-array-reduce.md
---

### What it does

Disallow `Array#reduce()` and `Array#reduceRight()`.

### Why is this bad?

`Array#reduce()` and `Array#reduceRight()` usually result in [hard-to-read](https://twitter.com/jaffathecake/status/1213077702300852224) and [less performant](https://www.richsnapp.com/article/2019/06-09-reduce-spread-anti-pattern) code. In almost every case, it can be replaced by `.map`, `.filter`, or a `for-of` loop.

It's only somewhat useful in the rare case of summing up numbers, which is allowed by default.

### Examples

Examples of **incorrect** code for this rule:

```javascript
array.reduce(reducer, initialValue);
array.reduceRight(reducer, initialValue);
```

## Configuration

This rule accepts a configuration object with the following properties:

### allowSimpleOperations

type: `boolean`

default: `true`

When set to `true`, allows simple operations (like summing numbers) in `reduce` and `reduceRight` calls.

## How to use

## Version

This rule was added in v0.0.19.

## References

---

---
url: /docs/guide/usage/linter/rules/unicorn/no-array-reverse.md
---

### What it does

Prefer using `Array#toReversed()` over `Array#reverse()`.

### Why is this bad?

`Array#reverse()` modifies the original array in place, which can lead to unintended side effects—especially
when the original array is used elsewhere in the code.

### Examples

Examples of **incorrect** code for this rule:

```js
const reversed = [...array].reverse();
```

Examples of **correct** code for this rule:

```js
const reversed = [...array].toReversed();
```

## Configuration

This rule accepts a configuration object with the following properties:

### allowExpressionStatement

type: `boolean`

default: `true`

This rule allows `array.reverse()` as an expression statement by default.
Set to `false` to forbid `Array#reverse()` even if it's an expression statement.

Examples of **incorrect** code for this rule with this option set to `false`:

```js
array.reverse();
```

## How to use

## Version

This rule was added in v1.15.0.

## References

---

---
url: /docs/guide/usage/linter/rules/unicorn/no-array-sort.md
---

### What it does

Prefer using `Array#toSorted()` over `Array#sort()`.

### Why is this bad?

`Array#sort()` modifies the original array in place, which can lead to unintended side effects—especially
when the original array is used elsewhere in the code.

### Examples

Examples of **incorrect** code for this rule:

```js
const sorted = [...array].sort();
```

Examples of **correct** code for this rule:

```js
const sorted = [...array].toSorted();
```

## Configuration

This rule accepts a configuration object with the following properties:

### allowAfterSpread

type: `boolean`

default: `false`

When set to `true`, allows sorting a fresh array created by a spread, e.g. `[...iterable].sort()`.
This avoids the double allocation of `toSorted()` when sorting an iterable such as a `Set`.

Example of **correct** code for this rule with `allowAfterSpread` set to `true`:

```js
const sorted = [...mySet].sort();
```

### allowExpressionStatement

type: `boolean`

default: `true`

When set to `true` (default), allows `array.sort()` as an expression statement.
Set to `false` to forbid `Array#sort()` even if it's an expression statement.

Example of **incorrect** code for this rule with `allowExpressionStatement` set to `false`:

```js
array.sort();
```

## How to use

## Version

This rule was added in v1.15.0.

## References

---

---
url: /docs/guide/usage/linter/rules/unicorn/no-await-expression-member.md
---

### What it does

Disallows member access from `await` expressions.

### Why is this bad?

When accessing a member from an `await` expression,
the `await` expression has to be parenthesized, which is not readable.

### Examples

Examples of **incorrect** code for this rule:

```javascript
async function bad() {
  const secondElement = (await getArray())[1];
}
```

Examples of **correct** code for this rule:

```javascript
async function good() {
  const [, secondElement] = await getArray();
}
```

## How to use

## Version

This rule was added in v0.0.19.

## References

---

---
url: /docs/guide/usage/linter/rules/unicorn/no-await-in-promise-methods.md
---

### What it does

Disallow using `await` in `Promise` method parameters.

### Why is this bad?

Using `await` on promises passed as arguments to `Promise.all()`,
`Promise.allSettled()`, `Promise.any()`, or `Promise.race()` is likely a
mistake.

### Examples

Examples of **incorrect** code for this rule:

```javascript
async function foo() {
  Promise.all([await promise, anotherPromise]);
  Promise.allSettled([await promise, anotherPromise]);
  Promise.any([await promise, anotherPromise]);
  Promise.race([await promise, anotherPromise]);
}
```

Examples of **correct** code for this rule:

```javascript
async function foo() {
  Promise.all([promise, anotherPromise]);
  Promise.allSettled([promise, anotherPromise]);
  Promise.any([promise, anotherPromise]);
  Promise.race([promise, anotherPromise]);
}
```

## How to use

## Version

This rule was added in v0.2.18.

## References

---

---
url: /docs/guide/usage/linter/rules/unicorn/no-confusing-array-with.md
---

### What it does

Disallows confusing uses of [`Array#with()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/with).

### Why is this bad?

`Array#with()` treats a negative index as an offset from the end of the array, unlike
methods such as `slice()` or `splice()`. Using a negative static index is usually a mistake.
Using `.length` as the index always produces `undefined`, since valid indices are
`0 .. length - 1`.

### Examples

Examples of **incorrect** code for this rule:

```javascript
array.with(-1, value);
array.with(array.length, value);
```

Examples of **correct** code for this rule:

```javascript
array.with(array.length - 1, value);
array.with(index, value);
```

## How to use

## Version

This rule was added in v1.73.0.

## References

---

---
url: /docs/guide/usage/linter/rules/unicorn/no-console-spaces.md
---

### What it does

Disallows leading/trailing space inside `console.log()` and similar methods.

### Why is this bad?

The `console.log()` method and similar methods join the parameters
with a space so adding a leading/trailing space to a parameter,
results in two spaces being added.

### Examples

Examples of **incorrect** code for this rule:

```javascript
console.log("abc ", "def");
```

Examples of **correct** code for this rule:

```javascript
console.log("abc", "def");
```

## How to use

## Version

This rule was added in v0.0.14.

## References

---

---
url: /docs/guide/usage/linter/rules/unicorn/no-document-cookie.md
---

### What it does

Disallows direct use of
[`document.cookie`](https://developer.mozilla.org/en-US/docs/Web/API/Document/cookie).

### Why is this bad?

It's not recommended to use
[`document.cookie`](https://developer.mozilla.org/en-US/docs/Web/API/Document/cookie)
directly as it's easy to get the string wrong. Instead, you should use
the [Cookie Store
API](https://developer.mozilla.org/en-US/docs/Web/API/Cookie_Store_API)
or a [cookie library](https://npmx.dev/search?q=cookie).

### Examples

Examples of **incorrect** code for this rule:

```javascript
document.cookie =
  "foo=bar" +
  "; Path=/" +
  "; Domain=example.com" +
  "; expires=Fri, 31 Dec 9999 23:59:59 GMT" +
  "; Secure";
```

Examples of **correct** code for this rule:

```javascript
async function storeCookies() {
  await cookieStore.set({
    name: "foo",
    value: "bar",
    expires: Date.now() + 24 * 60 * 60 * 1000,
    domain: "example.com",
  });
}
```

## How to use

## Version

This rule was added in v0.0.18.

## References

---

---
url: /docs/guide/usage/linter/rules/unicorn/no-empty-file.md
---

### What it does

Disallows files that do not contain any meaningful code.

This includes files that consist only of:

* Whitespace
* Comments
* Directives (e.g., `"use strict"`)
* Empty statements (`;`)
* Empty blocks (`{}`)
* Hashbangs (`#!/usr/bin/env node`)

### Why is this bad?

Files with no executable or exportable content are typically unintentional
or left over from refactoring. They clutter the codebase and may confuse
tooling or developers by appearing to serve a purpose when they do not.

### Examples

Examples of **incorrect** code for this rule:

```js
```

```js
// Comment
```

```js
/* Comment */
```

```js
"use strict";
```

```js
```

```js
{
}
```

```js
#!/usr/bin/env node
```

Examples of **correct** code for this rule:

```js
const x = 0;
```

```js
"use strict";
const x = 0;
```

```js
const x = 0;
```

```js
{
  const x = 0;
}
```

## How to use

## Version

This rule was added in v0.0.15.

## References

---

---
url: /docs/guide/usage/linter/rules/unicorn/no-hex-escape.md
---

### What it does

Enforces a convention of using [Unicode escapes](https://mathiasbynens.be/notes/javascript-escapes#unicode)
instead of [hexadecimal escapes](https://mathiasbynens.be/notes/javascript-escapes#hexadecimal) for
consistency and clarity.

### Why is this bad?

Using hexadecimal escapes can be less readable and harder to understand
when compared to Unicode escapes.

### Examples

Examples of **incorrect** code for this rule:

```javascript
const foo = "\x1B";
const foo = `\x1B${bar}`;
```

Examples of **correct** code for this rule:

```javascript
const foo = "\u001B";
const foo = `\u001B${bar}`;
```

## How to use

## Version

This rule was added in v0.0.18.

## References

---

---
url: /docs/guide/usage/linter/rules/unicorn/no-immediate-mutation.md
---

### What it does

Disallows mutating a variable immediately after initialization.

### Why is this bad?

When you initialize a variable and immediately mutate it, it's cleaner to include
the mutation in the initialization. This makes the code more readable and reduces
the number of statements.

### Examples

Examples of **incorrect** code for this rule:

```js
const array = [1, 2];
array.push(3);

const object = { foo: 1 };
object.bar = 2;

const set = new Set([1, 2]);
set.add(3);

const map = new Map([["foo", 1]]);
map.set("bar", 2);
```

Examples of **correct** code for this rule:

```js
const array = [1, 2, 3];

const object = { foo: 1, bar: 2 };

const set = new Set([1, 2, 3]);

const map = new Map([
  ["foo", 1],
  ["bar", 2],
]);
```

## How to use

## Version

This rule was added in v1.35.0.

## References

---

---
url: /docs/guide/usage/linter/rules/unicorn/no-instanceof-array.md
---

### What it does

Require `Array.isArray()` instead of `instanceof Array`.

### Why is this bad?

The `instanceof Array` check doesn't work across realms/contexts.
For example, frames/windows in browsers or the `vm` module in Node.js.

### Examples

Examples of **incorrect** code for this rule:

```javascript
array instanceof Array;
[1, 2, 3] instanceof Array;
```

Examples of **correct** code for this rule:

```javascript
Array.isArray(array);
Array.isArray([1, 2, 3]);
```

## How to use

## Version

This rule was added in v0.0.8.

## References

---

---
url: /docs/guide/usage/linter/rules/unicorn/no-instanceof-builtins.md
---

### What it does

Disallows the use of `instanceof` with ECMAScript built-in constructors because:

* it breaks across execution contexts (`iframe`, Web Worker, Node VM, etc.);
* it is often misleading (e.g. `instanceof Array` fails for a subclass);
* there is always a clearer and safer alternative (`Array.isArray`, `typeof`, `Buffer.isBuffer`, …).

### Why is this bad?

`instanceof` breaks across execution contexts (`iframe`, Web Worker, Node `vm`),
and may give misleading results for subclasses or exotic objects.

### Examples

Examples of **incorrect** code for this rule:

```javascript
if (arr instanceof Array) { … }
if (el instanceof HTMLElement) { … }
```

Examples of **correct** code for this rule:

```javascript
if (Array.isArray(arr)) { … }
if (el?.nodeType === 1) { … }
```

## Configuration

This rule accepts a configuration object with the following properties:

### exclude

type: `string[]`

default: `[]`

Constructor names to exclude from checking.

### include

type: `string[]`

default: `[]`

Additional constructor names to check beyond the default set.
Use this to extend the rule with additional constructors.

### strategy

type: `"strict" | "loose"`

default: `"loose"`

Controls which built-in constructors are checked.

#### `"strict"`

Additionally checks Error types, collections, typed arrays, and other built-in constructors.

#### `"loose"`

Only checks Array, Function, Error (if `useErrorIsError` is true), and primitive wrappers.

### useErrorIsError

type: `boolean`

default: `false`

When `true`, checks `instanceof Error` and suggests using `Error.isError()` instead.
Requires [the `Error.isError()` function](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error/isError)
to be available.

## How to use

## Version

This rule was added in v0.16.12.

## References

---

---
url: /docs/guide/usage/linter/rules/unicorn/no-invalid-fetch-options.md
---

### What it does

Disallow invalid options in `fetch()` and `new Request()`. Specifically, this rule ensures that
a body is not provided when the method is `GET` or `HEAD`, as it will result in a `TypeError`.

### Why is this bad?

The `fetch()` function throws a `TypeError` when the method is `GET` or `HEAD` and a body is provided.
This can lead to unexpected behavior and errors in your code. By disallowing such invalid options,
the rule ensures that requests are correctly configured and prevents unnecessary errors.

### Examples

Examples of **incorrect** code for this rule:

```javascript
const response = await fetch("/", { method: "GET", body: "foo=bar" });

const request = new Request("/", { method: "GET", body: "foo=bar" });
```

Examples of **correct** code for this rule:

```javascript
const response = await fetch("/", { method: "POST", body: "foo=bar" });

const request = new Request("/", { method: "POST", body: "foo=bar" });
```

## How to use

## Version

This rule was added in v0.15.12.

## References

---

---
url: /docs/guide/usage/linter/rules/unicorn/no-invalid-remove-event-listener.md
---

### What it does

It warns when you use a non-function value as the second argument of `removeEventListener`.

### Why is this bad?

The [`removeEventListener`](https://developer.mozilla.org/en-US/docs/Web/API/EventTarget/removeEventListener) function must be called with a reference to the same function that was passed to [`addEventListener`](https://developer.mozilla.org/en-US/docs/Web/API/EventTarget/addEventListener). Calling `removeEventListener` with an inline function or the result of an inline `.bind()` call is indicative of an error, and won't actually remove the listener.

### Examples

Examples of **incorrect** code for this rule:

```javascript
el.removeEventListener("click", () => {});
el.removeEventListener("click", function () {});
```

Examples of **correct** code for this rule:

```javascript
el.removeEventListener("click", handler);
el.removeEventListener("click", handler.bind(this));
```

## How to use

## Version

This rule was added in v0.0.16.

## References

---

---
url: /docs/guide/usage/linter/rules/unicorn/no-length-as-slice-end.md
---

### What it does

Disallow using `length` as the end argument of a `slice` call.

### Why is this bad?

Passing `length` as the end argument of a `slice` call is unnecessary and can be confusing.

### Examples

Examples of **incorrect** code for this rule:

```javascript
foo.slice(1, foo.length);
```

Examples of **correct** code for this rule:

```javascript
foo.slice(1);
```

## How to use

## Version

This rule was added in v0.7.0.

## References

---

---
url: /docs/guide/usage/linter/rules/unicorn/no-lonely-if.md
---

### What it does

Disallow `if` statements as the only statement in `if` blocks without `else`.

### Why is this bad?

It can be confusing to have an `if` statement without an `else` clause as the only statement in an `if` block.

### Examples

Examples of **incorrect** code for this rule:

```javascript
if (foo) {
  if (bar) {
  }
}
if (foo) if (bar) baz();
```

Examples of **correct** code for this rule:

```javascript
if (foo && bar) {
}
if (foo && bar) baz();
```

## How to use

## Version

This rule was added in v0.0.18.

## References

---

---
url: /docs/guide/usage/linter/rules/unicorn/no-magic-array-flat-depth.md
---

### What it does

Disallow magic numbers for [`Array.prototype.flat`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/flat)
depth.

### Why is this bad?

Magic numbers are hard to understand and maintain.
When calling `Array.prototype.flat`, it is usually called with
`1` or `Infinity`. If you are using a different number, it is
better to add a comment explaining the reason for the depth provided.

### Examples

Examples of **incorrect** code for this rule:

```javascript
array.flat(2);
array.flat(20);
```

Examples of **correct** code for this rule:

```javascript
array.flat(2 /* explanation */);
array.flat(1);
array.flat();
array.flat(Infinity);
```

## How to use

## Version

This rule was added in v0.4.2.

## References

---

---
url: /docs/guide/usage/linter/rules/unicorn/no-negated-condition.md
---

### What it does

Disallow negated conditions.

### Why is this bad?

Negated conditions are more difficult to understand. Code can be made more readable by inverting the condition.

### Examples

Examples of **incorrect** code for this rule:

```javascript
if (!a) {
  doSomethingC();
} else {
  doSomethingB();
}

!a ? doSomethingC() : doSomethingB();
```

Examples of **correct** code for this rule:

```javascript
if (a) {
  doSomethingB();
} else {
  doSomethingC();
}

a ? doSomethingB() : doSomethingC();
```

## How to use

## Version

This rule was added in v0.0.18.

## References

---

---
url: /docs/guide/usage/linter/rules/unicorn/no-negation-in-equality-check.md
---

### What it does

Disallow negated expressions on the left of (in)equality checks.

### Why is this bad?

A negated expression on the left of an (in)equality check is likely a mistake from trying to negate the whole condition.

### Examples

Examples of **incorrect** code for this rule:

```javascript
if (!foo === bar) {
}

if (!foo !== bar) {
}
```

Examples of **correct** code for this rule:

```javascript
if (foo !== bar) {
}

if (!(foo === bar)) {
}
```

## How to use

## Version

This rule was added in v0.5.3.

## References

---

---
url: /docs/guide/usage/linter/rules/unicorn/no-nested-ternary.md
---

### What it does

Disallow deeply nested ternary expressions.

Nested ternary expressions that are only one level deep and wrapped in parentheses are allowed by this rule.

### Why is this bad?

Nesting ternary expressions can make code more difficult to understand.

### Examples

Examples of **incorrect** code for this rule:

```javascript
const foo = i > 5 ? (i < 100 ? true : false) : true;
const foo = i > 5 ? true : i < 100 ? true : i < 1000 ? true : false;
```

Examples of **correct** code for this rule:

```javascript
const foo = i > 5 ? (i < 100 ? true : false) : true;
const foo = i > 5 ? (i < 100 ? true : false) : i < 100 ? true : false;
```

## How to use

## Version

This rule was added in v0.0.18.

## References

---

---
url: /docs/guide/usage/linter/rules/unicorn/no-new-array.md
---

### What it does

Disallow `new Array()`.

### Why is this bad?

When using the `Array` constructor with one argument, it's not clear whether the argument is meant to be the length of the array or the only element.

### Examples

Examples of **incorrect** code for this rule:

```javascript
const array = new Array(1);
const array = new Array(42);
const array = new Array(foo);
```

Examples of **correct** code for this rule:

```javascript
const array = Array.from({ length: 42 });
const array = [42];
```

## How to use

## Version

This rule was added in v0.0.16.

## References

---

---
url: /docs/guide/usage/linter/rules/unicorn/no-new-buffer.md
---

### What it does

Disallows the deprecated `new Buffer()` constructor.

### Why is this bad?

Enforces the use of [Buffer.from](https://nodejs.org/api/buffer.html#static-method-bufferfromarray) and [Buffer.alloc()](https://nodejs.org/api/buffer.html#static-method-bufferallocsize-fill-encoding) instead of [new Buffer()](https://nodejs.org/api/buffer.html#new-bufferarray), which has been deprecated since Node.js 4.

### Examples

Examples of **incorrect** code for this rule:

```javascript
const buffer = new Buffer(10);
```

Examples of **correct** code for this rule:

```javascript
const buffer = Buffer.alloc(10);
```

## How to use

## Version

This rule was added in v0.0.16.

## References

---

---
url: /docs/guide/usage/linter/rules/unicorn/no-null.md
---

### What it does

Disallow the use of the `null` literal, to encourage using `undefined` instead.

### Why is this bad?

There are some reasons for using `undefined` instead of `null`.

* From experience, most developers use `null` and `undefined` inconsistently and interchangeably, and few know when to use which.
* Supporting both `null` and `undefined` complicates input validation.
* Using `null` makes TypeScript types more verbose: `type A = {foo?: string | null}` vs `type A = {foo?: string}`.

### Examples

Examples of **incorrect** code for this rule:

```javascript
let foo = null;
```

Examples of **correct** code for this rule:

```javascript
let foo;
```

## Configuration

This rule accepts a configuration object with the following properties:

### checkArguments

type: `boolean`

default: `true`

When set to `true`, disallow the use of `null` as a direct function call or constructor argument.

### checkStrictEquality

type: `boolean`

default: `false`

When set to `true`, the rule will also check strict equality/inequality comparisons (`===` and `!==`) against `null`.

## How to use

## Version

This rule was added in v0.0.21.

## References

---

---
url: /docs/guide/usage/linter/rules/unicorn/no-object-as-default-parameter.md
---

### What it does

Disallow the use of an object literal as a default value for a parameter.

### Why is this bad?

Default parameters should not be passed to a function through an object literal. The `foo = {a: false}` parameter works fine if only used with one option. As soon as additional options are added, you risk replacing the whole `foo = {a: false, b: true}` object when passing only one option: `{a: true}`. For this reason, object destructuring should be used instead.

### Examples

Examples of **incorrect** code for this rule:

```javascript
function foo(foo = { a: false }) {}
```

Examples of **correct** code for this rule:

```javascript
function foo({ a = false } = {}) {}
```

## How to use

## Version

This rule was added in v0.0.16.

## References

---

---
url: /docs/guide/usage/linter/rules/unicorn/no-process-exit.md
---

### What it does

Disallow all usage of `process.exit()`.

### Why is this bad?

`process.exit()` should generally only be used in command-line utilities. In all other
types of applications, the code should throw an error instead.

### Examples

Examples of **incorrect** code for this rule:

```javascript
if (problem) {
  process.exit(1);
}
```

Examples of **correct** code for this rule:

```javascript
if (problem) {
  throw new Error("message");
}
```

```
#!/usr/bin/env node
if (problem) {
  process.exit(1);
}
```

## How to use

## Version

This rule was added in v0.2.9.

## References

---

---
url: /docs/guide/usage/linter/rules/unicorn/no-single-promise-in-promise-methods.md
---

### What it does

Disallow passing single-element arrays to `Promise` methods.

### Why is this bad?

Passing a single-element array to `Promise.all()`, `Promise.any()`, or
`Promise.race()` is likely a mistake.

### Examples

Examples of **incorrect** code for this rule:

```javascript
async function bad() {
  const foo = await Promise.all([promise]);
  const foo = await Promise.any([promise]);
  const foo = await Promise.race([promise]);
  const promise = Promise.all([nonPromise]);
}
```

Examples of **correct** code for this rule:

```javascript
async function good() {
  const foo = await promise;
  const promise = Promise.resolve(nonPromise);
  const foo = await Promise.all(promises);
  const foo = await Promise.any([promise, anotherPromise]);
  const [{ value: foo, reason: error }] = await Promise.allSettled([promise]);
}
```

## How to use

## Version

This rule was added in v0.2.18.

## References

---

---
url: /docs/guide/usage/linter/rules/unicorn/no-static-only-class.md
---

### What it does

Disallow `class` declarations that exclusively contain `static` members.

### Why is this bad?

A `class` with only `static` members should just be defined as an object instead.

### Examples

Examples of **incorrect** code for this rule:

```javascript
class A {
  static a() {}
}
```

Examples of **correct** code for this rule:

```javascript
class A {
  static a() {}

  constructor() {}
}
```

```javascript
const X = {
  foo: false,
  bar() {},
};
```

```javascript
class X {
  static #foo = false; // private field
  static bar() {}
}
```

## How to use

## Version

This rule was added in v0.0.16.

## References

---

---
url: /docs/guide/usage/linter/rules/unicorn/no-thenable.md
---

### What it does

Disallow defining a `then` property.

### Why is this bad?

If an object is defined as "thenable", once it's accidentally
used in an `await` expression, it may cause problems.

### Examples

Examples of **incorrect** code for this rule:

```javascript
async function example() {
  const foo = {
    unicorn: 1,
    then() {},
  };

  const { unicorn } = await foo;

  console.log("after"); // <- This will never execute
}
```

Examples of **correct** code for this rule:

```javascript
async function example() {
  const foo = {
    unicorn: 1,
    bar() {},
  };

  const { unicorn } = await foo;

  console.log("after");
}
```

## How to use

## Version

This rule was added in v0.0.13.

## References

---

---
url: /docs/guide/usage/linter/rules/unicorn/no-this-assignment.md
---

### What it does

Disallow assigning `this` to a variable.

### Why is this bad?

Assigning `this` to a variable is unnecessary and confusing.

### Examples

Examples of **incorrect** code for this rule:

```javascript
const foo = this;
class Bar {
  method() {
    foo.baz();
  }
}

new Bar().method();
```

Examples of **correct** code for this rule:

```javascript
class Bar {
  constructor(fooInstance) {
    this.fooInstance = fooInstance;
  }
  method() {
    this.fooInstance.baz();
  }
}

new Bar(this).method();
```

## How to use

## Version

This rule was added in v0.0.18.

## References

---

---
url: /docs/guide/usage/linter/rules/unicorn/no-typeof-undefined.md
---

### What it does

Disallow `typeof` comparisons with `undefined`.

### Why is this bad?

Checking if a value is `undefined` by using `typeof value === 'undefined'` is needlessly verbose. It's generally better to compare against `undefined` directly. The only time `typeof` is needed is when a global variable potentially does not exists, in which case, using `globalThis.value === undefined` may be better.

### Examples

Examples of **incorrect** code for this rule:

```javascript
typeof foo === "undefined";
```

Examples of **correct** code for this rule:

```javascript
foo === undefined;
```

## Configuration

This rule accepts a configuration object with the following properties:

### checkGlobalVariables

type: `boolean`

default: `false`

If set to `true`, also report `typeof x === "undefined"` when `x` may be a global
variable that is not declared (commonly checked via `typeof foo === "undefined"`).

## How to use

## Version

This rule was added in v0.0.18.

## References

---

---
url: /docs/guide/usage/linter/rules/unicorn/no-unnecessary-array-flat-depth.md
---

### What it does

Disallows passing `1` to `Array.prototype.flat`.

### Why is this bad?

Passing `1` is unnecessary.

### Examples

Examples of **incorrect** code for this rule:

```js
foo.flat(1);
```

Examples of **correct** code for this rule:

```js
foo.flat();
```

## How to use

## Version

This rule was added in v0.16.12.

## References

---

---
url: /docs/guide/usage/linter/rules/unicorn/no-unnecessary-array-splice-count.md
---

### What it does

Disallows passing `.length` or `Infinity` as the `deleteCount` or `skipCount` argument of `Array#splice()` or `Array#toSpliced()`.

### Why is this bad?

When calling `Array#splice(start, deleteCount)` or `Array#toSpliced(start, skipCount)`,
omitting the `deleteCount` or `skipCount` argument will delete or skip all elements after `start`.
Using `.length` or `Infinity` is unnecessary and makes the code more verbose.

### Examples

Examples of **incorrect** code for this rule:

```js
array.splice(1, array.length);
array.splice(1, Infinity);
array.splice(1, Number.POSITIVE_INFINITY);
array.toSpliced(1, array.length);
```

Examples of **correct** code for this rule:

```js
array.splice(1);
array.toSpliced(1);
```

## How to use

## Version

This rule was added in v1.20.0.

## References

---

---
url: /docs/guide/usage/linter/rules/unicorn/no-unnecessary-await.md
---

### What it does

Disallow awaiting on non-promise values.

### Why is this bad?

The `await` operator should only be used on `Promise` values.

### Examples

Examples of **incorrect** code for this rule:

```javascript
async function bad() {
  await await promise;
}
```

Examples of **correct** code for this rule:

```javascript
async function bad() {
  await promise;
}
```

## How to use

## Version

This rule was added in v0.0.12.

## References

---

---
url: /docs/guide/usage/linter/rules/unicorn/no-unnecessary-slice-end.md
---

### What it does

Disallows unnecessarily passing a second argument to `slice(...)`, for
cases where it would not change the result.

### Why is this bad?

When using `.slice(...)` without a second argument, the second argument
defaults to the object's length. As such, passing the length explicitly

* or using `Infinity` - is unnecessary.

### Examples

Examples of **incorrect** code for this rule:

```js
const foo = string.slice(1, string.length);
const foo = string.slice(1, Infinity);
const foo = string.slice(1, Number.POSITIVE_INFINITY);
```

Examples of **correct** code for this rule:

```js
const foo = string.slice(1);
```

## How to use

## Version

This rule was added in v0.16.10.

## References

---

---
url: /docs/guide/usage/linter/rules/unicorn/no-unreadable-array-destructuring.md
---

### What it does

Disallows destructuring values from an array in ways that are difficult to read.

### Why is this bad?

Destructuring can be very useful, but it can also make some code harder to read.
This rule prevents ignoring consecutive values (e.g. `let [,,foo] = array`)
when destructuring from an array.

### Examples

Examples of **incorrect** code for this rule:

```javascript
const [, , foo] = parts;
const [, , ...rest] = parts;
```

Examples of **correct** code for this rule:

```javascript
const [foo] = parts;
const foo = parts[3];
const rest = parts.slice(2);

// One is fine
const [, foo] = parts;
```

## How to use

## Version

This rule was added in v0.0.19.

## References

---

---
url: /docs/guide/usage/linter/rules/unicorn/no-unreadable-iife.md
---

### What it does

This rule disallows IIFEs with a parenthesized arrow function body.

### Why is this bad?

IIFEs with a parenthesized arrow function body are unreadable.

### Examples

Examples of **incorrect** code for this rule:

```javascript
const foo = ((bar) => (bar ? bar.baz : baz))(getBar());

const foo = ((bar, baz) => ({ bar, baz }))(bar, baz);
```

Examples of **correct** code for this rule:

```javascript
const bar = getBar();
const foo = bar ? bar.baz : baz;

const getBaz = (bar) => (bar ? bar.baz : baz);
const foo = getBaz(getBar());

const foo = ((bar) => {
  return bar ? bar.baz : baz;
})(getBar());
```

## How to use

## Version

This rule was added in v0.0.19.

## References

---

---
url: /docs/guide/usage/linter/rules/unicorn/no-useless-collection-argument.md
---

### What it does

Disallow useless values or fallbacks in `Set`, `Map`, `WeakSet`, or `WeakMap`.

### Why is this bad?

It is unnecessary to pass an empty array or empty string when
constructing a `Set`, `Map`, `WeakSet`, or `WeakMap`, since
they accept nullish values.

It is also unnecessary to provide a fallback for possible nullish values.

### Examples

Examples of **incorrect** code for this rule:

```js
const set = new Set([]);
const set = new Set("");
```

Examples of **correct** code for this rule:

```js
const set = new Set();
```

Examples of **incorrect** code for this rule:

```js
const set = new Set(foo ?? []);
const set = new Set(foo ?? "");
```

Examples of **correct** code for this rule:

```js
const set = new Set(foo);
```

## How to use

## Version

This rule was added in v1.28.0.

## References

---

---
url: /docs/guide/usage/linter/rules/unicorn/no-useless-error-capture-stack-trace.md
---

### What it does

Disallows unnecessary `Error.captureStackTrace(…)` in error constructors.

### Why is this bad?

Calling `Error.captureStackTrace(…)` inside the constructor of a built-in `Error` subclass
is unnecessary, since the `Error` constructor calls it automatically.

### Examples

Examples of **incorrect** code for this rule:

```js
class MyError extends Error {
  constructor() {
    Error.captureStackTrace(this, MyError);
  }
}
```

Examples of **correct** code for this rule:

```js
class MyError extends Error {
  constructor() {
    // No need to call Error.captureStackTrace
  }
}
```

## How to use

## Version

This rule was added in v1.20.0.

## References

---

---
url: /docs/guide/usage/linter/rules/unicorn/no-useless-fallback-in-spread.md
---

### What it does

Disallow useless fallback when spreading in object literals.

### Why is this bad?

Spreading [falsy values](https://developer.mozilla.org/en-US/docs/Glossary/Falsy) in object literals won't add any unexpected properties, so it's unnecessary to add an empty object as fallback.

### Examples

Examples of **incorrect** code for this rule:

```javascript
const object = { ...(foo || {}) };
```

Examples of **correct** code for this rule:

```javascript
const object = { ...foo };
const object = { ...(foo || { not: "empty" }) };
```

## How to use

## Version

This rule was added in v0.0.16.

## References

---

---
url: /docs/guide/usage/linter/rules/unicorn/no-useless-iterator-to-array.md
---

### What it does

Disallow unnecessary `.toArray()` on iterators.

### Why is this bad?

[`Iterator.prototype.toArray()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Iterator/toArray)
converts an iterator to an array. However, this conversion is unnecessary in many cases:

* The following builtins accept an iterable directly:
  * `Map` constructor
  * `WeakMap` constructor
  * `Set` constructor
  * `WeakSet` constructor
  * `TypedArray` constructor
  * `Array.from(…)`
  * `TypedArray.from(…)`
  * `Object.fromEntries(…)`
* `for…of` can iterate over any iterable, so converting to an array first is unnecessary.
* `yield*` can delegate to any iterable, so converting to an array first is unnecessary.
* `Promise.{all,allSettled,any,race}(…)` accept an iterable, so `.toArray()` is unnecessary.
  Removing `.toArray()` here can change a synchronous throw into an asynchronous rejection
  when iteration fails, so these cases are suggestions rather than autofixes.
* The spread operator (`...`) works on any iterable, so converting to an array first is unnecessary.
* Some `Array` methods also exist on `Iterator`, so converting to an array to call them is unnecessary:
  * `.every()`
  * `.find()`
  * `.forEach()`
  * `.reduce()`
  * `.some()`

`Array` callbacks receive additional arguments (for example, the 3rd `array` argument)
that `Iterator` callbacks do not. Removing `.toArray()` can change behavior if callbacks
depend on those extra arguments, so those cases are reported as suggestions.

This rule does not flag `.filter()`, `.map()`, or `.flatMap()` because their `Iterator`
versions return iterators, not arrays, so the semantics differ.

### Examples

Examples of **incorrect** code for this rule:

```js
const set = new Set(iterator.toArray());

const results = await Promise.all(iterator.toArray());

for (const item of iterator.toArray());

function* foo() {
  yield* iterator.toArray();
}

const items = [...iterator.toArray()];

call(...iterator.toArray());

iterator.toArray().every(fn);
```

Examples of **correct** code for this rule:

```js
const set = new Set(iterator);

const results = await Promise.all(iterator);

for (const item of iterator);

function * foo() {
	yield * iterator;
}

const items = [...iterator];

call(...iterator);

iterator.every(fn);

`.filter()` returns an array on Array but an iterator on Iterator
iterator.toArray().filter(fn);
```

## How to use

## Version

This rule was added in v1.59.0.

## References

---

---
url: /docs/guide/usage/linter/rules/unicorn/no-useless-length-check.md
---

### What it does

It checks for an unnecessary array length check in a logical expression.

The cases are:

* `array.length === 0 || array.every(Boolean)` (`array.every` returns `true` if array is has elements)
* `array.length > 0 && array.some(Boolean)` (`array.some` returns `false` if array is empty)

### Why is this bad?

An extra unnecessary length check is done.

### Examples

Examples of **incorrect** code for this rule:

```javascript
if (array.length === 0 || array.every(Boolean)) {
  // do something!
}
```

Examples of **correct** code for this rule:

```javascript
if (array.every(Boolean)) {
  // do something!
}
```

## How to use

## Version

This rule was added in v0.0.19.

## References

---

---
url: /docs/guide/usage/linter/rules/unicorn/no-useless-promise-resolve-reject.md
---

### What it does

Disallows returning values wrapped in `Promise.resolve` or `Promise.reject`
in an async function or a `Promise#then`/`catch`/`finally` callback.

### Why is this bad?

Wrapping a return value in `Promise.resolve` in an async function
or a `Promise#then`/`catch`/`finally` callback is unnecessary as all
return values in async functions and promise callback functions are
already wrapped in a `Promise`.

Similarly, returning an error wrapped in `Promise.reject` is equivalent
to simply `throw`ing the error. This is the same for `yield`ing in
async generators as well.

### Examples

Examples of **incorrect** code for this rule:

```javascript
async () => Promise.resolve(bar);
```

Examples of **correct** code for this rule:

```javascript
async () => bar;
```

## Configuration

This rule accepts a configuration object with the following properties:

### allowReject

type: `boolean`

default: `false`

If set to `true`, allows the use of `Promise.reject` in async functions and promise callbacks.

## How to use

## Version

This rule was added in v0.0.18.

## References

---

---
url: /docs/guide/usage/linter/rules/unicorn/no-useless-spread.md
---

### What it does

Disallows using spread syntax in following, unnecessary cases:

* Spread an array literal as elements of an array literal
* Spread an array literal as arguments of a call or a `new` call
* Spread an object literal as properties of an object literal
* Use spread syntax to clone an array created inline

### Why is this bad?

The following builtins accept an iterable, so it's unnecessary to
convert the iterable to an array:

* `Map` constructor
* `WeakMap` constructor
* `Set` constructor
* `WeakSet` constructor
* `TypedArray` constructor
* `Array.from(…)`
* `TypedArray.from(…)`
* `Promise.{all,allSettled,any,race}(…)`
* `Object.fromEntries(…)`

The `for…of` loop can iterate over any iterable object not just array,
so it's unnecessary to convert the iterable to an array.

The `yield*` can delegate to another iterable, so it's unnecessary to
convert the iterable to an array.

### Examples

Examples of **incorrect** code for this rule:

```javascript
const array = [firstElement, ...[secondElement], thirdElement];

await Promise.all([...iterable]);

for (const foo of [...set]);

function* foo() {
  yield* [...anotherGenerator()];
}

function foo(bar) {
  return [...bar.map((x) => x * 2)];
}
```

Examples of **correct** code for this rule:

```javascript
const array = [firstElement, secondElement, thirdElement];

await Promise.all(iterable);

for (const foo of set);

function* foo() {
  yield* anotherGenerator();
}

function foo(bar) {
  return bar.map((x) => x * 2);
}
```

## How to use

## Version

This rule was added in v0.0.19.

## References

---

---
url: /docs/guide/usage/linter/rules/unicorn/no-useless-switch-case.md
---

### What it does

Disallows useless `default` cases in `switch` statements.

### Why is this bad?

An empty case before the last `default` case is useless, as the
`default` case will catch it regardless.

### Examples

Examples of **incorrect** code for this rule:

```javascript
switch (foo) {
  case 1:
  default:
    handleDefaultCase();
    break;
}
```

Examples of **correct** code for this rule:

```javascript
switch (foo) {
  case 1:
  case 2:
    handleCase1And2();
    break;
}
```

## How to use

## Version

This rule was added in v0.0.18.

## References

---

---
url: /docs/guide/usage/linter/rules/unicorn/no-useless-undefined.md
---

### What it does

Prevents usage of `undefined` in cases where it would be useless.

::: warning
This rule can conflict with the default behaviors of the `eslint/array-callback-return`
and `eslint/getter-return` rules. For both rules, you can set
the `allowImplicit` option to avoid conflicts.
:::

### Why is this bad?

`undefined` is the default value for new variables, parameters,
return statements, etc, so specifying `undefined` in these cases
is pointless.

### Examples

Examples of **incorrect** code for this rule:

```javascript
let foo = undefined;
const noop = () => undefined;
```

Examples of **correct** code for this rule:

```javascript
let foo;
const noop = () => {};
```

## Configuration

This rule accepts a configuration object with the following properties:

### checkArguments

type: `boolean`

default: `true`

Whether to check for useless `undefined` in function call arguments.

### checkArrowFunctionBody

type: `boolean`

default: `true`

Whether to check for useless `undefined` in arrow function bodies.

## How to use

## Version

This rule was added in v0.6.1.

## References

---

---
url: /docs/guide/usage/linter/rules/unicorn/no-zero-fractions.md
---

### What it does

Prevents the use of zero fractions.

### Why is this bad?

There is no difference in JavaScript between, for example, `1`, `1.0` and `1.`, so prefer the former for consistency and brevity.

### Examples

Examples of **incorrect** code for this rule:

```javascript
const foo = 1.0;
const foo = -1.0;
const foo = 123_456.000_000;
```

Examples of **correct** code for this rule:

```javascript
const foo = 1;
const foo = -1;
const foo = 123456;
const foo = 1.1;
```

## How to use

## Version

This rule was added in v0.0.18.

## References

---

---
url: /docs/guide/usage/linter/rules/unicorn/number-literal-case.md
---

### What it does

This rule enforces proper case for numeric literals.

### Why is this bad?

When both an identifier and a numeric literal are in
lower case, it can be hard to differentiate between them.

### Examples

Examples of **incorrect** code for this rule:

```javascript
const foo = 0XFF;
const foo = 0xff;
const foo = 0Xff;
const foo = 0Xffn;

const foo = 0B10;
const foo = 0B10n;

const foo = 0O76;
const foo = 0O76n;

const foo = 2E-5;
```

Examples of **correct** code for this rule:

```javascript
const foo = 0xFF;
const foo = 0b10;
const foo = 0o76;
const foo = 0xFFn;
const foo = 2e+5;
```

## How to use

## Version

This rule was added in v0.0.18.

## References

---

---
url: /docs/guide/usage/linter/rules/unicorn/numeric-separators-style.md
---

### What it does

Enforces a convention of grouping digits using numeric separators.

### Why is this bad?

A long series of digits can be difficult to read, and
it can be difficult to determine the value of the number at a glance.
Breaking up the digits with numeric separators (`_`) can greatly
improve readability.

Compare the following two numbers and how easy it is to understand their magnitude:

```js
1000000000;
1_000_000_000;
```

This rule also enforces proper group size, for example
enforcing that the `_` separator is used every 3 digits.

### Examples

Examples of **incorrect** code for this rule:

```javascript
const invalid = [1_23_4444, 1_234.56789, 0xab_c_d_ef, 0b10_00_1111, 0o1_0_44_21, 1_294_28771_2n];
```

Examples of **correct** code for this rule:

```javascript
const valid = [1_234_567, 1_234.567_89, 0xab_cd_ef, 0b1000_1111, 0o10_4421, 1_294_287_712n];
```

## Configuration

This rule accepts a configuration object with the following properties:

### binary

type: `object`

default: `{"groupLength":4, "minimumDigits":0}`

Configuration for binary literals (e.g. `0b1010_0001` and bigint variants).
Controls how digits are grouped and when separators are applied.

#### binary.groupLength

type: `integer`

default: `0`

The number of digits per group when inserting numeric separators.
For example, a `groupLength` of 3 formats `1234567` as `1_234_567`.

#### binary.minimumDigits

type: `integer`

default: `0`

The minimum number of digits required before grouping is applied.
Values with fewer digits than this threshold will not be grouped.

#### binary.onlyIfContainsSeparator

type: `boolean`

Only enforce the rule when the numeric literal already contains a separator (`_`).

When `true`, numbers without separators are left as-is; when `false` (default),
grouping will be enforced for eligible numbers even if they don't include separators yet.

### hexadecimal

type: `object`

default: `{"groupLength":2, "minimumDigits":0}`

Configuration for hexadecimal literals (e.g. `0xAB_CD`, `0Xab_cd`, and bigint variants).
Controls how digits are grouped and when separators are applied.

#### hexadecimal.groupLength

type: `integer`

default: `0`

The number of digits per group when inserting numeric separators.
For example, a `groupLength` of 3 formats `1234567` as `1_234_567`.

#### hexadecimal.minimumDigits

type: `integer`

default: `0`

The minimum number of digits required before grouping is applied.
Values with fewer digits than this threshold will not be grouped.

#### hexadecimal.onlyIfContainsSeparator

type: `boolean`

Only enforce the rule when the numeric literal already contains a separator (`_`).

When `true`, numbers without separators are left as-is; when `false` (default),
grouping will be enforced for eligible numbers even if they don't include separators yet.

### number

type: `object`

Configuration for decimal numbers (integers, fraction parts, and exponents).
Controls how digits are grouped and when separators are applied.

#### number.fractionGroupLength

type: `integer`

default: `Infinity`

The size a group of digits in the fractional part (after the decimal point) should be.

#### number.groupLength

type: `integer`

default: `0`

The number of digits per group when inserting numeric separators.
For example, a `groupLength` of 3 formats `1234567` as `1_234_567`.

#### number.minimumDigits

type: `integer`

default: `0`

The minimum number of digits required before grouping is applied.
Values with fewer digits than this threshold will not be grouped.

#### number.onlyIfContainsSeparator

type: `boolean`

Only enforce the rule when the numeric literal already contains a separator (`_`).

When `true`, numbers without separators are left as-is; when `false` (default),
grouping will be enforced for eligible numbers even if they don't include separators yet.

### octal

type: `object`

default: `{"groupLength":4, "minimumDigits":0}`

Configuration for octal literals (e.g. `0o1234_5670` and bigint variants).
Controls how digits are grouped and when separators are applied.

#### octal.groupLength

type: `integer`

default: `0`

The number of digits per group when inserting numeric separators.
For example, a `groupLength` of 3 formats `1234567` as `1_234_567`.

#### octal.minimumDigits

type: `integer`

default: `0`

The minimum number of digits required before grouping is applied.
Values with fewer digits than this threshold will not be grouped.

#### octal.onlyIfContainsSeparator

type: `boolean`

Only enforce the rule when the numeric literal already contains a separator (`_`).

When `true`, numbers without separators are left as-is; when `false` (default),
grouping will be enforced for eligible numbers even if they don't include separators yet.

### onlyIfContainsSeparator

type: `boolean`

default: `false`

Only enforce the rule when the numeric literal already contains a separator (`_`).

When `true`, numbers without separators are left as-is; when `false` (default),
grouping will be enforced for eligible numbers even if they don't include separators yet.

## How to use

## Version

This rule was added in v0.0.19.

## References

---

---
url: /docs/guide/usage/linter/rules/unicorn/prefer-add-event-listener.md
---

### What it does

Enforces the use of `.addEventListener()` and `.removeEventListener()` over their `on`-function counterparts.

For example, `foo.addEventListener('click', handler);` is preferred over `foo.onclick = handler;` for HTML DOM Events.

### Why is this bad?

There are [numerous advantages of using `addEventListener`](https://stackoverflow.com/questions/6348494/addeventlistener-vs-onclick/35093997#35093997). Some of these advantages include registering unlimited event handlers and optionally having the event handler invoked only once.

### Examples

Examples of **incorrect** code for this rule:

```javascript
foo.onclick = () => {};
```

Examples of **correct** code for this rule:

```javascript
foo.addEventListener("click", () => {});
```

## How to use

## Version

This rule was added in v0.0.16.

## References

---

---
url: /docs/guide/usage/linter/rules/unicorn/prefer-array-find.md
---

### What it does

Encourages using `Array.prototype.find` and `Array.prototype.findLast` instead of
taking the first or last matching element from `filter(...)`.

### Why is this bad?

Using `filter(...)[0]` or array destructuring to get the first match is less
efficient and more verbose than using `find(...)`. `find` and `findLast`
short-circuit when a match is found, whereas `filter` evaluates the entire array.

### Examples

Examples of **incorrect** code for this rule:

```js
const match = users.filter((u) => u.id === id)[0];
const match = users.filter(fn).shift();
const [match] = users.filter(fn);

const match = users.filter(fn).at(-1);
const match = users.filter(fn).pop();
```

Examples of **correct** code for this rule:

```js
const match = users.find((u) => u.id === id);
const match = users.find(fn);

const match = users.findLast(fn);
```

## How to use

## Version

This rule was added in v0.16.12.

## References

---

---
url: /docs/guide/usage/linter/rules/unicorn/prefer-array-flat.md
---

### What it does

Prefers `Array#flat()` over legacy techniques to flatten arrays.

### Why is this bad?

ES2019 introduced a new method [`Array#flat()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/flat) that flatten arrays.

This rule aims to standardize the use of `Array#flat()` over legacy techniques to flatten arrays.

### Examples

Examples of **incorrect** code for this rule:

```javascript
const foo = array.flatMap((x) => x);
const foo = array.reduce((a, b) => a.concat(b), []);
const foo = array.reduce((a, b) => [...a, ...b], []);
const foo = [].concat(maybeArray);
const foo = [].concat(...array);
const foo = [].concat.apply([], array);
const foo = Array.prototype.concat.apply([], array);
const foo = Array.prototype.concat.call([], maybeArray);
const foo = Array.prototype.concat.call([], ...array);
```

Examples of **correct** code for this rule:

```javascript
const foo = array.flat();
const foo = [maybeArray].flat();
```

## How to use

## Version

This rule was added in v0.0.20.

## References

---

---
url: /docs/guide/usage/linter/rules/unicorn/prefer-array-flat-map.md
---

### What it does

Prefers the use of `.flatMap()` when `map().flat()` are used together.

### Why is this bad?

It is slightly more efficient to use `.flatMap(…)` instead of `.map(…).flat()`.

### Examples

Examples of **incorrect** code for this rule:

```javascript
const bar = [1, 2, 3].map((i) => [i]).flat();
```

Examples of **correct** code for this rule:

```javascript
const bar = [1, 2, 3].flatMap((i) => [i]);
```

## How to use

## Version

This rule was added in v0.0.14.

## References

---

---
url: /docs/guide/usage/linter/rules/unicorn/prefer-array-index-of.md
---

### What it does

Enforces using `indexOf` or `lastIndexOf` instead of `findIndex` or `findLastIndex`
when the callback is a simple strict equality comparison.

### Why is this bad?

Using `findIndex(x => x === value)` is unnecessarily verbose when `indexOf(value)`
accomplishes the same thing more concisely and clearly. It also avoids the overhead
of creating a callback function.

### Examples

Examples of **incorrect** code for this rule:

```js
values.findIndex((x) => x === "foo");
values.findLastIndex((x) => x === "bar");
```

Examples of **correct** code for this rule:

```js
values.indexOf("foo");
values.lastIndexOf("bar");
```

## How to use

## Version

This rule was added in v0.16.12.

## References

---

---
url: /docs/guide/usage/linter/rules/unicorn/prefer-array-some.md
---

### What it does

Prefers using [`Array#some()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/some) over [`Array#find()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/find), [`Array#findLast()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/findLast) with comparing to `undefined`,
or [`Array#findIndex()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/findIndex), [`Array#findLastIndex()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/findLastIndex)
and a non-zero length check on the result of [`Array#filter()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/filter)

### Why is this bad?

Using `.some()` is more idiomatic and easier to read.

### Examples

Examples of **incorrect** code for this rule:

```javascript
const foo = array.find(fn) ? bar : baz;
const foo = array.findLast((elem) => hasRole(elem)) !== null;
foo.findIndex(bar) < 0;
foo.findIndex((element) => element.bar === 1) !== -1;
foo.findLastIndex((element) => element.bar === 1) !== -1;
array.filter(fn).length === 0;
```

Examples of **correct** code for this rule:

```javascript
const foo = array.some(fn) ? bar : baz;
foo.some((element) => element.bar === 1);
!array.some(fn);
```

## How to use

## Version

This rule was added in v0.0.18.

## References

---

---
url: /docs/guide/usage/linter/rules/unicorn/prefer-at.md
---

### What it does

Prefer the [`Array#at()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/at) and
[`String#at()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/at)
methods for index access.

This rule also discourages using [`String#charAt()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/charAt).

### Why is this bad?

The `.at()` method is more readable and consistent for accessing elements by index,
especially for negative indices which access elements from the end of the array or string.

### Examples

Examples of **incorrect** code for this rule:

```js
const foo = array[array.length - 1];
const foo = array.slice(-1)[0];
const foo = string.charAt(string.length - 1);
```

Examples of **correct** code for this rule:

```js
const foo = array.at(-1);
const foo = array.at(-5);
const foo = string.at(-1);
```

## Configuration

This rule accepts a configuration object with the following properties:

### checkAllIndexAccess

type: `boolean`

default: `false`

Check all index access, not just special patterns like `array.length - 1`.
When enabled, `array[0]`, `array[1]`, etc. will also be flagged.

### getLastElementFunctions

type: `string[]`

default: `[]`

List of function names to treat as "get last element" functions.
These functions will be checked for `.at(-1)` usage.

## How to use

## Version

This rule was added in v1.20.0.

## References

---

---
url: /docs/guide/usage/linter/rules/unicorn/prefer-bigint-literals.md
---

### What it does

Requires using BigInt literals (e.g. `123n`) instead of calling the `BigInt()` constructor
with literal arguments such as numbers or numeric strings

### Why is this bad?

Using `BigInt(…)` with literal values is unnecessarily verbose and less idiomatic than using
a BigInt literal.

### Examples

Examples of **incorrect** code for this rule:

```js
BigInt(0);
BigInt(123);
BigInt(0xff);
BigInt(1e3);
BigInt("42");
BigInt("0x10");
```

Examples of **correct** code for this rule:

```js
0n;
123n;
0xffn;
1000n;
// Non-integer, dynamic, or non-literal input:
BigInt(x);
BigInt("not-a-number");
BigInt("1.23");
```

## How to use

## Version

This rule was added in v1.30.0.

## References

---

---
url: /docs/guide/usage/linter/rules/unicorn/prefer-blob-reading-methods.md
---

### What it does

Recommends using `Blob#text()` and `Blob#arrayBuffer()` over `FileReader#readAsText()` and `FileReader#readAsArrayBuffer()`.

### Why is this bad?

`FileReader` predates promises, and the newer [`Blob#arrayBuffer()`](https://developer.mozilla.org/en-US/docs/Web/API/Blob/arrayBuffer) and [`Blob#text()`](https://developer.mozilla.org/en-US/docs/Web/API/Blob/text) methods are much cleaner and easier to use.

### Examples

Examples of **incorrect** code for this rule:

```javascript
async function bad() {
  const arrayBuffer = await new Promise((resolve, reject) => {
    const fileReader = new FileReader();
    fileReader.addEventListener("load", () => {
      resolve(fileReader.result);
    });
    fileReader.addEventListener("error", () => {
      reject(fileReader.error);
    });
    fileReader.readAsArrayBuffer(blob);
  });
}
```

Examples of **correct** code for this rule:

```javascript
async function good() {
  const arrayBuffer = await blob.arrayBuffer();
}
```

## How to use

## Version

This rule was added in v0.0.16.

## References

---

---
url: /docs/guide/usage/linter/rules/unicorn/prefer-class-fields.md
---

### What it does

Prefers class field declarations over `this` assignments in constructors for static values.

### Why is this bad?

Class field declarations are more readable and less error-prone than assigning static
values to `this` in the constructor. Using class fields keeps the constructor cleaner
and makes the intent clearer.

### Examples

Examples of **incorrect** code for this rule:

```ts
class Foo {
  constructor() {
    this.bar = 1;
  }
}

class MyError extends Error {
  constructor(message: string) {
    super(message);
    this.name = "MyError";
  }
}

class Foo {
  foo = "foo";
  constructor() {
    this.foo = "bar";
  }
}
```

Examples of **correct** code for this rule:

```js
class Foo {
  bar = 1;
}

class MyError extends Error {
  name = "MyError";
}

class Foo {
  foo = "bar";
}
```

## How to use

## Version

This rule was added in v1.20.0.

## References

---

---
url: /docs/guide/usage/linter/rules/unicorn/prefer-classlist-toggle.md
---

### What it does

Prefers the use of `element.classList.toggle(className, condition)` over
conditional add/remove patterns.

### Why is this bad?

The `toggle()` method is more concise and expressive than using conditional
logic to switch between `add()` and `remove()`.

### Examples

Examples of **incorrect** code for this rule:

```javascript
if (condition) {
  element.classList.add("className");
} else {
  element.classList.remove("className");
}

condition ? element.classList.add("className") : element.classList.remove("className");

element.classList[condition ? "add" : "remove"]("className");
```

Examples of **correct** code for this rule:

```javascript
element.classList.toggle("className", condition);
```

## How to use

## Version

This rule was added in v1.20.0.

## References

---

---
url: /docs/guide/usage/linter/rules/unicorn/prefer-code-point.md
---

### What it does

Prefer usage of `String#codePointAt` over `String#charCodeAt`.
Prefer usage of `String.fromCodePoint` over `String.fromCharCode`.

### Why is this bad?

Unicode is better supported in [`String#codePointAt()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/codePointAt) and [`String.fromCodePoint()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/fromCodePoint).

[Difference between `String.fromCodePoint()` and `String.fromCharCode()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/fromCodePoint#compared_to_fromcharcode)

### Examples

Examples of **incorrect** code for this rule:

```javascript
"🦄".charCodeAt(0);
String.fromCharCode(0x1f984);
```

Examples of **correct** code for this rule:

```javascript
"🦄".codePointAt(0);
String.fromCodePoint(0x1f984);
```

## How to use

## Version

This rule was added in v0.0.16.

## References

---

---
url: /docs/guide/usage/linter/rules/unicorn/prefer-date-now.md
---

### What it does

Prefers use of `Date.now()` over `new Date().getTime()` or `new Date().valueOf()`.

### Why is this bad?

Using `Date.now()` is shorter and nicer than `new Date().getTime()`, and avoids unnecessary instantiation of `Date` objects.

### Examples

Examples of **incorrect** code for this rule:

```javascript
const ts = new Date().getTime();
const ts = new Date().valueOf();
```

Examples of **correct** code for this rule:

```javascript
const ts = Date.now();
```

## How to use

## Version

This rule was added in v0.0.16.

## References

---

---
url: /docs/guide/usage/linter/rules/unicorn/prefer-default-parameters.md
---

### What it does

Instead of reassigning a function parameter, default parameters should be used. The `foo = foo || 123` statement evaluates to `123` when `foo` is falsy, possibly leading to confusing behavior, whereas default parameters only apply when passed an `undefined` value.
This rule only reports reassignments to literal values.

You should disable this rule if you want your functions to deal with `null` and other falsy values the same way as `undefined`.
Default parameters are exclusively applied [when `undefined` is received.](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Functions/Default_parameters#passing_undefined_vs._other_falsy_values).
However, we recommend [moving away from `null`](https://github.com/sindresorhus/meta/discussions/7).

### Why is this bad?

Using default parameters makes it clear that a parameter has a default value, improving code readability and maintainability.

### Examples

Examples of **incorrect** code for this rule:

```js
function abc(foo) {
  foo = foo || "bar";
}

function abc(foo) {
  const bar = foo || "bar";
}
```

Examples of **correct** code for this rule:

```js
function abc(foo = "bar") {}

function abc(bar = "bar") {}

function abc(foo) {
  foo = foo || bar();
}
```

## How to use

## Version

This rule was added in v1.33.0.

## References

---

---
url: /docs/guide/usage/linter/rules/unicorn/prefer-dom-node-append.md
---

### What it does

Enforces the use of, for example, `document.body.append(div);` over `document.body.appendChild(div);` for DOM nodes.

### Why is this bad?

There are [some advantages of using `Node#append()`](https://developer.mozilla.org/en-US/docs/Web/API/ParentNode/append), like the ability to append multiple nodes and to append both [`DOMString`](https://developer.mozilla.org/en-US/docs/Web/API/DOMString) and DOM node objects.

### Examples

Examples of **incorrect** code for this rule:

```javascript
foo.appendChild(bar);
```

Examples of **correct** code for this rule:

```javascript
foo.append(bar);
```

## How to use

## Version

This rule was added in v0.0.18.

## References

---

---
url: /docs/guide/usage/linter/rules/unicorn/prefer-dom-node-dataset.md
---

### What it does

Use [`.dataset`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/dataset) on DOM elements over `getAttribute(…)`, `.setAttribute(…)`, `.removeAttribute(…)` and `.hasAttribute(…)`.

### Why is this bad?

The `dataset` property is a map of strings that contains all the `data-*` attributes from the element. It is a convenient way to access all of them at once.

### Examples

Examples of **incorrect** code for this rule:

```javascript
element.setAttribute("data-unicorn", "🦄");
```

Examples of **correct** code for this rule:

```javascript
element.dataset.unicorn = "🦄";
```

## How to use

## Version

This rule was added in v0.0.18.

## References

---

---
url: /docs/guide/usage/linter/rules/unicorn/prefer-dom-node-remove.md
---

### What it does

Prefers the use of `child.remove()` over `parentNode.removeChild(child)`.

### Why is this bad?

The DOM function [`Node#remove()`](https://developer.mozilla.org/en-US/docs/Web/API/ChildNode/remove) is preferred
over the indirect removal of an object with [`Node#removeChild()`](https://developer.mozilla.org/en-US/docs/Web/API/Node/removeChild).

### Examples

Examples of **incorrect** code for this rule:

```javascript
parentNode.removeChild(childNode);
```

Examples of **correct** code for this rule:

```javascript
childNode.remove();
```

## How to use

## Version

This rule was added in v0.0.18.

## References

---

---
url: /docs/guide/usage/linter/rules/unicorn/prefer-dom-node-text-content.md
---

### What it does

Enforces the use of `.textContent` over `.innerText` for DOM nodes.

### Why is this bad?

There are some disadvantages of using `.innerText`.

* `.innerText` returns rendered text and ignores hidden content, while `.textContent` returns the node's full text content.
* `.innerText` can trigger reflow because it takes CSS styles into account.
* `.innerText` is defined only for HTMLElement objects, while `.textContent` is defined for all Node objects.

### Examples

Examples of **incorrect** code for this rule:

```javascript
const text = foo.innerText;
```

Examples of **correct** code for this rule:

```javascript
const text = foo.textContent;
```

## How to use

## Version

This rule was added in v0.0.21.

## References

---

---
url: /docs/guide/usage/linter/rules/unicorn/prefer-event-target.md
---

### What it does

Prefers `EventTarget` over `EventEmitter`.

This rule reduces the bundle size and makes your code more cross-platform friendly.

See the [differences](https://nodejs.org/api/events.html#eventtarget-and-event-api) between `EventEmitter` and `EventTarget`.

### Why is this bad?

While [`EventEmitter`](https://nodejs.org/api/events.html#class-eventemitter) is only available in Node.js, [`EventTarget`](https://developer.mozilla.org/en-US/docs/Web/API/EventTarget) is also available in *Deno* and browsers.

### Examples

Examples of **incorrect** code for this rule:

```javascript
class Foo extends EventEmitter {}
```

Examples of **correct** code for this rule:

```javascript
class Foo extends OtherClass {}
```

## How to use

## Version

This rule was added in v0.0.18.

## References

---

---
url: /docs/guide/usage/linter/rules/unicorn/prefer-export-from.md
---

### What it does

When re-exporting from a module, it's unnecessary to import and then export.
It can be done in a single export…from declaration.
This rule encourages using direct re-export syntax (export ... from) instead of importing and then exporting.
It helps reduce boilerplate code and keeps the module scope clean by avoiding unnecessary local bindings.

### Why is this bad?

Separating re-exports into import and export statements is discouraged because it
unnecessarily pollutes the current module's scope and adds redundant boilerplate code.

### Examples

Examples of **incorrect** code for this rule:

```js
import defaultExport from "./foo.js";
export default defaultExport;
```

Examples of **correct** code for this rule:

```js
export { default } from "./foo.js";
```

Examples of **incorrect** code for this rule:

```js
import { named } from "./foo.js";
export { named };
```

Examples of **correct** code for this rule:

```js
export { named } from "./foo.js";
```

## Configuration

This rule accepts a configuration object with the following properties:

### checkUsedVariables

type: `boolean`

default: `true`

When false, if any import binding is used somewhere other than a re-export, all variables in the import declaration are ignored.

## How to use

## Version

This rule was added in v1.70.0.

## References

---

---
url: /docs/guide/usage/linter/rules/unicorn/prefer-global-this.md
---

### What it does

Enforces the use of [`globalThis`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/globalThis) instead of
environment‑specific global object aliases (`window`, `self`, or `global`).

Using the standard `globalThis` makes your code portable across browsers, Web Workers, Node.js,
and future JavaScript runtimes.

### Why is this bad?

**Portability** – `window` is only defined in browser main threads, `self` is used in Web Workers,
and `global` is Node‑specific. Choosing the wrong alias causes runtime crashes when the code is
executed outside of its original environment.

**Clarity** – `globalThis` clearly communicates that you are referring to the global object itself
rather than a particular platform.

### Examples

Examples of **incorrect** code for this rule:

```js
// Browser‑only
window.alert("Hi");

// Node‑only
if (typeof global.Buffer !== "undefined") {
}

// Web Worker‑only
self.postMessage("done");
```

Examples of **correct** code for this rule:

```js
globalThis.alert("Hi");

if (typeof globalThis.Buffer !== "undefined") {
}

globalThis.postMessage("done");
```

## How to use

## Version

This rule was added in v0.16.12.

## References

---

---
url: /docs/guide/usage/linter/rules/unicorn/prefer-import-meta-properties.md
---

### What it does

Prefer `import.meta.{dirname,filename}` over legacy
techniques for getting file paths.

### Why is this bad?

Starting with Node.js 20.11, `import.meta.dirname` and `import.meta.filename`
have been introduced in ES modules.
`import.meta.filename` is equivalent to `url.fileURLToPath(import.meta.url)`.
`import.meta.dirname` is equivalent to `path.dirname(import.meta.filename)`.
This rule replaces legacy patterns with `import.meta.dirname` and `import.meta.filename`.

### Examples

Examples of **incorrect** code for this rule:

```js
import path from "node:path";
import { fileURLToPath } from "url";

const filename = fileURLToPath(import.meta.url);
const dirname = path.dirname(fileURLToPath(import.meta.url));
const dirname = path.dirname(import.meta.filename);
const dirname = fileURLToPath(new URL(".", import.meta.url));
```

Examples of **correct** code for this rule:

```js
const filename = import.meta.filename;
const dirname = import.meta.dirname;
```

## How to use

## Version

This rule was added in v1.59.0.

## References

---

---
url: /docs/guide/usage/linter/rules/unicorn/prefer-includes.md
---

### What it does

Prefer `includes()` over `indexOf()` when checking for existence/non-existence.
All built-ins have `.includes()` in addition to `.indexOf()`.

### Why is this bad?

The `.includes()` method is more readable and less error-prone than `.indexOf()`.

### Examples

Examples of **incorrect** code for this rule:

```javascript
if (str.indexOf("foo") !== -1) {
}
```

Examples of **correct** code for this rule:

```javascript
if (str.includes("foo")) {
}
```

## How to use

## Version

This rule was added in v0.0.18.

## References

---

---
url: /docs/guide/usage/linter/rules/unicorn/prefer-keyboard-event-key.md
---

### What it does

Enforces the use of [`KeyboardEvent#key`](https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent/key)
over [`KeyboardEvent#keyCode`](https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent/keyCode),
which is deprecated.

The `.key` property is also more semantic and readable.

### Why is this bad?

The `keyCode`, `which`, and `charCode` properties are deprecated
and should be avoided in favor of the `key` property.

### Examples

Examples of **incorrect** code for this rule:

```js
window.addEventListener("keydown", (event) => {
  if (event.keyCode === 8) {
    console.log("Backspace was pressed");
  }
});

window.addEventListener("keydown", (event) => {
  console.log(event.keyCode);
});
```

Examples of **correct** code for this rule:

```js
window.addEventListener("keydown", (event) => {
  if (event.key === "Backspace") {
    console.log("Backspace was pressed");
  }
});

window.addEventListener("click", (event) => {
  console.log(event.key);
});
```

## How to use

## Version

This rule was added in v1.33.0.

## References

---

---
url: /docs/guide/usage/linter/rules/unicorn/prefer-logical-operator-over-ternary.md
---

### What it does

This rule finds ternary expressions that can be simplified to a logical operator.

### Why is this bad?

Using a logical operator is shorter and simpler than a ternary expression.

### Examples

Examples of **incorrect** code for this rule:

```javascript
const foo = bar ? bar : baz;
console.log(foo ? foo : bar);
```

Examples of **correct** code for this rule:

```javascript
const foo = bar || baz;
console.log(foo ?? bar);
```

## How to use

## Version

This rule was added in v0.0.15.

## References

---

---
url: /docs/guide/usage/linter/rules/unicorn/prefer-math-min-max.md
---

### What it does

Prefers use of `Math.min()` and `Math.max()` instead of ternary
expressions when performing simple comparisons.

### Why is this bad?

Using `Math.min()` and `Math.max()` for simple comparisons is more
concise, easier to understand, and less prone to errors than ternary
expressions. They clearly express the intent to find the minimum or
maximum value.

### Examples

Examples of **incorrect** code for this rule:

```javascript
height > 50 ? 50 : height;
height > 50 ? height : 50;
```

Examples of **correct** code for this rule:

```javascript
Math.min(height, 50);
Math.max(height, 50);
```

## How to use

## Version

This rule was added in v0.10.1.

## References

---

---
url: /docs/guide/usage/linter/rules/unicorn/prefer-math-trunc.md
---

### What it does

Prefers use of [`Math.trunc()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Math/trunc) instead of bitwise operations for clarity and more reliable results.

It prevents the use of the following bitwise operations:

* `x | 0` ([`bitwise OR`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Bitwise_OR) with 0)
* `~~x` (two [`bitwise NOT`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Bitwise_NOT))
* `x >> 0` ([`Signed Right Shift`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Right_shift) with 0)
* `x << 0` ([`Left Shift`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Left_shift) with 0)
* `x ^ 0` ([`bitwise XOR Shift`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Bitwise_XOR) with 0)

### Why is this bad?

Using bitwise operations to truncate numbers is not clear and do not work in [some cases](https://stackoverflow.com/a/34706108/11687747).

### Examples

Examples of **incorrect** code for this rule:

```javascript
const foo = 1.1 | 0;
```

Examples of **correct** code for this rule:

```javascript
const foo = Math.trunc(1.1);
```

## How to use

## Version

This rule was added in v0.0.18.

## References

---

---
url: /docs/guide/usage/linter/rules/unicorn/prefer-modern-dom-apis.md
---

### What it does

Enforces the use of:

* `childNode.replaceWith(newNode)` over `parentNode.replaceChild(newNode, oldNode)`
* `referenceNode.before(newNode)` over `parentNode.insertBefore(newNode, referenceNode)`
* `referenceNode.before('text')` over `referenceNode.insertAdjacentText('beforebegin', 'text')`
* `referenceNode.before(newNode)` over `referenceNode.insertAdjacentElement('beforebegin', newNode)`

### Why is this bad?

There are some advantages of using the newer DOM APIs, like:

* Traversing to the parent node is not necessary.
* Appending multiple nodes at once.
* Both `DOMString` and DOM node objects can be manipulated.

### Examples

Examples of **incorrect** code for this rule:

```javascript
oldChildNode.replaceWith(newChildNode);
```

Examples of **correct** code for this rule:

```javascript
parentNode.replaceChild(newChildNode, oldChildNode);
```

## How to use

## Version

This rule was added in v0.0.20.

## References

---

---
url: /docs/guide/usage/linter/rules/unicorn/prefer-modern-math-apis.md
---

### What it does

Checks for usage of legacy patterns for mathematical operations.

### Why is this bad?

Modern JavaScript provides more concise and readable alternatives to legacy patterns.

Currently, the following cases are checked:

* Prefer `Math.log10(x)` over alternatives
* Prefer `Math.hypot(…)` over alternatives

### Examples

Examples of **incorrect** code for this rule:

```javascript
Math.log(x) * Math.LOG10E;
Math.sqrt(a * a + b * b);
```

Examples of **correct** code for this rule:

```javascript
Math.log10(x);
Math.hypot(a, b);
```

## How to use

## Version

This rule was added in v0.1.1.

## References

---

---
url: /docs/guide/usage/linter/rules/unicorn/prefer-module.md
---

### What it does

Prefer JavaScript modules (ESM) over CommonJS.

### Why is this bad?

CommonJS globals and patterns (`require`, `module`, `exports`, `__filename`, `__dirname`)
make code harder to migrate and can block ESM-only features.

### Examples

Examples of **incorrect** code for this rule:

```js
"use strict";
const foo = require("foo");
module.exports = foo;
```

Examples of **correct** code for this rule:

```js
import foo from "foo";
export default foo;
```

## How to use

## Version

This rule was added in v1.50.0.

## References

---

---
url: /docs/guide/usage/linter/rules/unicorn/prefer-native-coercion-functions.md
---

### What it does

Prefers built-in functions over custom ones with the same functionality.

### Why is this bad?

If a function is equivalent to [`String`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String), [`Number`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number), [`BigInt`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/BigInt), [`Boolean`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean), or [`Symbol`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol), you should use the built-in one directly.
Wrapping the built-in in a function is moot.

### Examples

Examples of **incorrect** code for this rule:

```javascript
const foo = (v) => String(v);
foo(1);
const foo = (v) => Number(v);
array.some((v) => /* comment */ v);
```

Examples of **correct** code for this rule:

```javascript
String(1);
Number(1);
array.some(Boolean);
```

## How to use

## Version

This rule was added in v0.0.19.

## References

---

---
url: /docs/guide/usage/linter/rules/unicorn/prefer-negative-index.md
---

### What it does

Prefer using a negative index over `.length - index` when possible.

### Why is this bad?

Using a negative index with `at` or `slice` is generally more readable
and concise than using `.length - index`.

### Examples

Examples of **incorrect** code for this rule:

```js
foo.slice(foo.length - 2, foo.length - 1);
foo.at(foo.length - 1);
```

Examples of **correct** code for this rule:

```js
foo.slice(-2, -1);
foo.at(-1);
```

## How to use

## Version

This rule was added in v0.13.2.

## References

---

---
url: /docs/guide/usage/linter/rules/unicorn/prefer-node-protocol.md
---

### What it does

Prefer using the `node:` protocol when importing Node.js built-in modules.

### Why is this bad?

Node.js built-in modules should be imported using the `node:` protocol to avoid ambiguity with local modules.

### Examples

Examples of **incorrect** code for this rule:

```javascript
import fs from "fs";
```

Examples of **correct** code for this rule:

```javascript
import fs from "node:fs";
```

## How to use

## Version

This rule was added in v0.0.19.

## References

---

---
url: /docs/guide/usage/linter/rules/unicorn/prefer-number-coercion.md
---

### What it does

Prefer `Number()` over `parseFloat()` and base-10 `parseInt()`.

### Why is this bad?

`parseFloat()` and `parseInt()` parse numeric prefixes and ignore trailing text.
`Number()` parses the full input, which better matches intent when coercing values.

### Examples

Examples of **incorrect** code for this rule:

```javascript
const value = parseFloat(input);
const integer = parseInt(input, 10);
```

Examples of **correct** code for this rule:

```javascript
const value = Number(input);
const integer = Math.trunc(Number(input));
```

## How to use

## Version

This rule was added in v1.71.0.

## References

---

---
url: /docs/guide/usage/linter/rules/unicorn/prefer-number-properties.md
---

### What it does

Disallows use of `parseInt()`, `parseFloat()`, `isNaN()`, `isFinite()`, `NaN`, `Infinity` and `-Infinity` as global variables.

### Why is this bad?

ECMAScript 2015 moved globals onto the `Number` constructor for consistency and to slightly improve them. This rule enforces their usage to limit the usage of globals:

* [`Number.parseInt()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number/parseInt) over [`parseInt()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/parseInt)
* [`Number.parseFloat()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number/parseFloat) over [`parseFloat()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/parseFloat)
* [`Number.isNaN()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number/isNaN) over [`isNaN()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/isNaN) *(they have slightly [different behavior](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number/isNaN#difference_between_number.isnan_and_global_isnan))*
* [`Number.isFinite()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number/isFinite) over [`isFinite()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/isFinite) *(they have slightly [different behavior](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number/isFinite#difference_between_number.isfinite_and_global_isfinite))*
* [`Number.NaN`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number/NaN) over [`NaN`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/NaN)
* [`Number.POSITIVE_INFINITY`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number/POSITIVE_INFINITY) over [`Infinity`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Infinity)
* [`Number.NEGATIVE_INFINITY`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number/NEGATIVE_INFINITY) over [`-Infinity`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Infinity)

### Examples

Examples of **incorrect** code for this rule:

```javascript
const foo = parseInt("10", 2);
const bar = parseFloat("10.5");
```

Examples of **correct** code for this rule:

```javascript
const foo = Number.parseInt("10", 2);
const bar = Number.parseFloat("10.5");
```

## Configuration

This rule accepts a configuration object with the following properties:

### checkInfinity

type: `boolean`

default: `false`

If set to `true`, checks for usage of `Infinity` and `-Infinity` as global variables.

### checkNaN

type: `boolean`

default: `true`

If set to `true`, checks for usage of `NaN` as a global variable.

## How to use

## Version

This rule was added in v0.0.19.

## References

---

---
url: /docs/guide/usage/linter/rules/unicorn/prefer-object-from-entries.md
---

### What it does

Encourages using `Object.fromEntries` when converting an array of key-value pairs
into an object.

### Why is this bad?

Manually constructing objects from key-value pairs using `reduce` or `forEach`
is more verbose, error-prone, and harder to understand. The `Object.fromEntries`
method is clearer, more declarative, and built for exactly this purpose.

### Examples

Examples of **incorrect** code for this rule:

```js
const result = pairs.reduce((obj, [key, value]) => {
  obj[key] = value;
  return obj;
}, {});

const result = {};
pairs.forEach(([key, value]) => {
  result[key] = value;
});
```

Examples of **correct** code for this rule:

```js
const result = Object.fromEntries(pairs);
```

## Configuration

This rule accepts a configuration object with the following properties:

### functions

type: `string[]`

default: `["_.fromPairs", "lodash.fromPairs"]`

Additional functions to treat as equivalents to `Object.fromEntries`.

## How to use

## Version

This rule was added in v0.16.12.

## References

---

---
url: /docs/guide/usage/linter/rules/unicorn/prefer-optional-catch-binding.md
---

### What it does

Prefers omitting the catch binding parameter if it is unused.

### Why is this bad?

It is unnecessary to bind the error to a variable if it is not used.

### Examples

Examples of **incorrect** code for this rule:

```javascript
try {
  // ...
} catch (e) {}
```

Examples of **correct** code for this rule:

```javascript
try {
  // ...
} catch {}
```

## How to use

## Version

This rule was added in v0.0.17.

## References

---

---
url: /docs/guide/usage/linter/rules/unicorn/prefer-prototype-methods.md
---

### What it does

This rule prefers borrowing methods from the prototype instead of the instance.

### Why is this bad?

“Borrowing” a method from an instance of `Array` or `Object` is less clear than getting it from the corresponding prototype.

### Examples

Examples of **incorrect** code for this rule:

```javascript
const array = [].slice.apply(bar);
const type = {}.toString.call(foo);
Reflect.apply([].forEach, arrayLike, [callback]);
```

Examples of **correct** code for this rule:

```javascript
const array = Array.prototype.slice.apply(bar);
const type = Object.prototype.toString.call(foo);
Reflect.apply(Array.prototype.forEach, arrayLike, [callback]);
const maxValue = Math.max.apply(Math, numbers);
```

## How to use

## Version

This rule was added in v0.0.21.

## References

---

---
url: /docs/guide/usage/linter/rules/unicorn/prefer-query-selector.md
---

### What it does

Prefer `.querySelector()` over `.getElementById()`. And prefer `.querySelectorAll()`
over `.getElementsByClassName()`, `.getElementsByTagName()`, and `.getElementsByName()`.

### Why is this bad?

* Using `.querySelector()` and `.querySelectorAll()` is more flexible and allows for more specific selectors.
* It's better to use the same method to query DOM elements. This helps keep consistency and it lends itself to future improvements (e.g. more specific selectors).

### Examples

Examples of **incorrect** code for this rule:

```javascript
document.getElementById("foo");
document.getElementsByClassName("foo bar");
document.getElementsByTagName("main");
document.getElementsByClassName(fn());
document.getElementsByName("foo");
```

Examples of **correct** code for this rule:

```javascript
document.querySelector("#foo");
document.querySelector(".bar");
document.querySelector("main #foo .bar");
document.querySelectorAll(".foo.bar");
document.querySelectorAll("li a");
document.querySelector("li").querySelectorAll("a");
```

## How to use

## Version

This rule was added in v0.0.15.

## References

---

---
url: /docs/guide/usage/linter/rules/unicorn/prefer-reflect-apply.md
---

### What it does

Disallows the use of `Function.prototype.apply()` and suggests using `Reflect.apply()` instead.

### Why is this bad?

`Reflect.apply()` is arguably less verbose and easier to understand.
In addition, when you accept arbitrary methods,
it's not safe to assume `.apply()` exists or is not overridden.

### Examples

Examples of **incorrect** code for this rule:

```javascript
foo.apply(null, [42]);
```

Examples of **correct** code for this rule:

```javascript
Reflect.apply(foo, null);
```

## How to use

## Version

This rule was added in v0.0.19.

## References

---

---
url: /docs/guide/usage/linter/rules/unicorn/prefer-regexp-test.md
---

### What it does

Prefers `RegExp#test()` over `String#match()` and `String#exec()`.

### Why is this bad?

When you want to know whether a pattern is found in a string, use
[`RegExp#test()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp/test)
instead of [`String#match()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/match)
or [`RegExp#exec()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp/exec),
as it exclusively returns a boolean and therefore is more efficient.

### Examples

Examples of **incorrect** code for this rule:

```javascript
if (string.match(/unicorn/)) {
}
if (/unicorn/.exec(string)) {
}
```

Examples of **correct** code for this rule:

```javascript
if (/unicorn/.test(string)) {
}
Boolean(string.match(/unicorn/));
```

## How to use

## Version

This rule was added in v0.0.16.

## References

---

---
url: /docs/guide/usage/linter/rules/unicorn/prefer-response-static-json.md
---

### What it does

Enforces the use of `Response.json()` over `new Response(JSON.stringify())`.

### Why is this bad?

`Response.json()` is a more concise and semantically clear way to create JSON responses.
It automatically sets the correct `Content-Type` header (`application/json`) and handles
serialization, making the code more maintainable and less error-prone.

### Examples

Examples of **incorrect** code for this rule:

```javascript
const response = new Response(JSON.stringify(data));
const response = new Response(JSON.stringify(data), { status: 200 });
```

Examples of **correct** code for this rule:

```javascript
const response = Response.json(data);
const response = Response.json(data, { status: 200 });
```

## How to use

## Version

This rule was added in v1.29.0.

## References

---

---
url: /docs/guide/usage/linter/rules/unicorn/prefer-set-has.md
---

### What it does

Prefer `Set#has()` over `Array#includes()` when checking for existence or non-existence.

### Why is this bad?

`Set#has()` is faster than `Array#includes()`.

### Examples

Examples of **incorrect** code for this rule:

```js
const array = [1, 2, 3];
const hasValue = (value) => array.includes(value);
```

Examples of **correct** code for this rule:

```js
const set = new Set([1, 2, 3]);
const hasValue = (value) => set.has(value);
```

```js
const array = [1, 2, 3];
const hasOne = array.includes(1);
```

## How to use

## Version

This rule was added in v0.13.2.

## References

---

---
url: /docs/guide/usage/linter/rules/unicorn/prefer-set-size.md
---

### What it does

Prefer `Set#size` over `Set#length` when the `Set` is converted to an array.

### Why is this bad?

Using `Set#size` is more readable and performant.

### Examples

Examples of **incorrect** code for this rule:

```javascript
const length = [...new Set([1, 2, 3])].length;
```

Examples of **correct** code for this rule:

```javascript
const size = new Set([1, 2, 3]).size;
```

## How to use

## Version

This rule was added in v0.0.19.

## References

---

---
url: /docs/guide/usage/linter/rules/unicorn/prefer-single-call.md
---

### What it does

Enforces combining multiple `Array#{push,unshift}()`,
`Element#classList.{add,remove}()`, and `importScripts()` into a single call.

Supersedes the deprecated `unicorn/no-array-push-push` rule.

### Why is this bad?

Calling the same variadic method on the same receiver multiple times
consecutively can be merged into a single call, which is more concise
and can be marginally more performant.

### Examples

Examples of **incorrect** code for this rule:

```javascript
foo.push(1);
foo.push(2);

foo.unshift(1);
foo.unshift(2);

element.classList.add("foo");
element.classList.add("bar");

importScripts("foo.js");
importScripts("bar.js");
```

Examples of **correct** code for this rule:

```javascript
foo.push(1, 2);

foo.unshift(2, 1);

element.classList.add("foo", "bar");

importScripts("foo.js", "bar.js");
```

## Configuration

This rule accepts a configuration object with the following properties:

### ignore

type: `string[]`

default: `[]`

Methods to ignore.

## How to use

## Version

This rule was added in v1.70.0.

## References

---

---
url: /docs/guide/usage/linter/rules/unicorn/prefer-spread.md
---

### What it does

Enforces the use of [the spread operator (`...`)](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Spread_syntax) over outdated patterns.

### Why is this bad?

Using the spread operator is more concise and readable.

### Examples

Examples of **incorrect** code for this rule:

```javascript
const foo = Array.from(set);
const foo = Array.from(new Set([1, 2]));
```

Examples of **correct** code for this rule:

```javascript
[...set].map(() => {});
Array.from(...argumentsArray);
```

## How to use

## Version

This rule was added in v0.0.17.

## References

---

---
url: /docs/guide/usage/linter/rules/unicorn/prefer-string-raw.md
---

### What it does

Prefers use of `String.raw` to avoid escaping `\`.

### Why is this bad?

Excessive backslashes can make string values less readable which can be avoided by using `String.raw`.

### Examples

Examples of **incorrect** code for this rule:

```javascript
const file = "C:\\windows\\style\\path\\to\\file.js";
const regexp = new RegExp("foo\\.bar");
```

Examples of **correct** code for this rule:

```javascript
const file = String.raw`C:\windows\style\path\to\file.js`;
const regexp = new RegExp(String.raw`foo\.bar`);
```

## How to use

## Version

This rule was added in v0.12.0.

## References

---

---
url: /docs/guide/usage/linter/rules/unicorn/prefer-string-replace-all.md
---

### What it does

Prefers [`String#replaceAll()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/replaceAll) over [`String#replace()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/replace) when using a regex with the global flag.

### Why is this bad?

The [`String#replaceAll()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/replaceAll) method is both faster and safer as you don't have to use a regex and remember to escape it if the string is not a literal. And when used with a regex, it makes the intent clearer.

### Examples

Examples of **incorrect** code for this rule:

```js
foo.replace(/a/g, bar);
```

Examples of **correct** code for this rule:

```js
foo.replace(/a/, bar);
foo.replaceAll("a", bar);
foo.replaceAll(/a|b/g, bar);

const pattern = "not-a-regexp";
foo.replace(pattern, bar);
```

## How to use

## Version

This rule was added in v0.0.18.

## References

---

---
url: /docs/guide/usage/linter/rules/unicorn/prefer-string-slice.md
---

### What it does

Prefer [`String#slice()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/slice) over [`String#substr()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/substr) and [`String#substring()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/substring).

### Why is this bad?

[`String#substr()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/substr) and [`String#substring()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/substring) are the two lesser known legacy ways to slice a string. It's better to use [`String#slice()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/slice) as it's a more popular option with clearer behavior that has a consistent [`Array` counterpart](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/slice).

### Examples

Examples of **incorrect** code for this rule:

```javascript
"foo".substr(1, 2);
```

Examples of **correct** code for this rule:

```javascript
"foo".slice(1, 2);
```

## How to use

## Version

This rule was added in v0.0.18.

## References

---

---
url: /docs/guide/usage/linter/rules/unicorn/prefer-string-starts-ends-with.md
---

### What it does

Prefer [`String#startsWith()`](https://developer.mozilla.org/en/docs/Web/JavaScript/Reference/Global_Objects/String/startsWith) and [`String#endsWith()`](https://developer.mozilla.org/en/docs/Web/JavaScript/Reference/Global_Objects/String/endsWith) over using a regex with `/^foo/` or `/foo$/`.

::: warning
This rule is deprecated. Prefer the type-aware [`typescript/prefer-string-starts-ends-with`](https://oxc.rs/docs/guide/usage/linter/rules/typescript/prefer-string-starts-ends-with.html) rule instead.
:::

### Why is this bad?

Using `String#startsWith()` and `String#endsWith()` is more readable and performant as it does not need to parse a regex.

### Examples

Examples of **incorrect** code for this rule:

```javascript
const foo = "hello";
/^abc/.test(foo);
```

Examples of **correct** code for this rule:

```javascript
const foo = "hello";
foo.startsWith("abc");
```

## How to use

## Version

This rule was added in v0.0.18.

## References

---

---
url: /docs/guide/usage/linter/rules/unicorn/prefer-string-trim-start-end.md
---

### What it does

[`String#trimLeft()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/trimLeft) and [`String#trimRight()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/trimRight) are aliases of [`String#trimStart()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/trimStart) and [`String#trimEnd()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/trimEnd). This is to ensure consistency and use [direction](https://developer.mozilla.org/en-US/docs/Learn/CSS/Building_blocks/Handling_different_text_directions)-independent wording.

### Why is this bad?

The `trimLeft` and `trimRight` names are confusing and inconsistent with the rest of the language.

### Examples

Examples of **incorrect** code for this rule:

```javascript
str.trimLeft();
str.trimRight();
```

Examples of **correct** code for this rule:

```javascript
str.trimStart();
str.trimEnd();
```

## How to use

## Version

This rule was added in v0.0.16.

## References

---

---
url: /docs/guide/usage/linter/rules/unicorn/prefer-structured-clone.md
---

### What it does

Prefer using `structuredClone` to create a deep clone.

### Why is this bad?

`structuredClone` is the modern way to create a deep clone of a value.

### Examples

Examples of **incorrect** code for this rule:

```js
const clone = JSON.parse(JSON.stringify(foo));

const clone = _.cloneDeep(foo);
```

Examples of **correct** code for this rule:

```js
const clone = structuredClone(foo);
```

## Configuration

This rule accepts a configuration object with the following properties:

### functions

type: `string[]`

default: `["cloneDeep", "utils.clone"]`

List of functions that are allowed to be used for deep cloning instead of structuredClone.

## How to use

## Version

This rule was added in v0.9.0.

## References

---

---
url: /docs/guide/usage/linter/rules/unicorn/prefer-ternary.md
---

### What it does

Prefers ternary expressions over simple `if`/`else` statements.

### Why is this bad?

Simple `if`/`else` branches for the same operation are often shorter and
clearer when expressed as a ternary.

### Examples

Examples of **incorrect** code for this rule:

```js
if (test) {
  return a;
} else {
  return b;
}
```

Examples of **correct** code for this rule:

```js
return test ? a : b;
```

## Configuration

This rule accepts one of the following string values:

### `"always"`

Always enforce ternary usage when the branches can be safely merged.

### `"only-single-line"`

Only enforce ternary usage when the condition and both branches are single-line.

## How to use

## Version

This rule was added in v1.50.0.

## References

---

---
url: /docs/guide/usage/linter/rules/unicorn/prefer-top-level-await.md
---

### What it does

Prefer top-level await over top-level promises and async function calls.

### Why is this bad?

Top-level await is more readable and can prevent unhandled rejections.

### Examples

Examples of **incorrect** code for this rule:

```js
(async () => {
  await run();
})();

run().catch((error) => {
  console.error(error);
});
```

Examples of **correct** code for this rule:

```js
await run();

try {
  await run();
} catch (error) {
  console.error(error);
}
```

## How to use

## Version

This rule was added in v1.20.0.

## References

---

---
url: /docs/guide/usage/linter/rules/unicorn/prefer-type-error.md
---

### What it does

Enforce throwing a `TypeError` instead of a generic `Error` after a type checking if-statement.

### Why is this bad?

Throwing a `TypeError` instead of a generic `Error` after a type checking if-statement is more specific and helps to catch bugs.

### Examples

Examples of **incorrect** code for this rule:

```javascript
if (Array.isArray(foo)) {
  throw new Error("Expected foo to be an array");
}
```

Examples of **correct** code for this rule:

```javascript
if (Array.isArray(foo)) {
  throw new TypeError("Expected foo to be an array");
}
```

## How to use

## Version

This rule was added in v0.0.16.

## References

---

---
url: /docs/guide/usage/linter/rules/unicorn/relative-url-style.md
---

### What it does

Enforce consistent relative URL style.

### Why is this bad?

When using a relative URL in `new URL()`, the URL should either never or always use the `./` prefix consistently.

### Examples

Examples of **incorrect** code for this rule with the default `"never"` option:

```js
new URL("./foo", base);
```

Examples of **correct** code for this rule with the default `"never"` option:

```js
new URL("foo", base);
```

Examples of **incorrect** code for this rule with the `"always"` option:

```js
new URL("foo", base);
```

Examples of **correct** code for this rule with the `"always"` option:

```js
new URL("./foo", base);
```

## Configuration

This rule accepts one of the following string values:

### `"never"`

Never use a `./` prefix.

### `"always"`

Always add a `./` prefix to the relative URL when possible.

## How to use

## Version

This rule was added in v1.44.0.

## References

---

---
url: /docs/guide/usage/linter/rules/unicorn/require-array-join-separator.md
---

### What it does

Enforce using the separator argument with `Array#join()`.

### Why is this bad?

It's better to make it clear what the separator is when calling `Array#join()`,
instead of relying on the default comma (`','`) separator.

### Examples

Examples of **incorrect** code for this rule:

```javascript
foo.join();
```

Examples of **correct** code for this rule:

```javascript
foo.join(",");
```

## How to use

## Version

This rule was added in v0.0.19.

## References

---

---
url: /docs/guide/usage/linter/rules/unicorn/require-module-attributes.md
---

### What it does

This rule enforces a non-empty attribute list in `import`/`export` statements and `import()` expressions.

### Why is this bad?

Import attributes are meant to provide metadata about how a module should be loaded
(e.g., `with { type: "json" }`). An empty attribute object provides no information
and should be removed.

### Examples

Examples of **incorrect** code for this rule:

```js
import foo from "foo" with {};

export { foo } from "foo" with {};

const foo = await import("foo", {});

const foo = await import("foo", { with: {} });
```

Examples of **correct** code for this rule:

```js
import foo from "foo";

export { foo } from "foo";

const foo = await import("foo");

const foo = await import("foo");
```

## How to use

## Version

This rule was added in v1.35.0.

## References

---

---
url: /docs/guide/usage/linter/rules/unicorn/require-module-specifiers.md
---

### What it does

Enforce a non-empty specifier list in `import` and `export` statements.

### Why is this bad?

Empty `import`/`export` specifiers add no value and can be confusing.
If you want to import a module for side effects, use `import 'module'` instead.

### Examples

Examples of **incorrect** code for this rule:

```js
import {} from "foo";
import foo from "foo";
export {} from "foo";
export {};
```

Examples of **correct** code for this rule:

```js
import "foo";
import foo from "foo";
```

## How to use

## Version

This rule was added in v1.20.0.

## References

---

---
url: >-
  /docs/guide/usage/linter/rules/unicorn/require-number-to-fixed-digits-argument.md
---

### What it does

Enforce using the digits argument with `Number#toFixed()`.

### Why is this bad?

It's better to make it clear what the value of the digits argument is when calling `Number#toFixed()`,
instead of relying on the default value of `0`.

### Examples

Examples of **incorrect** code for this rule:

```javascript
number.toFixed();
```

Examples of **correct** code for this rule:

```javascript
number.toFixed(0);
number.toFixed(2);
```

## How to use

## Version

This rule was added in v0.0.15.

## References

---

---
url: /docs/guide/usage/linter/rules/unicorn/require-post-message-target-origin.md
---

### What it does

Enforce using the `targetOrigin` argument with `window.postMessage()`.

Note that this rule may have false positives, as it is not capable of
detecting all cases correctly without type information. As such, it
may not be a good idea to enable in cases where `postMessage()` may
be used with `BroadcastChannel` or worker/service worker contexts
(for example, `WorkerGlobalScope#postMessage`, where the second argument
is a transfer list or options object, not `targetOrigin`).

### Why is this bad?

When calling `window.postMessage()` without the `targetOrigin` argument,
the message cannot be received by any window.

### Examples

Examples of **incorrect** code for this rule:

```js
window.postMessage(message);
```

Examples of **correct** code for this rule:

```js
window.postMessage(message, "https://example.com");

window.postMessage(message, "*");
```

## How to use

## Version

This rule was added in v0.15.15.

## References

---

---
url: /docs/guide/usage/linter/rules/unicorn/switch-case-braces.md
---

### What it does

Requires empty switch cases to omit braces, while non-empty cases must use braces.
This reduces visual clutter for empty cases and enforces proper scoping for non-empty ones.

### Why is this bad?

Using braces unnecessarily for empty cases adds visual noise,
while omitting braces in non-empty cases can lead to scoping issues.

### Examples

Examples of **incorrect** code for this rule:

```javascript
switch (num) {
  case 1: {
  }
  case 2:
    console.log("Case 2");
    break;
}
```

Examples of **correct** code for this rule:

```javascript
switch (num) {
  case 1:
  case 2: {
    console.log("Case 2");
    break;
  }
}
```

Example config:

```json
"unicorn/switch-case-braces": ["error", "avoid"]
```

## Configuration

This rule accepts one of the following string values:

### `"always"`

Always require braces in case clauses (except empty cases).

### `"avoid"`

Allow braces only when needed for scoping (e.g., variable or function declarations).

## How to use

## Version

This rule was added in v0.0.15.

## References

---

---
url: /docs/guide/usage/linter/rules/unicorn/switch-case-break-position.md
---

### What it does

Enforce consistent `break`/`return`/`continue`/`throw` position in `case` clauses.

### Why is this bad?

Enforce that terminating statements (`break`, `return`, `continue`, `throw`) appear inside the block statement of a `case` clause, not after it.
This can happen when refactoring — for example, removing an `if` wrapper but leaving the `break` outside the braces.

### Examples

Examples of **incorrect** code for this rule:

```js
switch (foo) {
  case 1:
    {
      doStuff();
    }
    break;
}
```

Examples of **correct** code for this rule:

```js
switch (foo) {
  case 1: {
    doStuff();
    break;
  }
}
```

## How to use

## Version

This rule was added in v1.59.0.

## References

---

---
url: /docs/guide/usage/linter/rules/unicorn/text-encoding-identifier-case.md
---

### What it does

This rule enforces consistent casing for text encoding identifiers, specifically:

* `'utf8'` instead of `'UTF-8'` or `'utf-8'` (or `'utf-8'` if `withDash` is enabled)
* `'ascii'` instead of `'ASCII'`

### Why is this bad?

Inconsistent casing of encoding identifiers reduces code readability and
can lead to subtle confusion across a codebase. Although casing is not
strictly enforced by ECMAScript or Node.js, using lowercase is the
conventional and widely recognized style.

### Examples

Examples of **incorrect** code for this rule:

```javascript
import fs from "node:fs/promises";
async function bad() {
  await fs.readFile(file, "UTF-8");
  await fs.readFile(file, "ASCII");
  const string = buffer.toString("utf-8");
}
```

Examples of **correct** code for this rule:

```javascript
import fs from "node:fs/promises";
async function good() {
  await fs.readFile(file, "utf8");
  await fs.readFile(file, "ascii");
  const string = buffer.toString("utf8");
}
```

Examples of **correct** code for this rule with `{ "withDash": true }`:

```javascript
import fs from "node:fs/promises";
async function good() {
  await fs.readFile(file, "utf-8");
  await fs.readFile(file, "ascii");
  const string = buffer.toString("utf-8");
}
```

## Configuration

This rule accepts a configuration object with the following properties:

### withDash

type: `boolean`

default: `false`

If `true`, prefer `utf-8` over `utf8`.

## How to use

## Version

This rule was added in v0.0.15.

## References

---

---
url: /docs/guide/usage/linter/rules/unicorn/throw-new-error.md
---

### What it does

This rule makes sure you always use `new` when throwing an error.

### Why is this bad?

In JavaScript, omitting `new` (e.g., `throw Error('message')`) is allowed,
but it does not properly initialize the error object. This can lead to missing
stack traces or incorrect prototype chains. Using `new` makes the intent clear,
ensures consistent behavior, and helps avoid subtle bugs.

### Examples

Examples of **incorrect** code for this rule:

```javascript
throw Error("🦄");
throw TypeError("unicorn");
throw lib.TypeError("unicorn");
const e = Error("message");
```

Examples of **correct** code for this rule:

```javascript
throw new Error("🦄");
throw new TypeError("unicorn");
throw new lib.TypeError("unicorn");
const e = new Error("message");
```

## How to use

## Version

This rule was added in v0.0.14.

## References

---

---
url: /docs/guide/usage/formatter/unsupported-features.md
---

# Unsupported features

:::info
These features are planned. Follow our [milestone](https://github.com/oxc-project/oxc/milestone/19).
:::

## Configuration limitations

Not currently supported:

* `prettier` field in `package.json`
* Nested `.editorconfig` in sub directories
* `experimentalTernaries` and `experimentalOperatorPosition` options

Note: Default `printWidth` is `100` (Prettier uses `80`).

## Prettier plugins

Not supported. However, Oxfmt provides built-in alternatives:

* `sortImports`
  * Based on `eslint-plugin-perfectionist/sort-imports`
  * Disabled by default
* `sortTailwindcss`
  * Based on `prettier-plugin-tailwindcss`
  * Disabled by default
* `sortPackageJson`
  * Based on `prettier-plugin-packagejson`
  * Enabled by default
* `jsdoc`
  * Based on `prettier-plugin-jsdoc`
  * Disabled by default

See [Configuration file reference](./config-file-reference) for details.

For what Oxfmt does support across frameworks and file types, see the [compatibility matrix](/compatibility).

---

---
url: /docs/guide/usage/formatter/generated-cli.md
---

## Usage

**`oxfmt`** \[**`-c`**=*`PATH`*] \[*`PATH`*]...

## Mode Options:

* **`    --init`** —
  Initialize `.oxfmtrc.json` with default values
* **`    --migrate`**=*`SOURCE`* —
  Migrate configuration to `.oxfmtrc.json` from specified source Available sources: prettier, biome
* **`    --lsp`** —
  Start language server protocol (LSP) server
* **`    --stdin-filepath`**=*`PATH`* —
  Specify the file name to use to infer which parser to use

## Output Options:

* **`    --write`** —
  Format and write files in place (default)
* **`    --check`** —
  Check if files are formatted, also show statistics
* **`    --list-different`** —
  List files that would be changed

## Config Options

* **`-c`**, **`--config`**=*`PATH`* —
  Path to the configuration file (.json, .jsonc, .ts, .mts, .cts, .js, .mjs, .cjs)
* **`    --disable-nested-config`** —
  Do not search for configuration files in subdirectories

## Ignore Options

* **`    --ignore-path`**=*`PATH`* —
  Path to ignore file(s). Can be specified multiple times. If not specified, .gitignore and .prettierignore in the current directory are used.
* **`    --with-node-modules`** —
  Format code in node\_modules directory (skipped by default)

## Runtime Options

* **`    --no-error-on-unmatched-pattern`** —
  Do not exit with error when pattern is unmatched
* **`    --threads`**=*`INT`* —
  Number of threads to use. Set to 1 for using only 1 CPU core.

## Available positional items:

* *`PATH`* —
  Single file, path or list of paths. Glob patterns are also supported. (Be sure to quote them, otherwise your shell may expand them before passing.) Exclude patterns with `!` prefix like `'!**/fixtures/*.js'` are also supported. If not provided, current working directory is used.

## Available options:

* **`-h`**, **`--help`** —
  Prints help information
* **`-V`**, **`--version`** —
  Prints version information

---

---
url: /docs/guide/usage/linter/generated-cli.md
---

## Usage

**`oxlint`** \[**`-c`**=*`<./.oxlintrc.json>`*] \[*`PATH`*]...

## Basic Configuration

* **`-c`**, **`--config`**=*`<./.oxlintrc.json>`* —
  Oxlint configuration file

- `.json` and `.jsonc` config files are supported in all runtimes
- JavaScript/TypeScript config files are experimental and require running via Node.js
- you can use comments in configuration files.
- tries to be compatible with ESLint v8's format

  If not provided, Oxlint will look for a `.oxlintrc.json`, `.oxlintrc.jsonc`, `oxlint.config.ts`, or `oxlint.config.mts` file in the current working directory.

* **`    --tsconfig`**=*`<./tsconfig.json>`* —
  Override the TypeScript config used for import resolution. Oxlint automatically discovers the relevant `tsconfig.json` for each file. Use this only when your project uses a non-standard tsconfig name or location.

  ::: warning Avoid using this option. It can cause differences between import resolution, and type-aware linting. Type aware linting **does not** respect this option, and will always discover the appropriate `tsconfig.json` for each file automatically. :::

* **`    --init`** —
  Initialize oxlint configuration with default values

## Allowing / Denying Multiple Lints

Accumulate rules and categories from left to right on the command-line.

For example `-D correctness -A no-debugger` or `-A all -D no-debugger`.
The categories are:

* `correctness` - Code that is outright wrong or useless (default)
* `suspicious` - Code that is most likely wrong or useless
* `pedantic` - Lints which are rather strict or have occasional false positives
* `perf` - Code that could be written in a more performant way
* `style` - Code that should be written in a more idiomatic way
* `restriction` - Lints which prevent the use of language and library features
* `nursery` - New lints that are still under development
* `all` - All categories listed above except `nursery`. Does not enable plugins automatically.

Arguments:

* **`-A`**, **`--allow`**=*`NAME`* —
  Allow the rule or category (suppress the lint)
* **`-W`**, **`--warn`**=*`NAME`* —
  Warn on the rule or category (emit a warning)
* **`-D`**, **`--deny`**=*`NAME`* —
  Deny the rule or category (emit an error)

## Enable/Disable Plugins

* **`    --disable-unicorn-plugin`** —
  Disable unicorn plugin, which is turned on by default
* **`    --disable-oxc-plugin`** —
  Disable oxc unique rules, which is turned on by default
* **`    --disable-typescript-plugin`** —
  Disable TypeScript plugin, which is turned on by default
* **`    --import-plugin`** —
  Enable import plugin and detect ESM problems.
* **`    --react-plugin`** —
  Enable react plugin, which is turned off by default
* **`    --jsdoc-plugin`** —
  Enable jsdoc plugin and detect JSDoc problems
* **`    --jest-plugin`** —
  Enable the Jest plugin and detect test problems
* **`    --vitest-plugin`** —
  Enable the Vitest plugin and detect test problems
* **`    --jsx-a11y-plugin`** —
  Enable the JSX-a11y plugin and detect accessibility problems
* **`    --nextjs-plugin`** —
  Enable the Next.js plugin and detect Next.js problems
* **`    --react-perf-plugin`** —
  Enable the React performance plugin and detect rendering performance problems
* **`    --promise-plugin`** —
  Enable the promise plugin and detect promise usage problems
* **`    --node-plugin`** —
  Enable the node plugin and detect node usage problems
* **`    --vue-plugin`** —
  Enable the vue plugin and detect vue usage problems

## Fix Problems

* **`    --fix`** —
  Fix as many issues as possible. Only unfixed issues are reported in the output.
* **`    --fix-suggestions`** —
  Apply auto-fixable suggestions. May change program behavior.
* **`    --fix-dangerously`** —
  Apply dangerous fixes and suggestions

## Ignore Files

* **`    --ignore-path`**=*`PATH`* —
  Specify the file to use as your `.eslintignore`

* **`    --ignore-pattern`**=*`PAT`* —
  Specify patterns of files to ignore (in addition to those in `.eslintignore`)

  The supported syntax is the same as for `.eslintignore` and `.gitignore` files. You should quote your patterns in order to avoid shell interpretation of glob patterns.

* **`    --no-ignore`** —
  Disable excluding files from `.eslintignore` files, **`--ignore-path`** flags and **`--ignore-pattern`** flags

## Handle Warnings

* **`    --quiet`** —
  Disable reporting on warnings, only errors are reported
* **`    --deny-warnings`** —
  Ensure warnings produce a non-zero exit code
* **`    --max-warnings`**=*`INT`* —
  Specify a warning threshold, which can be used to force exit with an error status if there are too many warning-level rule violations in your project

## Output

* **`-f`**, **`--format`**=*`ARG`* —
  Use a specific output format. Possible values: `checkstyle`, `default`, `agent`, `github`, `gitlab`, `json`, `junit`, `sarif`, `stylish`, `unix`
* **`    --debug`**=*`OPTIONS`* —
  Enable debug output options. Options are comma-separated. Possible values:

- `files` - Print the list of files that will be linted, then exit.
- `timings` - Enable per-rule timing information.

## Miscellaneous

* **`    --silent`** —
  Do not display any diagnostics
* **`    --no-error-on-unmatched-pattern`** —
  Do not exit with an error when no files are selected for linting (for example, after applying ignore patterns)
* **`    --threads`**=*`INT`* —
  Number of threads to use. Set to 1 for using only 1 CPU core.
* **`    --print-config`** —
  This option outputs the configuration to be used. When present, no linting is performed and only config-related options are valid.

## Inline Configuration Comments

* **`    --report-unused-disable-directives`** —
  Report directive comments like `// oxlint-disable-line`, when no errors would have been reported on that line anyway
* **`    --report-unused-disable-directives-severity`**=*`SEVERITY`* —
  Same as `--report-unused-disable-directives`, but allows you to specify the severity level of the reported errors. Only one of these two options can be used at a time.

## Available positional items:

* *`PATH`* —
  Single file, single path or list of paths

## Available options:

* **`    --rules`** —
  List all the rules that are currently registered
* **`    --lsp`** —
  Start the language server
* **`    --disable-nested-config`** —
  Disable the automatic loading of nested configuration files
* **`    --type-aware`** —
  Enable rules that require type information
* **`    --type-check`** —
  Enable experimental type checking (includes TypeScript compiler diagnostics)
* **`-h`**, **`--help`** —
  Prints help information
* **`-V`**, **`--version`** —
  Prints version information

---

---
url: /docs/guide/usage/linter/generated-lsp-config.md
---

These options can be defined for each workspace folder separately.
File references in the options (e.g. `configPath`, `tsConfigPath`) are resolved relative to the workspace folder.

They can be sent by the client in `initialize` or `workspace/didChangeConfiguration` requests.
If the client supports `workspace/configuration`, the server will request the options from the client.

Example of `initialize` request:

```json
{
  "processId": 123,
  "rootUri": null,
  "workspaceFolders": [],
  "capabilities": {},
  "initializationOptions": [
    {
      "workspaceUri": "file:///home/user/project",
      "options": {
        "unusedDisableDirectives": "deny",
        "typeAware": true
      }
    }
  ]
}
```

Example of `workspace/didChangeConfiguration` request:

```json
{
  "settings": [
    {
      "workspaceUri": "file:///home/user/project",
      "options": {
        "unusedDisableDirectives": "deny",
        "disableNestedConfig": true
      }
    }
  ]
}
```

## configPath

type: `string`

Path to the config file. Similar to `--config` CLI option.
If set, it disables searching for config files.

## disableNestedConfig

type: `boolean`

Whether to disable nested config support. Similar to `--disable-nested-config` CLI option.
It gets automatically enabled when `configPath` is set.

## fixKind

type: `"safe_fix" | "safe_fix_or_suggestion" | "dangerous_fix" | "dangerous_fix_or_suggestion" | "none" | "all"`

What kind of fixes to generate for code actions.

## rulesCustomization

type: `Record<string, object>`

Customization for individual rules, allows to override the linter's diagnostics and autofix.
Example of lowering the severity of "no-unused-vars" rule to "hint" and disabling autofix for it:

```json
{
  "rulesCustomization": {
    "no-unused-vars": {
      "severity": "hint",
      "autofix": false
    }
  }
}
```

## run

type: `"onSave" | "onType"`

If your editor does not support `textDocument/diagnostic`,
this option handles when diagnostics are sent to the client.

## tsConfigPath

type: `string`

Path to the tsconfig file. Similar to `--tsconfig` CLI option.
If set, it disables auto discovery for tsconfig files.

## typeAware

type: `boolean`

Whether to enable/disable type-aware linting.
It will override the root config's `typeAware` option if set.

## unusedDisableDirectives

type: `"allow" | "warn" | "deny"`

How to handle unused disable directives. By default, they are allowed and ignored.

---

---
url: /docs/guide/usage/linter/versioning.md
---

# Versioning policy

Oxlint follows semantic versioning, with the goal of providing clarity and predictability as you upgrade.

What's considered a **breaking** change:

* Changes to the CLI interface that would break existing workflows.
* Changes to the configuration file (`.oxlintrc.json`) that would break existing setups.
* Renaming or removing a rule.

What's considered a **non-breaking** change:

* Adding new lint rules.
* Changing the default configuration for a rule.
* Improving rule descriptions or diagnostic messages.
* Adding new config options to existing rules.
* Fixes that change rule behavior to better align with the original ESLint rule's behavior.
* Adding new fields to the configuration file.

## Features Not Subject to Semver

The following features are not subject to semantic versioning. They may introduce breaking changes at any time, even in patch or minor releases:

* **JavaScript custom plugins** - The plugin API and behavior may change without notice.
* **Type-aware linting** - Type-aware rules and their behavior may change as this feature evolves.

## Are New Lint Errors a Breaking Change?

If a new version of Oxlint reports additional issues in your code, that’s expected. This behavior means Oxlint has improved — not that something in your project broke. New errors reflect stronger analysis, not a broken upgrade.

## What to Expect from New Versions

* **Patch version** (1.0.x): Bug fixes, performance improvements, internal refactors. These are always safe to upgrade.
* **Minor version** (1.x.0): New rules, better diagnostics, new features. These are not considered breaking changes even if they cause new errors to appear in your codebase.
* **Major version** (x.0.0): Reserved for breaking changes to the CLI or configuration format.

## With Renovate Bot

Add the snippet below to your Renovate config to let it keep Oxlint automatically up to date.

```json [renovate.json]
{
  "extends": ["config:recommended"],
  "packageRules": [
    {
      "matchPackageNames": ["oxlint"],
      "groupName": "oxlint",
      "automergeType": "branch",
      "stabilityDays": 1
    }
  ]
}
```

If you use [eslint-plugin-oxlint](https://npmx.dev/package/eslint-plugin-oxlint), ensure that it is also updated alongside Oxlint to avoid compatibility issues.

## With Dependabot

Add the snippet below to your Dependabot config to let it keep Oxlint automatically up to date.

```yaml
version: 2
updates:
  - package-ecosystem: "npm"
    directory: "/" # location of package.json
    schedule:
      interval: "daily"
    groups: # group all Oxlint updates together
      oxlint:
        patterns:
          - "oxlint"
    commit-message: # keep the history tidy
      prefix: "chore"
      include: "scope"
    ignore: # optional: ignore future majors
      - dependency-name: "oxlint"
        update-types: ["version-update:semver-major"]
    open-pull-requests-limit: 1 # one PR at a time
```

If you use [eslint-plugin-oxlint](https://npmx.dev/package/eslint-plugin-oxlint), ensure that it is also updated alongside Oxlint to avoid compatibility issues.

---

---
url: /docs/guide/usage/linter/rules/vitest/consistent-each-for.md
---

### What it does

This rule enforces consistency in which method is used to create parameterized tests.
This configuration affects different test function types (`test`, `it`, `describe`, `suite`).

### Why is this bad?

Without a consistent way to create parameterized tests, we rely on the developer to remember that
`.for` spreads the values as different arguments while `.each` passes the array as a single argument.

### Examples

Examples of **incorrect** code for this rule:

```js
// { test: 'for' }
test.each([[1, 1, 2]])("test", (a, b, expected) => {
  expect(a + b).toBe(expected);
});

// { describe: 'for' }
describe.each([[1], [2]])("suite %s", (n) => {
  test("test", () => {});
});
```

Examples of **correct** code for this rule:

```js
// { test: 'for' }
test.for([[1, 1, 2]])("test", ([a, b, expected]) => {
  expect(a + b).toBe(expected);
});

// { describe: 'for' }
describe.for([[1], [2]])("suite %s", ([n]) => {
  test("test", () => {});
});
```

## Configuration

This rule accepts a configuration object with the following properties:

### describe

type: `"for" | "each"`

Preferred method to create parameterized tests for `describe` blocks.

### it

type: `"for" | "each"`

Preferred method to create parameterized tests for `it` blocks.

### suite

type: `"for" | "each"`

Preferred method to create parameterized tests for `suite` blocks.

### test

type: `"for" | "each"`

Preferred method to create parameterized tests for `test` blocks.

## How to use

## Version

This rule was added in v1.39.0.

## References

---

---
url: /docs/guide/usage/linter/rules/vitest/consistent-test-filename.md
---

### What it does

This rule triggers an error when a file is considered a test file, but its name
does not match an expected filename format.

### Why is this bad?

Files that are tests but with an unexpected filename make it hard to distinguish between
source code files and test files.

### Examples

An example of an **incorrect** file path for this rule configured as `{"allTestPattern": "__tests__",  "pattern": ".*\.spec\.ts$"}`:

`__tests__/2.ts`

An example of a **correct** file path for this rule configured as `{"allTestPattern": "__tests__",  "pattern": ".*\.spec\.ts$"}`:

`__tests__/2.spec.ts`

## Configuration

This rule accepts a configuration object with the following properties:

### allTestPattern

type: `string`

Regex pattern to ensure we are linting only test filenames.
Decides whether a file is a testing file.

### pattern

type: `string`

Required regex to check if a test filename have a valid formart.
Pattern doesn't have a default value, you must provide one.

## How to use

## Version

This rule was added in v1.36.0.

## References

---

---
url: /docs/guide/usage/linter/rules/vitest/consistent-test-it.md
---

### What it does

Vitest allows you to choose how you want to define your tests, using the `it`
or the `test` keywords, with multiple permutations for each:

* **it:** `it`, `it.only`, `it.skip`, `it.concurrent`, `it.each`.
* **test:** `test`, `test.only`, `test.skip`, `test.concurrent`, `test.each`.

### Why is this bad?

It's a good practice to be consistent in your test suite, so that all tests are written in the same way.

## Configuration

This rule accepts a configuration object with the following properties:

### fn

type: `"it" | "test"`

default: `"test"`

Decides whether to use `test` or `it`.

Examples of **incorrect** code for `{ "fn": "test" }`:

```javascript
it("foo");
it.only("foo");
```

Examples of **correct** code for `{ "fn": "test" }`:

```javascript
test("foo");
test.only("foo");
```

Examples of **incorrect** code for `{ "fn": "it" }`:

```javascript
test("foo");
test.only("foo");
```

Examples of **correct** code for `{ "fn": "it" }`:

```javascript
it("foo");
it.only("foo");
```

### withinDescribe

type: `"it" | "test"`

default: `"it"`

Decides whether to use `test` or `it` within a `describe` scope.
If only `fn` is provided, this will default to the value of `fn`.

Examples of **incorrect** code for `{ "withinDescribe": "test" }`:

```javascript
describe("foo", function () {
  it("bar");
});
```

Examples of **correct** code for `{ "withinDescribe": "test" }`:

```javascript
describe("foo", function () {
  test("bar");
});
```

## How to use

## Version

This rule was added in v0.5.3.

## References

---

---
url: /docs/guide/usage/linter/rules/vitest/consistent-vitest-vi.md
---

### What it does

This rule triggers an error when an unexpected Vitest accessor is used.

### Why is this bad?

Not having a consistent vitest accessor can lead to confusion
when `vi` and `vitest` are used interchangeably.

### Examples

Examples of **incorrect** code for this rule:

```js
vitest.mock("./src/calculator.ts", { spy: true });

vi.stubEnv("NODE_ENV", "production");
```

Examples of **correct** code for this rule:

```js
vi.mock("./src/calculator.ts", { spy: true });

vi.stubEnv("NODE_ENV", "production");
```

## Configuration

This rule accepts a configuration object with the following properties:

### fn

type: `"vi" | "vitest"`

default: `"vi"`

Decides whether to prefer vitest function accessor

## How to use

## Version

This rule was added in v1.37.0.

## References

---

---
url: /docs/guide/usage/linter/rules/vitest/expect-expect.md
---

### What it does

This rule triggers when there is no call made to `expect` in a test, ensure that there is at least one `expect` call made in a test.

### Why is this bad?

People may forget to add assertions.

### Examples

Examples of **incorrect** code for this rule:

```javascript
it("should be a test", () => {
  console.log("no assertion");
});
test("should assert something", () => {});
```

## Configuration

This rule accepts a configuration object with the following properties:

### additionalTestBlockFunctions

type: `string[]`

default: `[]`

An array of function names that should also be treated as test blocks.

### assertFunctionNames

type: `string[]`

default: `["expect"]`

A list of function names that should be treated as assertion functions.

NOTE: The default value is `["expect"]` for Jest and
`["expect", "expectTypeOf", "assert", "assertType"]` for Vitest.

## How to use

## Version

This rule was added in v0.0.12.

## References

---

---
url: /docs/guide/usage/linter/rules/vitest/hoisted-apis-on-top.md
---

### What it does

Requires [hoisted](https://developer.mozilla.org/en-US/docs/Glossary/Hoisting) Vitest APIs
(`vi.mock`, `vi.unmock`, and `vi.hoisted`) to appear at the top level of the file.

### Why is this bad?

Vitest hoists certain APIs to the top of the file during transformation, so they always
run before any imports — regardless of where they appear in the source. Writing them
inside conditionals, test bodies, or other runtime locations can be misleading and confusing.

The code looks like it executes at runtime, but it actually runs first. This rule ensures
that these hoisted APIs are not allowed in confusing contexts.

### Examples

Examples of **incorrect** code for this rule:

```js
if (condition) {
  vi.mock("some-module", () => {});
}
```

```js
if (condition) {
  vi.unmock("some-module", () => {});
}
```

```js
if (condition) {
  vi.hoisted(() => {});
}
```

```js
describe("suite", () => {
  it("test", async () => {
    vi.mock("some-module", () => {});

    const sm = await import("some-module");
  });
});
```

Examples of **correct** code for this rule:

```js
if (condition) {
  vi.doMock("some-module", () => {});
}
```

```js
vi.mock("some-module", () => {});
if (condition) {
}
```

```js
vi.unmock("some-module", () => {});
if (condition) {
}
```

```js
vi.hoisted(() => {});
if (condition) {
}
```

```js
vi.mock("some-module", () => {});

describe("suite", () => {
  it("test", async () => {
    const sm = await import("some-module");
  });
});
```

## How to use

## Version

This rule was added in v1.39.0.

## References

---

---
url: /docs/guide/usage/linter/rules/vitest/max-expects.md
---

### What it does

This rule enforces a maximum number of `expect()` calls in a single test.

### Why is this bad?

Tests with many different assertions are likely mixing multiple objectives.
It is generally better to have a single objective per test to ensure that when a test fails,
the problem is easy to identify.

### Examples

Examples of **incorrect** code for this rule:

```javascript
test("should not pass", () => {
  expect(true).toBeDefined();
  expect(true).toBeDefined();
  expect(true).toBeDefined();
  expect(true).toBeDefined();
  expect(true).toBeDefined();
  expect(true).toBeDefined();
});

it("should not pass", () => {
  expect(true).toBeDefined();
  expect(true).toBeDefined();
  expect(true).toBeDefined();
  expect(true).toBeDefined();
  expect(true).toBeDefined();
  expect(true).toBeDefined();
});
```

## Configuration

This rule accepts a configuration object with the following properties:

### max

type: `integer`

default: `5`

Maximum number of `expect()` assertion calls allowed within a single test.

## How to use

## Version

This rule was added in v0.0.18.

## References

---

---
url: /docs/guide/usage/linter/rules/vitest/max-nested-describe.md
---

### What it does

This rule enforces a maximum depth to nested `describe()` calls.

### Why is this bad?

Nesting `describe()` blocks too deeply can make the test suite hard to read and understand.

### Examples

The following patterns are considered warnings (with the default option of
`{ "max": 5 } `):

Examples of **incorrect** code for this rule:

```javascript
describe("foo", () => {
  describe("bar", () => {
    describe("baz", () => {
      describe("qux", () => {
        describe("quxx", () => {
          describe("too many", () => {
            it("should get something", () => {
              expect(getSomething()).toBe("Something");
            });
          });
        });
      });
    });
  });
});

describe("foo", function () {
  describe("bar", function () {
    describe("baz", function () {
      describe("qux", function () {
        describe("quxx", function () {
          describe("too many", function () {
            it("should get something", () => {
              expect(getSomething()).toBe("Something");
            });
          });
        });
      });
    });
  });
});
```

Examples of **correct** code for this rule:

```ts
describe("foo", () => {
  describe("bar", () => {
    it("should get something", () => {
      expect(getSomething()).toBe("Something");
    });
  });
  describe("qux", () => {
    it("should get something", () => {
      expect(getSomething()).toBe("Something");
    });
  });
});

describe("foo2", function () {
  it("should get something", () => {
    expect(getSomething()).toBe("Something");
  });
});

describe("foo", function () {
  describe("bar", function () {
    describe("baz", function () {
      describe("qux", function () {
        describe("this is the limit", function () {
          it("should get something", () => {
            expect(getSomething()).toBe("Something");
          });
        });
      });
    });
  });
});
```

## Configuration

This rule accepts a configuration object with the following properties:

### max

type: `integer`

default: `5`

Maximum allowed depth of nested describe calls.

## How to use

## Version

This rule was added in v0.4.4.

## References

---

---
url: /docs/guide/usage/linter/rules/vitest/no-alias-methods.md
---

### What it does

Enforces Vitest's canonical matcher names instead of aliases.

### Why is this bad?

Vitest matcher aliases are discouraged because they make matcher usage inconsistent.
This rule makes it easier to search for all occurrences of a matcher and ensures consistency among matcher names.

### Examples

Examples of **incorrect** code for this rule:

```javascript
expect(a).toBeCalled();
expect(a).toBeCalledTimes();
expect(a).toBeCalledWith();
expect(a).lastCalledWith();
expect(a).nthCalledWith();
expect(a).toReturn();
expect(a).toReturnTimes();
expect(a).toReturnWith();
expect(a).lastReturnedWith();
expect(a).nthReturnedWith();
expect(a).toThrowError();
```

Examples of **correct** code for this rule:

```javascript
expect(a).toHaveBeenCalled();
expect(a).toHaveBeenCalledTimes();
expect(a).toHaveBeenCalledWith();
expect(a).toHaveBeenLastCalledWith();
expect(a).toHaveBeenNthCalledWith();
expect(a).toHaveReturned();
expect(a).toHaveReturnedTimes();
expect(a).toHaveReturnedWith();
expect(a).toHaveLastReturnedWith();
expect(a).toHaveNthReturnedWith();
expect(a).toThrow();
```

## How to use

## Version

This rule was added in v0.0.12.

## References

---

---
url: /docs/guide/usage/linter/rules/vitest/no-commented-out-tests.md
---

### What it does

This rule raises a warning about commented-out tests. It's similar to the
`no-disabled-tests` rule.

### Why is this bad?

You may forget to uncomment some tests. This rule raises a warning about commented-out tests.

It is generally better to skip a test if it's flaky, or remove it if it's no longer needed.

### Examples

Examples of **incorrect** code for this rule:

```javascript
// describe('foo', () => {});
// it('foo', () => {});
// test('foo', () => {});

// describe.skip('foo', () => {});
// it.skip('foo', () => {});
// test.skip('foo', () => {});
```

## How to use

## Version

This rule was added in v0.0.8.

## References

---

---
url: /docs/guide/usage/linter/rules/vitest/no-conditional-expect.md
---

### What it does

This rule prevents the use of `expect` in conditional blocks, such as `if` and `catch`.
This includes using `expect` in callbacks to functions named `catch`, which are assumed to be promises.

### Why is this bad?

Jest only considers a test to have failed if it throws an error, meaning if calls to
assertion functions like `expect` occur in conditional code such as a `catch` statement,
tests can end up passing but not actually test anything. Additionally, conditionals
tend to make tests more brittle and complex, as they increase the amount of mental
thinking needed to understand what is actually being tested.

### Examples

Examples of **incorrect** code for this rule:

```js
it("foo", () => {
  doTest && expect(1).toBe(2);
});

it("bar", () => {
  if (!skipTest) {
    expect(1).toEqual(2);
  }
});

it("baz", async () => {
  try {
    await foo();
  } catch (err) {
    expect(err).toMatchObject({ code: "MODULE_NOT_FOUND" });
  }
});

it("throws an error", async () => {
  await foo().catch((error) => expect(error).toBeInstanceOf(error));
});
```

Examples of **correct** code for this rule:

```js
it("foo", () => {
  expect(!value).toBe(false);
});

function getValue() {
  if (process.env.FAIL) {
    return 1;
  }
  return 2;
}

it("foo", () => {
  expect(getValue()).toBe(2);
});

it("validates the request", () => {
  try {
    processRequest(request);
  } catch {
  } finally {
    expect(validRequest).toHaveBeenCalledWith(request);
  }
});

it("throws an error", async () => {
  await expect(foo).rejects.toThrow(Error);
});
```

## How to use

## Version

This rule was added in v0.0.12.

## References

---

---
url: /docs/guide/usage/linter/rules/vitest/no-conditional-in-test.md
---

### What it does

Disallow conditional statements in tests.

### Why is this bad?

Conditional statements in tests can make the test harder to read and understand.
It is better to have a single test case per test function.

### Examples

Examples of **incorrect** code for this rule:

```js
it("foo", () => {
  if (true) {
    doTheThing();
  }
});

it("bar", () => {
  switch (mode) {
    case "none":
      generateNone();
    case "single":
      generateOne();
    case "multiple":
      generateMany();
  }

  expect(fixtures.length).toBeGreaterThan(-1);
});

it("baz", async () => {
  const promiseValue = () => {
    return something instanceof Promise ? something : Promise.resolve(something);
  };

  await expect(promiseValue()).resolves.toBe(1);
});
```

Examples of **correct** code for this rule:

```js
describe("my tests", () => {
  if (true) {
    it("foo", () => {
      doTheThing();
    });
  }
});

beforeEach(() => {
  switch (mode) {
    case "none":
      generateNone();
    case "single":
      generateOne();
    case "multiple":
      generateMany();
  }
});

it("bar", () => {
  expect(fixtures.length).toBeGreaterThan(-1);
});

const promiseValue = (something) => {
  return something instanceof Promise ? something : Promise.resolve(something);
};

it("baz", async () => {
  await expect(promiseValue()).resolves.toBe(1);
});
```

## How to use

## Version

This rule was added in v0.8.0.

## References

---

---
url: /docs/guide/usage/linter/rules/vitest/no-conditional-tests.md
---

### What it does

The rule disallows the use of conditional statements within test cases to
ensure that tests are deterministic and clearly readable.

### Why is this bad?

Conditional statements in test cases can make tests unpredictable and
harder to understand. Tests should be consistent and straightforward to
ensure reliable results and maintainability.

### Examples

Examples of **incorrect** code for this rule:

```js
describe("my tests", () => {
  if (true) {
    it("is awesome", () => {
      doTheThing();
    });
  }
});
```

Examples of **correct** code for this rule:

```js
describe("my tests", () => {
  it("is awesome", () => {
    doTheThing();
  });
});
```

## How to use

## Version

This rule was added in v0.8.0.

## References

---

---
url: /docs/guide/usage/linter/rules/vitest/no-disabled-tests.md
---

### What it does

This rule raises a warning about disabled tests.

### Why is this bad?

Jest has a feature that allows you to temporarily mark tests as disabled. This
feature is often helpful while debugging or to create placeholders for future
tests. Before committing changes we may want to check that all tests are
running.

### Examples

```js
describe.skip("foo", () => {});
it.skip("foo", () => {});
test.skip("foo", () => {});

describe["skip"]("bar", () => {});
it["skip"]("bar", () => {});
test["skip"]("bar", () => {});

xdescribe("foo", () => {});
xit("foo", () => {});
xtest("foo", () => {});

it("bar");
test("bar");

it("foo", () => {
  pending();
});
```

## How to use

## Version

This rule was added in v0.0.7.

## References

---

---
url: /docs/guide/usage/linter/rules/vitest/no-duplicate-hooks.md
---

### What it does

Disallows duplicate hooks in describe blocks.

### Why is this bad?

Having duplicate hooks in a describe block can lead to confusion and unexpected behavior.
When multiple hooks of the same type exist, they all execute in order, which can make it
difficult to understand the test setup flow and may result in redundant or conflicting
operations. This makes tests harder to maintain and debug.

### Examples

Examples of **incorrect** code for this rule:

```javascript
describe("foo", () => {
  beforeEach(() => {
    // some setup
  });
  beforeEach(() => {
    // some setup
  });
  test("foo_test", () => {
    // some test
  });
});

// Nested describe scenario
describe("foo", () => {
  beforeEach(() => {
    // some setup
  });
  test("foo_test", () => {
    // some test
  });
  describe("bar", () => {
    test("bar_test", () => {
      afterAll(() => {
        // some teardown
      });
      afterAll(() => {
        // some teardown
      });
    });
  });
});
```

Examples of **correct** code for this rule:

```javascript
describe("foo", () => {
  beforeEach(() => {
    // some setup
  });
  test("foo_test", () => {
    // some test
  });
});

// Nested describe scenario
describe("foo", () => {
  beforeEach(() => {
    // some setup
  });
  test("foo_test", () => {
    // some test
  });
  describe("bar", () => {
    test("bar_test", () => {
      beforeEach(() => {
        // some setup
      });
    });
  });
});
```

## How to use

## Version

This rule was added in v0.4.0.

## References

---

---
url: /docs/guide/usage/linter/rules/vitest/no-focused-tests.md
---

### What it does

This rule reminds you to remove `.only` from your tests by raising a warning
whenever you are using the exclusivity feature.

### Why is this bad?

Jest has a feature that allows you to focus tests by appending `.only` or
prepending `f` to a test-suite or a test-case. This feature is really helpful to
debug a failing test, so you don’t have to execute all of your tests. After you
have fixed your test and before committing the changes you have to remove
`.only` to ensure all tests are executed on your build system.

### Examples

Examples of **incorrect** code for this rule:

```javascript
describe.only("foo", () => {});
it.only("foo", () => {});
describe["only"]("bar", () => {});
it["only"]("bar", () => {});
test.only("foo", () => {});
test["only"]("bar", () => {});
fdescribe("foo", () => {});
fit("foo", () => {});
fit.each`
  table
`();
```

## How to use

## Version

This rule was added in v0.0.8.

## References

---

---
url: /docs/guide/usage/linter/rules/vitest/no-hooks.md
---

### What it does

Disallows Jest setup and teardown hooks, such as `beforeAll`.

### Why is this bad?

Jest provides global functions for setup and teardown tasks, which are
called before/after each test case and each test suite. The use of these
hooks promotes shared state between tests.

This rule reports for the following function calls:

* `beforeAll`
* `beforeEach`
* `afterAll`
* `afterEach`

### Examples

Examples of **incorrect** code for this rule:

```javascript
function setupFoo(options) {
  /* ... */
}
function setupBar(options) {
  /* ... */
}

describe("foo", () => {
  let foo;
  beforeEach(() => {
    foo = setupFoo();
  });
  afterEach(() => {
    foo = null;
  });
  it("does something", () => {
    expect(foo.doesSomething()).toBe(true);
  });
  describe("with bar", () => {
    let bar;
    beforeEach(() => {
      bar = setupBar();
    });
    afterEach(() => {
      bar = null;
    });
    it("does something with bar", () => {
      expect(foo.doesSomething(bar)).toBe(true);
    });
  });
});
```

## Configuration

This rule accepts a configuration object with the following properties:

### allow

type: `string[]`

default: `[]`

An array of hook function names that are permitted for use.

## How to use

## Version

This rule was added in v0.0.16.

## References

---

---
url: /docs/guide/usage/linter/rules/vitest/no-identical-title.md
---

### What it does

This rule looks at the title of every test and test suite.
It will report when two test suites or two test cases at the same level of a test suite have the same title.

### Why is this bad?

Having identical titles for two different tests or test suites may create confusion.
For example, when a test with the same title as another test in the same test suite fails, it is harder to know which one failed and thus harder to fix.

### Examples

Examples of **incorrect** code for this rule:

```javascript
describe("baz", () => {
  //...
});

describe("baz", () => {
  // Has the same title as a previous test suite
  // ...
});
```

## How to use

## Version

This rule was added in v0.0.14.

## References

---

---
url: /docs/guide/usage/linter/rules/vitest/no-import-node-test.md
---

### What it does

This rule warns when `node:test` is imported (usually accidentally).
With `--fix`, it will replace the import with `vitest`.

### Why is this bad?

Using `node:test` instead of `vitest` can lead to inconsistent test results
and missing features. `vitest` should be used for all testing to ensure
compatibility and access to its full functionality.

### Examples

Examples of **incorrect** code for this rule:

```javascript
import { test } from "node:test";
import { expect } from "vitest";

test("foo", () => {
  expect(1).toBe(1);
});
```

Examples of **correct** code for this rule:

```javascript
import { test, expect } from "vitest";

test("foo", () => {
  expect(1).toBe(1);
});
```

## How to use

## Version

This rule was added in v0.7.0.

## References

---

---
url: /docs/guide/usage/linter/rules/vitest/no-importing-vitest-globals.md
---

### What it does

The rule disallows importing any Vitest global functions.

### Why is this bad?

If a project is [configured to provide Vitest functions as globals](https://vitest.dev/config/globals.html),
this rule can be used to ensure that the globals are never imported
via `import` or `require`.

Note that this rule should *not* be used if the `globals` config
option is set to `false` in Vitest (`false` is the default configuration).

### Examples

Examples of **incorrect** code for this rule:

```js
import { test, expect } from "vitest";

test("foo", () => {
  expect(1).toBe(1);
});
```

```js
const { test, expect } = require("vitest");

test("foo", () => {
  expect(1).toBe(1);
});
```

Examples of **correct** code for this rule:

```js
test("foo", () => {
  expect(1).toBe(1);
});
```

## How to use

## Version

This rule was added in v1.49.0.

## References

---

---
url: /docs/guide/usage/linter/rules/vitest/no-interpolation-in-snapshots.md
---

### What it does

Prevents the use of string interpolations in snapshots.

### Why is this bad?

Interpolation prevents snapshots from being updated. Instead, properties should
be overloaded with a matcher by using
[property matchers](https://jestjs.io/docs/en/snapshot-testing#property-matchers).

### Examples

Examples of **incorrect** code for this rule:

```javascript
expect(something).toMatchInlineSnapshot(
  `Object {
    property: ${interpolated}
  }`,
);

expect(something).toMatchInlineSnapshot(
  { other: expect.any(Number) },
  `Object {
    other: Any<Number>,
    property: ${interpolated}
  }`,
);

expect(errorThrowingFunction).toThrowErrorMatchingInlineSnapshot(`${interpolated}`);
```

## How to use

## Version

This rule was added in v0.0.13.

## References

---

---
url: /docs/guide/usage/linter/rules/vitest/no-large-snapshots.md
---

### What it does

Disallow large snapshots.

### Why is this bad?

When using Jest's snapshot capability one should be mindful of the size of
created snapshots. As a general best practice snapshots should be limited in
size in order to be more manageable and reviewable. A stored snapshot is only as
good as its review and as such keeping it short, sweet, and readable is
important to allow for thorough reviews.

### Examples

Examples of **incorrect** code for this rule:

```javascript
exports[`a large snapshot 1`] = `
line 1
line 2
line 3
line 4
line 5
line 6
line 7
line 8
line 9
line 10
line 11
line 12
line 13
line 14
line 15
line 16
line 17
line 18
line 19
line 20
line 21
line 22
line 23
line 24
line 25
line 26
line 27
line 28
line 29
line 30
line 31
line 32
line 33
line 34
line 35
line 36
line 37
line 38
line 39
line 40
line 41
line 42
line 43
line 44
line 45
line 46
line 47
line 48
line 49
line 50
line 51
`;
```

Examples of **incorrect** code for this rule:

```js
exports[`a more manageable and readable snapshot 1`] = `
line 1
line 2
line 3
line 4
`;
```

## Configuration

This rule accepts a configuration object with the following properties:

### allowedSnapshots

type: `Record<string, array>`

default: `{}`

A map of snapshot file paths to arrays of snapshot names that are allowed to exceed the size limit.
Snapshot names can be specified as regular expressions.

### inlineMaxSize

type: `integer`

default: `50`

Maximum number of lines allowed for inline snapshots.

### maxSize

type: `integer`

default: `50`

Maximum number of lines allowed for external snapshot files.

## How to use

## Version

This rule was added in v0.4.3.

## References

---

---
url: /docs/guide/usage/linter/rules/vitest/no-mocks-import.md
---

### What it does

This rule reports imports from a path containing a `__mocks__` component.

### Why is this bad?

Manually importing mocks from a `__mocks__` directory can lead to unexpected behavior
and breaks Jest's automatic mocking system. Jest is designed to automatically resolve
and use mocks from `__mocks__` directories when `jest.mock()` is called. Directly
importing from these directories bypasses Jest's module resolution system and can cause
inconsistencies between test and production environments.

### Examples

Examples of **incorrect** code for this rule:

```ts
import thing from "./__mocks__/index";
require("./__mocks__/index");
```

Examples of **correct** code for this rule:

```ts
import thing from "thing";
require("thing");
```

## How to use

## Version

This rule was added in v0.0.13.

## References

---

---
url: /docs/guide/usage/linter/rules/vitest/no-restricted-matchers.md
---

### What it does

Ban specific matchers & modifiers from being used, and can suggest alternatives.

### Why is this bad?

Some matchers or modifiers might be discouraged in your codebase for various reasons:
they might be deprecated, cause confusion, have performance implications, or there
might be better alternatives available. This rule allows you to enforce consistent
testing patterns by restricting certain Jest matchers and providing guidance on
preferred alternatives.

### Examples

Bans are expressed in the form of a map, with the value being either a string message to be shown,
or null if only the default rule message should be used. Bans are checked against the start of
the expect chain - this means that to ban a specific matcher entirely you must specify all
six permutations, but allows you to ban modifiers as well. By default, this map is empty, meaning
no matchers or modifiers are banned.

Example configuration:

```json
{
  "jest/no-restricted-matchers": [
    "error",
    {
      "toBeFalsy": null,
      "resolves": "Use `expect(await promise)` instead.",
      "toHaveBeenCalledWith": null,
      "not.toHaveBeenCalledWith": null,
      "resolves.toHaveBeenCalledWith": null,
      "rejects.toHaveBeenCalledWith": null,
      "resolves.not.toHaveBeenCalledWith": null,
      "rejects.not.toHaveBeenCalledWith": null
    }
  ]
}
```

Examples of **incorrect** code for this rule with the above configuration:

```javascript
it("is false", () => {
  // if this has a modifier (i.e. `not.toBeFalsy`), it would be considered fine
  expect(a).toBeFalsy();
});

it("resolves", async () => {
  // all uses of this modifier are disallowed, regardless of matcher
  await expect(myPromise()).resolves.toBe(true);
});

describe("when an error happens", () => {
  it("does not upload the file", async () => {
    // all uses of this matcher are disallowed
    expect(uploadFileMock).not.toHaveBeenCalledWith("file.name");
  });
});
```

## Configuration

This rule accepts a configuration object with the following properties:

type: `object`

## How to use

## Version

This rule was added in v0.2.3.

## References

---

---
url: /docs/guide/usage/linter/rules/vitest/no-restricted-vi-methods.md
---

### What it does

Restrict the use of specific `jest` and `vi` methods.

### Why is this bad?

Certain Jest or Vitest methods may be deprecated, discouraged in specific
contexts, or incompatible with your testing environment. Restricting
them helps maintain consistent and reliable test practices.

By default, no methods are restricted by this rule.
You must configure the rule for it to disable anything.

### Examples

Examples of **incorrect** code for this rule:

```javascript
jest.useFakeTimers();
it("calls the callback after 1 second via advanceTimersByTime", () => {
  // ...

  jest.advanceTimersByTime(1000);

  // ...
});

test("plays video", () => {
  const spy = jest.spyOn(video, "play");

  // ...
});
```

## Configuration

This rule accepts a configuration object with the following properties:

type: `object`

## How to use

## Version

This rule was added in v0.2.3.

## References

---

---
url: /docs/guide/usage/linter/rules/vitest/no-standalone-expect.md
---

### What it does

Prevents `expect` statements outside of a `test` or `it` block. An `expect`
within a helper function (but outside of a `test` or `it` block) will not
trigger this rule.

Statements like `expect.hasAssertions()` will NOT trigger this rule since these
calls will execute if they are not in a test block.

### Why is this bad?

`expect` statements outside of test blocks will not be executed by the Jest
test runner, which means they won't actually test anything. This can lead to
false confidence in test coverage and may hide bugs that would otherwise be
caught by proper testing.

### Examples

Examples of **incorrect** code for this rule:

```javascript
describe("a test", () => {
  expect(1).toBe(1);
});
```

## Configuration

This rule accepts a configuration object with the following properties:

### additionalTestBlockFunctions

type: `string[]`

default: `[]`

An array of function names that should also be treated as test blocks.

## How to use

## Version

This rule was added in v0.0.13.

## References

---

---
url: /docs/guide/usage/linter/rules/vitest/no-test-prefixes.md
---

### What it does

Require using `.only` and `.skip` over `f` and `x`.

### Why is this bad?

Jest allows you to choose how you want to define focused and skipped tests,
with multiple permutations for each:

* only & skip: it.only, test.only, describe.only, it.skip, test.skip, describe.skip.
* 'f' & 'x': fit, fdescribe, xit, xtest, xdescribe.

This rule enforces usages from the only & skip list.

### Examples

Examples of **incorrect** code for this rule:

```javascript
fit("foo"); // invalid
fdescribe("foo"); // invalid
xit("foo"); // invalid
xtest("foo"); // invalid
xdescribe("foo"); // invalid
```

## How to use

## Version

This rule was added in v0.0.7.

## References

---

---
url: /docs/guide/usage/linter/rules/vitest/no-test-return-statement.md
---

### What it does

Disallow explicitly returning from tests.

### Why is this bad?

Tests in Jest should be void and not return values.
If you are returning Promises then you should update the test to use
`async/await`.

### Examples

Examples of **incorrect** code for this rule:

```javascript
test("one", () => {
  return expect(1).toBe(1);
});
```

Examples of **correct** code for this rule:

```javascript
test("one", () => {
  expect(1).toBe(1);
});
```

## How to use

## Version

This rule was added in v0.2.0.

## References

---

---
url: /docs/guide/usage/linter/rules/vitest/no-unneeded-async-expect-function.md
---

### What it does

Disallows unnecessary async function wrapper for expected promises.

### Why is this bad?

When the only statement inside an async wrapper is `await someCall()`,
the call should be passed directly to `expect` instead. This makes the
test code more concise and easier to read.

### Examples

Examples of **incorrect** code for this rule:

```js
await expect(async () => {
  await doSomethingAsync();
}).rejects.toThrow();

await expect(async () => await doSomethingAsync()).rejects.toThrow();
```

Examples of **correct** code for this rule:

```js
await expect(doSomethingAsync()).rejects.toThrow();
```

## How to use

## Version

This rule was added in v1.39.0.

## References

---

---
url: /docs/guide/usage/linter/rules/vitest/padding-around-after-all-blocks.md
---

### What it does

This rule enforces a line of padding before and after 1 or more
`afterAll` statements.

### Why is this bad?

Inconsistent formatting of code can make the code more difficult to read
and follow. This rule helps ensure that `afterAll` blocks are visually
separated from the rest of the code, making them easier to identify while
looking through test files.

### Examples

Examples of **incorrect** code for this rule:

```js
const thing = 123;
afterAll(() => {});
```

Examples of **correct** code for this rule:

```js
const thing = 123;

afterAll(() => {});
```

## How to use

## Version

This rule was added in v1.66.0.

## References

---

---
url: /docs/guide/usage/linter/rules/vitest/padding-around-test-blocks.md
---

### What it does

This rule enforces a line of padding before and after 1 or more
`test`/`it` statements.

### Why is this bad?

Inconsistent formatting of code can make the code more difficult to read
and follow. This rule helps ensure that test blocks are visually
separated from the rest of the code, making them easier to identify while
looking through test files.

### Examples

Examples of **incorrect** code for this rule:

```js
const thing = 123;
test("foo", () => {});
test("bar", () => {});
```

```js
const thing = 123;
it("foo", () => {});
it("bar", () => {});
```

Examples of **correct** code for this rule:

```js
const thing = 123;

test("foo", () => {});

test("bar", () => {});
```

```js
const thing = 123;

it("foo", () => {});

it("bar", () => {});
```

## How to use

## Version

This rule was added in v1.75.0.

## References

---

---
url: /docs/guide/usage/linter/rules/vitest/prefer-called-exactly-once-with.md
---

### What it does

It checks when a target is asserted with both `toHaveBeenCalledOnce` and `toHaveBeenCalledWith` instead of
`toHaveBeenCalledExactlyOnceWith`.

### Why is this bad?

The reader must deduce from both expectations that the spy function is called once and with specific arguments.

### Examples

Examples of **incorrect** code for this rule:

```js
test("foo", () => {
  const mock = vi.fn();
  mock("foo");
  expect(mock).toHaveBeenCalledOnce();
  expect(mock).toHaveBeenCalledWith("foo");
});
```

Examples of **correct** code for this rule:

```js
test("foo", () => {
  const mock = vi.fn();
  mock("foo");
  expect(mock).toHaveBeenCalledExactlyOnceWith("foo");
});
```

## How to use

## Version

This rule was added in v1.58.0.

## References

---

---
url: /docs/guide/usage/linter/rules/vitest/prefer-called-once.md
---

### What it does

Substitute `toBeCalledTimes(1)` and `toHaveBeenCalledTimes(1)` with
`toBeCalledOnce()` and `toHaveBeenCalledOnce()` respectively.

### Why is this bad?

The `*Times` matchers require reading the argument to know how many
times a spy is expected to be called. Most of the time, you expect a
method to be called once.

### Examples

Examples of **incorrect** code for this rule:

```js
test("foo", () => {
  const mock = vi.fn();
  mock("foo");
  expect(mock).toBeCalledTimes(1);
  expect(mock).toHaveBeenCalledTimes(1);
});
```

Examples of **correct** code for this rule:

```js
test("foo", () => {
  const mock = vi.fn();
  mock("foo");
  expect(mock).toBeCalledOnce();
  expect(mock).toHaveBeenCalledOnce();
});
```

## How to use

## Version

This rule was added in v1.39.0.

## References

---

---
url: /docs/guide/usage/linter/rules/vitest/prefer-called-times.md
---

### What it does

This rule aims to enforce the use of `toBeCalledTimes(1)` or `toHaveBeenCalledTimes(1)` over `toBeCalledOnce()` or `toHaveBeenCalledOnce()`.

### Why is this bad?

This rule aims to enforce the use of `toBeCalledTimes(1)` or `toHaveBeenCalledTimes(1)` over `toBeCalledOnce()` or `toHaveBeenCalledOnce()`.

### Examples

Examples of **incorrect** code for this rule:

```js
test("foo", () => {
  const mock = vi.fn();
  mock("foo");
  expect(mock).toBeCalledOnce();
  expect(mock).toHaveBeenCalledOnce();
});
```

Examples of **correct** code for this rule:

```js
test("foo", () => {
  const mock = vi.fn();
  mock("foo");
  expect(mock).toBeCalledTimes(1);
  expect(mock).toHaveBeenCalledTimes(1);
});
```

## How to use

## Version

This rule was added in v1.35.0.

## References

---

---
url: /docs/guide/usage/linter/rules/vitest/prefer-called-with.md
---

### What it does

Suggest using `toBeCalledWith()` or `toHaveBeenCalledWith()`

### Why is this bad?

When testing function calls, it's often more valuable to assert both
that a function was called AND what arguments it was called with.
Using `toBeCalled()` or `toHaveBeenCalled()` only verifies the function
was invoked, but doesn't validate the arguments, potentially missing
bugs where functions are called with incorrect parameters.

### Examples

Examples of **incorrect** code for this rule:

```javascript
expect(someFunction).toBeCalled();
expect(someFunction).toHaveBeenCalled();
```

Examples of **correct** code for this rule:

```javascript
expect(noArgsFunction).toBeCalledWith();
expect(roughArgsFunction).toBeCalledWith(expect.anything(), expect.any(Date));
expect(anyArgsFunction).toBeCalledTimes(1);
expect(uncalledFunction).not.toBeCalled();
```

## How to use

## Version

This rule was added in v0.2.5.

## References

---

---
url: /docs/guide/usage/linter/rules/vitest/prefer-comparison-matcher.md
---

### What it does

This rule checks for comparisons in tests that could be replaced with one of the
following built-in comparison matchers:

* `toBeGreaterThan`
* `toBeGreaterThanOrEqual`
* `toBeLessThan`
* `toBeLessThanOrEqual`

### Why is this bad?

Using generic matchers like `toBe(true)` with comparison expressions
makes tests less readable and provides less helpful error messages when
they fail. Jest's specific comparison matchers offer clearer intent and
better error output that shows the actual values being compared.

### Examples

Examples of **incorrect** code for this rule:

```js
expect(x > 5).toBe(true);
expect(x < 7).not.toEqual(true);
expect(x <= y).toStrictEqual(true);
```

Examples of **correct** code for this rule:

```js
expect(x).toBeGreaterThan(5);
expect(x).not.toBeLessThanOrEqual(7);
expect(x).toBeLessThanOrEqual(y);
// special case - see below
expect(x < "Carl").toBe(true);
```

## How to use

## Version

This rule was added in v0.2.15.

## References

---

---
url: /docs/guide/usage/linter/rules/vitest/prefer-describe-function-title.md
---

### What it does

When testing a specific function, this rule aims to enforce passing a named function to `describe()`
instead of an equivalent hardcoded string.

### Why is this bad?

For tests that are related to a specific function, if the function being tested is renamed,
the describe title will no longer match and can cause confusion in the future. Using the function
directly ensures consistency even if the function is renamed.

### Examples

Examples of **incorrect** code for this rule:

```js
// myFunction.test.js
import { myFunction } from "./myFunction";

describe("myFunction", () => {
  // ...
});
```

Examples of **correct** code for this rule:

```js
// myFunction.test.js
import { myFunction } from "./myFunction";

describe(myFunction, () => {
  // ...
});
```

## How to use

## Version

This rule was added in v1.39.0.

## References

---

---
url: /docs/guide/usage/linter/rules/vitest/prefer-each.md
---

### What it does

This rule enforces using `each` rather than manual loops.

### Why is this bad?

Manual loops for tests can be less readable and more error-prone. Using
`each` provides a clearer and more concise way to run parameterized tests,
improving readability and maintainability.

### Examples

Examples of **incorrect** code for this rule:

```js
for (const item of items) {
  describe(item, () => {
    expect(item).toBe("foo");
  });
}
```

Examples of **correct** code for this rule:

```js
describe.each(items)("item", (item) => {
  expect(item).toBe("foo");
});
```

## How to use

## Version

This rule was added in v0.9.0.

## References

---

---
url: /docs/guide/usage/linter/rules/vitest/prefer-equality-matcher.md
---

### What it does

Jest has built-in matchers for expecting equality, which allow for more readable
tests and error messages if an expectation fails.

### Why is this bad?

Testing equality expressions with generic matchers like `toBe(true)`
makes tests harder to read and understand. When tests fail, the error
messages are less helpful because they don't show what the actual values
were. Using specific equality matchers provides clearer test intent and
better debugging information.

### Examples

Examples of **incorrect** code for this rule:

```javascript
expect(x === 5).toBe(true);
expect(name === "Carl").not.toEqual(true);
expect(myObj !== thatObj).toStrictEqual(true);
```

Examples of **correct** code for this rule:

```javascript
expect(x).toBe(5);
expect(name).not.toEqual("Carl");
expect(myObj).toStrictEqual(thatObj);
```

## How to use

## Version

This rule was added in v0.2.9.

## References

---

---
url: /docs/guide/usage/linter/rules/vitest/prefer-expect-assertions.md
---

### What it does

Enforces that every test has either `expect.assertions(<number>)` or
`expect.hasAssertions()` as its first expression.

### Why is this bad?

Without explicit assertion counts, tests with asynchronous code,
callbacks, or loops may pass even if some `expect` calls are never
reached, silently hiding bugs.

### Examples

Examples of **incorrect** code for this rule:

```javascript
test("no assertions", () => {
  // ...
});
test("assertions not first", () => {
  expect(true).toBe(true);
  // ...
});
```

Examples of **correct** code for this rule:

```javascript
test("with assertion count", () => {
  expect.assertions(1);
  expect(true).toBe(true);
});
test("with hasAssertions", () => {
  expect.hasAssertions();
  expect(true).toBe(true);
});
```

///Examples of **incorrect** code with `{ "onlyFunctionsWithAsyncKeyword": true }`:

```javascript
test("fetches data", async () => {
  const data = await fetchData();
  expect(data).toBe("peanut butter");
});
```

Examples of **correct** code with `{ "onlyFunctionsWithAsyncKeyword": true }`:

```javascript
test("fetches data", async () => {
  expect.assertions(1);
  const data = await fetchData();
  expect(data).toBe("peanut butter");
});
```

Examples of **incorrect** code with `{ "onlyFunctionsWithExpectInLoop": true }`:

```javascript
test("all numbers are greater than zero", () => {
  for (const number of getNumbers()) {
    expect(number).toBeGreaterThan(0);
  }
});
```

Examples of **correct** code with `{ "onlyFunctionsWithExpectInLoop": true }`:

```javascript
test("all numbers are greater than zero", () => {
  expect.hasAssertions();
  for (const number of getNumbers()) {
    expect(number).toBeGreaterThan(0);
  }
});
```

Examples of **incorrect** code with `{ "onlyFunctionsWithExpectInCallback": true }`:

```javascript
test("callback test", () => {
  fetchData((data) => {
    expect(data).toBe("peanut butter");
  });
});
```

Examples of **correct** code with `{ "onlyFunctionsWithExpectInCallback": true }`:

```javascript
test("callback test", () => {
  expect.assertions(1);
  fetchData((data) => {
    expect(data).toBe("peanut butter");
  });
});
```

## Configuration

This rule accepts a configuration object with the following properties:

### onlyFunctionsWithAsyncKeyword

type: `boolean`

default: `false`

### onlyFunctionsWithExpectInCallback

type: `boolean`

default: `false`

### onlyFunctionsWithExpectInLoop

type: `boolean`

default: `false`

## How to use

## Version

This rule was added in v1.62.0.

## References

---

---
url: /docs/guide/usage/linter/rules/vitest/prefer-expect-resolves.md
---

### What it does

Prefer `await expect(...).resolves` over `expect(await ...)` when testing
promises.

### Why is this bad?

When working with promises, there are two primary ways you can test the
resolved value:

1. use the `resolve` modifier on `expect`
   (`await expect(...).resolves.<matcher>` style)
2. `await` the promise and assert against its result
   (`expect(await ...).<matcher>` style)

While the second style is arguably less dependent on `jest`, if the
promise rejects it will be treated as a general error, resulting in less
predictable behaviour and output from `jest`.

Additionally, favoring the first style ensures consistency with its
`rejects` counterpart, as there is no way of "awaiting" a rejection.

### Examples

Examples of **incorrect** code for this rule:

```javascript
it("passes", async () => {
  expect(await someValue()).toBe(true);
});
it("is true", async () => {
  const myPromise = Promise.resolve(true);
  expect(await myPromise).toBe(true);
});
```

Examples of **correct** code for this rule:

```javascript
it("passes", async () => {
  await expect(someValue()).resolves.toBe(true);
});
it("is true", async () => {
  const myPromise = Promise.resolve(true);

  await expect(myPromise).resolves.toBe(true);
});
it("errors", async () => {
  await expect(Promise.reject(new Error("oh noes!"))).rejects.toThrowError("oh noes!");
});
```

## How to use

## Version

This rule was added in v0.2.14.

## References

---

---
url: /docs/guide/usage/linter/rules/vitest/prefer-expect-type-of.md
---

### What it does

Enforce using [`toBeTypeOf`](https://vitest.dev/api/expect#tobetypeof) instead of `expect(typeof ...).toBe(...)`.

### Why is this bad?

`expect(typeof value).toBe(type)` works but is awkward and produces poor failure messages.
Vitest's built-in `toBeTypeOf` matcher performs the same `typeof` comparison with a clearer API and better error output.

### Examples

Examples of **incorrect** code for this rule:

```js
test("type checking", () => {
  expect(typeof "hello").toBe("string");
  expect(typeof 42).toBe("number");
  expect(typeof true).toBe("boolean");
  expect(typeof {}).toBe("object");
  expect(typeof (() => {})).toBe("function");
  expect(typeof Symbol()).toBe("symbol");
  expect(typeof 123n).toBe("bigint");
  expect(typeof undefined).toBe("undefined");
});
```

Examples of **correct** code for this rule:

```js
test("type checking", () => {
  expect("hello").toBeTypeOf("string");
  expect(42).toBeTypeOf("number");
  expect(true).toBeTypeOf("boolean");
  expect({}).toBeTypeOf("object");
  expect(() => {}).toBeTypeOf("function");
  expect(Symbol()).toBeTypeOf("symbol");
  expect(123n).toBeTypeOf("bigint");
  expect(undefined).toBeTypeOf("undefined");
});
```

## How to use

## Version

This rule was added in v1.44.0.

## References

---

---
url: /docs/guide/usage/linter/rules/vitest/prefer-hooks-in-order.md
---

### What it does

Ensures that hooks are in the order that they are called in.

### Why is this bad?

While hooks can be setup in any order, they're always called by `jest` in this
specific order:

1. `beforeAll`
2. `beforeEach`
3. `afterEach`
4. `afterAll`

This rule aims to make that more obvious by enforcing grouped hooks be setup in
that order within tests.

### Examples

Examples of **incorrect** code for this rule:

```javascript
describe("foo", () => {
  beforeEach(() => {
    seedMyDatabase();
  });
  beforeAll(() => {
    createMyDatabase();
  });
  it("accepts this input", () => {
    // ...
  });
  it("returns that value", () => {
    // ...
  });
  describe("when the database has specific values", () => {
    const specificValue = "...";
    beforeEach(() => {
      seedMyDatabase(specificValue);
    });
    it("accepts that input", () => {
      // ...
    });
    it("throws an error", () => {
      // ...
    });
    afterEach(() => {
      clearLogger();
    });
    beforeEach(() => {
      mockLogger();
    });
    it("logs a message", () => {
      // ...
    });
  });
  afterAll(() => {
    removeMyDatabase();
  });
});
```

Examples of **correct** code for this rule:

```javascript
describe("foo", () => {
  beforeAll(() => {
    createMyDatabase();
  });
  beforeEach(() => {
    seedMyDatabase();
  });
  it("accepts this input", () => {
    // ...
  });
  it("returns that value", () => {
    // ...
  });
  describe("when the database has specific values", () => {
    const specificValue = "...";
    beforeEach(() => {
      seedMyDatabase(specificValue);
    });
    it("accepts that input", () => {
      // ...
    });
    it("throws an error", () => {
      // ...
    });
    beforeEach(() => {
      mockLogger();
    });
    afterEach(() => {
      clearLogger();
    });
    it("logs a message", () => {
      // ...
    });
  });
  afterAll(() => {
    removeMyDatabase();
  });
});
```

## How to use

## Version

This rule was added in v0.6.0.

## References

---

---
url: /docs/guide/usage/linter/rules/vitest/prefer-hooks-on-top.md
---

### What it does

While hooks can be setup anywhere in a test file, they are always called in a
specific order, which means it can be confusing if they're intermixed with test
cases.

### Why is this bad?

When hooks are mixed with test cases, it becomes harder to understand
the test setup and execution order. This can lead to confusion about
which hooks apply to which tests and when they run. Grouping hooks at
the top of each `describe` block makes the test structure clearer and
more maintainable.

### Examples

Examples of **incorrect** code for this rule:

```javascript
describe("foo", () => {
  beforeEach(() => {
    seedMyDatabase();
  });

  it("accepts this input", () => {
    // ...
  });

  beforeAll(() => {
    createMyDatabase();
  });

  it("returns that value", () => {
    // ...
  });

  describe("when the database has specific values", () => {
    const specificValue = "...";
    beforeEach(() => {
      seedMyDatabase(specificValue);
    });

    it("accepts that input", () => {
      // ...
    });

    it("throws an error", () => {
      // ...
    });

    afterEach(() => {
      clearLogger();
    });

    beforeEach(() => {
      mockLogger();
    });

    it("logs a message", () => {
      // ...
    });
  });

  afterAll(() => {
    removeMyDatabase();
  });
});
```

Examples of **correct** code for this rule:

```javascript
describe("foo", () => {
  beforeAll(() => {
    createMyDatabase();
  });

  beforeEach(() => {
    seedMyDatabase();
  });

  afterAll(() => {
    clearMyDatabase();
  });

  it("accepts this input", () => {
    // ...
  });

  it("returns that value", () => {
    // ...
  });

  describe("when the database has specific values", () => {
    const specificValue = "...";

    beforeEach(() => {
      seedMyDatabase(specificValue);
    });

    beforeEach(() => {
      mockLogger();
    });

    afterEach(() => {
      clearLogger();
    });

    it("accepts that input", () => {
      // ...
    });

    it("throws an error", () => {
      // ...
    });

    it("logs a message", () => {
      // ...
    });
  });
});
```

## How to use

## Version

This rule was added in v0.4.2.

## References

---

---
url: /docs/guide/usage/linter/rules/vitest/prefer-import-in-mock.md
---

### What it does

This rule enforces using a dynamic `import()` in `vi.mock()` or `vi.doMock()`, which improves type information and IntelliSense for the mocked module.

### Why is this bad?

A lack of type information and IntelliSense increases the risk of mismatches between the real module and its mock.

### Examples

Examples of **incorrect** code for this rule:

```js
vi.mock("./path/to/module");
vi.doMock("./path/to/module");
```

Examples of **correct** code for this rule:

```js
vi.mock(import("./path/to/module"));
vi.doMock(import("./path/to/module"));
```

## Configuration

This rule accepts a configuration object with the following properties:

### fixable

type: `boolean`

Whether the rule should generate fixes or not.

## How to use

## Version

This rule was added in v1.49.0.

## References

---

---
url: /docs/guide/usage/linter/rules/vitest/prefer-importing-vitest-globals.md
---

### What it does

Enforces explicit imports from 'vitest' instead of using Vitest globals.

### Why is this bad?

Using Vitest globals without importing them relies on implicit global configuration
(`globals: true` in vitest config). Explicit imports make dependencies clear,
improve IDE support, and ensure compatibility across different setups.

### Examples

Examples of **incorrect** code for this rule:

```js
describe("suite", () => {
  it("test", () => {
    expect(true).toBe(true);
  });
});
```

Examples of **correct** code for this rule:

```js
import { describe, it, expect } from "vitest";

describe("suite", () => {
  it("test", () => {
    expect(true).toBe(true);
  });
});
```

## How to use

## Version

This rule was added in v1.59.0.

## References

---

---
url: /docs/guide/usage/linter/rules/vitest/prefer-lowercase-title.md
---

### What it does

Enforce `it`, `test`, `describe`, and `bench` to have descriptions that begin with a
lowercase letter. This provides more readable test failures.

### Why is this bad?

Lowercase messages for test failures generally result in more grammatically correct
failure messages when you have a test failure.

### Examples

Examples of **incorrect** code for this rule:

```javascript
it("Adds 1 + 2 to equal 3", () => {
  expect(sum(1, 2)).toBe(3);
});
```

Examples of **correct** code for this rule:

```javascript
it("adds 1 + 2 to equal 3", () => {
  expect(sum(1, 2)).toBe(3);
});
```

## Configuration

This rule accepts a configuration object with the following properties:

### allowedPrefixes

type: `string[]`

default: `[]`

This array option allows specifying prefixes, which contain capitals that titles
can start with. This can be useful when writing tests for API endpoints, where
you'd like to prefix with the HTTP method.
By default, nothing is allowed (the equivalent of `{ "allowedPrefixes": [] }`).

Example of **correct** code for the `{ "allowedPrefixes": ["GET"] }` option:

```js
/* jest/prefer-lowercase-title: ["error", { "allowedPrefixes": ["GET"] }] */
describe("GET /live");
```

### ignore

type: `string[]`

default: `[]`

This array option controls which Jest or Vitest functions are checked by this rule. There
are four possible values:

* `"describe"`
* `"test"`
* `"it"`
* `"bench"`

By default, none of these options are enabled (the equivalent of
`{ "ignore": [] }`).

Example of **correct** code for the `{ "ignore": ["describe"] }` option:

```js
/* jest/prefer-lowercase-title: ["error", { "ignore": ["describe"] }] */
describe("Uppercase description");
```

Example of **correct** code for the `{ "ignore": ["test"] }` option:

```js
/* jest/prefer-lowercase-title: ["error", { "ignore": ["test"] }] */
test("Uppercase description");
```

Example of **correct** code for the `{ "ignore": ["it"] }` option:

```js
/* jest/prefer-lowercase-title: ["error", { "ignore": ["it"] }] */
it("Uppercase description");
```

### ignoreTopLevelDescribe

type: `boolean`

default: `false`

This option can be set to allow only the top-level `describe` blocks to have a
title starting with an upper-case letter.

Example of **correct** code for the `{ "ignoreTopLevelDescribe": true }` option:

```js
/* jest/prefer-lowercase-title: ["error", { "ignoreTopLevelDescribe": true }] */
describe("MyClass", () => {
  describe("#myMethod", () => {
    it("does things", () => {
      //
    });
  });
});
```

### lowercaseFirstCharacterOnly

type: `boolean`

default: `true`

This option can be set to only validate that the first character of a test name is lowercased.

Example of **correct** code for the `{ "lowercaseFirstCharacterOnly": true }` option:

```js
/* vitest/prefer-lowercase-title: ["error", { "lowercaseFirstCharacterOnly": true }] */
describe("myClass", () => {
  describe("myMethod", () => {
    it("does things", () => {
      //
    });
  });
});
```

Example of **incorrect** code for the `{ "lowercaseFirstCharacterOnly": true }` option:

```js
/* vitest/prefer-lowercase-title: ["error", { "lowercaseFirstCharacterOnly": true }] */
describe("MyClass", () => {
  describe("MyMethod", () => {
    it("does things", () => {
      //
    });
  });
});
```

## How to use

## Version

This rule was added in v0.15.9.

## References

---

---
url: /docs/guide/usage/linter/rules/vitest/prefer-mock-promise-shorthand.md
---

### What it does

When working with mocks of functions that return promises, Jest provides some
API sugar functions to reduce the amount of boilerplate you have to write.
These methods should be preferred when possible.

### Why is this bad?

Using generic mock functions like `mockImplementation(() => Promise.resolve())`
or `mockReturnValue(Promise.reject())` is more verbose and less readable than
Jest's specialized promise shorthands. The shorthand methods like
`mockResolvedValue()` and `mockRejectedValue()` are more expressive and
make the test intent clearer.

### Examples

Examples of **incorrect** code for this rule:

```javascript
jest.fn().mockImplementation(() => Promise.resolve(123));
jest.spyOn(fs.promises, "readFile").mockReturnValue(Promise.reject(new Error("oh noes!")));

myFunction
  .mockReturnValueOnce(Promise.resolve(42))
  .mockImplementationOnce(() => Promise.resolve(42))
  .mockReturnValue(Promise.reject(new Error("too many calls!")));
```

Examples of **correct** code for this rule:

```javascript
jest.fn().mockResolvedValue(123);
jest.spyOn(fs.promises, "readFile").mockRejectedValue(new Error("oh noes!"));

myFunction
  .mockResolvedValueOnce(42)
  .mockResolvedValueOnce(42)
  .mockRejectedValue(new Error("too many calls!"));
```

## How to use

## Version

This rule was added in v0.2.16.

## References

---

---
url: /docs/guide/usage/linter/rules/vitest/prefer-mock-return-shorthand.md
---

### What it does

When working with mocks of functions that return simple values, Jest provides some API sugar functions to reduce the amount of boilerplate you have to write.

### Why is this bad?

Not using Jest's API sugar functions adds unnecessary boilerplate and makes tests harder to read. These helpers clearly express intent
and reduce errors, keeping tests simple and maintainable.

### Examples

Examples of **incorrect** code for this rule:

```js
jest.fn().mockImplementation(() => "hello world");

jest
  .spyOn(fs.promises, "readFile")
  .mockImplementationOnce(() => Promise.reject(new Error("oh noes!")));

myFunction
  .mockImplementationOnce(() => 42)
  .mockImplementationOnce(() => Promise.resolve(42))
  .mockReturnValue(0);
```

Examples of **correct** code for this rule:

```js
jest.fn().mockResolvedValue(123);

jest.spyOn(fs.promises, "readFile").mockReturnValue(Promise.reject(new Error("oh noes!")));
jest.spyOn(fs.promises, "readFile").mockRejectedValue(new Error("oh noes!"));

jest.spyOn(fs, "readFileSync").mockImplementationOnce(() => {
  throw new Error("oh noes!");
});

myFunction.mockResolvedValueOnce(42).mockResolvedValueOnce(42).mockReturnValue(0);
```

## How to use

## Version

This rule was added in v1.49.0.

## References

---

---
url: /docs/guide/usage/linter/rules/vitest/prefer-snapshot-hint.md
---

### What it does

Enforces including a hint string with snapshot matchers (toMatchSnapshot and toThrowErrorMatchingSnapshot).

### Why is this bad?

Auto-numbered snapshot names are fragile — adding or reordering assertions shifts all subsequent numbers, causing unrelated snapshots to appear changed and obscuring real differences in code review.

### Examples

Examples of **incorrect** code for this rule configured as `always`:

```js
const snapshotOutput = ({ stdout, stderr }) => {
  expect(stdout).toMatchSnapshot();
  expect(stderr).toMatchSnapshot();
};

describe("cli", () => {
  describe("--version flag", () => {
    it("prints the version", async () => {
      snapshotOutput(await runCli(["--version"]));
    });
  });

  describe("--config flag", () => {
    it("reads the config", async () => {
      const { stdout, parsedConfig } = await runCli(["--config", "jest.config.js"]);

      expect(stdout).toMatchSnapshot();
      expect(parsedConfig).toMatchSnapshot();
    });

    it("prints nothing to stderr", async () => {
      const { stderr } = await runCli(["--config", "jest.config.js"]);

      expect(stderr).toMatchSnapshot();
    });

    describe("when the file does not exist", () => {
      it("throws an error", async () => {
        await expect(
          runCli(["--config", "does-not-exist.js"]),
        ).rejects.toThrowErrorMatchingSnapshot();
      });
    });
  });
});
```

Examples of **incorrect** code for this rule configured as `multi`:

```js
const snapshotOutput = ({ stdout, stderr }) => {
  expect(stdout).toMatchSnapshot();
  expect(stderr).toMatchSnapshot();
};

describe("cli", () => {
  describe("--version flag", () => {
    it("prints the version", async () => {
      snapshotOutput(await runCli(["--version"]));
    });
  });

  describe("--config flag", () => {
    it("reads the config", async () => {
      const { stdout, parsedConfig } = await runCli(["--config", "jest.config.js"]);

      expect(stdout).toMatchSnapshot();
      expect(parsedConfig).toMatchSnapshot();
    });

    it("prints nothing to stderr", async () => {
      const { stderr } = await runCli(["--config", "jest.config.js"]);

      expect(stderr).toMatchSnapshot();
    });
  });
});
```

Examples of **correct** code for this rule configured as `always`:

```js
const snapshotOutput = ({ stdout, stderr }, hints) => {
  expect(stdout).toMatchSnapshot({}, `stdout: ${hints.stdout}`);
  expect(stderr).toMatchSnapshot({}, `stderr: ${hints.stderr}`);
};

describe("cli", () => {
  describe("--version flag", () => {
    it("prints the version", async () => {
      snapshotOutput(await runCli(["--version"]), {
        stdout: "version string",
        stderr: "empty",
      });
    });
  });

  describe("--config flag", () => {
    it("reads the config", async () => {
      const { stdout } = await runCli(["--config", "jest.config.js"]);

      expect(stdout).toMatchSnapshot({}, "stdout: config settings");
    });

    it("prints nothing to stderr", async () => {
      const { stderr } = await runCli(["--config", "jest.config.js"]);

      expect(stderr).toMatchInlineSnapshot();
    });

    describe("when the file does not exist", () => {
      it("throws an error", async () => {
        await expect(
          runCli(["--config", "does-not-exist.js"]),
        ).rejects.toThrowErrorMatchingSnapshot("stderr: config error");
      });
    });
  });
});
```

Examples of **correct** code for this rule configured as `multi`:

```js
const snapshotOutput = ({ stdout, stderr }, hints) => {
  expect(stdout).toMatchSnapshot({}, `stdout: ${hints.stdout}`);
  expect(stderr).toMatchSnapshot({}, `stderr: ${hints.stderr}`);
};

describe("cli", () => {
  describe("--version flag", () => {
    it("prints the version", async () => {
      snapshotOutput(await runCli(["--version"]), {
        stdout: "version string",
        stderr: "empty",
      });
    });
  });

  describe("--config flag", () => {
    it("reads the config", async () => {
      const { stdout } = await runCli(["--config", "jest.config.js"]);

      expect(stdout).toMatchSnapshot();
    });

    it("prints nothing to stderr", async () => {
      const { stderr } = await runCli(["--config", "jest.config.js"]);

      expect(stderr).toMatchInlineSnapshot();
    });

    describe("when the file does not exist", () => {
      it("throws an error", async () => {
        await expect(
          runCli(["--config", "does-not-exist.js"]),
        ).rejects.toThrowErrorMatchingSnapshot();
      });
    });
  });
});
```

## Configuration

This rule accepts one of the following string values:

### `"always"`

Require a hint to always be provided when using external snapshot matchers.

### `"multi"`

Require a hint to be provided when there are multiple external snapshot matchers within the scope (meaning it includes nested calls).

## How to use

## Version

This rule was added in v1.59.0.

## References

---

---
url: /docs/guide/usage/linter/rules/vitest/prefer-spy-on.md
---

### What it does

When mocking a function by overwriting a property you have to manually restore
the original implementation when cleaning up. When using `jest.spyOn()` Jest
keeps track of changes, and they can be restored with `jest.restoreAllMocks()`,
`mockFn.mockRestore()` or by setting `restoreMocks` to `true` in the Jest
config.

Note: The mock created by `jest.spyOn()` still behaves the same as the original
function. The original function can be overwritten with
`mockFn.mockImplementation()` or by some of the
[other mock functions](https://jestjs.io/docs/en/mock-function-api).

### Why is this bad?

Directly overwriting properties with mock functions can lead to cleanup issues
and test isolation problems. When you manually assign a mock to a property,
you're responsible for restoring the original implementation, which is easy to
forget and can cause tests to interfere with each other. Using `jest.spyOn()`
provides automatic cleanup capabilities and makes your tests more reliable.

### Examples

Examples of **incorrect** code for this rule:

```javascript
Date.now = jest.fn();
Date.now = jest.fn(() => 10);
```

Examples of **correct** code for this rule:

```javascript
jest.spyOn(Date, "now");
jest.spyOn(Date, "now").mockImplementation(() => 10);
```

## How to use

## Version

This rule was added in v0.2.14.

## References

---

---
url: /docs/guide/usage/linter/rules/vitest/prefer-strict-boolean-matchers.md
---

### What it does

Enforce using `toBe(true)` and `toBe(false)` over matchers that coerce types to boolean.

### Why is this bad?

Truthy/falsy matchers coerce values to boolean and can hide type mistakes.
Strict boolean assertions make intent explicit and avoid accidental coercion.

### Examples

Examples of **incorrect** code for this rule:

```javascript
expect(foo).toBeTruthy();
expectTypeOf(foo).toBeTruthy();
expect(foo).toBeFalsy();
expectTypeOf(foo).toBeFalsy();
```

Examples of **correct** code for this rule:

```javascript
expect(foo).toBe(true);
expectTypeOf(foo).toBe(true);
expect(foo).toBe(false);
expectTypeOf(foo).toBe(false);
```

## How to use

## Version

This rule was added in v1.57.0.

## References

---

---
url: /docs/guide/usage/linter/rules/vitest/prefer-strict-equal.md
---

### What it does

This rule triggers a warning if `toEqual()` is used to assert equality.

### Why is this bad?

The `toEqual()` matcher performs a deep equality check but ignores
`undefined` values in objects and arrays. This can lead to false
positives where tests pass when they should fail. `toStrictEqual()`
provides more accurate comparison by checking for `undefined` values.

### Examples

Examples of **incorrect** code for this rule:

```javascript
expect({ a: "a", b: undefined }).toEqual({ a: "a" });
```

Examples of **correct** code for this rule:

```javascript
expect({ a: "a", b: undefined }).toStrictEqual({ a: "a" });
```

## How to use

## Version

This rule was added in v0.2.13.

## References

---

---
url: /docs/guide/usage/linter/rules/vitest/prefer-to-be.md
---

### What it does

Recommends using `toBe` matcher for primitive literals and specific
matchers for `null`, `undefined`, and `NaN`.

### Why is this bad?

When asserting against primitive literals such as numbers and strings,
the equality matchers all operate the same, but read slightly
differently in code.

This rule recommends using the `toBe` matcher in these situations, as
it forms the most grammatically natural sentence. For `null`,
`undefined`, and `NaN` this rule recommends using their specific `toBe`
matchers, as they give better error messages as well.

### Examples

Examples of **incorrect** code for this rule:

```javascript
expect(value).not.toEqual(5);
expect(getMessage()).toStrictEqual("hello world");
expect(loadMessage()).resolves.toEqual("hello world");
```

Examples of **correct** code for this rule:

```javascript
expect(value).not.toBe(5);
expect(getMessage()).toBe("hello world");
expect(loadMessage()).resolves.toBe("hello world");
expect(didError).not.toBe(true);
expect(catchError()).toStrictEqual({ message: "oh noes!" });
```

## How to use

## Version

This rule was added in v0.2.14.

## References

---

---
url: /docs/guide/usage/linter/rules/vitest/prefer-to-be-falsy.md
---

### What it does

This rule warns when `toBe(false)` is used with `expect` or `expectTypeOf`.
With `--fix`, it will be replaced with `toBeFalsy()`.

### Why is this bad?

Using `toBe(false)` is less expressive and may not account for other falsy
values like `0`, `null`, or `undefined`. `toBeFalsy()` provides a more
comprehensive check for any falsy value, improving the robustness of the tests.

### Examples

Examples of **incorrect** code for this rule:

```javascript
expect(foo).toBe(false);
expectTypeOf(foo).toBe(false);
```

Examples of **correct** code for this rule:

```javascript
expect(foo).toBeFalsy();
expectTypeOf(foo).toBeFalsy();
```

## How to use

## Version

This rule was added in v0.7.1.

## References

---

---
url: /docs/guide/usage/linter/rules/vitest/prefer-to-be-object.md
---

### What it does

This rule enforces using `toBeObject()` to check if a value is of type `Object`.

### Why is this bad?

Using other methods such as `toBeInstanceOf(Object)` or `instanceof Object` can
be less clear and potentially misleading. Enforcing the use of `toBeObject()`
provides more explicit and readable code, making your intentions clear and
improving the overall maintainability and readability of your tests.

### Examples

Examples of **incorrect** code for this rule:

```js
expectTypeOf({}).toBeInstanceOf(Object);
expectTypeOf({} instanceof Object).toBeTruthy();
```

Examples of **correct** code for this rule:

```js
expectTypeOf({}).toBeObject();
expectTypeOf({}).toBeObject();
```

## How to use

## Version

This rule was added in v0.9.2.

## References

---

---
url: /docs/guide/usage/linter/rules/vitest/prefer-to-be-truthy.md
---

### What it does

This rule warns when `toBe(true)` is used with `expect` or `expectTypeOf`.
With `--fix`, it will be replaced with `toBeTruthy()`.

### Why is this bad?

Using `toBe(true)` is less flexible and may not account for other truthy
values like non-empty strings or objects. `toBeTruthy()` checks for any
truthy value, which makes the tests more comprehensive and robust.

### Examples

Examples of **incorrect** code for this rule:

```javascript
expect(foo).toBe(true);
expectTypeOf(foo).toBe(true);
```

Examples of **correct** code for this rule:

```javascript
expect(foo).toBeTruthy();
expectTypeOf(foo).toBeTruthy();
```

## How to use

## Version

This rule was added in v0.7.1.

## References

---

---
url: /docs/guide/usage/linter/rules/vitest/prefer-to-contain.md
---

### What it does

In order to have a better failure message, `toContain()` should be used upon
asserting expectations on an array containing an object.

### Why is this bad?

This rule triggers a warning if `toBe()`, `toEqual()` or `toStrictEqual()` is
used to assert object inclusion in an array

### Examples

Examples of **incorrect** code for this rule:

```javascript
expect(a.includes(b)).toBe(true);
expect(a.includes(b)).not.toBe(true);
expect(a.includes(b)).toBe(false);
expect(a.includes(b)).toEqual(true);
expect(a.includes(b)).toStrictEqual(true);
```

Examples of **correct** code for this rule:

```javascript
expect(a).toContain(b);
expect(a).not.toContain(b);
```

## How to use

## Version

This rule was added in v0.2.14.

## References

---

---
url: /docs/guide/usage/linter/rules/vitest/prefer-to-have-been-called-times.md
---

### What it does

In order to have a better failure message, [`toHaveBeenCalledTimes` should be used
instead of directly checking the length of `mock.calls`](https://github.com/jest-community/eslint-plugin-jest/blob/v29.5.0/docs/rules/prefer-to-have-been-called-times.md).

### Why is this bad?

This rule triggers a warning if `toHaveLength` is used to assert the number of times a mock is called.

### Examples

Examples of **incorrect** code for this rule:

```js
expect(someFunction.mock.calls).toHaveLength(1);
expect(someFunction.mock.calls).toHaveLength(0);
expect(someFunction.mock.calls).not.toHaveLength(1);
```

Examples of **correct** code for this rule:

```js
expect(someFunction).toHaveBeenCalledTimes(1);
expect(someFunction).toHaveBeenCalledTimes(0);
expect(someFunction).not.toHaveBeenCalledTimes(0);
expect(uncalledFunction).not.toBeCalled();
expect(method.mock.calls[0][0]).toStrictEqual(value);
```

## How to use

## Version

This rule was added in v1.34.0.

## References

---

---
url: /docs/guide/usage/linter/rules/vitest/prefer-to-have-length.md
---

### What it does

In order to have a better failure message, `toHaveLength()` should be used upon
asserting expectations on objects length property.

### Why is this bad?

This rule triggers a warning if `toBe()`, `toEqual()` or `toStrictEqual()` is
used to assert objects length property.

### Examples

Examples of **incorrect** code for this rule:

```javascript
expect(files["length"]).toBe(1);
expect(files["length"]).toBe(1);
expect(files["length"])["not"].toBe(1);
```

Examples of **correct** code for this rule:

```javascript
expect(files).toHaveLength(1);
```

## How to use

## Version

This rule was added in v0.2.13.

## References

---

---
url: /docs/guide/usage/linter/rules/vitest/prefer-todo.md
---

### What it does

When test cases are empty then it is better to mark them as `test.todo` as it
will be highlighted in the summary output.

### Why is this bad?

This rule triggers a warning if empty test cases are used without 'test.todo'.

### Examples

Examples of **incorrect** code for this rule:

```javascript
test("i need to write this test"); // invalid
test("i need to write this test", () => {}); // invalid
test.skip("i need to write this test", () => {}); // invalid
```

Examples of **correct** code for this rule:

```javascript
test.todo("i need to write this test");
```

## How to use

## Version

This rule was added in v0.0.16.

## References

---

---
url: /docs/guide/usage/linter/rules/vitest/require-awaited-expect-poll.md
---

### What it does

This rule ensures that promises returned by `expect.poll` and `expect.element` calls are handled properly.

### Why is this bad?

`expect.poll` and `expect.element` return promises. If not awaited or returned,
the test completes before the assertion resolves, meaning the test will pass
regardless of whether the assertion succeeds or fails.

### Examples

Examples of **incorrect** code for this rule:

```js
test("element exists", () => {
  asyncInjectElement();

  expect.poll(() => document.querySelector(".element")).toBeInTheDocument();
});
```

Examples of **correct** code for this rule:

```js
test("element exists", () => {
  asyncInjectElement();

  return expect.poll(() => document.querySelector(".element")).toBeInTheDocument();
});
test("element exists", async () => {
  asyncInjectElement();

  await expect.poll(() => document.querySelector(".element")).toBeInTheDocument();
});
```

## How to use

## Version

This rule was added in v1.58.0.

## References

---

---
url: /docs/guide/usage/linter/rules/vitest/require-hook.md
---

### What it does

This rule flags any expression that is either at the toplevel of a test file or
directly within the body of a `describe`, *except* for the following:

* `import` statements
* `const` variables
* `let` *declarations*, and initializations to `null` or `undefined`
* Classes
* Types
* Calls to the standard Jest globals

### Why is this bad?

Having setup and teardown code outside of hooks can lead to unpredictable test
behavior. Code that runs at the top level executes when the test file is loaded,
not when tests run, which can cause issues with test isolation and make tests
dependent on execution order. Using proper hooks like `beforeEach`, `beforeAll`,
`afterEach`, and `afterAll` ensures that setup and teardown code runs at the
correct time and maintains test isolation.

### Examples

Examples of **incorrect** code for this rule:

```javascript
import { database, isCity } from "../database";
import { Logger } from "../../../src/Logger";
import { loadCities } from "../api";

jest.mock("../api");

const initializeCityDatabase = () => {
  database.addCity("Vienna");
  database.addCity("San Juan");
  database.addCity("Wellington");
};

const clearCityDatabase = () => {
  database.clear();
};

initializeCityDatabase();

test("that persists cities", () => {
  expect(database.cities.length).toHaveLength(3);
});
test("city database has Vienna", () => {
  expect(isCity("Vienna")).toBeTruthy();
});

test("city database has San Juan", () => {
  expect(isCity("San Juan")).toBeTruthy();
});

describe("when loading cities from the api", () => {
  let consoleWarnSpy = jest.spyOn(console, "warn");
  loadCities.mockResolvedValue(["Wellington", "London"]);

  it("does not duplicate cities", async () => {
    await database.loadCities();
    expect(database.cities).toHaveLength(4);
  });
});
clearCityDatabase();
```

Examples of **correct** code for this rule:

```javascript
import { database, isCity } from "../database";
import { Logger } from "../../../src/Logger";
import { loadCities } from "../api";

jest.mock("../api");
const initializeCityDatabase = () => {
  database.addCity("Vienna");
  database.addCity("San Juan");
  database.addCity("Wellington");
};

const clearCityDatabase = () => {
  database.clear();
};

beforeEach(() => {
  initializeCityDatabase();
});

test("that persists cities", () => {
  expect(database.cities.length).toHaveLength(3);
});

test("city database has Vienna", () => {
  expect(isCity("Vienna")).toBeTruthy();
});

test("city database has San Juan", () => {
  expect(isCity("San Juan")).toBeTruthy();
});

describe("when loading cities from the api", () => {
  let consoleWarnSpy;
  beforeEach(() => {
    consoleWarnSpy = jest.spyOn(console, "warn");
    loadCities.mockResolvedValue(["Wellington", "London"]);
  });

  it("does not duplicate cities", async () => {
    await database.loadCities();
    expect(database.cities).toHaveLength(4);
  });
});
afterEach(() => {
  clearCityDatabase();
});
```

## Configuration

This rule accepts a configuration object with the following properties:

### allowedFunctionCalls

type: `string[]`

default: `[]`

An array of function names that are allowed to be called outside of hooks.

## How to use

## Version

This rule was added in v0.3.2.

## References

---

---
url: >-
  /docs/guide/usage/linter/rules/vitest/require-local-test-context-for-concurrent-snapshots.md
---

### What it does

The rule is intended to ensure that concurrent snapshot tests are executed
within a properly configured local test context.

### Why is this bad?

Running snapshot tests concurrently without a proper context can lead to
unreliable or inconsistent snapshots. Ensuring that concurrent tests are
correctly configured with the appropriate context helps maintain accurate
and stable snapshots, avoiding potential conflicts or failures.

### Examples

Examples of **incorrect** code for this rule:

```javascript
test.concurrent("myLogic", () => {
  expect(true).toMatchSnapshot();
});

describe.concurrent("something", () => {
  test("myLogic", () => {
    expect(true).toMatchInlineSnapshot();
  });
});
```

Examples of **correct** code for this rule:

```javascript
test.concurrent("myLogic", ({ expect }) => {
  expect(true).toMatchSnapshot();
});

test.concurrent("myLogic", (context) => {
  context.expect(true).toMatchSnapshot();
});
```

## How to use

## Version

This rule was added in v0.8.0.

## References

---

---
url: /docs/guide/usage/linter/rules/vitest/require-mock-type-parameters.md
---

### What it does

Enforces the use of type parameters on `vi.fn()`, and optionally on `vi.importActual()` and `vi.importMock()`.

By default, only `vi.fn()` is checked. Set `checkImportFunctions` to `true` to also check `vi.importActual()` and `vi.importMock()`.

### Why is this bad?

Without explicit type parameters, `vi.fn()` creates a mock typed as `(...args: any[]) => any`.
This disables type checking between the mock and the real implementation, which can lead to two problems:

* tests that fail due to incorrect mock usage when they should pass
* or worse, tests that pass while the mock silently diverges from the actual runtime behavior.

### Examples

Examples of **incorrect** code for this rule configured as `{ "checkImportFunctions": false }`:

```ts
import { vi } from "vitest";

test("foo", () => {
  const myMockedFn = vi.fn();
});
```

Examples of **incorrect** code for this rule configured as `{ "checkImportFunctions": true }`:

```ts
import { vi } from "vitest";

vi.mock("./example.js", async () => {
  const originalModule = await vi.importActual("./example.js");

  return { ...originalModule };
});
const fs = await vi.importMock("fs");
```

Examples of **correct** code for this rule configured as `{ "checkImportFunctions": false }`:

```ts
import { vi } from "vitest";

test("foo", () => {
  const myMockedFnOne = vi.fn<(arg1: string, arg2: boolean) => number>();
  const myMockedFnTwo = vi.fn<() => void>();
  const myMockedFnThree = vi.fn<any>();
});
```

Examples of **correct** code for this rule configured as `{ "checkImportFunctions": true }`:

```ts
import { vi } from "vitest";

vi.mock("./example.js", async () => {
  const originalModule = await vi.importActual<any>("./example.js");

  return { ...originalModule };
});
const fs = await vi.importMock<any>("fs");
```

## Configuration

This rule accepts a configuration object with the following properties:

### checkImportFunctions

type: `boolean`

default: `false`

Also require type parameters for `importActual` and `importMock`.

## How to use

## Version

This rule was added in v1.58.0.

## References

---

---
url: /docs/guide/usage/linter/rules/vitest/require-test-timeout.md
---

### What it does

Requires every test to have a timeout specified, either as a numeric third
argument, a `{ timeout }` option, or via `vi.setConfig({ testTimeout: ... })`.

### Why is this bad?

Tests without an explicit timeout rely on the default, which may be too
generous to catch performance regressions or too short for slow CI
environments, leading to flaky failures.

### Examples

Examples of **incorrect** code for this rule:

```js
it("slow test", async () => {
  await doSomethingSlow();
});
```

Examples of **correct** code for this rule:

```js
// good (numeric timeout)
test("slow test", async () => {
  await doSomethingSlow();
}, 1000);

// good (options object)
test("slow test", { timeout: 1000 }, async () => {
  await doSomethingSlow();
});

// good (file-level)
vi.setConfig({ testTimeout: 1000 });

test("slow test", async () => {
  await doSomethingSlow();
});
```

## How to use

## Version

This rule was added in v1.58.0.

## References

---

---
url: /docs/guide/usage/linter/rules/vitest/require-to-throw-message.md
---

### What it does

This rule triggers a warning if `toThrow()` or `toThrowError()` is used without an error message.

### Why is this bad?

Using `toThrow()` or `toThrowError()` without specifying an expected error message
makes tests less specific and harder to debug. When a test only checks that an
error was thrown but not what kind of error, it can pass even when the wrong
error is thrown, potentially hiding bugs. Providing an expected error message
or error type makes tests more precise and helps catch regressions more effectively.

### Examples

Examples of **incorrect** code for this rule:

```javascript
test("all the things", async () => {
  expect(() => a()).toThrow();
  expect(() => a()).toThrowError();
  await expect(a()).rejects.toThrow();
  await expect(a()).rejects.toThrowError();
});
```

Examples of **correct** code for this rule:

```javascript
test("all the things", async () => {
  expect(() => a()).toThrow("a");
  expect(() => a()).toThrowError("a");
  await expect(a()).rejects.toThrow("a");
  await expect(a()).rejects.toThrowError("a");
});
```

## How to use

## Version

This rule was added in v0.2.9.

## References

---

---
url: /docs/guide/usage/linter/rules/vitest/require-top-level-describe.md
---

### What it does

Requires test cases and hooks to be inside a top-level `describe` block.

### Why is this bad?

Having tests and hooks organized within `describe` blocks provides better
structure and grouping for test suites. It makes test output more readable
and helps with test organization, especially in larger codebases.

This rule triggers a warning if a test case (`test` and `it`) or a hook
(`beforeAll`, `beforeEach`, `afterEach`, `afterAll`) is not located in a
top-level `describe` block.

### Examples

Examples of **incorrect** code for this rule:

```javascript
// Above a describe block
test("my test", () => {});
describe("test suite", () => {
  it("test", () => {});
});

// Below a describe block
describe("test suite", () => {});
test("my test", () => {});

// Same for hooks
beforeAll("my beforeAll", () => {});
describe("test suite", () => {});
afterEach("my afterEach", () => {});
```

Examples of **correct** code for this rule:

```javascript
// Above a describe block
// In a describe block
describe("test suite", () => {
  test("my test", () => {});
});

// In a nested describe block
describe("test suite", () => {
  test("my test", () => {});
  describe("another test suite", () => {
    test("my other test", () => {});
  });
});
```

## Configuration

This rule accepts a configuration object with the following properties:

### maxNumberOfTopLevelDescribes

type: `integer`

default: `Infinity`

The maximum number of top-level `describe` blocks allowed in a test file.

## How to use

## Version

This rule was added in v0.4.2.

## References

---

---
url: /docs/guide/usage/linter/rules/vitest/valid-describe-callback.md
---

### What it does

This rule validates that the second parameter of a `describe()` function is a
callback function. This callback function:

* should not contain any parameters
* should not contain any `return` statements

Vitest supports async `describe()` callbacks, so this rule allows them.

### Why is this bad?

Using an improper `describe()` callback function can lead to unexpected test
errors.

### Examples

Examples of **incorrect** code for this rule:

```javascript
// Callback function parameters are not allowed
describe("myFunction()", (done) => {
  // ...
});

// Returning a value from a describe block is not allowed
describe("myFunction", () =>
  it("returns a truthy value", () => {
    expect(myFunction()).toBeTruthy();
  }));
```

## How to use

## Version

This rule was added in v0.0.8.

## References

---

---
url: /docs/guide/usage/linter/rules/vitest/valid-expect.md
---

### What it does

Checks that `expect()` is called correctly.

### Why is this bad?

`expect()` is a function that is used to assert values in tests.
It should be called with a single argument, which is the value to be tested.
If you call `expect()` with no arguments, or with more than one argument, it will not work as expected.

### Examples

Examples of **incorrect** code for this rule:

```javascript
expect();
expect("something");
expect(true).toBeDefined;
expect(Promise.resolve("Hi!")).resolves.toBe("Hi!");
```

Examples of **correct** code for this rule:

```javascript
expect("something").toEqual("something");
expect(true).toBeDefined();
await expect(Promise.resolve("Hi!")).resolves.toBe("Hi!");
```

## Configuration

This rule accepts a configuration object with the following properties:

### alwaysAwait

type: `boolean`

default: `false`

When `true`, async assertions must be awaited in all contexts (not just return statements).

### asyncMatchers

type: `string[]`

default: `["toResolve", "toReject"]`

List of matchers that are considered async and therefore require awaiting (e.g. `toResolve`, `toReject`).

### maxArgs

type: `integer`

default: `1`

Maximum number of arguments `expect` should be called with.

### minArgs

type: `integer`

default: `1`

Minimum number of arguments `expect` should be called with.

## How to use

## Version

This rule was added in v0.0.14.

## References

---

---
url: /docs/guide/usage/linter/rules/vitest/valid-expect-in-promise.md
---

### What it does

Ensures that `expect` calls inside promise chains (`.then()`, `.catch()`,
`.finally()`) are properly awaited or returned from the test.

### Why is this bad?

When `expect` is called inside a promise callback that is not awaited or
returned, the test may pass even if the assertion fails because the test
completes before the promise resolves. This leads to silently passing
tests with broken assertions.

### Examples

Examples of **incorrect** code for this rule:

```javascript
test("promise test", async () => {
  something().then((value) => {
    expect(value).toBe("red");
  });
});

test("promises test", () => {
  const onePromise = something().then((value) => {
    expect(value).toBe("red");
  });
  const twoPromise = something().then((value) => {
    expect(value).toBe("blue");
  });

  return Promise.any([onePromise, twoPromise]);
});
```

Examples of **correct** code for this rule:

```javascript
test("promise test", async () => {
  await something().then((value) => {
    expect(value).toBe("red");
  });
});

test("promises test", () => {
  const onePromise = something().then((value) => {
    expect(value).toBe("red");
  });
  const twoPromise = something().then((value) => {
    expect(value).toBe("blue");
  });

  return Promise.all([onePromise, twoPromise]);
});
```

## How to use

## Version

This rule was added in v1.60.0.

## References

---

---
url: /docs/guide/usage/linter/rules/vitest/valid-title.md
---

### What it does

Checks that the titles of Jest and Vitest blocks are valid.

Titles must be:

* not empty,
* strings,
* not prefixed with their block name,
* have no leading or trailing spaces.

### Why is this bad?

Titles that are not valid can be misleading and make it harder to understand the purpose of the test.

### Examples

Examples of **incorrect** code for this rule:

```javascript
describe("", () => {});
describe("foo", () => {
  it("", () => {});
});
it("", () => {});
test("", () => {});
xdescribe("", () => {});
xit("", () => {});
xtest("", () => {});
```

Examples of **correct** code for this rule:

```javascript
describe("foo", () => {});
it("bar", () => {});
test("baz", () => {});
```

### Options

```typescript
interface Options {
  ignoreSpaces?: boolean;
  ignoreTypeOfTestName?: boolean;
  ignoreTypeOfDescribeName?: boolean;
  allowArguments?: boolean;
  disallowedWords?: string[];
  mustNotMatch?: Partial<Record<"describe" | "test" | "it", string>> | string;
  mustMatch?: Partial<Record<"describe" | "test" | "it", string>> | string;
}
```

## How to use

## Version

This rule was added in v0.0.14.

## References

---

---
url: /docs/guide/usage/linter/rules/vitest/warn-todo.md
---

### What it does

This rule warns about usage of `.todo` in `describe`, `it`, or `test` functions.

### Why is this bad?

The tests you push should be complete. Any pending/`TODO` code should not be committed.

### Examples

Examples of **incorrect** code for this rule:

```js
describe.todo("foo", () => {});
it.todo("foo", () => {});
test.todo("foo", () => {});
```

Examples of **correct** code for this rule:

```js
describe([])("foo", () => {});
it([])("foo", () => {});
test([])("foo", () => {});
```

## How to use

## Version

This rule was added in v1.37.0.

## References

---

---
url: /docs/contribute/vscode.md
---

# VS Code Extension

::: tip
This page is for contributing to the Oxc VS Code extension.
To download the extension, see the [Visual Studio Marketplace](https://marketplace.visualstudio.com/items?itemName=oxc.oxc-vscode) or the [Open VSX Registry](https://open-vsx.org/extension/oxc/oxc-vscode).
:::

## Development

Clone the [oxc-vscode](https://github.com/oxc-project/oxc-vscode) repository and run `pnpm install`.

## Building and running the extension locally

There are two options for running and testing your changes to the Oxc VS Code extension.

**Via command line:**

* Run `pnpm build` to compile the VS Code extension and build the release version of the language server.
* Run `pnpm install-extension` to install it into VS Code.
* Press `Ctrl` + `Shift` + `P` and search for "Developer: Reload Window".
* You are now able to manually test your changes inside VS Code.

**Via VS Code itself:**

* Open the `oxc-vscode` repository in VS Code.
* Go to the "Run and Debug" tab in the left sidebar of your editor.
* Select the `Launch VS Code Extension` configuration.
* Click the green play button at the top.
* This will build the VS Code extension and launch a new VS Code window with the newly built VS Code extension installed.

### Testing unreleased versions of `oxlint`/`oxfmt`

Build the project in the [oxc project](https://github.com/oxc-project/oxc) with:

```bash
cd apps/oxlint && pnpm build-test
cd ../oxfmt && pnpm build-test
```

Then configure the VS Code extension to use the local build via the extension settings in `settings.json`:

```json
{
  "oxc.path.oxlint": "/path/to/oxc/apps/oxlint/dist/cli.js",
  "oxc.path.oxfmt": "/path/to/oxc/apps/oxfmt/dist/cli.js"
}
```

### Use the output channel

To see what the extension and language server are doing, use the `Oxc` output channel in VS Code.
To get more information, enable the following extension setting in `settings.json`:

```json
{
  "oxc.trace.server": "verbose"
}
```

In the language server integration for `oxlint`/`oxfmt` (for example, the `oxc_language_server` crate), you can use the `info!` or `error!` macros to send messages to the `Oxc` output channel in VS Code.

### Writing a test

Depending on your changes, you should create a test.
Write tests in the VS Code extension only when they are specific to VS Code.
Tests for LSP communication with the tools should be added in `oxlint/oxfmt` or in the Rust crate `oxc_language_server`.

Example:

* VS Code: status bar changes
* oxlint: returned diagnostics / code actions
* oxc\_language\_server: workspace problems

---

---
url: /docs/guide/usage/linter/rules/vue/component-definition-name-casing.md
---

### What it does

Enforce specific casing for component definition names.

### Why is this bad?

Defining component names without a consistent casing makes templates
harder to read and harder to grep. Picking either `PascalCase` or
`kebab-case` and sticking with it across the codebase removes a class
of bikeshedding and search misses.

### Examples

Examples of **incorrect** code for this rule (default `PascalCase`):

```vue
<script>
export default {
  name: "foo-bar",
};
</script>
```

Examples of **correct** code for this rule (default `PascalCase`):

```vue
<script>
export default {
  name: "FooBar",
};
</script>
```

## Configuration

This rule accepts one of the following string values:

type: `"PascalCase" | "kebab-case"`

## How to use

## Version

This rule was added in v1.68.0.

## References

---

---
url: /docs/guide/usage/linter/rules/vue/define-emits-declaration.md
---

### What it does

Enforce consistent declaration style for `defineEmits` in Vue.
This rule only works in `<script setup>` with `lang="ts"`.

### Why is this bad?

Inconsistent code style can be confusing and make code harder to read
through.

### Examples

Examples of **incorrect** code for this rule:

```vue
// "vue/define-emits-declaration": ["error", "type-based"]
<script setup lang="ts">
const emit = defineEmits(["change", "update"]);
const emit2 = defineEmits({
  change: (id) => typeof id === "number",
  update: (value) => typeof value === "string",
});
</script>

// "vue/define-emits-declaration": ["error", "type-literal"]
<script setup lang="ts">
const emit = defineEmits<{
  (e: "change", id: number): void;
  (e: "update", value: string): void;
}>();
</script>

// "vue/define-emits-declaration": ["error", "runtime"]
<script setup lang="ts">
const emit = defineEmits<{
  (e: "change", id: number): void;
  (e: "update", value: string): void;
}>();
</script>
```

Examples of **correct** code for this rule:

```vue
// "vue/define-emits-declaration": ["error", "type-based"]
<script setup lang="ts">
const emit = defineEmits<{
  (e: "change", id: number): void;
  (e: "update", value: string): void;
}>();
const emit2 = defineEmits<{
  change: [id: number];
  update: [value: string];
}>();
</script>

// "vue/define-emits-declaration": ["error", "type-literal"]
<script setup lang="ts">
const emit = defineEmits<{
  change: [id: number];
  update: [value: string];
}>();
</script>

// "vue/define-emits-declaration": ["error", "runtime"]
<script setup lang="ts">
const emit = defineEmits<{
  (e: "change", id: number): void;
  (e: "update", value: string): void;
}>();
const emit2 = defineEmits({
  change: (id) => typeof id === "number",
  update: (value) => typeof value === "string",
});
</script>
```

## Configuration

This rule accepts one of the following string values:

### `"type-based"`

Enforces the use of a named TypeScript type or interface as the
argument to `defineEmits`, e.g. `defineEmits<MyEmits>()`.

### `"type-literal"`

Enforces the use of an inline type literal as the argument to
`defineEmits`, e.g. `defineEmits<{ (event: string): void }>()`.

### `"runtime"`

Enforces the use of runtime declaration, where emits are declared
using an array or object, e.g. `defineEmits(['event1', 'event2'])`.

## How to use

## Version

This rule was added in v1.15.0.

## References

---

---
url: /docs/guide/usage/linter/rules/vue/define-props-declaration.md
---

### What it does

Enforce consistent declaration style for `defineProps` in Vue.
This rule only works in `<script setup>` with `lang="ts"`.

### Why is this bad?

Inconsistent code style can be confusing and make code harder to
read through.

### Examples

Examples of **incorrect** code for this rule:

```vue
// "vue/define-props-declaration": ["error", "type-based"]
<script setup lang="ts">
const props = defineProps({
  kind: { type: String },
});
</script>

// "vue/define-props-declaration": ["error", "runtime"]
<script setup lang="ts">
const props = defineProps<{
  kind: string;
}>();
</script>
```

Examples of **correct** code for this rule:

```vue
// "vue/define-props-declaration": ["error", "type-based"]
<script setup lang="ts">
const props = defineProps<{
  kind: string;
}>();
</script>

// "vue/define-props-declaration": ["error", "runtime"]
<script setup lang="ts">
const props = defineProps({
  kind: { type: String },
});
</script>
```

## Configuration

This rule accepts one of the following string values:

### `"type-based"`

Enforce type-based declaration.

### `"runtime"`

Enforce runtime declaration.

## How to use

## Version

This rule was added in v1.15.0.

## References

---

---
url: /docs/guide/usage/linter/rules/vue/define-props-destructuring.md
---

### What it does

This rule enforces a consistent style for handling Vue 3 Composition API props,
allowing you to choose between requiring destructuring or prohibiting it.

### Why is this bad?

By default, the rule requires you to use destructuring syntax when `defineProps`
is assigned to a variable and warns against combining `withDefaults` with destructuring.

### Examples

Examples of **incorrect** code for this rule:

```vue
<script setup lang="ts">
const props = defineProps(["foo"]);
const propsWithDefaults = withDefaults(defineProps(["foo"]), { foo: "default" });
const { baz } = withDefaults(defineProps(["baz"]), { baz: "default" });
const props = defineProps<{ foo?: string }>();
const propsWithDefaults = withDefaults(defineProps<{ foo?: string }>(), { foo: "default" });
</script>
```

Examples of **correct** code for this rule:

```vue
<script setup lang="ts">
const { foo } = defineProps(["foo"]);
const { bar = "default" } = defineProps(["bar"]);
const { foo } = defineProps<{ foo?: string }>();
const { bar = "default" } = defineProps<{ bar?: string }>();
</script>
```

## Configuration

This rule accepts a configuration object with the following properties:

### destructure

type: `"only-when-assigned" | "always" | "never"`

default: `"only-when-assigned"`

Require or prohibit destructuring.

#### `"only-when-assigned"`

Requires destructuring when `defineProps` is assigned to a variable and warns against using `withDefaults` with destructuring

#### `"always"`

Requires destructuring when using `defineProps` and warns against using `withDefaults` with destructuring

#### `"never"`

Requires using a variable to store props and prohibits destructuring

## How to use

## Version

This rule was added in v1.20.0.

## References

---

---
url: /docs/guide/usage/linter/rules/vue/max-props.md
---

### What it does

Enforce a maximum number of props defined for a given Vue component.

### Why is this bad?

A large number of props on a component can indicate that it is trying
to do too much and may be difficult to maintain or understand.

By limiting the number of props, developers are encouraged to avoid
overly complex components and instead create smaller, more focused
components that are easier to reason about.

### Examples

Examples of **incorrect** code for this rule with the default `{ "maxProps": 1 }` option:

```js
<script setup>
defineProps({
  prop1: String,
  prop2: String,
})
</script>
```

Examples of **correct** code for this rule with the default `{ "maxProps": 1 }` option:

```js
<script setup>
defineProps({
  prop1: String,
})
</script>
```

## Configuration

This rule accepts a configuration object with the following properties:

### maxProps

type: `integer`

default: `1`

The maximum number of props allowed in a Vue SFC.

## How to use

## Version

This rule was added in v1.19.0.

## References

---

---
url: /docs/guide/usage/linter/rules/vue/next-tick-style.md
---

### What it does

Enforce Promise or callback style in `nextTick`.

### Why is this bad?

In Vue.js, `nextTick` can be used either by passing a callback or
by using the returned Promise. Mixing these styles makes the code
harder to read and inconsistent. Choose one style consistently.

### Examples

Examples of **incorrect** code for this rule with default `"promise"` option:

```js
this.$nextTick(() => {});
Vue.nextTick(() => {});
import { nextTick } from "vue";
nextTick(() => {});
```

Examples of **correct** code for this rule with default `"promise"` option:

```js
this.$nextTick().then(() => {});
await Vue.nextTick();
import { nextTick } from "vue";
await nextTick();
```

Examples of **incorrect** code for this rule with `"callback"` option:

```js
await this.$nextTick();
Vue.nextTick().then(() => {});
```

Examples of **correct** code for this rule with `"callback"` option:

```js
this.$nextTick(() => {});
Vue.nextTick(() => {});
```

## Configuration

This rule accepts one of the following string values:

### `"promise"`

Require using the Promise returned by `nextTick`.

### `"callback"`

Require passing a callback function to `nextTick`.

## How to use

## Version

This rule was added in v1.69.0.

## References

---

---
url: /docs/guide/usage/linter/rules/vue/no-arrow-functions-in-watch.md
---

### What it does

This rule disallows using arrow functions when defining a watcher.

### Why is this bad?

Arrow functions bind `this` lexically, which means they don't have access to the Vue component instance.
In Vue watchers, you often need access to `this` to interact with component data, methods, or other properties.
Using regular functions or method shorthand ensures proper `this` binding.

### Examples

Examples of **incorrect** code for this rule:

```vue
<script>
export default {
  watch: {
    foo: () => {},
    bar: {
      handler: () => {},
    },
    baz: [
      (val) => {},
      {
        handler: () => {},
      },
    ],
  },
};
</script>
```

Examples of **correct** code for this rule:

```vue
<script>
export default {
  watch: {
    foo() {},
    bar: function () {},
    baz: {
      handler: function () {},
    },
  },
};
</script>
```

## How to use

## Version

This rule was added in v1.39.0.

## References

---

---
url: /docs/guide/usage/linter/rules/vue/no-async-in-computed-properties.md
---

### What it does

Disallow asynchronous actions in computed properties.

### Why is this bad?

Asynchronous actions inside computed properties may lead to an unexpected
behavior. A computed property's value should be a synchronous function of
its dependencies.

### Examples

Examples of **incorrect** code for this rule:

```vue
<script>
export default {
  computed: {
    pro() {
      return Promise.all([new Promise((resolve, reject) => {})]);
    },
    foo: async function () {
      return await someFunc();
    },
    bar() {
      return fetch(url).then((response) => {});
    },
    tim() {
      setTimeout(() => {}, 0);
    },
    inst() {
      return new Promise((resolve, reject) => {});
    },
  },
};
</script>
```

Examples of **correct** code for this rule:

```vue
<script>
export default {
  computed: {
    foo() {
      return this.bar;
    },
  },
};
</script>
```

## Configuration

### ignoredObjectNames

type: `string[]`

default: `[]`

Names of identifiers whose member-call chains (`.then` / `.catch` / `.finally`)
should be ignored. Useful for libraries like Zod where `.catch(default)` is
a builder API, not a Promise method.

## How to use

## Version

This rule was added in v1.71.0.

## References

---

---
url: /docs/guide/usage/linter/rules/vue/no-computed-properties-in-data.md
---

### What it does

Disallow accessing computed properties inside `data()`.

### Why is this bad?

`data()` runs **before** computed properties are initialized, so
`this.<computedName>` evaluates to `undefined` and leaves silently
broken state in the component instance.

### Examples

Examples of **incorrect** code for this rule:

```vue
<script>
export default {
  data() {
    const foo = this.foo; // `foo` is a computed property
    return {};
  },
  computed: {
    foo() {},
  },
};
</script>
```

Examples of **correct** code for this rule:

```vue
<script>
export default {
  data() {
    const foo = this.foo; // `foo` is a prop, not a computed
    return {};
  },
  props: ["foo"],
};
</script>
```

## How to use

## Version

This rule was added in v1.67.0.

## References

---

---
url: /docs/guide/usage/linter/rules/vue/no-deprecated-data-object-declaration.md
---

### What it does

Disallow object declarations for `data` (in Vue.js 3.0.0+).

### Why is this bad?

In Vue 3, declaring `data` as an object causes the same object to be
shared between every instance of the component, which leads to cross-
instance state pollution. `data` must be a function that returns a
fresh object per instance.

### Examples

Examples of **incorrect** code for this rule:

```vue
<script>
export default {
  data: {
    foo: "bar",
  },
};
</script>
```

Examples of **correct** code for this rule:

```vue
<script>
export default {
  data() {
    return { foo: "bar" };
  },
};
</script>
```

## How to use

## Version

This rule was added in v1.62.0.

## References

---

---
url: /docs/guide/usage/linter/rules/vue/no-deprecated-delete-set.md
---

### What it does

Disallow using deprecated `$set` / `$delete` (in Vue.js 3.0.0+).

### Why is this bad?

In Vue 3, the instance methods `$set` / `$delete` and the global
`Vue.set` / `Vue.delete` were removed. Reactivity is now backed by
Proxies, so plain assignment and the `delete` operator work as
expected and these helpers are no longer needed.

### Examples

Examples of **incorrect** code for this rule:

```vue
<script>
export default {
  mounted() {
    this.$set(obj, key, value);
    this.$delete(obj, key);
    Vue.set(obj, key, value);
    Vue.delete(obj, key);
  },
};
</script>
```

Examples of **correct** code for this rule:

```vue
<script>
export default {
  mounted() {
    obj[key] = value;
    delete obj[key];
  },
};
</script>
```

## How to use

## Version

This rule was added in v1.62.0.

## References

---

---
url: /docs/guide/usage/linter/rules/vue/no-deprecated-destroyed-lifecycle.md
---

### What it does

Disallow using deprecated `destroyed` and `beforeDestroy` lifecycle hooks in Vue.js 3.0.0+.

### Why is this bad?

In Vue.js 3.0.0+, the `destroyed` and `beforeDestroy` lifecycle hooks have been renamed
to `unmounted` and `beforeUnmount` respectively. Using the old names is deprecated and
may cause confusion or compatibility issues.

### Examples

Examples of **incorrect** code for this rule:

```vue
<script>
export default {
  beforeDestroy() {},
  destroyed() {},
};
</script>
```

Examples of **correct** code for this rule:

```vue
<script>
export default {
  beforeUnmount() {},
  unmounted() {},
};
</script>
```

## How to use

## Version

This rule was added in v1.35.0.

## References

---

---
url: /docs/guide/usage/linter/rules/vue/no-deprecated-events-api.md
---

### What it does

Disallow using deprecated Events API (`$on`, `$off`, `$once`) in Vue.js 3.0.0+.

### Why is this bad?

In Vue.js 3.0.0+, the internal event APIs `$on`, `$off`, and `$once` have been removed.
These methods were used for event handling between components but are no longer available.

### Examples

Examples of **incorrect** code for this rule:

```vue
<script>
export default {
  mounted() {
    this.$on("event", () => {});
    this.$off("event");
    this.$once("event", () => {});
  },
};
</script>
```

Examples of **correct** code for this rule:

```vue
<script>
import mitt from "mitt";

const emitter = mitt();

export default {
  mounted() {
    emitter.on("event", () => {});
    emitter.off("event");
    emitter.once("event", () => {});
  },
};
</script>
```

## How to use

## Version

This rule was added in v1.62.0.

## References

---

---
url: /docs/guide/usage/linter/rules/vue/no-deprecated-model-definition.md
---

### What it does

Disallow deprecated `model` definition (in Vue.js 3.0.0+).

### Why is this bad?

Vue 3 removed the per-component `model` option. Instead, `v-model`
works through the `modelValue` prop and the `update:modelValue` event,
so a `model: { prop, event }` block is no longer needed.

With `{ "allowVue3Compat": true }`, a `model` block is allowed if it
already uses the Vue 3-compatible `modelValue` / `update:modelValue`
(or kebab-case `model-value` / `update:model-value`) pair, easing
migration.

### Examples

Examples of **incorrect** code for this rule:

```vue
<script>
export default {
  model: {
    prop: "foo",
    event: "update",
  },
};
</script>
```

Examples of **correct** code for this rule with the
`{ "allowVue3Compat": true }` option:

```vue
<script>
export default {
  model: {
    prop: "modelValue",
    event: "update:modelValue",
  },
};
</script>
```

## Configuration

### allowVue3Compat

type: `boolean`

default: `false`

Allow `model: { prop: 'modelValue', event: 'update:modelValue' }` (or
the kebab-case `model-value` variant) which is forwards-compatible with
Vue 3's `v-model`.

## How to use

## Version

This rule was added in v1.63.0.

## References

---

---
url: /docs/guide/usage/linter/rules/vue/no-deprecated-props-default-this.md
---

### What it does

Disallow deprecated `this` access in props default function (in Vue.js 3.0.0+).

### Why is this bad?

In Vue.js 3.0.0+, props default factory functions no longer have access to
`this`. They are invoked before the component instance is created, so
`this` is `undefined`. The factory should rely on its first argument (the
raw props passed by the parent) instead.

### Examples

Examples of **incorrect** code for this rule:

```vue
<script>
export default {
  props: {
    a: String,
    b: {
      default() {
        return this.a;
      },
    },
  },
};
</script>
```

Examples of **correct** code for this rule:

```vue
<script>
export default {
  props: {
    a: String,
    b: {
      default(props) {
        return props.a;
      },
    },
  },
};
</script>
```

## How to use

## Version

This rule was added in v1.67.0.

## References

---

---
url: /docs/guide/usage/linter/rules/vue/no-deprecated-vue-config-keycodes.md
---

### What it does

Disallow using deprecated `Vue.config.keyCodes` (in Vue.js 3.0.0+).

### Why is this bad?

`Vue.config.keyCodes` was removed in Vue 3. Code that relies on it will
silently stop working when upgrading.

### Examples

Examples of **incorrect** code for this rule:

```js
Vue.config.keyCodes = { enter: 13 };
```

Examples of **correct** code for this rule:

```js
Vue.config.silent = true;
```

## How to use

## Version

This rule was added in v1.62.0.

## References

---

---
url: /docs/guide/usage/linter/rules/vue/no-dupe-keys.md
---

### What it does

Disallow duplication of field names.

### Why is this bad?

Duplicate keys in Vue component options (props, data, computed, methods, setup)
can cause unexpected behavior because they may overwrite each other at runtime,
and they cause name collisions in the template.

### Examples

Examples of **incorrect** code for this rule:

```vue
<script>
export default {
  props: ["foo"],
  computed: {
    foo() {},
  },
};
</script>
```

Examples of **correct** code for this rule:

```vue
<script>
export default {
  props: ["foo"],
  computed: {
    bar() {},
  },
};
</script>
```

## Configuration

### groups

type: `string[]`

default: `[]`

Additional group names to search for duplicate keys in, on top of the
built-in `props`, `computed`, `data`, `methods` and `setup` groups.

## How to use

## Version

This rule was added in v1.70.0.

## References

---

---
url: /docs/guide/usage/linter/rules/vue/no-export-in-script-setup.md
---

### What it does

Disallow `export` in `<script setup>`

### Why is this bad?

The previous version of `<script setup>` RFC used `export` to define variables used in templates,
but the new `<script setup>` RFC has been updated to define without using `export`.
See [Vue RFCs - 0040-script-setup](https://github.com/vuejs/rfcs/blob/master/active-rfcs/0040-script-setup.md) for more details.

### Examples

Examples of **incorrect** code for this rule:

```vue
<script setup>
export let msg = "Hello!";
</script>
```

Examples of **correct** code for this rule:

```vue
<script setup>
let msg = "Hello!";
</script>
```

## How to use

## Version

This rule was added in v1.20.0.

## References

---

---
url: /docs/guide/usage/linter/rules/vue/no-expose-after-await.md
---

### What it does

Disallow asynchronously registered `expose`.

### Why is this bad?

`defineExpose` and `context.expose()` registered after an `await`
expression in `<script setup>` or `setup()` may not work as expected
because they are registered after the component instance has finished
setting up.

### Examples

Examples of **incorrect** code for this rule:

```vue
<script setup>
await doSomething();
defineExpose({/* ... */}); // error
</script>
```

Examples of **correct** code for this rule:

```vue
<script setup>
defineExpose({/* ... */}); // ok
await doSomething();
</script>
```

## How to use

## Version

This rule was added in v1.67.0.

## References

---

---
url: /docs/guide/usage/linter/rules/vue/no-import-compiler-macros.md
---

### What it does

Disallow importing Vue compiler macros.

### Why is this bad?

Compiler Macros like:

* `defineProps`
* `defineEmits`
* `defineExpose`
* `withDefaults`
* `defineModel`
* `defineOptions`
* `defineSlots`

are globally available in Vue 3's `<script setup>` and do not require explicit imports.

### Examples

Examples of **incorrect** code for this rule:

```vue
<script setup>
import { defineProps, withDefaults } from "vue";
</script>
```

Examples of **correct** code for this rule:

```vue
<script setup>
import { ref } from "vue";
</script>
```

## How to use

## Version

This rule was added in v1.21.0.

## References

---

---
url: /docs/guide/usage/linter/rules/vue/no-lifecycle-after-await.md
---

### What it does

Disallow asynchronously registered lifecycle hooks.

### Why is this bad?

Lifecycle hooks must be registered synchronously during `setup()` execution.
If a lifecycle hook is called after an `await` statement, it may be registered
too late and might not work as expected.

### Examples

Examples of **incorrect** code for this rule:

```vue
<script>
import { onMounted } from "vue";
export default {
  async setup() {
    await doSomething();
    onMounted(() => {
      /* ... */
    }); // error
  },
};
</script>
```

Examples of **correct** code for this rule:

```vue
<script>
import { onMounted } from "vue";
export default {
  async setup() {
    onMounted(() => {
      /* ... */
    }); // ok
    await doSomething();
  },
};
</script>
```

## How to use

## Version

This rule was added in v1.39.0.

## References

---

---
url: /docs/guide/usage/linter/rules/vue/no-multiple-slot-args.md
---

### What it does

Disallow passing multiple arguments to scoped slots.

### Why is this bad?

Users have to use the arguments in fixed order and cannot omit the ones they don't need.
e.g. if you have a slot that passes in 5 arguments but the user actually only need the last 2 of them,
they will have to declare all 5 just to use the last 2.

More information can be found in [vuejs/vue#9468](https://github.com/vuejs/vue/issues/9468#issuecomment-462210146)

### Examples

Examples of **incorrect** code for this rule:

```vue
<script>
export default {
  render(h) {
    var children = this.$scopedSlots.default(foo, bar);
    var children = this.$scopedSlots.default(...foo);
  },
};
</script>
```

Examples of **correct** code for this rule:

```vue
<script>
export default {
  render(h) {
    var children = this.$scopedSlots.default();
    var children = this.$scopedSlots.default(foo);
    var children = this.$scopedSlots.default({ foo, bar });
  },
};
</script>
```

## How to use

## Version

This rule was added in v1.15.0.

## References

---

---
url: /docs/guide/usage/linter/rules/vue/no-required-prop-with-default.md
---

### What it does

Enforce props with default values to be optional.

### Why is this bad?

If a prop is declared with a default value, whether it is required or not,
we can always skip it in actual use. In that situation, the default value would be applied.
So, a required prop with a default value is essentially the same as an optional prop.

### Examples

Examples of **incorrect** code for this rule:

```vue
<script setup lang="ts">
const props = withDefaults(
  defineProps<{
    name: string | number;
    age?: number;
  }>(),
  {
    name: "Foo",
  },
);
</script>
```

Examples of **correct** code for this rule:

```vue
<script setup lang="ts">
const props = withDefaults(
  defineProps<{
    name?: string | number;
    age?: number;
  }>(),
  {
    name: "Foo",
  },
);
</script>
```

## How to use

## Version

This rule was added in v1.17.0.

## References

---

---
url: /docs/guide/usage/linter/rules/vue/no-reserved-component-names.md
---

### What it does

Disallow Vue component names that collide with HTML / SVG element names
(and optionally Vue built-in component names).

### Why is this bad?

Using a reserved name silently shadows the standard element / built-in
component, producing confusing behavior at runtime.

### Examples

Examples of **incorrect** code for this rule:

```vue
<script>
export default {
  name: "div",
};
</script>
```

Examples of **correct** code for this rule:

```vue
<script>
export default {
  name: "MyComponent",
};
</script>
```

## Configuration

This rule accepts a configuration object with the following properties:

### disallowVue3BuiltInComponents

type: `boolean`

default: `false`

Disallow Vue 3 built-in component names (e.g. `Teleport`, `Suspense`).
Note: this also catches Vue 2 built-ins because Vue 3's set includes them.

### disallowVueBuiltInComponents

type: `boolean`

default: `false`

Disallow Vue 2 built-in component names (e.g. `Transition`, `KeepAlive`).

### htmlElementCaseSensitive

type: `boolean`

default: `false`

Match HTML / SVG element names case-sensitively. When `false` (default),
the capitalized form of an HTML element (e.g. `Div`) is also reported.

## How to use

## Version

This rule was added in v1.68.0.

## References

---

---
url: /docs/guide/usage/linter/rules/vue/no-reserved-keys.md
---

### What it does

Disallow overwriting reserved Vue instance keys (e.g. `$data`, `$emit`)
or using `_`-prefixed keys inside `data` / `asyncData`.

### Why is this bad?

Vue exposes a number of instance properties (`$emit`, `$data`, `$props`,
etc.). Defining a prop, computed, data, method or setup return key with
the same name overwrites the underlying Vue API and silently breaks the
component (e.g. `methods: { $emit() {} }` clobbers event emission).
Vue also reserves `_`-prefixed names inside its reactivity system, so
`data() { return { _foo: 1 } }` may collide with internal state.

### Examples

Examples of **incorrect** code for this rule:

```vue
<script>
export default {
  props: ["$data"],
  methods: {
    $emit() {},
  },
};
</script>
```

Examples of **correct** code for this rule:

```vue
<script>
export default {
  props: ["fooData"],
  methods: {
    send() {},
  },
};
</script>
```

## Configuration

### groups

type: `string[]`

default: `[]`

Extra component option groups to inspect, on top of the built-in
`props` / `computed` / `data` / `asyncData` / `methods` / `setup`.

### reserved

type: `string[]`

default: `[]`

Extra reserved key names to disallow, on top of the built-in list.

## How to use

## Version

This rule was added in v1.69.0.

## References

---

---
url: /docs/guide/usage/linter/rules/vue/no-reserved-props.md
---

### What it does

Disallow reserved attribute names (e.g. `key`, `ref`) from being used as
prop names.

### Why is this bad?

Vue treats a number of attributes specially (`key` and `ref` in Vue 3;
additionally `is`, `slot`, `slot-scope`, `class` and `style` in Vue 2).
Declaring a prop with one of these names collides with the framework's
own handling and breaks the component.

### Examples

Examples of **incorrect** code for this rule:

```vue
<script>
export default {
  props: {
    ref: String,
    key: String,
  },
};
</script>
```

Examples of **correct** code for this rule:

```vue
<script>
export default {
  props: {
    foo: String,
  },
};
</script>
```

## Configuration

### vueVersion

type: `integer`

default: `3`

Vue major version whose reserved attribute set is applied. Vue 2 reserves
more names (`is`, `slot`, `class`, `style`, ...) than Vue 3.

## How to use

## Version

This rule was added in v1.69.0.

## References

---

---
url: /docs/guide/usage/linter/rules/vue/no-shared-component-data.md
---

### What it does

Enforce that the `data` property of a Vue component definition is a
function.

### Why is this bad?

When `data` is declared as an object literal, the same object is shared
across every instance of the component, which causes cross-instance
state pollution. Returning a fresh object from a function avoids that.

This rule targets component definitions reached through
`Vue.component(...)`, `Vue.extend(...)`, `Vue.mixin(...)`,
`app.component(...)`, `app.mixin(...)`, `component(...)`,
`createApp(...)`, `defineComponent(...)`, `defineNuxtComponent(...)`,
and `export default {}` inside `.vue` files. `new Vue({...})` is not
covered (the instance does not share `data` between components).

### Examples

Examples of **incorrect** code for this rule:

```vue
<script>
Vue.component("some-comp", {
  data: {
    foo: "bar",
  },
});
</script>
```

Examples of **correct** code for this rule:

```vue
<script>
Vue.component("some-comp", {
  data() {
    return { foo: "bar" };
  },
});
</script>
```

## How to use

## Version

This rule was added in v1.67.0.

## References

---

---
url: /docs/guide/usage/linter/rules/vue/no-side-effects-in-computed-properties.md
---

### What it does

Disallow side effects in computed properties.

### Why is this bad?

It is considered a very bad practice to introduce side effects inside computed properties.
It makes the code unpredictable and hard to understand.

### Examples

Examples of **incorrect** code for this rule:

```vue
<script>
export default {
  computed: {
    fullName() {
      this.firstName = "lorem"; // side effect
      return `${this.firstName} ${this.lastName}`;
    },
  },
};
</script>
```

Examples of **correct** code for this rule:

```vue
<script>
export default {
  computed: {
    fullName() {
      return `${this.firstName} ${this.lastName}`;
    },
  },
};
</script>
```

## How to use

## Version

This rule was added in v1.70.0.

## References

---

---
url: /docs/guide/usage/linter/rules/vue/no-this-in-before-route-enter.md
---

### What it does

Disallow `this` usage in a `beforeRouteEnter` method.

This rule is only relevant when using `vue-router`.

### Why is this bad?

Inside a `beforeRouteEnter` method, there is no access to `this`.
See [the vue-router docs](https://router.vuejs.org/guide/advanced/navigation-guards.html#in-component-guards).
This behavior isn't obvious, and so this lint rule can help prevent runtime errors in some cases.

### Examples

Examples of **incorrect** code for this rule:

```js
export default {
  beforeRouteEnter(to, from, next) {
    this.a; // Error: 'this' is not available
    next();
  },
};
```

Examples of **correct** code for this rule:

```js
export default {
  beforeRouteEnter(to, from, next) {
    // anything without `this`
  },
};
```

## How to use

## Version

This rule was added in v1.37.0.

## References

---

---
url: /docs/guide/usage/linter/rules/vue/no-watch-after-await.md
---

### What it does

Disallow asynchronously-registered `watch`.

### Why is this bad?

`watch` and `watchEffect` registered after an `await` expression in
`setup()` may not work as expected because they are registered after
the component instance has finished setting up.

### Examples

Examples of **incorrect** code for this rule:

```vue
<script>
import { watch } from "vue";
export default {
  async setup() {
    await doSomething();
    watch(foo, () => {
      /* ... */
    }); // error
  },
};
</script>
```

Examples of **correct** code for this rule:

```vue
<script>
import { watch } from "vue";
export default {
  async setup() {
    watch(foo, () => {
      /* ... */
    }); // ok
    await doSomething();
  },
};
</script>
```

## How to use

## Version

This rule was added in v1.67.0.

## References

---

---
url: /docs/guide/usage/linter/rules/vue/prefer-import-from-vue.md
---

### What it does

Enforce imports from `vue` instead of `@vue/*`.

### Why is this bad?

Imports from the following modules are almost always wrong. You should import from vue instead.

* `@vue/runtime-dom`
* `@vue/runtime-core`
* `@vue/reactivity`
* `@vue/shared`

### Examples

Examples of **incorrect** code for this rule:

```js
import { createApp } from "@vue/runtime-dom";
import { Component } from "@vue/runtime-core";
import { ref } from "@vue/reactivity";
```

Examples of **correct** code for this rule:

```js
import { createApp, ref, Component } from "vue";
```

## How to use

## Version

This rule was added in v1.20.0.

## References

---

---
url: /docs/guide/usage/linter/rules/vue/prop-name-casing.md
---

### What it does

Enforce a specific casing (camelCase or snake\_case) for Vue component
prop names.

### Why is this bad?

Inconsistent prop name casing makes templates harder to read and grep
for. Pinning props to a single casing across the codebase keeps the
declaration site and the call site aligned.

### Examples

Examples of **incorrect** code for this rule (default `camelCase`):

```vue
<script>
export default {
  props: {
    greeting_text: String,
  },
};
</script>
```

Examples of **correct** code for this rule (default `camelCase`):

```vue
<script>
export default {
  props: {
    greetingText: String,
  },
};
</script>
```

## Configuration

### The 1st option

type: `"camelCase" | "snake_case"`

### The 2nd option

This option is an object with the following properties:

#### ignoreProps

type: `string[]`

Prop names to ignore, as regular expression patterns.

## How to use

## Version

This rule was added in v1.69.0.

## References

---

---
url: /docs/guide/usage/linter/rules/vue/require-default-export.md
---

### What it does

Require components to be the default export.

### Why is this bad?

Using SFCs (Single File Components) without a default export is
not supported in Vue 3. Components should be exported as the default export.

### Examples

Examples of **incorrect** code for this rule:

```vue
<script>
const foo = "foo";
</script>
```

Examples of **correct** code for this rule:

```vue
<script>
export default {
  data() {
    return {
      foo: "foo",
    };
  },
};
</script>
```

## How to use

## Version

This rule was added in v1.21.0.

## References

---

---
url: /docs/guide/usage/linter/rules/vue/require-default-prop.md
---

### What it does

Requires default value to be set for props that are not marked as
`required`.

### Why is this bad?

A prop that is neither required nor given a default is implicitly
`undefined` when omitted. Forcing a default keeps the component's
behavior explicit and avoids `undefined` leaking into the template and
logic. `Boolean` props are exempt because they already default to
`false`.

### Examples

Examples of **incorrect** code for this rule:

```vue
<script>
export default {
  props: {
    name: String,
  },
};
</script>
```

Examples of **correct** code for this rule:

```vue
<script>
export default {
  props: {
    name: {
      type: String,
      default: "",
    },
  },
};
</script>
```

## How to use

## Version

This rule was added in v1.70.0.

## References

---

---
url: /docs/guide/usage/linter/rules/vue/require-direct-export.md
---

### What it does

This rule requires that the component object be directly exported.

### Why is this bad?

Indirect exports can make it harder to understand the component structure
and may cause issues with Vue's component system.

### Examples

Examples of **incorrect** code for this rule:

```vue
<script>
const A = {};
export default A;
</script>
```

```vue
<script>
export default function () {}
</script>
```

Examples of **correct** code for this rule:

```vue
<script>
export default {};
</script>
```

```vue
<script>
export default function (props) {
  return h("div", props.msg);
}
</script>
```

Examples of **incorrect** code for this rule with the `disallowFunctionalComponentFunction: true` option:

```vue
<script>
export default (props) => h("div", props.msg);
</script>
```

## Configuration

This rule accepts a configuration object with the following properties:

### disallowFunctionalComponentFunction

type: `boolean`

default: `false`

When set `true`, disallow functional component functions.

## How to use

## Version

This rule was added in v1.69.0.

## References

---

---
url: /docs/guide/usage/linter/rules/vue/require-prop-type-constructor.md
---

### What it does

Require `props` type values to be a constructor function (e.g. `String`,
`Number`, `Boolean`) rather than a string, number, or other literal.

### Why is this bad?

Vue uses the prop type for runtime validation and dev-time warnings. A
string like `'String'` looks like the constructor but is never matched
against an actual value, silently disabling the check.

### Examples

Examples of **incorrect** code for this rule:

```vue
<script>
export default {
  props: {
    foo: "String",
    bar: { type: "Number" },
  },
};
</script>
```

Examples of **correct** code for this rule:

```vue
<script>
export default {
  props: {
    foo: String,
    bar: { type: Number },
  },
};
</script>
```

## How to use

## Version

This rule was added in v1.68.0.

## References

---

---
url: /docs/guide/usage/linter/rules/vue/require-prop-types.md
---

### What it does

This rule enforces that a props statement contains a type definition.

### Why is this bad?

In committed code, prop definitions should always be as detailed as
possible, specifying at least type(s).

### Examples

Examples of **incorrect** code for this rule:

```vue
<script setup>
const props = defineProps({
  name: String,
});
</script>
```

Examples of **correct** code for this rule:

```vue
<script setup>
const props = defineProps({
  name: { type: String },
});
</script>

// Or with validator
<script setup>
const props = defineProps({
  name: {
    validator: (value) => value.length > 0,
  },
});
</script>
```

## How to use

## Version

This rule was added in v1.69.0.

## References

---

---
url: /docs/guide/usage/linter/rules/vue/require-render-return.md
---

### What it does

Enforce that a `render` function always returns a value.

### Why is this bad?

A Vue component's `render` function must produce a VNode tree. If a
code path falls through without returning, Vue receives `undefined`
and silently renders nothing.

### Examples

Examples of **incorrect** code for this rule:

```vue
<script>
export default {
  render() {
    if (foo) {
      return h("div");
    }
    // falls through without returning
  },
};
</script>
```

Examples of **correct** code for this rule:

```vue
<script>
export default {
  render() {
    return h("div");
  },
};
</script>
```

## How to use

## Version

This rule was added in v1.67.0.

## References

---

---
url: /docs/guide/usage/linter/rules/vue/require-slots-as-functions.md
---

### What it does

Enforce properties of `$slots` to be used as functions.

### Why is this bad?

In Vue.js 3, `this.$slots.<name>` is a function (slot render function),
not an array of vnodes like in Vue.js 2. Treating slot properties as
values (e.g. `this.$slots.default.filter(...)`) breaks at runtime.

### Examples

Examples of **incorrect** code for this rule:

```vue
<script>
export default {
  render(h) {
    var children = this.$slots.default
    return h('div', children.filter(...))
  }
}
</script>
```

Examples of **correct** code for this rule:

```vue
<script>
export default {
  render(h) {
    var children = this.$slots.default();
    return h("div", children);
  },
};
</script>
```

## How to use

## Version

This rule was added in v1.67.0.

## References

---

---
url: /docs/guide/usage/linter/rules/vue/require-typed-ref.md
---

### What it does

Require `ref` and `shallowRef` functions to be strongly typed.

### Why is this bad?

With TypeScript it is easy to prevent usage of `any` by using `noImplicitAny`.
Unfortunately this rule is easily bypassed with Vue `ref()` function.
Calling `ref()` function without a generic parameter or an initial value leads to ref having `Ref<any>` type.

### Examples

Examples of **incorrect** code for this rule:

```typescript
const count = ref();
const name = shallowRef();
```

Examples of **correct** code for this rule:

```typescript
const count = ref<number>();
const a = ref(0);
```

## How to use

## Version

This rule was added in v1.17.0.

## References

---

---
url: /docs/guide/usage/linter/rules/vue/return-in-computed-property.md
---

### What it does

Enforce that a `return` statement is present in every computed property.

### Why is this bad?

A Vue computed property is a getter that must produce a value. Forgetting
to return turns the value into `undefined`, which silently breaks
templates and reactive code that depend on the computed.

### Examples

Examples of **incorrect** code for this rule:

```vue
<script>
export default {
  computed: {
    foo() {
      // missing return
    },
  },
};
</script>
```

Examples of **correct** code for this rule:

```vue
<script>
export default {
  computed: {
    foo() {
      return this.bar;
    },
  },
};
</script>
```

## Configuration

### treatUndefinedAsUnspecified

type: `boolean`

default: `true`

When `true` (default), `return;` (without a value) is treated as a missing return.
Set to `false` to allow bare `return;` as if it returned a value.

## How to use

## Version

This rule was added in v1.63.0.

## References

---

---
url: /docs/guide/usage/linter/rules/vue/return-in-emits-validator.md
---

### What it does

Enforce that a `return` statement is present in `emits` validators
(in Vue.js 3.0.0+).

### Why is this bad?

An `emits` validator must return a boolean indicating whether the
emitted payload is valid. Forgetting to return a value (or returning
only falsy values) makes the validator effectively reject every emit,
breaking the component contract silently.

### Examples

Examples of **incorrect** code for this rule:

```vue
<script>
export default {
  emits: {
    foo() {
      // missing return
    },
  },
};
</script>
```

Examples of **correct** code for this rule:

```vue
<script>
export default {
  emits: {
    foo(payload) {
      return typeof payload === "string";
    },
  },
};
</script>
```

## How to use

## Version

This rule was added in v1.67.0.

## References

---

---
url: /docs/guide/usage/linter/rules/vue/valid-define-emits.md
---

### What it does

Enforce valid usage of the `defineEmits` compiler macro in Vue.

This rule reports `defineEmits` compiler macros in the following cases:

* `defineEmits` is referencing locally declared variables.
* `defineEmits` has both a literal type and an argument. e.g. `defineEmits<(e: 'foo')=>void>(['bar'])`
* `defineEmits` has been called multiple times.
* Custom events are defined in both `defineEmits` and `export default {}`.
* Custom events are not defined in either `defineEmits` or `export default {}`.

### Why is this bad?

Misusing `defineEmits` can lead to runtime errors, unclear component contracts, and lost type safety.
Vue may still compile the code, but emitted events may break silently or be typed incorrectly.

### Examples

Examples of **incorrect** code for this rule:

```vue
<script setup>
const def = { notify: null };
defineEmits(def);
</script>
```

```vue
<script setup lang="ts">
defineEmits<(e: "notify") => void>({ submit: null });
</script>
```

```vue
<script setup>
defineEmits({ notify: null });
defineEmits({ submit: null });
</script>
```

```vue
<script>
export default {
  emits: ["notify"],
};
</script>
<script setup>
defineEmits({ submit: null });
</script>
```

Examples of **correct** code for this rule:

```vue
<script setup>
defineEmits({ notify: null });
</script>
```

```vue
<script setup>
defineEmits(["notify"]);
</script>
```

```vue
<script setup lang="ts">
defineEmits<(e: "notify") => void>();
</script>
```

```vue
<script>
export default {
  emits: ["notify"],
};
</script>
<script setup>
defineEmits();
</script>
```

## How to use

## Version

This rule was added in v1.14.0.

## References

---

---
url: /docs/guide/usage/linter/rules/vue/valid-define-options.md
---

### What it does

Enforce valid use of the `defineOptions` compiler macro.

### Why is this bad?

`defineOptions` is a compiler macro for `<script setup>`. It must be called
with a single object literal containing component options that are evaluable
at compile time. Misuse such as referencing locally declared variables,
declaring `props`/`emits`/`expose`/`slots`, calling without arguments, or
passing type arguments cannot be processed by the compiler.

### Examples

Examples of **incorrect** code for this rule:

```vue
<script setup>
defineOptions(); // no options object
defineOptions({ name: "A" });
defineOptions({ name: "B" }); // multiple calls
defineOptions({ props: { msg: String } }); // use `defineProps()` instead
</script>
```

Examples of **correct** code for this rule:

```vue
<script setup>
defineOptions({ name: "foo", inheritAttrs: false });
</script>
```

## How to use

## Version

This rule was added in v1.67.0.

## References

---

---
url: /docs/guide/usage/linter/rules/vue/valid-define-props.md
---

### What it does

Enforce valid usage of the `defineProps` compiler macro in Vue.

This rule reports `defineProps` compiler macros in the following cases:

* `defineProps` is referencing locally declared variables.
* `defineProps` has both a literal type and an argument. e.g. `defineProps<{ /*props*/ }>({ /*props*/ })`
* `defineProps` has been called multiple times.
* Props are defined in both `defineProps` and `export default {}`.
* Props are not defined in either `defineProps` or `export default {}`.

### Why is this bad?

Misusing `defineProps` can lead to runtime errors, and lost type safety.
Vue may still compile the code, but properties may break silently or be typed incorrectly.

### Examples

Examples of **incorrect** code for this rule:

```vue
<script setup>
const def = { msg: String };
defineProps(def);
</script>
```

```vue
<script setup lang="ts">
defineProps<{ msg?: string }>({ msg: String });
</script>
```

```vue
<script setup>
defineProps({ msg: String });
defineProps({ count: Number });
</script>
```

```vue
<script>
export default {
  props: { msg: String },
};
</script>
<script setup>
defineProps({ count: Number });
</script>
```

Examples of **correct** code for this rule:

```vue
<script setup>
defineProps({ msg: String });
</script>
```

```vue
<script setup>
defineProps(["msg"]);
</script>
```

```vue
<script setup lang="ts">
defineProps<{ msg?: string }>();
</script>
```

```vue
<script>
export default {
  props: { msg: String },
};
</script>
<script setup>
defineProps();
</script>
```

## How to use

## Version

This rule was added in v1.15.0.

## References

---

---
url: /docs/guide/usage/linter/rules/vue/valid-next-tick.md
---

### What it does

Enforce valid `nextTick` function calls.

### Why is this bad?

`nextTick` is a function that takes either a callback or returns a Promise.
Misuse (accessing it as a value, passing extra arguments, both awaiting and
passing a callback) is almost always a bug.

### Examples

Examples of **incorrect** code for this rule:

```vue
<script>
import { nextTick } from "vue";
export default {
  async mounted() {
    nextTick(); // missing await or callback
    this.$nextTick; // not invoked
    this.$nextTick(a, b); // too many args
    await this.$nextTick(callback); // both await and callback
  },
};
</script>
```

Examples of **correct** code for this rule:

```vue
<script>
import { nextTick } from "vue";
export default {
  async mounted() {
    await nextTick();
    this.$nextTick(callback);
    this.$nextTick().then(callback);
  },
};
</script>
```

## How to use

## Version

This rule was added in v1.67.0.

## References

---

---
url: /docs/guide/what-is-oxc.md
description: The fastest toolchain for JavaScript and TypeScript.
---

# What is Oxc?

/oʊ ɛks siː/

The Oxidation Compiler is a collection of high-performance tools for JavaScript and TypeScript written in Rust.

Oxc is part of [VoidZero](https://voidzero.dev)'s vision for a unified, high-performance toolchain for JavaScript. It powers [Rolldown](https://rolldown.rs) ([Vite 8's bundler](https://vite.dev/blog/announcing-vite8)) and enables the next generation of ultra-fast development tools that work seamlessly together.

\* Oxidation is the chemical process that creates rust

## Fastest tooling across the stack

Oxc focuses on performance across the whole toolchain. This includes parsing, module resolution, linting, formatting, transforms, and minification.

## Philosophy

Oxc is built around a few core ideas.

### Performance is a feature

Oxc treats speed as a product requirement. Faster tools improve the local feedback loop and reduce CI cost. Performance regressions are treated as bugs.

### One toolchain, shared building blocks

Oxc is a suite. Tools like the linter, formatter, parser, transformer, minifier, and resolver are built on shared components. This reduces duplicated work and makes behavior more consistent across the stack.

### Correctness with clear boundaries

Oxc aims to be correct and predictable. When behavior differs from other tools, the differences should be documented. Compatibility is a feature, not an accident.

### Practical developer experience

Oxc focuses on a workflow that works in real projects. Defaults should be sensible, configuration should be understandable, and output should be stable.

## What you get

Oxc includes end-user tools and reusable compiler building blocks:

* [Oxlint](/docs/guide/usage/linter) is the fastest linter for JavaScript and TypeScript. It targets compatibility with the ESLint ecosystem.
* [Oxfmt](/docs/guide/usage/formatter) is the fastest formatter. It targets Prettier-compatible formatting.
* [Parser](/docs/guide/usage/parser) is the fastest JS and TS parser with an AST for tooling.
* [Transformer](/docs/guide/usage/transformer) provides fastest TS, JSX, and modern JavaScript transforms.
* [Minifier](/docs/guide/usage/minifier) is the fastest minifier for production output.
* [Resolver](/docs/guide/usage/resolver) is the fastest module resolver for JS and TS projects.
* [TypeScript Runner](/docs/guide/usage/oxc-node) runs TypeScript and JSX directly in Node.js.

You can use each tool on its own, or use them together as one toolchain.

## Who Oxc is for

* **App and library developers** who want the fastest lint and format loop locally and in CI.
* **Toolchain and platform teams** who want a fast compiler-grade foundation at scale.
* **Tool authors** who want fast reusable crates or npm packages for JS tooling.

---

---
url: /docs/guide/usage/minifier/whitespace-stripping.md
---
# Whitespace Stripping

Oxc minifier supports removing whitespace and comments.

This feature is enabled by default and can be disabled by setting the `codegen.removeWhitespace` option to `false`.

---

---
url: /docs/guide/usage/linter/writing-js-plugins.md
---

# Writing JS Plugins

:::info
JS plugins are currently in alpha, and remain under active development.

All APIs should behave identically to ESLint. If you find any differences in behavior,
that's a bug - please [report it](https://github.com/oxc-project/oxc/issues/new?template=linter_bug_report.yaml).
:::

## ESLint-compatible API

Oxlint provides a plugin API identical to ESLint's. See ESLint's docs on
[creating a plugin](https://eslint.org/docs/latest/extend/plugins) and
[custom rules](https://eslint.org/docs/latest/extend/custom-rules).

A simple plugin which flags files containing more than 5 class declarations:

```js
// plugin.js
const rule = {
  create(context) {
    let classCount = 0;

    return {
      ClassDeclaration(node) {
        classCount++;
        if (classCount === 6) {
          context.report({ message: "Too many classes", node });
        }
      },
    };
  },
};

const plugin = {
  meta: {
    name: "best-plugin-ever",
  },
  rules: {
    "max-classes": rule,
  },
};

export default plugin;
```

::: code-group

```json [.oxlintrc.json]
{
  "jsPlugins": ["./plugin.js"],
  "rules": {
    "best-plugin-ever/max-classes": "error"
  }
}
```

```ts [oxlint.config.ts]
import { defineConfig } from "oxlint";

export default defineConfig({
  jsPlugins: ["./plugin.js"],
  rules: {
    "best-plugin-ever/max-classes": "error",
  },
});
```

:::

## Alternative API

Oxlint also provides a slightly different alternative API which is more performant.

Rules created with this API **remain compatible with ESLint** (see [below](#what-does-eslintcompatplugin-do)).

Same rule as above, using the alternative API:

```js
import { eslintCompatPlugin } from "@oxlint/plugins";

const rule = {
  createOnce(context) {
    // Define counter variable
    let classCount;

    return {
      before() {
        // Reset counter before traversing AST of each file
        classCount = 0;
      },
      // Same as before
      ClassDeclaration(node) {
        classCount++;
        if (classCount === 6) {
          context.report({ message: "Too many classes", node });
        }
      },
    };
  },
};

const plugin = eslintCompatPlugin({
  meta: {
    name: "best-plugin-ever",
  },
  rules: {
    "max-classes": rule,
  },
});

export default plugin;
```

The differences are:

1. Wrap the plugin object in `eslintCompatPlugin(...)`.

```diff
- const plugin = {
+ const plugin = eslintCompatPlugin({
```

2. Use `createOnce` instead of `create`.

```diff
-   create(context) {
+   createOnce(context) {
```

3. `create` (ESLint's API) is called repeatedly *for each file*, whereas `createOnce` is called once only.
   Perform any per-file setup in `before` hook instead.

```diff
-     let classCount = 0;
+     let classCount;

      return {
+       before() {
+         classCount = 0; // Reset counter
+       },
        ClassDeclaration(node) {
          classCount++;
          if (classCount === 6) {
            context.report({ message: "Too many classes", node });
          }
        },
      };
```

### What does `eslintCompatPlugin` do?

`eslintCompatPlugin` adds a `create` method to each rule in the plugin, which delegates to `createOnce`.

**This means the plugin can be used with either Oxlint or ESLint.**

* In Oxlint, it'll get a perf boost from the faster `createOnce` API.
* In ESLint, it'll work exactly the same as if it was written with the original ESLint `create` API.

If you're publishing a plugin to NPM, add `@oxlint/plugins` as a *runtime* dependency (not a dev dependency).

### Skipping AST traversal

Returning `false` from `before` hook causes the rule to skip this file.

```js
// This rule does not run on files which start with a `// @skip-me` comment
const rule = {
  createOnce(context) {
    return {
      before() {
        if (context.sourceCode.text.startsWith("// @skip-me")) {
          return false;
        }
      },
      FunctionDeclaration(node) {
        // Do stuff
      },
    };
  },
};
```

This is equivalent to this pattern in ESLint:

```js
const rule = {
  create(context) {
    if (context.sourceCode.text.startsWith("// @skip-me")) {
      return {};
    }

    return {
      FunctionDeclaration(node) {
        // Do stuff
      },
    };
  },
};
```

### `before` hook

`before` hook runs before the AST is visited.

IMPORTANT: `before` hook is NOT guaranteed to run on every file.

At present it does, but in future we intend to add logic on Rust side to determine if the rule needs to run or not,
based on what AST nodes the rule is "interested in", and what the AST contains.
This will enable better performance by skipping redundant calls from Rust into JS.

In example above, if a file does not contain any `FunctionDeclaration`s, running the rule on that file will be skipped
entirely, *including* skipping the `before` hook.

If you need code to always run once for every file, implement a `Program` visitor instead:

```js
const rule = {
  createOnce(context) {
    return {
      Program(node) {
        // This always runs for every file, even if it
        // doesn't contain any `FunctionDeclaration`s
      },
      FunctionDeclaration(node) {
        /* do stuff */
      },
    };
  },
};
```

### `after` hook

There is also an `after` hook. It runs once per file, *after* the whole AST has been traversed (after `Program:exit`).

Use it to clean up any expensive resources used during the rule's AST traversal.

If `before` hook returns `false` to skip running the rule on the file, `after` hook will be skipped too.

Same as `before` hook, `after` hook is NOT guaranteed to run on every file (see [above](#when-before-hook-runs)).

## Why is the alternative API faster?

Short answer: Right now it isn't. But it *will be soon*.

Prior to the initial technical preview release of JS plugins, we have undergone a lengthy "R\&D" process. We have
identified many optimization opportunities, and have prototyped the *next* version of Oxlint plugins, which has
*extremely* good performance.

Many of those optimizations are not in the current release, but we'll be polishing them and folding them into Oxlint
over the next few months.

The alternative API is designed to enable and capitalize on these optimizations. By adopting the alternative API now,
plugin authors will see their plugins get a significant speed boost in future "for free", just by bumping `oxlint`
version, without any code changes.

### What are those optimizations?

Returning to the "no more than 5 classes" rule example from above:

```js
const rule = {
  create(context) {
    let classCount = 0;

    return {
      ClassDeclaration(node) {
        classCount++;
        if (classCount === 6) {
          context.report({ message: "Too many classes", node });
        }
      },
    };
  },
};
```

The `create` method is called once per file, each time with a new `context` object.

Why is that a problem?

For maximum performance, ideally we want to statically know what AST nodes the rule is
"interested in". With that information, we can perform 2 optimizations:

1. Don't walk the AST on JS side. Instead, during traversal of AST on Rust side, compile a list of "pointers" to
   the relevant AST nodes. Send that list to JS, and JS can "jump" straight to the relevant AST nodes, rather than
   searching the whole AST.

2. If the AST doesn't contain *any* AST nodes which match what the rule is interested in (in example above, if file
   contains no class declarations), skip calling into JS entirely for that file.

But JS is a dynamic language, and `create` could do *anything*. It could return a completely different visitor each time
it's called. So we have to call `create` to find out whether we needed to call `create`!

In comparison, with the alternative API, `createOnce` is called only once, and we then know what the rule does.
This enables the above optimizations.

To be clear, the `create` API was *not* a poor design decision on ESLint's part. It just presents some difficulties once
Rust-JS interop comes into play.

## Writing tests for custom rules

Oxlint provides a `RuleTester` API based on ESLint's `RuleTester`. This can be used to write unit tests for custom rules, to ensure that the custom rule you've written covers all relevant cases.

For example, with Vitest as the test runner you can write tests for the "no more than 5 classes" rule like this:

```js
import { RuleTester } from "oxlint/plugins-dev";
import { describe, it } from "vitest";
import { maxClasses } from "./max-classes.js";

RuleTester.describe = describe;
RuleTester.it = it;

const ruleTester = new RuleTester({ languageOptions: { parserOptions: { lang: "ts" } } });

// List valid and invalid cases, including the expected error messages for invalid cases.
ruleTester.run("max-classes", maxClasses, {
  valid: [
    "class A {}",
    // Exactly at the limit.
    "class A {} class B {} class C {} class D {} class E {}",
    // Expressions are not declarations, so they never count.
    "const a = class {}; const b = class {}; const c = class {}; const d = class {}; const e = class {}; const f = class {};",
  ],
  invalid: [
    {
      name: "the sixth declaration",
      code: "class A {} class B {} class C {} class D {} class E {} class F {}",
      // Columns are 0-indexed; the span covers the whole class declaration.
      errors: [{ messageId: "maxClasses", line: 1, column: 55, endColumn: 65 }],
    },
  ],
});
```

## Next steps

See the [API Support](./js-plugins#api-support) section for the ESLint APIs which are supported for usage in Oxlint plugins.