01. GOFLIX 프로젝트 소개와 개발환경 설정

React + Vite + Tailwind CSS로 영화 웹앱 만들기 - 환경 구축편

코드 블록의 Try it Yourself 버튼으로 직접 실행할 수 있다.

구문

💡TIP

Gemini CLI로 구현하기 — 프로젝트 생성 & 패키지 설치

프롬프트: gemini "React 19 + Vite + Tailwind CSS 4 프로젝트를 생성해줘. 프로젝트 이름은 [프로젝트명]이야. react-router, axios, @fortawesome/react-fontawesome, @fortawesome/free-solid-svg-icons, swiper 패키지도 함께 설치해줘. .env 파일 예시와 vite.config.js도 작성해줘."
- 사용 가이드: 터미널을 열고 프로젝트를 생성할 폴더로 이동한다. [프로젝트명]을 원하는 이름으로 바꾼 뒤 실행한다.

1. GOFLIX 프로젝트 소개

이번 시리즈에서는 GOFLEX라는 넷플릭스 스타일의 영화 웹 애플리케이션(애플리케이션)을 처음부터 끝까지 직접 만든다. 완성하면 이런 기능이 동작한다.

TMDB API에서 실시간 영화 데이터를 가져와 화면에 표시
현재 상영작, 인기작, 최고 평점 영화를 카드 형태로 나열
영화를 클릭하면 상세 정보 + 예고편 보기
카테고리별 목록 + 페이지네이션
AI 챗봇과 대화

완성된 프로젝트의 기술 스택(Tech Stack, 기술 구성)은 다음과 같다.

💡TIP

**컴포넌트(Component)**란? 레고 블록처럼, 화면을 구성하는 작은 조각이다. 버튼 하나, 카드 하나, 헤더 하나가 각각 컴포넌트이다. 이 조각들을 조립하면 전체 페이지가 완성된다.

기술	역할
React 19 (리액트)	UI 컴포넌트 구성
Vite (비트)	빌드 도구, 개발 서버
Tailwind CSS 4 (테일윈드)	유틸리티 기반 스타일링
React Router 7 (리액트 라우터)	페이지 이동(라우팅)
Axios (액시오스)	HTTP 요청
Font Awesome (폰트어썸)	아이콘
Swiper (스와이퍼)	슬라이드/캐러셀

2. Node.js 설치 확인

터미널(Terminal, 명령창)을 열고 아래 명령어를 입력한다. 버전 번호가 출력되면 이미 설치된 상태이다.

node -v
npm -v

💡TIP

Node.js가 설치되어 있지 않다면 https://nodejs.org 에서 LTS 버전을 다운로드하여 설치한다.

3. 프로젝트 생성

npm create vite@latest frontend -- --template react
cd frontend

줄	설명
1	`npm create vite@latest`로 Vite 프로젝트 생성 도구를 실행한다. `frontend`는 폴더 이름이고, `--template react`는 React 템플릿을 사용하겠다는 뜻이다.
2	생성된 `frontend` 폴더 안으로 이동한다.

4. 필요한 패키지 설치

npm install axios react-router tailwindcss @tailwindcss/vite @fortawesome/fontawesome-svg-core @fortawesome/free-solid-svg-icons @fortawesome/react-fontawesome swiper

패키지	역할
`axios`	서버에 HTTP 요청을 보내는 도구
`react-router`	URL에 따라 다른 페이지를 보여주는 라우팅 라이브러리
`tailwindcss`, `@tailwindcss/vite`	CSS를 클래스명(class)으로 빠르게 작성하는 도구
`@fortawesome/*`	아이콘을 React 컴포넌트로 사용하는 도구
`swiper`	터치 슬라이드/캐러셀 라이브러리

5. Vite 설정 파일 작성

import { defineConfig } from "vite";
import react from "@vitejs/plugin-react";
import tailwindcss from "@tailwindcss/vite";

export default defineConfig({
  plugins: [react(), tailwindcss()],
});

