설정

Oxlint는 기본 설정만으로도 동작하지만, 대부분의 팀은 설정 파일(.oxlintrc.json 또는 oxlint.config.ts)을 커밋해 로컬·에디터·CI에서 일관되게 린트합니다.

이 페이지는 프로젝트 설정을 다룹니다: 규칙, 카테고리, 플러그인, overrides, 공통 옵션.

설정 파일 만들기

현재 디렉터리에 시작용 설정(JSON)을 만들려면:

oxlint --init

Oxlint는 현재 작업 디렉터리에서 .oxlintrc.json 또는 oxlint.config.ts를 찾습니다. 설정을 명시할 수도 있습니다(이 경우 중첩 설정 조회는 비활성화됩니다).

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

참고:

.oxlintrc.json은 주석을 지원합니다(jsonc처럼).
형식은 ESLint v8(eslintrc.json)과 호환되도록 설계되었습니다.
한 디렉터리에서 .oxlintrc.json과 oxlint.config.ts를 동시에 쓸 수는 없습니다.

최소 설정 예:

.oxlintrc.json

json

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

TypeScript 설정 파일(`oxlint.config.ts`)

oxlint.config.ts라는 이름의 TypeScript 설정 파일도 지원합니다.

oxlint.config.ts

import { defineConfig } from "oxlint";

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

참고:

파일 이름은 oxlint.config.ts여야 하며 --config로 넘길 때도 마찬가지입니다.
default export는 객체여야 하며, 타입을 위해 defineConfig로 감싸는 것을 권장합니다.
TypeScript 설정은 Node 기반 oxlint 패키지(JS 런타임)가 필요합니다. 단독 바이너리를 쓰면 .oxlintrc.json을 사용하세요.
TypeScript를 실행할 수 있는 Node가 필요합니다(Node v22.18+ 또는 v24+).

설정 파일 형식

설정 파일은 JSON 객체(.oxlintrc.json)이거나 설정 객체를 default export하는 TypeScript 모듈(oxlint.config.ts)입니다. 흔한 최상위 필드:

rules: 규칙 켜기/끄기, 심각도, 규칙 옵션
categories: 비슷한 목적의 규칙 묶음 켜기
plugins: 추가 규칙을 제공하는 내장 플러그인 켜기
jsPlugins: JavaScript 플러그인 설정(알파)
overrides: 파일 패턴별로 다른 설정 적용
extends: 다른 파일에서 설정 상속
ignorePatterns: 설정 파일 기준으로 무시할 파일 추가
env: 흔한 환경의 미리 정의된 전역 켜기
globals: 사용자 정의 전역 선언(읽기 전용/쓰기 가능)
settings: 여러 규칙이 공유하는 플러그인 전역 설정
options: 린터 수준 옵션(예: options.typeAware, options.typeCheck)

전체 필드 목록은 설정 파일 참조를 보세요.

린터 옵션 설정

린터 동작은 options로 설정합니다. 전체 목록은 설정 파일 참조를 보세요.

예:

.oxlintrc.jsonoxlint.config.ts

json

{
  "options": {
    "typeAware": true,
    "typeCheck": true,
    "maxWarnings": 10
  }
}

import { defineConfig } from "oxlint";

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

options.typeAware는 CLI의 --type-aware와 같습니다.
options.typeCheck(실험적)는 CLI의 --type-check와 같습니다.
options.maxWarnings는 CLI의 --max-warnings와 같습니다.

CLI와 설정이 동시에 있으면 CLI가 우선합니다.

options.typeAware와 options.typeCheck는 루트 설정 파일에서만 지원됩니다.

규칙 설정

규칙은 rules 아래에 둡니다.

규칙 값은:

심각도 문자열("off", "warn", "error"), 또는
[심각도, 옵션] 배열

ESLint 코어 규칙이고 이름이 유일하면 플러그인 접두사 없이 쓸 수 있습니다. 예: no-console은 eslint/no-console과 같습니다.

.oxlintrc.jsonoxlint.config.ts

json

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

import { defineConfig } from "oxlint";

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

심각도 값

ESLint 스타일 심각도:

규칙 끄기: "off" 또는 "allow"
경고: "warn"
오류: "error" 또는 "deny"

규칙 옵션

규칙 옵션은 배열로 지정합니다.

.oxlintrc.jsonoxlint.config.ts

json

{
  "rules": {
    "no-plusplus": ["error", { "allowForLoopAfterthoughts": true }]
  }
}

import { defineConfig } from "oxlint";

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

사용 가능한 규칙과 각 설정 옵션은 규칙 참조에 나열되어 있습니다.

CLI에서 심각도 덮어쓰기

빠르게 실험할 때 명령줄에서 심각도를 바꿀 수 있습니다.

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

인자는 왼쪽에서 오른쪽으로 적용됩니다.

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

카테고리로 규칙 묶음 켜기

카테고리로 비슷한 목적의 규칙을 한꺼번에 켜거나 끕니다. 기본적으로 Oxlint는 correctness 카테고리 규칙을 켭니다.

categories로 설정합니다.

.oxlintrc.jsonoxlint.config.ts

json

{
  "categories": {
    "correctness": "error",
    "suspicious": "warn",
    "pedantic": "off"
  }
}

import { defineConfig } from "oxlint";

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

사용 가능한 카테고리 예:

