Webpack 프로젝트를 만들어 본 적이 있고 브라우저 탭에 기본적인 지구 아이콘이나 빈 사각형이 표시되는 것을 발견했다면, 여러분만 겪은 일은 아닙니다. Webpack은 기본적으로 favicon을 처리하지 않기 때문에 직접 연결해야 합니다. 파일을 어디에 두고 link tag를 어떻게 삽입하는지 알면 설정은 몇 줄이면 충분합니다.
이 가이드는 favicon 파일을 프로젝트에 배치하는 것부터 브라우저에서 확인하는 것까지, Webpack 프로젝트에 favicon을 추가하는 방법을 안내합니다. 간단한 copy 방식과 HtmlWebpackPlugin 방식, 그리고 대부분의 개발자가 빠지기 쉬운 함정까지 다룹니다.
사전 준비 사항
Webpack과 webpack-cli가 설치된 정상 동작하는 Webpack 프로젝트가 필요합니다. HTML을 생성하기 위해 html-webpack-plugin을 사용하고 있다면 더 좋습니다. 권장하는 방식에서는 이 plugin을 사용합니다. 바로 사용할 준비가 된 favicon 파일(ICO, PNG 또는 SVG)이 필요합니다. favicon 파일이 필요하다면 multi-size ICO 생성 가이드를 참고하세요.
1단계: 프로젝트에 favicon 배치하기
static assets를 위한 폴더가 없다면 하나 만드세요. 일반적으로 사용하는 위치는 src/assets/ 또는 public/입니다. favicon 파일을 그곳에 넣으세요. 브라우저 호환성을 최대한 확보하기 위해 여기서는 favicon.ico라고 부르겠습니다. favicon.png이나 favicon.svg도 사용할 수 있습니다. SVG는 최신 browser에서 지원되지만 구형 browser에는 fallback이 필요합니다(PNG fallback을 적용한 SVG).
이 가이드에서는 파일이 src/assets/favicon.ico에 있다고 가정합니다.
2단계: Webpack이 favicon을 복사하도록 설정하기
Webpack이 해당 파일을 처리하여 build output에 포함되도록 해야 합니다. 가장 간단한 방법은 copy-webpack-plugin을 사용하는 것입니다. 다음과 같이 설치하세요:
npm install --save-dev copy-webpack-plugin
그런 다음 webpack.config.js에 다음과 같이 추가합니다:
const CopyPlugin = require('copy-webpack-plugin');
module.exports = {
// ... other config
plugins: [
new CopyPlugin({
patterns: [
{ from: 'src/assets/favicon.ico', to: 'favicon.ico' }
]
})
]
};이 과정은 favicon을 출력 디렉터리의 루트에 복사합니다(예: dist/favicon.ico). link 태그가 없으면 브라우저가 자동으로 /favicon.ico를 요청하므로 이것만으로도 작동할 수 있습니다. 다만 제어하거나 ICO가 아닌 형식을 사용하려면 명시적인 link 태그가 더 좋습니다.
3단계: HtmlWebpackPlugin으로 link 태그 주입
html-webpack-plugin을 사용한다면 HTML 템플릿에 favicon link를 직접 추가할 수 있습니다. index.html 템플릿(일반적으로 src/에 있음)의 <head> 안에 다음을 추가하세요:
<link rel='icon' href='favicon.ico' type='image/x-icon'>파일이 출력 루트에 복사되기 때문에 상대 경로 favicon.ico가 정상적으로 해석됩니다. 하위 디렉터리에서 서빙하는 경우 /favicon.ico 같은 절대 경로를 사용하거나 Webpack에서 publicPath를 설정하세요.
SVG favicon은 다음과 같이 사용합니다:
<link rel='icon' href='favicon.svg' type='image/svg+xml'>PNG는 다음과 같이 사용합니다:
<link rel='icon' href='favicon.png' type='image/png'>rel='icon' 속성은 사이트 아이콘을 지정하는 방법으로 HTML 표준에 정의되어 있습니다. 브라우저는 이 속성을 사용해 탭, 북마크, 기록에 가장 적합한 아이콘을 선택합니다.
4단계: 빌드 및 확인
빌드 명령을 실행하세요(예: npm run build). 출력 폴더에 favicon.ico가 나타나는지 확인합니다. 그런 다음 빌드 결과를 로컬에서 서빙하고(예: npx serve dist) 브라우저에서 열어 보세요. 탭에 아이콘이 표시되어야 합니다. 표시되지 않으면 캐시를 우회하도록 hard-refresh(Ctrl+Shift+R 또는 Cmd+Shift+R)를 하세요.
페이지 소스를 확인해 link 태그가 존재하는지, 경로가 올바른지 확인할 수도 있습니다.
자주 발생하는 문제
- 잘못된 output path:
CopyPlugin의to경로에 하위 폴더를 포함했다면 link tag도 일치해야 합니다. 예를 들어to: 'assets/favicon.ico'를 사용하는 경우href='assets/favicon.ico'가 필요합니다. - Production에서 파일이 누락됨: 일부 설정에서는 개발 중일 때만 asset을 복사합니다. 모든 모드에서
CopyPlugin이 실행되도록 설정해야 합니다. - 캐시 문제: 브라우저는 favicon을 강하게 캐시합니다. favicon을 업데이트할 때는
favicon.ico?v=2와 같은 query string을 사용하거나 build에 cache busting을 설정하세요(cache busting 모범 사례 참고). - fallback 없는 SVG: 구형 브라우저는 SVG favicon을 무시합니다. 항상 ICO 또는 PNG fallback을 포함해야 합니다.
- 파일이 루트에 없음: link tag를 사용하지 않고 기본
/favicon.ico요청에 의존한다면 파일이 서비스되는 디렉터리의 루트에 있어야 합니다.
결론
Webpack 프로젝트에 favicon을 추가하는 일은 핵심 두 가지를 알면 간단합니다. 파일을 output에 복사하고 HTML에서 참조하면 됩니다. copy-webpack-plugin으로 asset을 옮기고 템플릿에 link rel='icon' tag를 추가하세요. 그뿐입니다. 브라우저 탭이 다듬어진 professionally한 디자인을 갖게 됩니다.
완전한 favicon 세트(ICO, PNG, Apple Touch, manifest icons)를 생성해야 한다면 Mzu favicondl을 사용해 필요한 파일을 한 번에 만들어 보세요.