줄	설명
1	Vite의 설정 함수 `defineConfig`를 가져온다.
2	React 플러그인을 가져온다. JSX 문법을 사용할 수 있게 해준다.
3	Tailwind CSS 플러그인을 가져온다.
5-7	`plugins` 배열에 React와 Tailwind 플러그인을 등록한다.

6. CSS 초기 설정

src/index.css 파일을 열고 기존 내용을 모두 지운 뒤 아래를 작성한다.

@import url("https://cdn.jsdelivr.net/gh/orioncactus/pretendard@v1.3.9/dist/web/variable/pretendardvariable.min.css");

@import "tailwindcss";

@theme {
  --font-sans: "Pretendard Variable", sans-serif;
}

줄	설명
1	Pretendard(프리텐다드) 한글 웹폰트를 CDN(씨디엔, 콘텐츠 전송 네트워크)에서 불러온다. 한글이 예쁘게 보이려면 폰트가 필요하다.
3	Tailwind CSS의 모든 유틸리티 클래스를 불러온다. 유틸리티 클래스란, `text-white`(흰 글자), `bg-black`(검정 배경)처럼 하나의 역할만 하는 짧은 클래스이다. CSS 파일을 따로 만들지 않고 HTML에 직접 클래스를 붙여서 디자인한다.
5-7	`@theme`으로 Tailwind의 기본 폰트를 Pretendard로 변경한다. 이 설정 하나로 프로젝트 전체의 글꼴이 한꺼번에 바뀐다.

⚠️WARNING

기존에 Vite가 자동 생성한 CSS 코드는 모두 삭제해야 한다. 남겨두면 스타일이 충돌할 수 있다.

7. 폴더 구조 정리

src 폴더 안에 다음과 같은 구조를 만든다.

frontend/
├── public/
│   └── video.mp4            ← 히어로 영상 (선택)
├── src/
│   ├── api/
│   │   └── axios.js         ← API 통신 설정
│   ├── components/
│   │   ├── Card.jsx         ← 영화 카드
│   │   ├── Category.jsx     ← 카테고리별 목록
│   │   ├── ErrorPage.jsx    ← 404 에러 페이지
│   │   ├── Footer.jsx       ← 하단 푸터
│   │   ├── Header.jsx       ← 상단 헤더 + 검색
│   │   ├── Home.jsx         ← 메인 페이지
│   │   ├── MovieDetail.jsx  ← 영화 상세
│   │   ├── Section.jsx      ← 영화 목록 섹션
│   │   └── UI.jsx           ← 공통 UI 컴포넌트
│   ├── App.jsx              ← 레이아웃 + 데이터 로딩
│   ├── index.css            ← Tailwind + 폰트 설정
│   └── main.jsx             ← React 앱 시작점
├── index.html
├── vite.config.js
└── package.json

ℹ️INFO

components와 api 폴더는 직접 만들어야 한다. 터미널에서 mkdir src/components src/api 명령어를 실행하면 된다.

8. 개발 서버 실행

npm run dev

터미널에 http://localhost:5173 같은 주소가 표시되면 성공이다.

💡TIP

개발 서버를 종료하려면 터미널에서 Ctrl + C를 누르면 된다.

9. TMDB API 키 발급

https://www.themoviedb.org 에 회원가입한다.
로그인 후 Settings(설정) → API 메뉴로 이동한다.
API Key(API 키)를 복사한다.

프로젝트 루트에 .env 파일을 만들어 저장한다.

VITE_TMDB_API_KEY=여기에_발급받은_키를_붙여넣기

줄	설명
1	`VITE_` 접두사가 붙어야 Vite가 이 값을 코드에서 사용할 수 있게 해준다.

⚠️WARNING

.env 파일은 비밀 정보이다. .gitignore에 .env를 추가하여 GitHub에 올라가지 않도록 반드시 확인한다.

10. 전체 코드

import { defineConfig } from "vite";
import react from "@vitejs/plugin-react";
import tailwindcss from "@tailwindcss/vite";

export default defineConfig({
  plugins: [react(), tailwindcss()],
});

01. GOFLIX 프로젝트 소개와 개발환경 설정

React + Vite + Tailwind CSS로 영화 웹앱 만들기 - 환경 구축편

