정적 에셋은 왜 src에서 관리하는 것이 좋을까?

이번 포스팅에서는 React + Vite 환경에서 정적 에셋을 public과 src 디렉토리에서 관리한 경험을 살펴보고 스스로 도출한 결론을 설명해 보려고 합니다.

 

6주 동안 진행된 morak 프로젝트에서는 정적 에셋을 관리하는 assets 디렉토리를 src → public → 그리고 다시 src 디렉토리로 옮겨 관리하게 되었는데요. 

 

이 의사 결정 과정에 대해 서술해 보고, 결론적으로 왜 src에서 관리하게 되었는지, public과 src 디렉토리에서 관리했을 때 각 어떤 장단점을 얻을 수 있는지를 설명해 보겠습니다.

 

.
├── public
│   └── assets # 어디에 두는 것이
└── src
    └── assets # 맞을까?

 

 

assets을 src → public으로 옮기게 된 배경

assets을 src 디렉토리에서 public 디렉토리로 옮기게 된 이유는 단순합니다. 빌드 시 에셋의 경로가 올바르지 않기 때문이었습니다.

 

다음과 같이 작성한 이미지 태그는 로컬 서버 환경에서는 이미지를 제대로 불러왔지만, 빌드 환경에서는 src 폴더가 생기지 않기 때문에 이미지를 찾을 수 없어 엑박이 뜨는 이슈가 있었습니다. 

 

public 디렉토리에서 assets을 관리한다면 빌드 시 public 하위의 디렉토리들은 dist 디렉토리에 같은 이름으로 만들어지기 때문에 문제를 해결할 수 있었습니다.

<img src='/src/assets/image.png' />

 

 

사실 이 문제는 public으로 옮기는 것이 아니라 더 쉬운 해결책이 있었지만... 하단에서 설명하도록 하겠습니다.

 

public으로 assets을 옮겼을 때 생긴 문제

프로젝트에서는 svg 파일을 ReactComponent로 import 해서 사용하고 있었고, 로컬 서버 빌드 시 다음과 같은 경고 메시지가 콘솔에 출력됩니다.

 

import { ReactComponent as Icon } from '../../public/arrow.svg';

function Main() {
    return (
    	<div>
            <Icon />
        </div>
    )
}

 

 

public 디렉토리에 있는 정적 에셋은 JavaScript 코드를 통해 import 할 수 없다는 내용의 경고였습니다.

JavaScript 파일에서 import 하기를 원한다면 src 디렉토리에서 사용하라고 하네요.

 

그러나 저희는 시간적 여유가 없었다는 핑계로 이 에러 발생의 원인을 제대로 알아보지 않고 넘어갔습니다.

그리고 일주일 뒤 멘토링 시간, 멘토님께서 이 에러에 대한 질문을 해 주셨습니다. 그리고 꼭 알아보라는 말을 덧붙이셨죠.

 

우선 Assets in public directory cannot be imported from JavaScript 에러 메시지에 대한 이유를 알아봅시다.

 

Vite에서의 asset 관리

Vite 공식 문서에는 다음과 같이 설명되어 있습니다.

 

---

다음 에셋의 경우

• robots.txt와 같이 소스 코드에서 참조되지 않는 에셋
• 해싱 없이 항상 같은 이름을 갖는 에셋
• 또는 URL을 얻기 위해 굳이 import 할 필요 없는 에셋

public 디렉터리 아래에 에셋을 위치시키세요.

이곳에 위치한 에셋은 개발 시에 / 경로에, 배포 시에는 dist 디렉터리에 위치하게 됩니다.

 

마지막으로, 다음의 사항을 유의해주세요.

• public 디렉터리에 위치해 있는 에셋을 가져오고자 하는 경우, 항상 루트를 기준으로 하는 절대 경로로 가져와야만 합니다. ( public/icon.png 에셋은 소스 코드에서 /icon.png으로 접근이 가능합니다.)
• public 디렉터리에 위치한 에셋은 JavaScript 코드로 가져올 수 없습니다.

---

 

그리고 Vite 공식 문서 내용 중 정적 에셋 핸들링하기 섹션에 따르면 src 디렉토리 내에 있는 정적 에셋은 import 문으로 가져와 사용할 수 있습니다.

 

import Image from './main.png'

function Main() {
    return <img src={Image} />;
}

 

정적 에셋을 import 문으로 사용하면, Vite가 내부적으로 Webpack의 file-loader와 비슷한 처리를 해 줍니다.

따라서 개발 시에는 Image 객체가 /main.png 값으로 할당되고, 빌드 시에는 추가 설정 없이 /main.[hash].png과 같은 값이 할당됩니다.

 

 

