React 프로젝트 시작하기 w. Vite

# 빠른 설치

아래 구성 내용을 React(Compiler)+TS 템플릿으로 준비했습니다.
보다 쉽게 프로젝트를 시작하세요!

1
2
3
4
5
6
7
8
# 현재 프로젝트(폴더)에 템플릿 복사
npx degit ParkYoungWoong/vite-template--react-ts .

# 패키지 설치
npm i

# 개발 서버 실행
npm run dev

# 스킬 활용

Claude Code, Cursor 등의 AI 코딩 도구에서 Skills 기능을 사용하면, 대화형으로 자동 설치 및 구성할 수 있습니다.
다음 명령으로 스킬을 설치합니다.

1
npx skills add ParkYoungWoong/skills --skill react-vite-scaffold

설치 후 AI 코딩 도구에서 React 프로젝트를 시작하면, 스킬이 자동으로 활성화되어 위 구성(ESLint, Prettier, 경로 별칭 등)을 포함한 프로젝트를 생성합니다.
혹은 다음 클로드 코드 예시와 같이 각 도구에서 스킬을 수동으로 호출할 수도 있습니다.

1
❯ /react-vite-scaffold

# Vite 프로젝트 생성

VS Code로 프로젝트 폴더를 열고 터미널에서 다음 명령을 순서대로 실행합니다.

1
2
3
4
5
6
7
# 현재 경로에 프로젝트 구성
npm create vite@latest .

  Select a framework: React
  Select a variant: TypeScript + React Compiler
  Which linter to use?: ESLint
  Install with npm and start now? Yes

혹은. 터미널에서 프로젝트를 생성할 경로로 이동 후 다음 명령을 순서대로 실행합니다.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
# 현재 경로에 프로젝트 폴더 생성 및 구성
npm create vite@latest <프로젝트_폴더_이름>

  Select a framework: React
  Select a variant: TypeScript + React Compiler
  Which linter to use?: ESLint
  Install with npm and start now? No

# 프로젝트 경로로 이동
cd <프로젝트_폴더_이름>

# 의존성 패키지 설치
npm i

# 현재 경로를 새로운 VS Code 창으로 열기
code .
# 혹은 현재 VS Code 창에서 열기
code . -r
# 혹은 수동으로 프로젝트 열기

# 개발 서버 실행
npm run dev

TypeScript + React Compiler 변형(Variant)으로 생성한 프로젝트는 다음과 같이 @rolldown/plugin-babel 플러그인과 reactCompilerPreset 프리셋으로 React Compiler를 구성합니다.
React Compiler에 대한 자세한 내용은 React Compiler 핵심 정리 글을 참고하세요.

1
2
3
4
5
6
7
8
9
10
11
import { defineConfig } from 'vite'
import react, { reactCompilerPreset } from '@vitejs/plugin-react'
import babel from '@rolldown/plugin-babel'

// https://vite.dev/config/
export default defineConfig({
  plugins: [
    react(),
    babel({ presets: [reactCompilerPreset()] })
  ]
})

# ESLint + Prettier 구성

• ESLint: 코드 품질 확인 및 버그, 안티패턴(Anti-pattern)을 감지
• Prettier - Code formatter: 코드 스타일 및 포맷팅 관리, 일관된 코드 스타일을 적용 가능

# VS Code 확장 프로그램 설치

ESLint와 Prettier를 사용하기 위해 VS Code에서 각 확장 프로그램을 설치합니다.
설치 후에는 VS Code를 재시작하는 것이 좋습니다.

ESLint

Prettier - Code formatter

# 패키지 설치 및 구성

프로젝트를 생성할 때 Which linter to use?에서 ESLint를 선택했다면, ESLint 관련 패키지는 이미 설치되어 있습니다.
따라서 Prettier 관련 패키지만 추가로 설치하면 됩니다.
각 패키지는 모두 런타임에서 필요치 않은 개발용이기 때문에, -D 플래그를 사용해 '개발 의존성 패키지(Dev Dependencies)'로 설치합니다.

