Vite에서 Browserslist 경고가 나타난 이유와 해결 방법

| 서론

안녕하세요, 팡일입니다.

Vite 프로젝트에서 npm run dev를 실행하던 중 다음과 같은 경고 메시지가 나타났습니다.

Browserslist: browsers data (caniuse-lite) is 7 months old.
Please run:
  npx update-browserslist-db@latest

처음에는 프로젝트 실행에 문제가 생긴 에러처럼 보였지만, 로그를 확인해 보니 Vite 개발 서버는 정상적으로 실행되고 있었습니다.

VITE v7.3.0 ready in 594 ms

➜ Local: http://localhost:5173/

즉, 이 메시지는 개발 서버 실행을 중단시키는 에러가 아니라, 프로젝트에서 참고하는 브라우저 데이터가 오래되었으니 최신 상태로 업데이트하라는 경고였습니다.

이번 글에서는 해당 경고를 해결하는 방법과 함께, 메시지에 등장하는 Browserslist와 caniuse-lite가 어떤 역할을 하는지 간단히 정리해보려고 합니다.

| Browserslist는 무엇일까?

Browserslist는 프로젝트에서 어떤 브라우저를 지원할지 정의하는 도구입니다.

프론트엔드 프로젝트에서는 Chrome, Safari, Firefox 등 다양한 브라우저의 서로 다른 지원 범위를 고려해야 합니다. 모든 브라우저가 같은 CSS 속성이나 JavaScript 문법을 동일하게 지원하는 것은 아니기 때문입니다.

Babel, Autoprefixer, PostCSS와 같은 도구들은 Browserslist에 정의된 지원 범위를 참고하여 필요한 문법을 변환하거나 CSS 접두사를 추가합니다.

예를 들어 프로젝트에서 다음과 같이 설정할 수 있습니다.

// 예시: package.json
{
  "name": "my-project",
  "version": "1.0.0",

  "browserslist": [
    "> 0.5%",
    "last 2 versions",
    "not dead"
  ]
}

이는 일정 수준 이상의 사용률을 가진 브라우저와 각 브라우저의 최근 두 개 버전을 지원하고, 더 이상 관리되지 않는 브라우저는 제외한다는 의미입니다.

| caniuse-lite는 무엇일까?

caniuse-lite는 각 브라우저가 어떤 웹 기술을 지원하는지 담고 있는 데이터입니다.

특정 버전의 Safari가 어떤 CSS 속성을 지원하는지, Chrome에서 특정 JavaScript 기능을 사용할 수 있는지와 같은 정보가 포함되어 있습니다.

두 가지의 역할을 간단히 정리하면 다음과 같습니다.

Browserslist
→ 프로젝트가 지원할 브라우저의 범위를 정의한다.

caniuse-lite
→ 각 브라우저의 웹 기술 지원 정보를 제공한다.

Browserslist는 프로젝트의 지원 정책을 정하고, caniuse-lite는 그 정책을 계산하는 데 필요한 실제 브라우저 데이터를 제공하는 구조입니다.

브라우저는 계속해서 새로운 버전으로 업데이트되기 때문에, 프로젝트에서 사용하는 브라우저 데이터 역시 주기적으로 갱신할 필요가 있습니다. 이 데이터가 일정 기간 이상 오래되면 Browserslist가 업데이트를 권장하는 경고를 출력합니다.

| 해결 방법

경고 메시지에서 안내한 다음 명령어를 프로젝트 루트에서 실행했습니다.

npx update-browserslist-db@latest

실행 결과는 다음과 같았습니다.

Latest version:     1.0.30001806
Installed version:  1.0.30001762

Removing old caniuse-lite from lock file
Installing new caniuse-lite version

caniuse-lite has been successfully updated

No target browser changes

명령어는 현재 설치된 버전과 최신 버전을 비교한 뒤, lock 파일에 기록된 오래된 caniuse-lite 정보를 제거하고 최신 버전으로 교체합니다.

업데이트 과정에서 package-lock.json, pnpm-lock.yaml, yarn.lock과 같은 lock 파일이 변경될 수 있습니다. 팀 프로젝트라면 변경된 lock 파일의 내용을 확인한 뒤 함께 커밋하면 됩니다.

| No target browser changes는 무슨 의미일까?

업데이트 마지막에 나타난 다음 문장이 조금 헷갈릴 수 있습니다.

No target browser changes

이 문장은 업데이트가 적용되지 않았다는 의미가 아닙니다.

브라우저 지원 데이터는 최신으로 업데이트되었지만, 프로젝트가 실제로 지원해야 하는 브라우저 목록은 이전과 동일하다는 의미입니다. 즉, 업데이트는 정상적으로 완료되었지만 프로젝트의 브라우저 지원 범위에는 변화가 없었다는 뜻입니다.

따라서 다음 문장이 출력되었다면 업데이트는 정상적으로 완료된 것입니다.

caniuse-lite has been successfully updated

이후 다시 개발 서버를 실행하여 기존 경고가 사라졌는지 확인하면 됩니다.

npm run dev

| 마무리

이번 메시지는 프로젝트에 문제가 발생했다는 에러가 아니라, 브라우저 지원 데이터를 최신 상태로 유지하라는 경고였습니다.

안내된 명령어를 실행하는 것만으로도 해결할 수 있었지만, 그 과정에서 Browserslist가 프로젝트의 지원 브라우저 범위를 관리하고, caniuse-lite가 브라우저별 웹 기술 지원 정보를 제공한다는 것을 알 수 있었습니다.

개발 중 경고 메시지를 마주했을 때 해결 명령어만 실행하고 넘어갈 수도 있지만, 메시지에 등장하는 도구의 역할을 함께 살펴보면 프로젝트가 동작하는 구조를 조금 더 깊게 이해할 수 있습니다.