← Back to rules

import/extensions 제한

작동 방식

일부 파일 해결 알고리즘은 가져오기 소스 경로 내에서 파일 확장자를 생략할 수 있도록 허용합니다.
예를 들어, 아직 ESM/import를 지원하지 않는 노드 해결기(Node resolver)는 CJS에서 기본적으로 .js 확장자가 자동으로 해결되기 때문에, ./foo/bar를 절대 경로 /User/someone/foo/bar.js로 해결할 수 있습니다.
해결기의 종류에 따라 더 많은 확장자를 자동으로 해결하도록 구성할 수 있습니다.
코드베이스 전반에서 파일 확장자 사용을 일관되게 유지하기 위해, 이 규칙은 특정 파일 확장자의 사용을 강제하거나 금지할 수 있습니다.

왜 문제가 되는가?

기반 파일 해결 알고리즘(예: Vite가 제공하는 것 등)은 성능 향상을 위해 파일 확장자를 명시하는 것을 권장합니다.

예시

이 규칙에 대해 잘못된 코드 예시:

다음 패턴은 구성이 "always"로 설정될 때 문제로 간주됩니다:

import foo from "./foo";
import bar from "./bar";
import Component from "./Component";
import foo from "@/foo";

다음 패턴은 구성이 "never"로 설정될 때 문제로 간주됩니다:

import foo from "./foo.js";
import bar from "./bar.json";
import Component from "./Component.jsx";
import express from "express/index.js";

이 규칙에 대해 올바른 코드 예시:

다음 패턴은 구성이 "always"로 설정될 때 문제로 간주되지 않습니다:

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";

다음 패턴은 구성이 "never"로 설정될 때 문제로 간주되지 않습니다:

import foo from "./foo";
import bar from "./bar";
import Component from "./Component";
import express from "express/index";
import * as path from "path";

확장자별 구성 예시:

// 구성: { "vue": "always", "ts": "never" }
import Component from "./Component.vue"; // ✓ OK - .vue는 "always"로 구성됨
import utils from "./utils"; // ✓ OK - .ts는 "never"로 구성됨
import styles from "./styles.css"; // ✓ OK - .css는 구성되지 않아 무시됨

// 구성: ["ignorePackages", { "js": "never", "ts": "never" }]
import foo from "./foo"; // ✓ OK - 확장자가 없음
import bar from "lodash/fp"; // ✓ OK - 패키지 가져오기, 무시됨 (ignorePackages가 true로 설정됨)

구성

이 규칙은 세 가지 유형의 구성을 수락합니다:

1. 전역 규칙(문자열): "always", "never", 또는 "ignorePackages"

{
  "rules": {
    // 모든 가져오기(패키지 포함)에 대해 확장자를 요구함
    // 예: `import React from 'react';`는 허용되지 않음.
    // 일반적으로 `always`를 사용할 경우 `ignorePackages`를 항상 `true`로 설정해야 합니다.
    "import/extensions": ["error", "always"],
  },
}

2. 확장자별 규칙(객체): { "js": "always", "jsx": "never", ... }

{
  "rules": {
    "import/extensions": [
      "error",
      // 확장자별 규칙:
      // .js 가져오기에 확장자 요구, .ts 가져오기에 확장자 금지
      { "js": "always", "ts": "never", "ignorePackages": true },
    ],
  },
}

3. 복합 구성(배열): ["error", "always", { "js": "never" }] 또는 ["error", { "js": "always" }]

{
  "rules": {
    "import/extensions": [
      "error",
      "always", // 기본값: 모든 가져오기에 확장자 요구
      {
        "ts": "never", // 전역 값 재정의, 특정 파일 유형의 가져오기에 확장자 금지
        "ignorePackages": true,
      },
    ],
  },
}

기본 동작(구성 없음): 모든 가져오기(모든 종류)는 통과합니다.
구성되지 않은 파일 확장자는 무시되어 잘못된 경고를 방지합니다.

이 규칙은 다음 속성을 가진 구성 객체를 수락합니다:

checkTypeImports

type: boolean

기본값: false

확장자 규칙을 적용할 때 타입 가져오기를 확인할지 여부.

// checkTypeImports가 `false`인 경우, 다음 가져오기가 확장자를 포함하느냐 여부에 관계없이 항상 허용됩니다:
import type { Foo } from "./foo";
import type { Foo } from "./foo.ts";

ignorePackages

type: boolean

기본값: false

확장자 규칙을 적용할 때 패키지 가져오기를 무시할지 여부.

IMPORTANT

이 규칙을 always로 설정할 경우, ignorePackages도 true로 설정해야 합니다.
그렇지 않으면 확장자가 없는 패키지 가져오기(예: import React from 'react';)가 금지되며, 이는 바람직하지 않고 복구 불가능합니다.

확장자별이 아닌 부울 옵션으로, 패키지 가져오기를 "항상" 규칙에서 제외합니다.

구성 객체에서 설정 가능: ["error", "always", { "ignorePackages": true }]

레거시 단축 형식: ["error", "ignorePackages"]는 ["error", "always", { "ignorePackages": true }]와 동일합니다.

• "always" 사용 시: true면 패키지 가져오기(예: lodash, @babel/core)에 확장자가 필요하지 않음
• "never" 사용 시: 이 옵션은 영향 없음; 패키지 가져오기에서는 여전히 확장자가 금지됨

예시: ["error", "always", { "ignorePackages": true }]는 import foo from "lodash"를 허용하지만, import bar from "./bar.js"에는 확장자를 요구함

pathGroupOverrides

type: array

기본값: []

맞춤형 가져오기 심볼에 대한 경로 그룹 오버라이드.

커스텀 가져오기 프로토콜(멀티레포 툴, 커스텀 해결기)에 대한 패턴-액션 쌍의 배열입니다.
각 오버라이드는 { "pattern": "<glob-pattern>", "action": "enforce" | "ignore" } 구조를 가집니다.

패턴 매칭: 글로브 패턴(*, **, {a,b})을 사용하여 가져오기 심볼을 매칭합니다.
참고로 패턴 매칭은 빠른 라이브러리인 fast-glob을 사용하여 러스트에서 수행되며, 원래 ESLint 규칙이 사용하는 자바스크립트 글로브 라이브러리와 다를 수 있습니다.

액션:

• "enforce": 정상적인 확장자 검증 적용(전역/확장자별 규칙 존중)
• "ignore": 매칭되는 가져오기에 대해 모든 확장자 검증 건너뛰기

우선순위: 처음으로 매칭되는 패턴이 우선 적용됩니다.

예시:

{
  "pattern": "rootverse{*,*/**}",
  "action": "ignore"
}

rootverse+debug:src, rootverse+bfe:src/symbols에서의 가져오기를 매칭하고, 확장자가 있는지 여부를 무시합니다.

pathGroupOverrides[n]

type: object

pathGroupOverrides[n].action

type: "enforce" | "ignore"

경로 그룹 오버라이드에 대한 액션.

매칭되는 맞춤형 가져오기 심볼에 대한 가져오기 확장자 검증 방식을 결정합니다.

"enforce"

매칭되는 가져오기에 확장자 검증을 강제 적용(구성 기반으로 확장자 요구)

"ignore"

매칭되는 가져오기를 완전히 무시(모든 확장자 검증 건너뛰기)

pathGroupOverrides[n].pattern

type: string

가져오기 심볼을 매칭할 글로브 패턴입니다. 이는 러스트의 fast-glob 라이브러리를 사용하여 매칭됩니다.

사용 방법

이 규칙을 활성화하려면 구성 파일 또는 CLI에서 다음과 같이 사용할 수 있습니다:

Config (.oxlintrc.json)

{
  "plugins": ["import"],
  "rules": {
    "import/extensions": "error"
  }
}

CLI

oxlint --deny import/extensions --import-plugin

참고 자료

• 규칙 소스