1
npm i -D prettier eslint-config-prettier eslint-plugin-prettier

다음과 같이 구성 파일의 extends 옵션에 플러그인을 추가합니다.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
import js from '@eslint/js'
import prettierRecommended from 'eslint-plugin-prettier/recommended'
// ...

export default defineConfig([
  globalIgnores(['dist']),
  {
    files: ['**/*.{ts,tsx}'],
    extends: [
      js.configs.recommended,
      // ...
      prettierRecommended
    ],
    // ...
  }
])

추가로, 프로젝트 루트 경로에 .prettierrc 파일을 생성하고 다음과 같이 내용을 추가합니다.
자세한 규칙은 Prettier / Options 에서 확인할 수 있습니다.

1
2
3
4
5
6
7
8
9
{
  "semi": false,
  "singleQuote": true,
  "singleAttributePerLine": true,
  "bracketSameLine": true,
  "endOfLine": "auto",
  "trailingComma": "none",
  "arrowParens": "avoid"
}

# 자동 포맷팅 설정

VS Code에서 자동 포맷팅을 사용하려면, 다음 옵션을 사용자 설정(settings.json)에 추가합니다.
같은 옵션을 중복 추가하지 않도록, 이미 설정되어 있는지 꼼꼼히 확인하세요.

1
2
3
4
5
{
  "editor.codeActionsOnSave": {
    "source.fixAll.eslint": "explicit"
  }
}

사용자 설정(전역)은, 명령 팔레트에서 settings.json로 검색할 수 있습니다.

사용자 설정 열기(JSON)

현재 프로젝트에서만 사용하는 사용자 설정(지역)을 통해 *.jsx, *.tsx 파일에 대한 자동 포맷팅을 사용할 수도 있습니다.
프로젝트의 루트 경로에 .vscode/settings.json 폴더와 파일을 생성해 다음과 같이 내용을 추가할 수 있습니다.

1
2
3
4
{
  "editor.formatOnSave": true,
  "editor.defaultFormatter": "esbenp.prettier-vscode"
}

# 경로 별칭 구성

경로 별칭(Path Alias)을 사용하면, 프로젝트 내의 파일을 쉽게 참조할 수 있어 편리합니다.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
import { defineConfig } from 'vite'
import react, { reactCompilerPreset } from '@vitejs/plugin-react'
import babel from '@rolldown/plugin-babel'

// https://vite.dev/config/
export default defineConfig({
  plugins: [
    react(),
    babel({ presets: [reactCompilerPreset()] })
  ],
  resolve: {
    alias: [
      { find: '@', replacement: '/src' }
    ]
  }
})

이를 통해 복잡해질 수 있는 상대 경로를 사용하지 않고, 특정 경로 위치를 바로 참조할 수 있습니다.

1
2
// import type { Routes } from '../../../../routes'
import type { Routes } from '@/routes'

타입스크립트에서도 경로 인식이 가능하도록, 다음과 같이 구성 옵션을 추가합니다.
생성한 프로젝트의 tsconfig.json 파일에서 tsconfig.app.json 파일을 참조하는 경우, 해당 옵션을 tsconfig.app.json 파일에 추가합니다.

1
2
3
4
5
6
7
8
{
  "compilerOptions": {
    // ...
    "paths": {
      "@/*": ["./src/*"]
    }
  }
}

TypeScript 6버전부터 baseUrl 옵션은 폐기 예정(Deprecated)으로 사용하면 오류가 발생하므로, paths 옵션만 사용합니다.
TypeScript 5버전 이하를 사용하는 경우에는 baseUrl 옵션이 필요할 수 있습니다.

1
2
3
4
5
6
7
8
9
{
  "compilerOptions": {
    // ...
    "baseUrl": ".",
    "paths": {
      "@/*": ["./src/*"]
    }
  }
}