[React] React + Vite + TypeScript 프로젝트 초기 설정 방법

 

이전에 리액트 앱을 만들때 항상 npx create-react-app을 이용해왔다.

하지만, 리액트 공식적으로도 요즘 cra를 비추하는 추세였다. 이유는 다음과 같다.

• CRA는 Webpack으로 어플리케이션을 번들링하여, 빌드 시 앱이 굉장히 무거워지고, 변경사항을 반영하는데 있어서 오랜 시간이 걸린다.
• 서버 사이르 렌더링을 처리하는데 있어 세팅을 하는 것이 어려우며, 게다가 타입스크립트를 지원하지 않는다.
• 용량이 너무 크고, 의존성 설치에 있어 굉장히 오랜 시간이 걸린다.

이전 프로젝트는 빌드 시간을 크게 체감하지 못했는데, 현재 1년째 진행중인 프로젝트의 규모가 커져 빌드 시간이 3분 가까이 소요되는 문제가 있었다. 심지어, 기능 업데이트를 할 계획이어서 CRA로 해당 프로젝트를 진행하기에 한계가 있다 생각하였다. 또한 CRA는 의존성 설치를 할 때마다 수많은 Warning이 발생하면서 하나하나 의존성 관계를 봐야하는 번거로움도 있었다.

 

Vite와 CRA의 차이점은 이전 포스팅인 마이그레이션 하는 방법에서 더 자세히 다룬다.

https://itguswjd.tistory.com/214

[React] CRA에서 Vite로 마이그레이션하기

따라서 이번 포스팅에서는 React+Vite+TypeScript로 프로젝트를 생성하고 초기 설정 방법을 알아보고자 한다.

 

 

 

01. 프로젝트 생성

1️⃣ npm create vite@latest [프로젝트 명] -- --template react-ts

먼저 본인의 npm 버전을 확인해주고 맞는 버전에 따라 프로젝트를 생성해야 한다.

 

// npm 6.x
npm create vite@latest [프로젝트 명] --template react-ts
// npm 7+, extra double-dash is needed:
npm create vite@latest [프로젝트 명] -- --template react-ts

 

npm -v로 버전 확인 결과 7이상이므로 아래 명령어로 프로젝트를 생성하였다.

 

이때 react-ts 부분은 사용할 프레임워크와 언어에 따라 다르다.

JavaScript	TypeScript
vanilla	vanilla-ts
vue	vue-ts
react	react-ts
preact	preact-ts
lit	lit-ts
svelte	svelte-ts

 

만약 자바스크립트를 이용해 react, vite 앱을 생성하고 싶다면 react-ts대신 react 입력을 하면 된다.

 

 

 

2️⃣ npm install

앞서 npm create vite@latest [프로젝트 명] -- --template react-ts로 프로젝트를 생성하면

cd 프로젝트명

 

위 명령어로 디렉토리를 이동한다. 하지만 생성된 프로젝트에서 Main.tsx나 App.tsx등의 파일을 들어가보면 

import { StrictMode } from 'react'
import { createRoot } from 'react-dom/client'

위와 같은 코드에서 오류가 발생하는 것을 볼 수 있으며, 프로젝트 실행도 되지 않을 것이다.

이는 아직 프로젝트에 package.json에 있는 라이브러리들이 설치되지 않아서 import 해오지 못하기 때문이다.

 

npm install

따라서 npm install을 통해 프로젝트에서 필요한 모든 의존성(dependencies)을 설치한다.

 

 

 

3️⃣ npm run dev

npm install을 완료하고 터미널에 npm run dev를 입력하면 프로젝트가 실행되는 것을 확인할 수 있을 것이다.

 

 

 

 

02. react, vite, typescript로 생성한 프로젝트 초기 파일

 

• public : 정적 자산(static assets)을 담는 폴더. 이 폴더에 있는 파일들은 빌드 과정에서 그대로 배포. 이미지, 아이콘 등을 이곳에 저장하며, 이 파일들은 번들링되지 않고 그대로 최종 결과물에 포함.

 

• src : 프로젝트의 소스 코드가 들어가는 메인 폴더. 모든 컴포넌트, 로직, 스타일링 파일들이 이곳에 위치. src에 있는 main.tsx는 어플리케이션의 진입점

 

• vite-env.d.ts : Vite에서 사용하는 환경 변수 파일. TypeScript에서 Vite 관련 타입을 정의하는데 사용. Vite에 의해 자동으로 생성되는 파일로, Vite에서 사용하는 전역 변수를 TypeScript가 이해할 수 있도록 도움.

 

• .gitignore : git에 추적되지 않도록 할 파일이나 폴더를 지정하는 파일. 빌드 결과물, 환경 설정 파일 등 버전 관리에 포함되지 않아야 하는 파일을 명시하여, 불필요한 파일이 git에 포함되지 않도록 방지. node_modules/, .env, dist/ 등을 무시.

 

