React + Vite + PWA 프로젝트 셋팅 가이드

이 글에서는 React, Vite, PWA(Progressive Web App)를 결합하여 빠르고 설치 가능한 웹 애플리케이션을 설정하는 과정을 다룹니다.

---

1. 프로젝트 초기화

1.1 프로젝트 생성 명령어

Vite PWA 플러그인을 포함한 프로젝트를 생성하기 위해 다음 명령어를 실행합니다:

npm create @vite-pwa/pwa@latest

명령어 실행 후 제공되는 옵션에서 원하는 설정을 선택합니다. 여기서는 React와 TypeScript를 사용하는 프로젝트를 기준으로 설명합니다.

1.2 옵션 선택 과정

• Framework: React
• Use TypeScript?: Yes
• Use SW (Service Worker)?: Yes
• Strategies: generateSW (자동 생성)
• Router Mode: History
• Use Framework Router?: Yes (React Router 사용)
• Use Icons?: Yes (PWA 아이콘 자동 생성)
• Theme Color: 원하는 색상 입력 (예: #ffffff)

저는 Icons를 아래 사이트를 이용해 따로 만들었습니다.
📌 https://favicomatic.com/

1.3 생성된 디렉토리 구조

프로젝트 생성 후 주요 파일과 디렉토리는 다음과 같습니다:

icons폴더 내에 제가 사용할 아이콘 이미지 파일들을 넣어두었습니다.

---

2. PWA 설정 및 주요 파일 설명

2.1 manifest.json

PWA의 설정 파일로, 앱 이름, 아이콘, 테마 색상 등을 정의합니다. 기본적으로 public/manifest.json에 위치하며, 다음과 같은 내용이 포함됩니다:

{
  "name": "My PWA App",
  "short_name": "PWA App",
  "theme_color": "#ffffff",
  "background_color": "#000000",
  "display": "standalone",
  "icons": [
    {
      "src": "/icon-192x192.png",
      "sizes": "192x192",
      "type": "image/png"
    },
    {
      "src": "/icon-512x512.png",
      "sizes": "512x512",
      "type": "image/png"
    }
  ]
}

2.2 vite.config.ts

Vite 설정 파일에서 PWA 플러그인을 설정합니다. 위 Strategies 옵션에서 generateSW 채택하여 Service Worker를 자동 생성합니다.

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

export default defineConfig({
  plugins: [
    react(),
    VitePWA({
      registerType: 'autoUpdate',
      manifest: {
        name: 'My PWA App',
        short_name: 'PWA App',
        theme_color: '#ffffff',
        icons: [
          {
            src: "icons/apple-touch-icon-60x60.png", // 사용할 이미지 경로
            sizes: "60x60",
            type: "image/png",
          },
          {
            src: "icons/apple-touch-icon-152x152.png",
            sizes: "192x192",
            type: "image/png",
          },
        ],
      },
    }),
  ],
});

---

3. React Router 설정

PWA에서 라우팅을 관리하려면 React Router를 설치하고 설정해야 합니다:

3.1 React Router 설치

npm install react-router-dom

3.2 라우팅 설정

src/App.tsx 파일에 라우터를 설정합니다:

import { BrowserRouter as Router, Routes, Route } from 'react-router-dom';
import Home from './components/Home';
import About from './components/About';

function App() {
  return (
    <Router>
      <Routes>
        <Route path="/" element={<Home />} />
        <Route path="/about" element={<About />} />
      </Routes>
    </Router>
  );
}

export default App;

---

4. 빌드 및 PWA 테스트

4.1 개발 서버 실행

개발 서버를 실행해 PWA 기능을 테스트합니다:

npm run dev

• 브라우저에서 http://localhost:3000으로 접속.
• Chrome 개발자 도구 → Application → Service Workers 탭에서 Service Worker 등록 상태를 확인합니다.

4.2 프로덕션 빌드

npm run build
npm run preview

빌드된 앱에서 PWA 설치 가능 여부를 확인합니다. 브라우저 주소창 오른쪽에 "설치" 아이콘이 표시됩니다.

---

추후 버셀로 베포까지 셋팅하는 내용을 추가할 예정입니다.