feat: add docs for oxlint.config.ts

camc314 · camc314 · commit b30d030d9985 · 2026-02-10T22:40:13.000Z
diff --git a/src/docs/guide/usage/linter/config.md b/src/docs/guide/usage/linter/config.md
@@ -1,23 +1,23 @@
 ---
 title: Configuration
-description: Configure Oxlint using a .oxlintrc.json file.
+description: Configure Oxlint using .oxlintrc.json or oxlint.config.ts.
 ---
 
 # Configuration
 
-Oxlint works out of the box, but most teams commit a configuration file to keep linting consistent across local runs, editors, and CI.
+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:
+To generate a starter config in the current directory (JSON):
 
 ```sh
 oxlint --init
 ```
 
-Oxlint automatically looks for a `.oxlintrc.json` in the current working directory. You can also pass a config explicitly (note that this will disable nested config lookup):
+Oxlint automatically looks for a `.oxlintrc.json` or `oxlint.config.ts` 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
@@ -27,8 +27,9 @@ oxlint --config ./oxlintrc.json
 
 Notes:
 
-- Only `.json` config files are supported, but oxlint configuration files support comments (like jsonc).
+- `.oxlintrc.json` supports comments (like jsonc).
 - The configuration format aims to be compatible with ESLint v8's format (`eslintrc.json`).
+- You can use either `.oxlintrc.json` or `oxlint.config.ts` in a directory, but not both.
 
 A minimal configuration looks like this:
 
@@ -44,9 +45,33 @@ A minimal configuration looks like this:
 }
 ```
 
+### TypeScript config file (`oxlint.config.ts`)
+
+Oxlint also supports a TypeScript configuration file named `oxlint.config.ts`.
+
+```ts [oxlint.config.ts]
+import { defineConfig } from "oxlint";
+
+export default defineConfig({
+  categories: {
+    correctness: "warn",
+  },
+  rules: {
+    "eslint/no-unused-vars": "error",
+  },
+});
+```
+
+Notes:
+
+- The file must be named `oxlint.config.ts` (including when passed via `--config`).
+- 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.
+
 ## Configuration file format
 
-A configuration file is a JSON object. The most common top-level fields are:
+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.
@@ -259,6 +284,16 @@ Paths in `extends` are resolved relative to the configuration file that declares
 }
 ```
 
+```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],
+});
+```
+
 ## Configure environments and globals
 
 Use `env` to enable predefined globals for common environments such as browser or node.
diff --git a/src/docs/guide/usage/linter/ignore-files.md b/src/docs/guide/usage/linter/ignore-files.md
@@ -8,7 +8,7 @@ description: Control which files Oxlint lints.
 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 `.oxlintrc.json` 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.
+> 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
 
@@ -22,7 +22,7 @@ Hidden files are not automatically ignored.
 
 ## `ignorePatterns`
 
-The recommended approach is to define ignores in `.oxlintrc.json` using `ignorePatterns`. This keeps ignores close to the configuration they belong to and works naturally with nested configs.
+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.
 
@@ -39,7 +39,7 @@ In monorepos, nested configs can ignore package specific output without affectin
 
 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 `.oxlintrc.json`, and we strongly recommend moving over to `"ignorePatterns"` soon after migrating, if not during migration.
+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
 
diff --git a/src/docs/guide/usage/linter/nested-config.md b/src/docs/guide/usage/linter/nested-config.md
@@ -1,19 +1,19 @@
 ---
 title: Nested configuration files
-description: Use multiple .oxlintrc.json files to apply different Oxlint settings to different parts of a repository.
+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` and applies them based on where files live in the directory tree.
+Oxlint can use multiple configuration files in the same repository. It automatically detects configuration files named `.oxlintrc.json` or `oxlint.config.ts` 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 `.oxlintrc.json` relative to that file.
+For each file being linted, Oxlint uses the nearest config file (`.oxlintrc.json` or `oxlint.config.ts`) relative to that file.
 
 Given the following structure:
 
@@ -23,7 +23,7 @@ my-project/
 ├── src/
 │   ├── index.js
 ├── package1/
-│   ├── .oxlintrc.json
+│   ├── oxlint.config.ts
 │   └── index.js
 └── package2/
     ├── .oxlintrc.json
@@ -33,7 +33,7 @@ my-project/
 Configuration resolution works as follows:
 
 - `src/index.js` uses `my-project/.oxlintrc.json`
-- `package1/index.js` uses `my-project/package1/.oxlintrc.json`
+- `package1/index.js` uses `my-project/package1/oxlint.config.ts`
 - `package2/index.js` uses `my-project/package2/.oxlintrc.json`
 
 ## What to expect
diff --git a/src/docs/guide/usage/linter/quickstart.md b/src/docs/guide/usage/linter/quickstart.md
@@ -84,6 +84,10 @@ Initialize the `.oxlintrc.json` config with default values:
 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`. See [Configuration](/docs/guide/usage/linter/config#typescript-config) for details.
+
 Then run Oxlint:
 
 ```sh