• eslint.confing.js : ESLint 설정 파일. JavaScript와 TypeScript 코드에서 문법 및 스타일을 검사. 해당 파일에서 프로젝트에 맞는 코드 스타일 규칙을 정의.

 

• index.html : 어플리케이션의 진입점 HTML 파일. 이 파일을 통해 브라우저에 앱을 렌더링. 이 파일에서 Vite는 빌드 시 필요한 스크립트를 삽입하고, root라는 아이디를 가진 <div> 태그에 React 컴포넌트를 렌더링. 

 

• package-lock.json : 정확한 의존성 트리와 각 패키지의 버전을 기록하는 파일. npm install을 실행할 때 설치된 모든 패키지의 버전 및 의존성을 기록하여, 동일한 환경에서 동일한 버전의 패키지가 설치되도록 보장. 프로젝트의 일관성을 유지하는데 중요하며, 의존성 트리 구조를 명확히 보여줌.

 

• package.json : 프로젝트의 메타 정보(이름, 버전, 설명 등)와 프로젝트에서 사용하는 패키지의 의존성(dependencies, devDependencies)을 관리. 프로젝트 스크립트(scripts)를 정의하여 npm run dev, npm run build와 같은 명령어를 실행할 수 있게 함.

 

• tsconfig.app.json : 프로젝트의 TypeScript 설정 파일 중 하나로, 앱과 관련된 구체적인 설정이 포함. TypeScript 컴파일러에게 어떻게 코드를 해석하고, 어떤 설정을 따를지 정의. 일반적인 설정은 tsconfig.json에 있지만, 앱에 특정한 추가 설정이 필요할 경우 이 파일에 정의.

 

• tsconfig.json : 프로젝트의 주요 TypeScript 설정 파일. TypeScript 컴파일러가 프로젝트 내에서 어떻게 코드를 해석할지를 설정하는 파일. 프로젝트의 전반적인 타입 검사 방식을 설정. JSX 지원, 모듈 시스템 설정, 타겟 브라우저 정의 등이 가능.

 

• tsconfig.node.json : Node.js와 관련된 TypeScript 설정이 포함된 파일. 이 파일은 Vite에서 사용하는 설정을 추가. vite.config.ts와 같은 Node.js 환경에서 실행되는 TypeScript 파일에 대해 별도의 설정을 제공하여 Node에서의 실행을 최적화.

 

• vite.config.ts : Vite의 설정 파일. Vite의 빌드와 관련된 설정을 정의. 플러그인 추가, 서버 설정, 경로 별칭 설정 등을 수행 가능.

 

 

 

 

 

03. ESLint와 prettier 설정

ESLint는 코드의 문법 오류를 찾아주는 도구이며, Prettier는 코드를 자동으로 포맷팅하는 도구이다.

하지만, 두 개를 함께 설정하지 않으면 서로 다른 규칙이 적용되어 충돌이 발생할 수 있다.

 

1️⃣ VSCode extension 설치

ESLint Extension

Prettier Extension

 

2️⃣ 패키지 설치

npm install -D -E prettier

먼저 prettier 관련 패키지를 설치해준다. 이때 -D와 -E가 의미하는 것은 다음과 같다.

• --save-dev or -D : devDependencies 내 라이브러리 추가 및 배포가 아닌 개발시에만 사용
• --save-exact or -E : 특정 버전 고정하여 설치. 정확한 SemVer 버전 사용 시 (^5.1.3 이 아닌 5.1.3)

npm install -D eslint-config-prettier eslint-plugin-prettier

 

다음으로는 ESLint와 Prettier 충돌을 방지하기 위한 패키지를 설치해야 한다.

• eslint-config-prettier : ESLint와 Prettier의 충돌을 방지하는 설정을 제공하는 패키지
• esling-plugin-prettier : Prettier의 포맷팅 규칙을 ESLint의 규칙처럼 실행할 수 있도록 해주는 ESLint 플러그인

 

 

3️⃣ eslint 설정 파일(eslint.config.js) 수정

다음은 eslint.config.js 파일을 수정해야 한다.

import js from '@eslint/js';
import globals from 'globals';
import reactHooks from 'eslint-plugin-react-hooks';
import reactRefresh from 'eslint-plugin-react-refresh';
import tseslint from 'typescript-eslint';
import prettier from 'eslint-plugin-prettier'; // Prettier 플러그인 추가
import eslintConfigPrettier from 'eslint-config-prettier'; // Prettier 충돌 방지용

export default tseslint.config(
  { ignores: ['dist'] },
  {
    extends: [
      js.configs.recommended,
      ...tseslint.configs.recommended,
      eslintConfigPrettier, // Prettier와 충돌 방지
    ],
    files: ['**/*.{ts,tsx}'],
    languageOptions: {
      ecmaVersion: 2020,
      globals: globals.browser,
    },
    plugins: {
      'react-hooks': reactHooks,
      'react-refresh': reactRefresh,
      prettier, // Prettier 플러그인 추가
    },
    rules: {
      ...reactHooks.configs.recommended.rules,
      'react-refresh/only-export-components': [
        'warn',
        { allowConstantExport: true },
      ],
      'prettier/prettier': 'warn', // Prettier 포맷팅 규칙을 ESLint에서 검사
    },
  },
);

 

 