이 방식으로 저희는 public 디렉터리에서 에셋을 관리할 경우 콘솔에 에러가 뜨는 문제를 해결하고, src 디렉터리에서 에셋을 사용할 경우 빌드 시 이미지의 엑박이 뜨는 문제를 간단히 해결할 수 있었습니다.

 

 

 

 

그러나 저는 여기서 public 디렉터리에 위치한 에셋은 JavaScript 코드로 가져올 수 없습니다에 대한 이유가 궁금했습니다.

이유를 찾아보던 중, Why React can not access images from public - DEV Community 글을 발견했습니다.

 

이 글에서는 이렇게 말합니다.

public 디렉터리는 프로덕션을 빌드할 때 최종 번들의 일부가 아니기 때문에 번들러가 처리하지 않는 html 파일을 조정할 수 있다고 해도 마찬가지입니다. src 디렉터리 내에서 관리되는 이미지는 최종 번들의 결과물 중 하나가 되고, src 디렉토리 내에 있는 이미지는 자바스크립트 모듈로서 import 될 수 있습니다.

 

 

 

 

이해를 돕기 위해 빌드된 결과물의 차이도 살펴보도록 하겠습니다.

 

public 디렉터리의 에셋을 사용한 경우

 

/public/assets/main.png를 이미지로 삽입한다면 다음과 같이 url 형태로 삽입합니다.

<img src='/assets/main.png' />

 

 

개발자 도구의 source 탭에서 살펴본 파일 구조는 다음과 같습니다.

.
├── assets
│   ├── index-[hash].js
│   └── index-[hash].css
└── main.png

 

assets의 하위에는 하나로 번들링 된 js 파일과 css 파일이 있고, assets와 같은 경로에 main.png 이미지가 있는 구조입니다.

 

 

src 디렉터리의 에셋을 사용한 경우

개발자 도구의 source 탭에서 살펴본 파일 구조는 다음과 같습니다.

.
└── assets
    ├── index-[hash].js
    ├── index-[hash].css
    └── main.png

 

하나로 번들링 된 js 파일과 css 파일, 그리고 이미지 파일이 모두 assets 디렉토리에 들어 있는 구조입니다. 

이제야 src 디렉토리 내에 있는 이미지는 자바스크립트 모듈로서 import 된다라는 뜻을 이해했습니다.

 

 

정적 에셋 관리 위치에 따른 장단점

 

그렇다면 왜 이미지가 번들의 결과물 중 하나로 사용되지 않는 방식은 피해야 하는 걸까요?

제가 생각한 정적 에셋을 public과 src 디렉터리 각각에서 관리했을 때의 장단점은 다음과 같습니다.

 

첫 번째는 타입 안정성입니다. src 디렉터리 안에서 관리되는 에셋이 삭제되면 빌드가 실패하기 때문에 에셋이 삭제되었다는 것을 알 수 있습니다. 반대로 public 디렉터리는 빌드가 가능하기 때문에 안정성이 보장되지 않는다는 문제가 있습니다.

 

두 번째는 위에서 언급한 아티클과 결과에 따르면 public 디렉터리의 에셋은 Webpack이나 Vite 같은 모듈 번들러를 통해서 처리되지 않기 때문에 빌드 최적화의 혜택을 받지 못한다는 점이 있습니다.

 

세 번째는 public 디렉터리에서 관리하는 에셋의 파일명은 그대로인 채 내용만 변경된다면, 에셋이 캐싱 되어 업데이트되지 않을 위험성도 존재한다는 점입니다.

 

 

따라서 Vite가 public 폴더에서의 에셋 사용을 경고하는 이유는, 모듈 시스템을 통한 의존성 관리와 빌드 과정의 최적화를 권장하기 때문일 것이라는 결론을 내릴 수 있었습니다.

 

마치며

이전 프로젝트에서는 src 디렉터리의 에셋을 import 하는 형태의 코드를 당연하게 작성하고 있었습니다.

하지만 이번 프로젝트에서는 기존 코드 스타일이 아닌 열린 사고로 다른 스타일의 코드도 경험해 보자는 마음가짐을 가졌는데요.

단순히 문자열로 작성되었던 경로를 import 형태로 바꾸었다면 문제를 빨리 해결하고 다음 스텝으로 넘어갈 수도 있었을 겁니다.

 

빠른 해결책을 얻지 못한 대신 이런저런 시도와 삽질을 통해 당연하게 생각하고 있었던 정적 에셋의 관리 위치에 대해 다시 고민해 보고 Vite에서 발생하는 에러의 근본적인 원인까지 더 깊게 파고들어 볼 수 있었던 시간이었습니다.