도구

요약

ESLint를 사용하여 프론트엔드 코드 표준을 캡슐화하고 적용합니다. 환경 변수 REVEAL_ESLINT_TODO를 환경(및 IDE)에서 1로 설정하면 .eslint_todo/*.mjs에서 제외된 보류 중인 eslint todo 항목을 확인할 수 있습니다.

ESLint#

ESLint를 사용하여 프론트엔드 코드 표준을 캡슐화하고 적용합니다. 구성은 gitlab-eslint-config 프로젝트에서 확인할 수 있습니다.

환경 변수 REVEAL_ESLINT_TODO를 환경(및 IDE)에서 1로 설정하면 .eslint_todo/*.mjs에서 제외된 보류 중인 eslint todo 항목을 확인할 수 있습니다. 이를 통해 기존의 eslint 예외 항목을 드러내어 일상 작업 중에 수정할 수 있습니다.

Yarn 스크립트#

이 섹션에서는 ESLint를 사용하여 파일을 검증하고 자동 수정을 적용하는 데 사용할 수 있는 yarn 스크립트를 설명합니다.

ESLint로 스테이지된 모든 파일(git diff 기반)을 검사하려면 다음 스크립트를 실행합니다:

yarn run lint:eslint:staged

발견된 문제 목록이 콘솔에 출력됩니다.

ESLint 자동 수정을 스테이지된 모든 파일(git diff 기반)에 적용하려면 다음 스크립트를 실행합니다:

yarn run lint:eslint:staged:fix

수동 변경이 필요한 경우 변경 사항 목록이 콘솔에 출력됩니다.

리포지터리에서 특정 파일을 ESLint로 검사하려면 다음 스크립트를 실행합니다($PATH_TO_FILE를 실제 경로로 교체):

yarn run lint:eslint $PATH_TO_FILE

리포지터리의 모든 파일을 ESLint로 검사하려면 다음 스크립트를 실행합니다:

yarn run lint:eslint:all

발견된 문제 목록이 콘솔에 출력됩니다.

ESLint 자동 수정을 리포지터리의 모든 파일에 적용하려면 다음 스크립트를 실행합니다:

yarn run lint:eslint:all:fix

수동 변경이 필요한 경우 변경 사항 목록이 콘솔에 출력됩니다.

전역 규칙 업데이트에만 사용하세요. 그렇지 않으면 변경 사항으로 인해 대규모 머지 리퀘스트가 발생할 수 있습니다.

새 파일에서 ESLint 비활성화#

새 파일을 생성할 때 ESLint를 비활성화하지 마세요. 기존 파일에는 레거시 호환성 이유로 기존 규칙이 비활성화되어 있을 수 있지만, 현재 리팩토링 중입니다.

특정 ESLint 규칙을 비활성화하지 마세요. 기술 부채 발생을 방지하기 위해, 기존 코드 모듈을 호출/인스턴스화하는 경우에만 다음 규칙을 비활성화할 수 있습니다.

이러한 규칙은 줄 단위로 비활성화하세요. 그러면 향후 리팩토링이 더 쉬워집니다. 예를 들어 eslint-disable-next-line 또는 eslint-disable-line을 사용하세요.

단일 위반에 대해 ESLint 비활성화#

단일 위반에 대해 규칙을 비활성화해야 하는 경우, 필요한 최소한의 코드 범위에서만 비활성화하세요:

// bad
/* eslint-disable no-new */

import Foo from 'foo';

new Foo();

// better
import Foo from 'foo';

// eslint-disable-next-line no-new
new Foo();

todo 파일 생성#

코드베이스 전체에서 많은 위반을 발견하는 새 ESLint 규칙을 활성화할 때, 그러한 위반을 일시적으로 무시하기 위해 todo 파일을 생성하는 것이 더 쉬울 수 있습니다. 이 접근 방식에는 장단점이 있습니다:

장점:

특정 규칙을 위반하는 모든 파일에 대한 단일 진실 공급원(Single Source Of Truth, SSOT). 이를 통해 발생한 기술 부채를 해결하기 위한 작업을 더 쉽게 추적할 수 있습니다.
규칙을 처음 활성화할 때 위반하는 모든 파일을 수정할 필요가 없으므로 변경 집합이 더 작아집니다.

단점:

전체 파일에 대해 규칙을 비활성화하면 해당 파일에 동일한 유형의 위반이 더 많이 도입될 수 있습니다.
여러 동시 머지 리퀘스트에서 위반을 수정할 때 todo 파일에서 충돌이 자주 발생하여 MR 작성자가 브랜치를 리베이스해야 합니다.

todo 파일을 생성하려면 scripts/frontend/generate_eslint_todo_list.mjs 스크립트를 실행합니다:

node scripts/frontend/generate_eslint_todo_list.mjs <rule_name>

예를 들어, vue/no-unused-properties 규칙에 대한 todo 파일 생성:

node scripts/frontend/generate_eslint_todo_list.mjs vue/no-unused-properties

이렇게 하면 .eslint_todo/vue-no-unused-properties.mjs에 ESLint 구성이 생성되어 전역 구성에 자동으로 추가됩니다.

주어진 규칙에 대한 todo 파일이 생성되면, 해당 위반을 해결하기 위한 작업을 계획해야 합니다. todo 파일은 가능한 한 단기간에 처리되어야 합니다. 일부 위반을 해결할 수 없는 경우 단일 위반에 대해 ESLint 비활성화를 사용하여 인라인 무시로 전환하세요.

모든 위반 파일이 수정되면 todo 파일과 .eslint_todo/index.mjs의 export 구문을 함께 제거해야 합니다.

no-undef 규칙과 전역 변수 선언#

no-undef 규칙을 절대 비활성화하지 마세요. 대신 /* global Foo */로 전역 변수를 선언하세요.

여러 전역 변수를 선언할 때는 항상 변수마다 하나씩 /* global [name] */ 줄을 사용하세요.

// bad
/* globals Flash, Cookies, jQuery */

// good
/* global Flash */
/* global Cookies */
/* global jQuery */

import/no-deprecated를 사용하여 함수 사용 중단#

@gitlab/eslint-plugin Node 모듈에는 eslint-plugin-import 패키지가 포함되어 있습니다.

import/no-deprecated 규칙을 사용하여 @deprecated 태그가 있는 JSDoc 블록으로 함수를 사용 중단(deprecated)으로 표시할 수 있습니다:

/**
 * Convert search query into an object
 *
 * @param {String} query from "document.location.search"
 * @param {Object} options
 * @param {Boolean} options.gatherArrays - gather array values into an Array
 * @returns {Object}
 *
 *For example: "?one=1&two=2" into {one: 1, two: 2}
 * @deprecated Please use `queryToObject` instead. See https://gitlab.com/gitlab-org/gitlab/-/issues/283982 for more information
 */
export function queryToObject(query, options = {}) {
  ...
}

다음을 강력히 권장합니다:

이 함수를 사용하려는 개발자를 위한 대안 경로를 제공하세요.
마이그레이션 프로세스를 추적하는 이슈 링크를 제공하세요.

사용 중단된 함수를 다른 파일로 임포트하면 사용이 탐지됩니다. 같은 파일 내에서 함수를 사용할 경우에는 탐지되지 않습니다.

이후 $ yarn eslint를 실행하면 사용 중단된 사용 목록을 확인할 수 있습니다:

$ yarn eslint

./app/assets/javascripts/issuable_form.js
   9:10  error  Deprecated: Please use `queryToObject` instead. See https://gitlab.com/gitlab-org/gitlab/-/issues/283982 for more information  import/no-deprecated
  33:23  error  Deprecated: Please use `queryToObject` instead. See https://gitlab.com/gitlab-org/gitlab/-/issues/283982 for more information  import/no-deprecated
...

이 규칙의 비활성화 케이스를 Grep하여 작업 목록을 생성함으로써 사용 중단된 사용을 제거하는 노력을 추적하는 이슈를 만드세요:

$ grep "eslint-disable.*import/no-deprecated" -r .

./app/assets/javascripts/issuable_form.js:import { queryToObject, objectToQuery } from './lib/utils/url_utility'; // eslint-disable-line import/no-deprecate
./app/assets/javascripts/issuable_form.js:  // eslint-disable-next-line import/no-deprecated

내 파일에서 vue/multi-word-component-names가 비활성화됨#

단일 이름 컴포넌트는 Vue 스타일 가이드에서 권장하지 않습니다.

