v0 결과물을 Cursor 프로젝트로 이식

학습 목표

skeleton 프로젝트의 구조와 각 파일의 역할을 설명할 수 있다.
v0 결과물을 skeleton 프로젝트에 이식하는 과정을 수행할 수 있다.
package.json 핵심 스크립트의 의미를 이해한다.
wrangler.jsonc가 Cloudflare 배포에서 하는 역할을 설명할 수 있다.

skeleton 프로젝트란?

skeleton 프로젝트는 미리 준비된 뼈대이다. 집을 지을 때 철근 뼈대를 먼저 세우듯이, 웹사이트를 만들 때도 기본 구조가 갖춰진 프로젝트에서 시작하면 훨씬 효율적이다.

우리가 사용하는 skeleton은 Next.js 15 + Cloudflare Workers 배포용 프로젝트이다.

프로젝트 구조

skeleton/
├── src/
│   └── app/
│       ├── page.tsx        # 메인 페이지 (사용자가 처음 보는 화면)
│       ├── layout.tsx      # 레이아웃 (모든 페이지 공통 틀)
│       ├── globals.css     # 전역 스타일 (사이트 전체 디자인)
│       └── favicon.ico     # 파비콘 (브라우저 탭 아이콘)
├── public/                 # 정적 파일 (이미지, 폰트 등)
├── package.json            # 의존성 목록 (Next.js 15, React 19, Tailwind 4)
├── wrangler.jsonc          # Cloudflare Workers 설정
├── open-next.config.ts     # OpenNext 설정 (Cloudflare 배포 연동)
├── next.config.ts          # Next.js 설정
├── tsconfig.json           # TypeScript 설정
└── .dev.vars               # 로컬 개발 환경변수

핵심 파일 설명

src/app/page.tsx - 메인 페이지

사용자가 사이트에 접속했을 때 가장 처음 보게 되는 화면이다. v0에서 만든 디자인이 이 파일에 들어간다.

src/app/layout.tsx - 레이아웃

모든 페이지에 공통으로 적용되는 틀이다. HTML의 <head> 태그, 폰트 설정, 메타 정보 등이 여기에 포함된다.

src/app/globals.css - 전역 스타일

Tailwind CSS 설정과 사이트 전체에 적용되는 디자인이 정의되어 있다.

wrangler.jsonc - Cloudflare Workers 설정

Cloudflare에 배포할 때 필요한 설정 파일이다.

설정 항목	의미
compatibility_date	Cloudflare Workers 호환 날짜
nodejs_compat	Node.js 호환성 플래그
assets	정적 파일 바인딩 설정

.dev.vars - 로컬 환경변수

로컬 개발 환경에서 사용하는 환경변수 파일이다. API KEY 같은 민감 정보를 여기에 저장하며, 절대 Github에 올리지 않는다.

package.json 핵심 스크립트

package.json에는 프로젝트 실행에 필요한 **스크립트(명령어)**가 정의되어 있다.

스크립트	명령어	역할	언제 사용?
dev	`npm run dev`	로컬 개발 서버 실행	코드 수정하면서 실시간 확인
build	`npm run build`	Next.js 프로덕션 빌드	배포 전 빌드 검증
preview	`npm run preview`	Cloudflare 환경에서 미리보기	배포 전 최종 확인
deploy	`npm run deploy`	Cloudflare에 직접 배포	수동 배포가 필요할 때

참고: 보통 npm run dev로 개발하고, npm run build로 빌드가 성공하는지 확인한 뒤, Github에 push하면 Cloudflare가 자동으로 배포한다. npm run deploy는 수동 배포가 필요한 특수한 경우에만 사용한다.

이식 과정

v0에서 다운로드한 ZIP 파일을 skeleton 프로젝트에 이식하는 전체 과정이다.

단계별 상세 설명

1단계: ZIP 다운로드 및 압축 해제

v0에서 Download ZIP 버튼을 클릭하면, 프로젝트 코드가 압축 파일로 다운로드된다. 이 파일의 압축을 풀면 v0가 생성한 코드 파일들이 나온다.

2단계: skeleton 폴더에 파일 이동

skeleton 프로젝트 폴더에 v0의 파일들을 복사한다. 이때 기존 skeleton 파일과 v0 파일이 겹치는 부분이 있을 수 있는데, 이것은 다음 단계에서 Cursor AI가 처리해준다.

3단계: Cursor에서 프로젝트 열기

Cursor를 실행하고 File → Open Folder(또는 Open Project)로 skeleton 프로젝트 폴더를 연다.

4단계: Cursor AI에게 이식 요청

Cursor의 채팅창에 다음과 같이 요청한다.

v0에서 다운로드한 디자인 코드를 기존 skeleton 프로젝트에 이식해줘.
- page.tsx에 v0의 메인 디자인을 적용
- globals.css에 필요한 스타일 추가
- 필요한 컴포넌트 파일 생성
- Tailwind CSS 클래스 유지

5단계: 확인

bash

npm install    # 의존성 설치
npm run dev    # 로컬 서버 실행

브라우저에서 http://localhost:3000에 접속하여 v0의 디자인이 정상적으로 표시되는지 확인한다.

주의사항

항목	설명
의존성 충돌	v0의 package.json과 skeleton의 package.json이 충돌할 수 있다. Cursor AI에게 해결 요청
파일 경로	v0와 skeleton의 폴더 구조가 다를 수 있다. AI가 자동으로 맞춰줌
Tailwind 버전	skeleton은 Tailwind 4를 사용한다. v0가 다른 버전을 사용한 경우 AI에게 변환 요청
.dev.vars	환경변수 파일은 v0에 없으므로, 나중에 API 연동 시 직접 작성해야 함

핵심 정리

순서	할 일	결과
1	v0 ZIP 다운로드 & 압축 해제	코드 파일 확보
2	skeleton 폴더에 파일 배치	프로젝트 구조 완성
3	Cursor에서 열고 AI에게 이식 요청	코드 통합 완료
4	npm install → npm run dev	로컬에서 정상 동작 확인

다음 단계: 화면이 완성되었다면, 이제 사이트에 실제 데이터를 보여주기 위한 OPEN API를 선정하고 연동하는 단계로 넘어간다.

v0 결과물을 Cursor 프로젝트로 이식 ​

학습 목표 ​

skeleton 프로젝트란? ​

프로젝트 구조 ​

핵심 파일 설명 ​

src/app/page.tsx - 메인 페이지 ​

src/app/layout.tsx - 레이아웃 ​

src/app/globals.css - 전역 스타일 ​

wrangler.jsonc - Cloudflare Workers 설정 ​

.dev.vars - 로컬 환경변수 ​

package.json 핵심 스크립트 ​

이식 과정 ​

단계별 상세 설명 ​

1단계: ZIP 다운로드 및 압축 해제 ​

2단계: skeleton 폴더에 파일 이동 ​

3단계: Cursor에서 프로젝트 열기 ​

4단계: Cursor AI에게 이식 요청 ​

5단계: 확인 ​

주의사항 ​

핵심 정리 ​