React + TypeScript + Vite

개발 환경

0. Synology NAS (DS925+) 사전 준비사항

• Node.js v22

• 작업 경로: /volume1/demo/react

node -v  # v22.19.0
npm -v   # 10.9.3

---

1. 프로젝트 생성

npm create vite@latest [project-name]

선택 항목

• Select a framework: React

• Select a variant: TypeScript

• Use rolldown-vite (Experimental)?: No

• Install with npm and start now: Yes

권한 주의 사항

• root 권한으로 생성 시

  • 일반 사용자 접근 불가

  • 소유자 및 권한 수정 필요

sudo chown -R sokuree:users project-name
chmod -R 755 project-name
ls -ld project-name

출력 예:

drwxr-xr-x 1 sokuree users 4096 Dec 16 project-name

---

2. 개발 환경 설정

2.1 Synology NAS Reverse Proxy 설정

소스 (클라이언트 → NAS)

항목	값
프로토콜	HTTPS
호스트 이름	react.sokuree.com
포트	443
HSTS	활성화

대상 (NAS → Vite)

항목	값
프로토콜	HTTP
호스트 이름	localhost
포트	5173

---

2.2 vite.config.ts 설정

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

// https://vite.dev/config/
export default defineConfig({
  server: {
    host: true, // 0.0.0.0 바인딩 (프록시/외부 접근 허용)
    port: 5173,
    allowedHosts: [
      'user.domain.com', // 역방향 프록시로 들어오는 Host 명시 허용
    ],
  },
  plugins: [react()],
})

---

3. Vite + TypeScript alias 경로 통합 설정

3.1 vite.config.ts

export default defineConfig({
  // Vite Path Aliases: import 경로를 상대경로 대신 별칭으로 사용하기 위한 설정
  resolve: {
    alias: {
      '@': fileURLToPath(new URL('./src', import.meta.url)),
      '@assets': fileURLToPath(new URL('./src/assets', import.meta.url)),
      '@components': fileURLToPath(new URL('./src/components', import.meta.url)),
      '@pages': fileURLToPath(new URL('./src/pages', import.meta.url)),
      '@recoil': fileURLToPath(new URL('./src/recoil', import.meta.url)),
      '@types': fileURLToPath(new URL('./src/types', import.meta.url)),
      '@apis': fileURLToPath(new URL('./src/apis', import.meta.url)),
    },
  },

  // SCSS 전역 설정
  css: {
    preprocessorOptions: {
      scss: {
        additionalData: '@import "./src/assets/styles/main.scss";'
      },
    },
  },
})

3.2 tsconfig.app.json

{
  "compilerOptions": {

    /* TypeScript 컴파일용 경로 별칭(alias) 설정 */
    "baseUrl": ".",
    "paths": {
      "@/*": ["src/*"],
      "@components/*": ["src/components/*"],
      "@assets/*": ["src/assets/*"],
      "@/components*": ["src/components*"],
      "@/pages/*": ["src/pages/*"],
      "@/types*": ["src/types*"],
      "@/recoil/*": ["src/recoil/*"],
      "@/apis/*": ["src/apis/*"],
    }
  },
  "include": ["src"],
  "references": [{"path": "./tsconfig.node.json"}]
}

4. 라이브러리 (npm Package) 설치

1. HTTP 클라이언트 라이브러리

   npm install axios
   

2. React SPA의 라우팅, 로컬 저장, 검색·정렬을 담당하는 핵심 라이브러리 묶음

   npm install react-router-dom localforage match-sorter sort-by
   

3. Node.js 타입 정의 패키지 (TypeScript 전용)

   npm install @types/node
   

4. React UI 컴포넌트 라이브러리 (Toast 알림)

   npm install react-simple-toasts
   

5. React 중앙집중식 상태 관리 라이브러리 (Recoil)

   npm install recoil
   

6. CSS 스타일링을 위한 SASS/SCSS 전처리기

   npm install -D sass