단일 이름 컴포넌트는 다른 HTML 컴포넌트와 혼동될 수 있어 문제가 됩니다. 예를 들어 컴포넌트를 <table>로 이름 지으면 HTML <table> 렌더링이 중단됩니다.

이를 해결하기 위해 .vue 파일과 해당 참조를 두 단어 이상을 사용하여 이름을 바꾸어야 합니다. 예를 들면:

user/table.vue는 user/users_table.vue로 이름을 바꾸고 UsersTable로 임포트하여 <users-table />로 사용할 수 있습니다.

GraphQL 스키마 및 오퍼레이션 유효성 검사#

@graphql-eslint/eslint-plugin을 사용하여 GraphQL 스키마와 오퍼레이션을 린트합니다. 이 플러그인이 제대로 작동하려면 전체 스키마가 필요합니다. 따라서 ESLint를 로컬에서 실행할 때 최신 스키마 덤프를 생성하는 것이 권장됩니다. ./scripts/dump_graphql_schema 스크립트를 실행하여 이를 수행할 수 있습니다.

Prettier로 포맷팅#

코드는 스타일 가이드를 따르기 위해 Prettier로 자동 포맷팅됩니다. Prettier는 표준 prettier 규칙에 따라 .js, .vue, .graphql, .scss 파일의 포맷팅을 처리합니다. Prettier의 모든 설정은 .prettierrc에서 확인할 수 있습니다.

에디터#

워크플로에 Prettier를 포함하는 권장 방법은 선호하는 에디터(모든 주요 에디터 지원)를 그에 맞게 설정하는 것입니다. 파일이 저장될 때마다 Prettier가 실행되도록 설정하는 것을 권장합니다. 선호하는 에디터에서 Prettier를 사용하는 방법은 Prettier 문서를 참조하세요.

전역 Yarn 스크립트와 동일한 파일 형식(.js, .vue, .graphql, .scss)만 Prettier로 포맷팅하도록 주의하세요. 예를 들어 Visual Studio Code 설정 파일에서 파일 형식을 제외할 수 있습니다:

  "prettier.disableLanguages": [
      "json",
      "markdown"
  ]

Yarn 스크립트#

전역 포맷팅을 위해 다음 yarn 스크립트를 사용할 수 있습니다:

yarn run lint:prettier:staged:fix

Prettier로 스테이지된 모든 파일(git diff 기반)을 업데이트하고 필요한 변경 사항을 저장합니다.

yarn run lint:prettier:staged

Prettier로 스테이지된 모든 파일(git diff 기반)을 검사하고 수동 업데이트가 필요한 파일을 콘솔에 출력합니다.

yarn run lint:prettier

Prettier로 모든 파일을 검사하고 수동 업데이트가 필요한 파일을 콘솔에 출력합니다.

yarn run lint:prettier:fix

Prettier로 리포지터리의 모든 파일을 포맷팅합니다.

VS Code 설정#

Prettier를 기본 포매터로 선택#

Prettier를 포매터로 선택하려면 사용자 또는 워크스페이스 설정에 다음 속성을 추가합니다:

{
  "[html]": {
    "editor.defaultFormatter": "esbenp.prettier-vscode"
  },
  "[javascript]": {
    "editor.defaultFormatter": "esbenp.prettier-vscode"
  },
  "[vue]": {
    "editor.defaultFormatter": "esbenp.prettier-vscode"
  },
  "[graphql]": {
    "editor.defaultFormatter": "esbenp.prettier-vscode"
  }
}

저장 시 포맷팅#

파일을 저장할 때 Prettier로 자동 포맷팅하려면 사용자 또는 워크스페이스 설정에 다음 속성을 추가합니다:

{
  "[html]": {
    "editor.formatOnSave": true
  },
  "[javascript]": {
    "editor.formatOnSave": true
  },
  "[vue]": {
    "editor.formatOnSave": true
  },
  "[graphql]": {
    "editor.formatOnSave": true
  },
}

도구

GitLab v19.1

원문 보기

번역일: 2026-06-19

요약

ESLint#

ESLint를 사용하여 프론트엔드 코드 표준을 캡슐화하고 적용합니다. 구성은 gitlab-eslint-config 프로젝트에서 확인할 수 있습니다.

Yarn 스크립트#