코드 블록의 Try it Yourself 버튼으로 직접 실행할 수 있다.

구문

💡TIP

Gemini CLI로 구현하기 — 프로젝트 생성 & 패키지 설치

프롬프트: gemini "React 19 + Vite + Tailwind CSS 4 프로젝트를 생성해줘. 프로젝트 이름은 [프로젝트명]이야. react-router, axios, @fortawesome/react-fontawesome, @fortawesome/free-solid-svg-icons, swiper 패키지도 함께 설치해줘. .env 파일 예시와 vite.config.js도 작성해줘."
- 사용 가이드: 터미널을 열고 프로젝트를 생성할 폴더로 이동한다. [프로젝트명]을 원하는 이름으로 바꾼 뒤 실행한다.

1. GOFLIX 프로젝트 소개

TMDB API에서 실시간 영화 데이터를 가져와 화면에 표시
현재 상영작, 인기작, 최고 평점 영화를 카드 형태로 나열
영화를 클릭하면 상세 정보 + 예고편 보기
카테고리별 목록 + 페이지네이션
AI 챗봇과 대화

완성된 프로젝트의 기술 스택(Tech Stack, 기술 구성)은 다음과 같다.

💡TIP

기술	역할
React 19 (리액트)	UI 컴포넌트 구성
Vite (비트)	빌드 도구, 개발 서버
Tailwind CSS 4 (테일윈드)	유틸리티 기반 스타일링
React Router 7 (리액트 라우터)	페이지 이동(라우팅)
Axios (액시오스)	HTTP 요청
Font Awesome (폰트어썸)	아이콘
Swiper (스와이퍼)	슬라이드/캐러셀

2. Node.js 설치 확인

터미널(Terminal, 명령창)을 열고 아래 명령어를 입력한다. 버전 번호가 출력되면 이미 설치된 상태이다.

node -v
npm -v

💡TIP

Node.js가 설치되어 있지 않다면 https://nodejs.org 에서 LTS 버전을 다운로드하여 설치한다.

3. 프로젝트 생성

npm create vite@latest frontend -- --template react
cd frontend

줄	설명
1	`npm create vite@latest`로 Vite 프로젝트 생성 도구를 실행한다. `frontend`는 폴더 이름이고, `--template react`는 React 템플릿을 사용하겠다는 뜻이다.
2	생성된 `frontend` 폴더 안으로 이동한다.

4. 필요한 패키지 설치

npm install axios react-router tailwindcss @tailwindcss/vite @fortawesome/fontawesome-svg-core @fortawesome/free-solid-svg-icons @fortawesome/react-fontawesome swiper

패키지	역할
`axios`	서버에 HTTP 요청을 보내는 도구
`react-router`	URL에 따라 다른 페이지를 보여주는 라우팅 라이브러리
`tailwindcss`, `@tailwindcss/vite`	CSS를 클래스명(class)으로 빠르게 작성하는 도구
`@fortawesome/*`	아이콘을 React 컴포넌트로 사용하는 도구
`swiper`	터치 슬라이드/캐러셀 라이브러리

5. Vite 설정 파일 작성

import { defineConfig } from "vite";
import react from "@vitejs/plugin-react";
import tailwindcss from "@tailwindcss/vite";

export default defineConfig({
  plugins: [react(), tailwindcss()],
});

줄	설명
1	Vite의 설정 함수 `defineConfig`를 가져온다.
2	React 플러그인을 가져온다. JSX 문법을 사용할 수 있게 해준다.
3	Tailwind CSS 플러그인을 가져온다.
5-7	`plugins` 배열에 React와 Tailwind 플러그인을 등록한다.

6. CSS 초기 설정

src/index.css 파일을 열고 기존 내용을 모두 지운 뒤 아래를 작성한다.

@import url("https://cdn.jsdelivr.net/gh/orioncactus/pretendard@v1.3.9/dist/web/variable/pretendardvariable.min.css");

@import "tailwindcss";

@theme {
  --font-sans: "Pretendard Variable", sans-serif;
}