correctness: 확실히 잘못되었거나 쓸모없는 코드
suspicious: 잘못되었거나 쓸모없을 가능성이 큰 코드
pedantic: 매우 엄격하거나 가끔 거짓 양성이 있을 수 있는 규칙
perf: 런타임 성능 개선을 목표로 하는 규칙
style: 관용적·일관된 스타일 규칙
restriction: 특정 패턴·기능 사용 금지
nursery: 개발 중이라 바뀔 수 있는 규칙

CLI에서도 같은 -A, -W, -D로 카테고리를 바꿀 수 있습니다.

oxlint -D correctness -D suspicious

플러그인 설정

플러그인은 사용 가능한 규칙 집합을 넓힙니다.

Oxlint는 Rust로 많은 인기 플러그인을 네이티브 지원합니다. 큰 JavaScript 의존성 없이 넓은 규칙 커버리지를 얻습니다. 네이티브 플러그인을 보세요.

plugins로 설정합니다. plugins를 설정하면 기본 플러그인 집합을 덮어쓰므로, 켜고 싶은 플러그인을 모두 배열에 넣어야 합니다.

.oxlintrc.jsonoxlint.config.ts

json

{
  "plugins": ["unicorn", "typescript", "oxc"]
}

import { defineConfig } from "oxlint";

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

기본 플러그인을 모두 끄려면:

.oxlintrc.jsonoxlint.config.ts

json

{
  "plugins": []
}

import { defineConfig } from "oxlint";

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

플러그인 상세와 --import-plugin 같은 CLI 플래그는 네이티브 플러그인을 보세요.

JS 플러그인 설정(알파)

jsPlugins로 JavaScript 플러그인을 씁니다. 기존 ESLint 플러그인·고급 연동을 위한 호환 목적입니다.

참고:

JS 플러그인은 알파이며 시맨틱 버전 보장 대상이 아닙니다.

JS 플러그인은 문자열이거나 별칭이 있는 객체로 선언합니다.

.oxlintrc.jsonoxlint.config.ts

json

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

import { defineConfig } from "oxlint";

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

react, unicorn, typescript, oxc, import, jest, vitest, jsx-a11y, nextjs 등은 Rust로 네이티브 구현되어 있어 이름이 예약됩니다. 예약된 플러그인의 JavaScript 버전이 필요하면 사용자 정의 name으로 충돌을 피하세요.

자세한 내용은 JS 플러그인을 보세요.

파일 패턴별 설정 적용

테스트, 스크립트, TypeScript 전용 경로 등에 서로 다른 설정을 쓰려면 overrides를 사용합니다.

overrides는 객체 배열입니다. 각 override는 다음을 가질 수 있습니다.

files: 글로브 패턴
rules: 규칙 설정(최상위 rules와 같은 형태)
env: 환경 설정
globals: 전역 설정
plugins: 이 override에서만 플러그인 집합 변경(선택)
jsPlugins: 이 override 전용 JS 플러그인(알파)

예:

.oxlintrc.jsonoxlint.config.ts

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"
      }
    }
  ]
}

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",
      },
    },
  ],
});

공유 설정 확장

extends로 다른 설정 파일을 상속합니다.

extends의 경로는 extends를 선언한 설정 파일 기준으로 해석됩니다. 설정은 첫 항목부터 마지막까지 병합되며, 뒤가 앞을 덮어씁니다.

.oxlintrc.jsonoxlint.config.ts

json

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

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

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

환경·전역 설정

env로 브라우저·node 등 흔한 환경의 미리 정의된 전역을 켭니다.

globals로 프로젝트 전용 전역을 선언하거나, 읽기 전용/쓰기 가능으로 표시하거나, 달리 있을 전역을 끕니다.

.oxlintrc.jsonoxlint.config.ts

json

{
  "env": {
    "es6": true
  },
  "globals": {
    "MY_GLOBAL": "readonly",
    "Promise": "off"
  }
}

import { defineConfig } from "oxlint";

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

globals 값:

"readonly", "readable", false
"writable", "writeable", true
"off" — 전역 비활성

플러그인 설정(`settings`)

여러 규칙이 공유하는 플러그인 전역 설정입니다.

예(모노레포 + React + jsx-a11y):

.oxlintrc.jsonoxlint.config.ts

json

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

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",
      },
    },
  },
});

다음 단계

무시 파일: 무시 패턴, .gitignore, .eslintignore, 심볼릭 링크
인라인 무시 주석: 인라인 억제·범위 예외
중첩 설정: 모노레포·패키지별 설정
설정 파일 참조: 전체 스키마·필드 설명
CLI 참조: 플래그·출력 형식 전체 목록

설정 ​

설정 파일 만들기 ​

TypeScript 설정 파일(oxlint.config.ts) ​

설정 파일 형식 ​

린터 옵션 설정 ​

규칙 설정 ​

심각도 값 ​

규칙 옵션 ​

CLI에서 심각도 덮어쓰기 ​

카테고리로 규칙 묶음 켜기 ​

플러그인 설정 ​

JS 플러그인 설정(알파) ​

파일 패턴별 설정 적용 ​

공유 설정 확장 ​

환경·전역 설정 ​

플러그인 설정(settings) ​

다음 단계 ​

설정

설정 파일 만들기

TypeScript 설정 파일(`oxlint.config.ts`)

설정 파일 형식

린터 옵션 설정

규칙 설정

심각도 값

규칙 옵션

CLI에서 심각도 덮어쓰기

카테고리로 규칙 묶음 켜기

플러그인 설정

JS 플러그인 설정(알파)

파일 패턴별 설정 적용

공유 설정 확장

환경·전역 설정

플러그인 설정(`settings`)

다음 단계