이 섹션에서는 ESLint를 사용하여 파일을 검증하고 자동 수정을 적용하는 데 사용할 수 있는 yarn 스크립트를 설명합니다.

ESLint로 스테이지된 모든 파일(git diff 기반)을 검사하려면 다음 스크립트를 실행합니다:

yarn run lint:eslint:staged

발견된 문제 목록이 콘솔에 출력됩니다.

ESLint 자동 수정을 스테이지된 모든 파일(git diff 기반)에 적용하려면 다음 스크립트를 실행합니다:

yarn run lint:eslint:staged:fix

수동 변경이 필요한 경우 변경 사항 목록이 콘솔에 출력됩니다.

리포지터리에서 특정 파일을 ESLint로 검사하려면 다음 스크립트를 실행합니다($PATH_TO_FILE를 실제 경로로 교체):

yarn run lint:eslint $PATH_TO_FILE

리포지터리의 모든 파일을 ESLint로 검사하려면 다음 스크립트를 실행합니다:

yarn run lint:eslint:all

발견된 문제 목록이 콘솔에 출력됩니다.

ESLint 자동 수정을 리포지터리의 모든 파일에 적용하려면 다음 스크립트를 실행합니다:

yarn run lint:eslint:all:fix

수동 변경이 필요한 경우 변경 사항 목록이 콘솔에 출력됩니다.

전역 규칙 업데이트에만 사용하세요. 그렇지 않으면 변경 사항으로 인해 대규모 머지 리퀘스트가 발생할 수 있습니다.

새 파일에서 ESLint 비활성화#

단일 위반에 대해 ESLint 비활성화#

단일 위반에 대해 규칙을 비활성화해야 하는 경우, 필요한 최소한의 코드 범위에서만 비활성화하세요:

// bad
/* eslint-disable no-new */

import Foo from 'foo';

new Foo();

// better
import Foo from 'foo';

// eslint-disable-next-line no-new
new Foo();

todo 파일 생성#

장점:

특정 규칙을 위반하는 모든 파일에 대한 단일 진실 공급원(Single Source Of Truth, SSOT). 이를 통해 발생한 기술 부채를 해결하기 위한 작업을 더 쉽게 추적할 수 있습니다.
규칙을 처음 활성화할 때 위반하는 모든 파일을 수정할 필요가 없으므로 변경 집합이 더 작아집니다.

단점:

전체 파일에 대해 규칙을 비활성화하면 해당 파일에 동일한 유형의 위반이 더 많이 도입될 수 있습니다.
여러 동시 머지 리퀘스트에서 위반을 수정할 때 todo 파일에서 충돌이 자주 발생하여 MR 작성자가 브랜치를 리베이스해야 합니다.

todo 파일을 생성하려면 scripts/frontend/generate_eslint_todo_list.mjs 스크립트를 실행합니다:

node scripts/frontend/generate_eslint_todo_list.mjs <rule_name>

예를 들어, vue/no-unused-properties 규칙에 대한 todo 파일 생성:

node scripts/frontend/generate_eslint_todo_list.mjs vue/no-unused-properties

이렇게 하면 .eslint_todo/vue-no-unused-properties.mjs에 ESLint 구성이 생성되어 전역 구성에 자동으로 추가됩니다.

모든 위반 파일이 수정되면 todo 파일과 .eslint_todo/index.mjs의 export 구문을 함께 제거해야 합니다.

no-undef 규칙과 전역 변수 선언#

no-undef 규칙을 절대 비활성화하지 마세요. 대신 /* global Foo */로 전역 변수를 선언하세요.

여러 전역 변수를 선언할 때는 항상 변수마다 하나씩 /* global [name] */ 줄을 사용하세요.

// bad
/* globals Flash, Cookies, jQuery */

// good
/* global Flash */
/* global Cookies */
/* global jQuery */

import/no-deprecated를 사용하여 함수 사용 중단#

@gitlab/eslint-plugin Node 모듈에는 eslint-plugin-import 패키지가 포함되어 있습니다.

import/no-deprecated 규칙을 사용하여 @deprecated 태그가 있는 JSDoc 블록으로 함수를 사용 중단(deprecated)으로 표시할 수 있습니다:

/**
 * Convert search query into an object
 *
 * @param {String} query from "document.location.search"
 * @param {Object} options
 * @param {Boolean} options.gatherArrays - gather array values into an Array
 * @returns {Object}
 *
 *For example: "?one=1&two=2" into {one: 1, two: 2}
 * @deprecated Please use `queryToObject` instead. See https://gitlab.com/gitlab-org/gitlab/-/issues/283982 for more information
 */
export function queryToObject(query, options = {}) {
  ...
}

다음을 강력히 권장합니다:

이 함수를 사용하려는 개발자를 위한 대안 경로를 제공하세요.
마이그레이션 프로세스를 추적하는 이슈 링크를 제공하세요.

사용 중단된 함수를 다른 파일로 임포트하면 사용이 탐지됩니다. 같은 파일 내에서 함수를 사용할 경우에는 탐지되지 않습니다.

이후 $ yarn eslint를 실행하면 사용 중단된 사용 목록을 확인할 수 있습니다:

$ yarn eslint

./app/assets/javascripts/issuable_form.js
   9:10  error  Deprecated: Please use `queryToObject` instead. See https://gitlab.com/gitlab-org/gitlab/-/issues/283982 for more information  import/no-deprecated
  33:23  error  Deprecated: Please use `queryToObject` instead. See https://gitlab.com/gitlab-org/gitlab/-/issues/283982 for more information  import/no-deprecated
...

이 규칙의 비활성화 케이스를 Grep하여 작업 목록을 생성함으로써 사용 중단된 사용을 제거하는 노력을 추적하는 이슈를 만드세요:

$ grep "eslint-disable.*import/no-deprecated" -r .

./app/assets/javascripts/issuable_form.js:import { queryToObject, objectToQuery } from './lib/utils/url_utility'; // eslint-disable-line import/no-deprecate
./app/assets/javascripts/issuable_form.js:  // eslint-disable-next-line import/no-deprecated

내 파일에서 vue/multi-word-component-names가 비활성화됨#

단일 이름 컴포넌트는 Vue 스타일 가이드에서 권장하지 않습니다.

이를 해결하기 위해 .vue 파일과 해당 참조를 두 단어 이상을 사용하여 이름을 바꾸어야 합니다. 예를 들면:

user/table.vue는 user/users_table.vue로 이름을 바꾸고 UsersTable로 임포트하여 <users-table />로 사용할 수 있습니다.

GraphQL 스키마 및 오퍼레이션 유효성 검사#

Prettier로 포맷팅#

에디터#

  "prettier.disableLanguages": [
      "json",
      "markdown"
  ]

Yarn 스크립트#

전역 포맷팅을 위해 다음 yarn 스크립트를 사용할 수 있습니다:

yarn run lint:prettier:staged:fix

Prettier로 스테이지된 모든 파일(git diff 기반)을 업데이트하고 필요한 변경 사항을 저장합니다.

yarn run lint:prettier:staged

Prettier로 스테이지된 모든 파일(git diff 기반)을 검사하고 수동 업데이트가 필요한 파일을 콘솔에 출력합니다.

yarn run lint:prettier

Prettier로 모든 파일을 검사하고 수동 업데이트가 필요한 파일을 콘솔에 출력합니다.

yarn run lint:prettier:fix

Prettier로 리포지터리의 모든 파일을 포맷팅합니다.

VS Code 설정#

Prettier를 기본 포매터로 선택#

Prettier를 포매터로 선택하려면 사용자 또는 워크스페이스 설정에 다음 속성을 추가합니다:

{
  "[html]": {
    "editor.defaultFormatter": "esbenp.prettier-vscode"
  },
  "[javascript]": {
    "editor.defaultFormatter": "esbenp.prettier-vscode"
  },
  "[vue]": {
    "editor.defaultFormatter": "esbenp.prettier-vscode"
  },
  "[graphql]": {
    "editor.defaultFormatter": "esbenp.prettier-vscode"
  }
}

저장 시 포맷팅#

파일을 저장할 때 Prettier로 자동 포맷팅하려면 사용자 또는 워크스페이스 설정에 다음 속성을 추가합니다:

{
  "[html]": {
    "editor.formatOnSave": true
  },
  "[javascript]": {
    "editor.formatOnSave": true
  },
  "[vue]": {
    "editor.formatOnSave": true
  },
  "[graphql]": {
    "editor.formatOnSave": true
  },
}