ESLint와 Prettier의 충돌을 방지하기 위해 extends에 eslintConfigPrettier를 추가한다.

Prettier 규칙을 ESLint가 검사할 수 있도록 plugins에 prettier를 추가하고, rules에 'prettier/prettier': 'warn'을 추가한다.

 

 

 

4️⃣ prettier 설정 파일(.prettierrc) 추가

prettier 설정 파일이 존재하지 않으면 default 값으로 자동 적용이 되지만 커스텀하여 사용할 수 있도록 프로젝트 최상단에 .prettierrc 파일을 생성한 뒤 다음과 같이 원하는 설정 값들을 넣어주면 된다.

{
  "printWidth": 100, // 한 줄의 최대 길이를 설정 (100자까지 허용)
  "tabWidth": 2, // 들여쓰기 시 사용하는 탭의 너비를 설정 (2칸 들여쓰기)
  "trailingComma": "all",  // 객체나 배열의 마지막 요소 뒤에 항상 쉼표를 추가. 예: { a: 1, b: 2, }
  "singleQuote": true,  // 문자열을 작은따옴표로 감쌀지 설정 (true일 경우 작은따옴표 사용)
  "jsxSingleQuote": true, // JSX 안에서 속성 값을 작은따옴표로 감쌀지 설정. 예: <Component prop='value' />
  "semi": false // 문장의 끝에 세미콜론을 추가할지 여부 (false일 경우 세미콜론을 사용하지 않음)
}

 

 

 

5️⃣ VSCode 설정에서 Default Formatter에 Pretter 지정

 

마지막으로 맥북 기준 Command ,를 통해 설정으로 들어가서 default formater에 prettier로 설정하면 된다.

 

 

 

 

04. 절대 경로 변경 ( tsconfig.json )

우선 상대 경로로 import 했을 때의 방식은 다음과 같다.

./ 또는 ../을 이용하여 경로를 찾아가서 import 해야 한다.
뎁스가 깊어지고, 폴더가 다양해지면 나중에는 ../../../../파일명의 형태처럼 복잡하고 가독성이 떨어지게 된다.
그래서 이 문제를 해결하기 위해 절대 경로를 설정해야 한다. vite + typescript를 이용하여 절대 경로를 설정할 경우 vite-tsconfig-paths 모듈을 사용하여 절대경로를 설정하거나, 모듈을 사용하지 않고 절대경로를 설정하는 두가지의 방법이 있다.

 

 

#1. vite-tsconfig-paths 모듈 사용하지 않는 경우

이 경우, Vite의 resolve.alias를 직접 설정하여 절대 경로를 설정해야 한다.

 

1️⃣ @types/node 설치

npm install -D @types/node

path를 타입스크립트에서 사용하기 위해서는 @types/node를 설치가 필요하다. 위 명령어를 통해 @types/node를 설치한다.

 

 

2️⃣ Vite 설정(vite.config.ts)

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

export default defineConfig({
  resolve: {
    alias: {
      '@': path.resolve(__dirname, 'src') // '@'를 src 디렉토리로 매핑
    },
  },
});

 

Vite의 resolve.alias 옵션을 사용하여 절대 경로를 수동으로 설정한다.

 

 

3️⃣ tsconfig.json에서 paths 옵션 설정

{
  "compilerOptions": {
    "baseUrl": ".", // 프로젝트 루트 디렉토리 기준
    "paths": {
      "@/*": ["src/*"] // '@'를 src 디렉토리로 매핑
    }
  }
}

 

 

 

 

 

#2. vite-tsconfig-paths 모듈 사용하는 경우

1️⃣ npm install -D vite-tsconfig-paths

npm install -D vite-tsconfig-paths

먼저, vite-tsconfig-paths를 설치한다.

 

 

2️⃣ Vite 설정(vite.config.ts)

vite.config.ts 파일에서 vite-tsconfig-paths를 플러그인으로 추가한다.

import { defineConfig } from 'vite';
import path from 'path';
import tsconfigPaths from 'vite-tsconfig-paths'; // 플러그인 추가

export default defineConfig({
  plugins: [tsconfigPaths()], // 플러그인 적용
});

 

 

3️⃣ tsconfig.json에서 paths 옵션 설정

{
  "compilerOptions": {
    "baseUrl": ".", // 프로젝트 루트 디렉토리 기준
    "paths": {
      "@/*": ["src/*"] // '@'를 src 디렉토리로 매핑
    }
  }
}

tsconfig.json에서 paths 옵션을 설정한다.

이 경우, Vite는 tsconfig.json 파일에 설정된 경로를 자동으로 인식하여, 절대 경로를 사용할 수 있다.