줄	설명
1	Pretendard(프리텐다드) 한글 웹폰트를 CDN(씨디엔, 콘텐츠 전송 네트워크)에서 불러온다. 한글이 예쁘게 보이려면 폰트가 필요하다.
3	Tailwind CSS의 모든 유틸리티 클래스를 불러온다. 유틸리티 클래스란, `text-white`(흰 글자), `bg-black`(검정 배경)처럼 하나의 역할만 하는 짧은 클래스이다. CSS 파일을 따로 만들지 않고 HTML에 직접 클래스를 붙여서 디자인한다.
5-7	`@theme`으로 Tailwind의 기본 폰트를 Pretendard로 변경한다. 이 설정 하나로 프로젝트 전체의 글꼴이 한꺼번에 바뀐다.

⚠️WARNING

기존에 Vite가 자동 생성한 CSS 코드는 모두 삭제해야 한다. 남겨두면 스타일이 충돌할 수 있다.

7. 폴더 구조 정리

src 폴더 안에 다음과 같은 구조를 만든다.

frontend/
├── public/
│   └── video.mp4            ← 히어로 영상 (선택)
├── src/
│   ├── api/
│   │   └── axios.js         ← API 통신 설정
│   ├── components/
│   │   ├── Card.jsx         ← 영화 카드
│   │   ├── Category.jsx     ← 카테고리별 목록
│   │   ├── ErrorPage.jsx    ← 404 에러 페이지
│   │   ├── Footer.jsx       ← 하단 푸터
│   │   ├── Header.jsx       ← 상단 헤더 + 검색
│   │   ├── Home.jsx         ← 메인 페이지
│   │   ├── MovieDetail.jsx  ← 영화 상세
│   │   ├── Section.jsx      ← 영화 목록 섹션
│   │   └── UI.jsx           ← 공통 UI 컴포넌트
│   ├── App.jsx              ← 레이아웃 + 데이터 로딩
│   ├── index.css            ← Tailwind + 폰트 설정
│   └── main.jsx             ← React 앱 시작점
├── index.html
├── vite.config.js
└── package.json

ℹ️INFO

components와 api 폴더는 직접 만들어야 한다. 터미널에서 mkdir src/components src/api 명령어를 실행하면 된다.

8. 개발 서버 실행

npm run dev

터미널에 http://localhost:5173 같은 주소가 표시되면 성공이다.

💡TIP

개발 서버를 종료하려면 터미널에서 Ctrl + C를 누르면 된다.

9. TMDB API 키 발급

https://www.themoviedb.org 에 회원가입한다.
로그인 후 Settings(설정) → API 메뉴로 이동한다.
API Key(API 키)를 복사한다.

프로젝트 루트에 .env 파일을 만들어 저장한다.

VITE_TMDB_API_KEY=여기에_발급받은_키를_붙여넣기

줄	설명
1	`VITE_` 접두사가 붙어야 Vite가 이 값을 코드에서 사용할 수 있게 해준다.

⚠️WARNING

.env 파일은 비밀 정보이다. .gitignore에 .env를 추가하여 GitHub에 올라가지 않도록 반드시 확인한다.

10. 전체 코드

import { defineConfig } from "vite";
import react from "@vitejs/plugin-react";
import tailwindcss from "@tailwindcss/vite";

export default defineConfig({
  plugins: [react(), tailwindcss()],
});

01. GOFLIX 프로젝트 소개와 개발환경 설정

구문

1. GOFLIX 프로젝트 소개

관련링크

2. Node.js 설치 확인

3. 프로젝트 생성

4. 필요한 패키지 설치

5. Vite 설정 파일 작성

6. CSS 초기 설정

7. 폴더 구조 정리

8. 개발 서버 실행

9. TMDB API 키 발급

10. 전체 코드

01. GOFLIX 프로젝트 소개와 개발환경 설정

구문

1. GOFLIX 프로젝트 소개

관련링크

2. Node.js 설치 확인

3. 프로젝트 생성

4. 필요한 패키지 설치

5. Vite 설정 파일 작성

6. CSS 초기 설정

7. 폴더 구조 정리

8. 개발 서버 실행

9. TMDB API 키 발급

10. 전체 코드