Vite로 마이그레이션하면서 막혔던 설정, 이렇게 해결했습니다

저도 처음엔 Vite로 프로젝트 마이그레이션할 때 생각보다 삽질을 많이 했어요. 기존에 Webpack이나 CRA(Create React App) 환경에서 Vite로 넘어가려니 설정도 다르고, 오류도 여기저기 나서 머리가 복잡하더라고요. 그래서 이걸 정리하면서 독자분들이 겪을 만한 문제들을 한 번에 해결할 수 있게 FAQ 형태로 모아봤습니다.

이 글에서는 Vite 마이그레이션 과정에서 자주 묻는 질문과 제가 직접 부딪혔던 문제들을 순서대로 다루면서, 실무에 바로 써먹을 수 있는 팁과 예시 코드를 같이 공유할게요.

개발 환경 / 버전 정보

저는 Node 18, Vite 4.3.9, 그리고 React 18 환경에서 작업했습니다. 물론 Vue나 Svelte도 비슷한 부분이 많으니 참고하시면 좋을 거예요.

Q1. 기존 Webpack 별칭(alias)을 Vite에서 어떻게 설정하나요?

사실 이 부분이 가장 헷갈리더라고요. Webpack config에 있던 resolve.alias를 Vite에서는 resolve.alias로 설정하는데 경로나 형식이 약간 다릅니다.

import { defineConfig } from 'vite'
import path from 'path'

export default defineConfig({
  resolve: {
    alias: {
      '@': path.resolve(__dirname, 'src')
    }
  }
})

여기서 중요한 건 path.resolve를 꼭 사용해서 절대 경로로 지정해줘야 한다는 점입니다.

Q2. CSS, SASS 전처리기 설정이 안 돼요. 뭘 놓친 건가요?

Vite는 기본적으로 CSS 모듈과 SASS를 지원하지만, 별도 설정이 필요할 때가 있어요. 예를 들어 SASS 변수를 전역으로 사용하려면 vite.config.js에서 css.preprocessorOptions을 설정하면 됩니다.

export default defineConfig({
  css: {
    preprocessorOptions: {
      scss: {
        additionalData: `@import "src/styles/variables.scss";`
      }
    }
  }
})

이렇게 하면 모든 SASS 파일에서 자동으로 변수를 쓸 수 있어서 편하더라고요.

Q3. 환경변수(.env) 파일들이 먹히지 않아요. 왜 그런 걸까요?

Vite의 환경변수는 CRA와 약간 달라서 VITE_ 로 시작하는 변수만 클라이언트 쪽에서 사용할 수 있어요. 예를 들어 .env 파일에 REACT_APP_API_URL 같은 변수는 쓸 수 없고 VITE_API_URL 이런 식으로 바꿔야 제대로 동작해요.

그리고 import.meta.env.VITE_API_URL 형태로 접근해야 합니다.

Q4. React Fast Refresh가 작동하지 않아요

Vite는 기본적으로 React Fast Refresh를 지원하는데 안 되는 경우 대개 설정이나 버전 문제였어요. 제가 겪은 문제는 @vitejs/plugin-react-swc와 react-refresh 버전이 맞지 않아서 그랬더라고요.

가장 안전한 방법은 최신 Vite React 플러그인을 쓰는 건데요, vite.config.js에 이렇게 쓰면 됩니다.

import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react-swc'

export default defineConfig({
  plugins: [react()]
})

Q5. Vite 빌드 후 공용 경로(base)가 달라서 리소스가 안 보입니다

이건 프로젝트를 깃허브 페이지나 서브폴더에 배포할 때 자주 나오는 문제에요. Vite 기본 빌드는 /를 기준으로 리소스를 참조하는데, 배포 경로가 다르면 이미지나 스크립트가 못 읽혀서 화면이 이상해지죠.

해결하려면 vite.config.js에 base 설정을 추가하세요.

export default defineConfig({
  base: '/repository-name/',
})

저는 깃허브 페이지에 배포하면서 이걸 깜빡해서 한참 헤맸는데, 이 설정만 제대로 해주면 해결됩니다.

Q6. Vite에서 SVG 파일을 React 컴포넌트로 바로 쓰고 싶어요

SVG를 컴포넌트처럼 사용하려면 보통 @svgr/webpack 같은 걸 쓰는데, Vite에선 별도 플러그인을 써야 해요.

제 경우에는 vite-plugin-svgr 플러그인이 잘 맞아서 다음처럼 썼습니다.

import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react-swc'
import svgr from 'vite-plugin-svgr'

export default defineConfig({
  plugins: [react(), svgr()]
})

// 사용 예시
// import { ReactComponent as Logo } from './logo.svg'
// <Logo />

Q7. HMR(핫 모듈 리플레이스먼트)이 안 되거나 느려졌어요

Vite는 기본적으로 HMR이 빠르지만, 의외로 node_modules 내 대용량 라이브러리나 너무 많은 파일이 바뀌면 느려질 때가 있어요. 저도 커스텀 훅에서 무한 리렌더링이 걸린 걸 모르고 한참 문제 찾았던 적이 있거든요.

HMR 문제 해결법은 여러 가지인데, optimizeDeps.exclude 옵션으로 히트맵이 너무 큰 모듈을 제외하거나, 과도한 의존성을 줄이는 게 효과적입니다.

Q8. Typescript 설정, tsconfig 경로 별칭이 안 맞아요

Vite가 tsconfig.json 경로 별칭을 바로 인식하지 않아서 모듈을 못 찾는 경우가 있는데, 이땐 vite-tsconfig-paths 플러그인을 쓰는 게 편해요.

import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react-swc'
import tsconfigPaths from 'vite-tsconfig-paths'

export default defineConfig({
  plugins: [react(), tsconfigPaths()]
})

이렇게 하면 tsconfig.json의 paths 설정을 Vite가 그대로 따라가서 별칭 문제를 깔끔하게 해결할 수 있습니다.

마무리

Vite로 마이그레이션할 때는 설정 방식이나 환경변수, 별칭 처리 등 기존과 다르게 해야 하는 부분이 꽤 많아서 처음엔 당황할 수밖에 없더라고요. 저도 삽질하면서 직접 해결책을 찾으니, 이렇게 하나씩 정리해두니 다시 헷갈리지 않고 편하게 쓸 수 있었어요.

혹시 더 복잡한 설정이나 특정 프레임워크 적용 문제 있으면 댓글로 알려 주세요. 비슷한 문제 겪고 계신 분들께 도움이 될 수 있도록 또 정리해볼게요.