Next.js 프로젝트에서 Husky와 Biome 설정 방법 (2026 가이드)

Source: Dev.to

Introduction

대부분의 JavaScript/TypeScript 프로젝트는 ESLint + Prettier를 사용해 린팅과 포맷팅을 합니다.
Biome – 빠른 Rust 기반 올인원 도구 – 가 두 역할을 대체합니다. Biome을 Husky와 함께 사용하면 모든 커밋이 자동으로 포맷팅 및 린팅 기준을 충족하도록 할 수 있습니다.

이 가이드는 lint‑staged 없이, 그리고 기존 ESLint/Prettier 설정 없이 npm을 이용해 Next.js 프로젝트에 Husky + Biome을 가장 깔끔하게 설정하는 방법을 보여줍니다.

Why Biome?

1. Fast – Rust 기반 엔진 → 매우 빠른 포맷팅 및 린팅.
2. All‑in‑One – 린팅, 포맷팅, 자동 수정, import 정리를 모두 처리.
3. Simple – 단일 설정 파일: biome.json.
4. No lint-staged required – Biome이 스테이징된 파일만 검사하는 기능을 기본 제공.

Step 1 — Install Husky & Biome

npm install -D @biomejs/biome husky

Step 2 — Initialize Husky

npx husky init

이 명령으로 다음이 생성됩니다:

.husky/
  pre-commit

Step 3 — Add a Biome Configuration

biome.json 파일을 생성합니다:

{
  "$schema": "https://biomejs.dev/schemas/2.3.8/schema.json",
  "vcs": {
    "enabled": true,
    "clientKind": "git",
    "useIgnoreFile": true
  },
  "files": {
    "ignoreUnknown": false
  },
  "formatter": {
    "enabled": true,
    "indentStyle": "tab"
  },
  "linter": {
    "enabled": true,
    "rules": {
      "recommended": true
    }
  },
  "javascript": {
    "formatter": {
      "quoteStyle": "double"
    }
  },
  "assist": {
    "enabled": true,
    "actions": {
      "source": {
        "organizeImports": "on"
      }
    }
  }
}

Step 3.5 — Add Husky & Biome Scripts in package.json

scripts 섹션을 다음과 같이 업데이트합니다:

{
  "scripts": {
    "prepare": "husky",
    "lint": "biome check .",
    "format": "biome format --write ."
  }
}

• prepare → Husky Git 훅을 자동으로 설치합니다.
• lint → 전체 Biome 검사를 실행합니다.
• format → 프로젝트 전체를 포맷합니다.

Step 4 — Configure the Pre‑Commit Hook

.husky/pre-commit 파일을 다음 내용으로 교체합니다:

#!/bin/sh
npx biome check --staged --write

Note: Biome은 --apply 플래그를 제거했으며, 이제 수정 적용을 위해서는 --write 플래그를 사용합니다. 이 명령은 커밋 전에 스테이징된 파일만 포맷팅 + 린팅합니다.

Step 5 — Test the Setup

1. 포맷이 엉망인 코드를 작성해 봅니다:

   const  a={b:1}

2. 스테이징하고 커밋합니다:

   git add .
   git commit -m "test"

Biome이 자동으로 다음과 같이 고칩니다:

const a = { b: 1 };

커밋이 성공하면 설정이 정상적으로 동작한 것입니다.

Step 6 — (Optional) Remove ESLint & Prettier

Biome으로 완전히 전환한다면 다음을 삭제합니다:

• .eslintrc.*
• .prettierrc
• 모든 ESLint 패키지
• 모든 Prettier 패키지

Biome이 이들을 완전히 대체합니다.

Final Snippets

복사해서 바로 사용할 수 있는 레퍼런스로 활용하세요.

package.json Scripts

{
  "scripts": {
    "prepare": "husky",
    "lint": "biome check .",
    "format": "biome format --write ."
  }
}

.husky/pre-commit

#!/bin/sh
npx biome check --staged --write

biome.json

{
  "$schema": "https://biomejs.dev/schemas/2.3.8/schema.json",
  "vcs": {
    "enabled": true,
    "clientKind": "git",
    "useIgnoreFile": true
  },
  "files": {
    "ignoreUnknown": false
  },
  "formatter": {
    "enabled": true,
    "indentStyle": "tab"
  },
  "linter": {
    "enabled": true,
    "rules": {
      "recommended": true
    }
  },
  "javascript": {
    "formatter": {
      "quoteStyle": "double"
    }
  },
  "assist": {
    "enabled": true,
    "actions": {
      "source": {
        "organizeImports": "on"
      }
    }
  }
}

Conclusion

Biome + Husky를 사용하면 2026년에 코드 품질을 유지하는 가장 깔끔한 방법을 제공받게 됩니다:

• ESLint/Prettier보다 빠름
• 의존성 감소
• 최신 Git‑hook 워크플로우
• 스테이징된 파일만 자동 검사
• 간단한 설정

Next.js, React, TypeScript, Node 프로젝트에 최적입니다.