[React & TS] 프로젝트 생성, 초기 설정

1. 프로젝트 생성

터미널을 이용해 프로젝트를 생성합니다.

npm create vite@latest ts_project -- --template react-ts

 

위 명령어에서 ts_project는 프로젝트 폴더 이름입니다. 원하는 이름으로 변경할 수 있습니다.

프로젝트 폴더가 생성되었다면 폴더로 이동 후 패키지를 설치합니다.

cd ts_project
npm install

 

설치가 완료되면, 프로젝트의 기본 구조와 주요 파일들이 자동으로 생성됩니다.

 

2. 프로젝트 구조

Vite와 TypeScript 템플릿을 사용해 생성된 프로젝트는 기본적인 파일 구조가 설정되어 있습니다.

• src: 소스 코드가 포함된 폴더로, 컴포넌트와 유틸리티 파일들을 여기에 배치합니다.
• assets: 이미지, 아이콘, 폰트등 정적 파일을 저장하는 폴더입니다.
• api: API 호출과 관련된 코드를 저장하는 폴더입니다.
• components: 재사용 가능한 UI 컴포넌트를 저장하는 폴더입니다.
• pages: 각 페이지에 해당하는 컴포넌트를 저장하는 폴더입니다. 라우터와 연결되는 최상위 페이지 컴포넌트를 여기에 포함합니다.
• utils: 유틸리티 함수들을 저장하는 폴더입니다. 다양한 곳에서 사용할 수 있는 함수들을 모아둡니다. 예를 들어 날짜 포맷팅, 숫자 포맷팅, API 응답 처리 함수와 같은 유틸리티 코드가 여기에 위치할 수 있습니다.
• main.tsx: React 애플리케이션의 진입 파일입니다.
• App.tsx: 기본 컴포넌트 파일로, 최상위 UI가 여기에 포함되어 있습니다.
• vite.config.ts: Vite 설정 파일로, 빌드와 서버 관련 설정을 조정할 수 있습니다.
• tsconfig.json: TypeScript 설정 파일입니다. 타입 시스템과 컴파일러 옵션을 관리합니다.

 

3. 절대 경로 설정

tsconfig.json

{
  // TypeScript 컴파일러가 코드를 컴파일할 때 사용할 옵션들을 설정합니다.
  "compilerOptions": {
    ...options, // 나머지 옵션들
    // 경로 설정이 src 디렉토리를 기준으로 작동
    "baseUrl": "./src",
    // 프로젝트 내에서 별칭(alias)을 설정할 수 있도록 합니다. 
    // 각 별칭은 폴더 구조에 따라 짧은 이름으로 경로를 참조하게 도와줍니다.
    "paths": {
      "@components/*": ["components/*"],
      "@pages/*": ["pages/*"],
      "@api/*": ["api/*"],
      "@utils/*": ["utils/*"],
      "@images/*": ["assets/images/*"],
      "@icons/*": ["assets/icons/*"]
    }
  },
  // 컴파일러가 src 폴더 내의 모든 .ts와 .tsx 파일들만 컴파일하도록 지정합니다.
  "include": ["src/**/*.ts", "src/**/*.tsx"],
}

 

vite.config.ts

import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';
// resolve는 Node.js의 path 모듈에서 가져오는 함수로, 파일 시스템 경로를 쉽게 정의할 수 있게 해줍니다.
import { resolve } from 'path';

// https://vite.dev/config/
export default defineConfig({
  plugins: [react()],
  resolve: {
    alias: [
      { find: '@', replacement: resolve(__dirname, './src') },
      {
        find: '@components',
        replacement: resolve(__dirname, './src/components'),
      },
      { find: '@pages', replacement: resolve(__dirname, './src/pages') },
      { find: '@api', replacement: resolve(__dirname, './src/api') },
      { find: '@utils', replacement: resolve(__dirname, './src/utils') },
      {
        find: '@images',
        replacement: resolve(__dirname, './src/assets/images'),
      },
      {
        find: '@icons',
        replacement: resolve(__dirname, './src/assets/icons'),
      },
    ],
  },
});

 

경로 별칭을 활용하여, 프로젝트 파일을 불러올 때 경로를 짧고 일관되게 작성할 수 있습니다. Vite 환경에서 React 프로젝트를 더 효율적이고 깔끔하게 관리할 수 있도록 도와주는 초기 설정입니다.

 

4. ESLint와 Prettier 설정

코드 스타일과 린팅 규칙을 관리하기 위해 ESLint와 Prettier를 설정합니다. 이를 통해 코드의 일관성을 유지하고 통일된 코드 스타일을 적용할 수 있습니다.

npm install eslint prettier eslint-config-prettier eslint-plugin-prettier eslint-plugin-react @typescript-eslint/parser @typescript-eslint/eslint-plugin -D

 

ESLint 설정 파일 생성 및 설정(.eslintrc.cjs)

module.exports = {
  root: true,
  env: { browser: true, es2020: true },
  extends: ['eslint:recommended', 'plugin:@typescript-eslint/recommended', 'plugin:react-hooks/recommended'],
  // 배포 파일이 포함된 dist 폴더는 검사하지 않도록 설정합니다.
  // .eslintrc.cjs 설정 파일도 검사하지 않도록 무시합니다.
  ignorePatterns: ['dist', '.eslintrc.cjs'],
  // TypeScript 코드를 이해하고, TypeScript에 맞춘 linting을 가능하게 합니다.
  parser: '@typescript-eslint/parser',
  plugins: ['react', 'react-refresh', 'react-hooks', 'jsx-a11y', 'prettier', 'import'],
  rules: {
     // 알 수 없는 props(React에서 지원하지 않는 속성)를 사용할 경우 오류로 표시합니다. 단, css 속성은 허용합니다
    'react/no-unknown-property': ['error', { ignore: ['css'] }],
    // TypeScript에서 사용하지 않는 변수가 있을 경우 오류로 표시합니다.
    'no-unused-vars': 'off',
    '@typescript-eslint/no-unused-vars': 'error',
    // React 17부터 JSX 내에서 import React from 'react' 구문을 필요로 하지 않기 때문에, 이 규칙을 꺼서 불필요한 경고를 방지합니다.'
    react/react-in-jsx-scope': 'off',
    'react-refresh/only-export-components': 'off',
  },
};

 

프로젝트의 루트에 .eslintrc.js 파일을 생성하고 위 내용을 추가합니다. 프로젝트 진행 시 필요한 옵션들을 직접 추가 삭제하면서 작성해 보세요.

 

Prettier 설정 파일 생성(.prettierrc)

{
  "singleQuote": true,
  "semi": true,
  "tabWidth": 2,
  "trailingComma": "all",
  "printWidth": 80,
  "arrowParens": "always"
}

 

프로젝트의 루트에 .prettierrc 파일을 생성하고 위 내용을 추가합니다. 프로젝트 진행 시 본인 설정에 맞게 변경해서 사용해 보세요.

 

5. 프로젝트 실행

모든 설정이 완료되면 프로젝트를 실행하여 설정이 정상적으로 작동하는지 확인해 보세요.

npm run dev

> ts_project@0.0.0 dev
> vite


  VITE v5.4.10  ready in 3200 ms

  ➜  Local:   http://localhost:5173/

 

이 명령어를 실행하면 Vite 개발 서버가 시작되고, 기본 포트(보통 5173번)에서 애플리케이션을 확인할 수 있습니다. 브라우저에 http://localhost:5173을 입력하면 프로젝트가 실행되는 것을 볼 수 있습니다.

 

추천글

[React & TS] 프로젝트 기술 스택 선정