[React 실전] Cursor AI로 포트폴리오 홈페이지 만들기 — 설치부터 배포까지

안녕하세요!

오늘은 지난 글에서 React 개념을 정리했으니, 

이번엔 실제로 React로 포트폴리오 홈페이지를 만든 과정을 정리 했어요.

Cursor AI를 쓰면서 막혔던 것들, 삽질했던 것들, 해결한 방법까지 실제 경험 기준으로 적어볼게요.

 "나도 해보고 싶은데 어디서 시작하지?" 하는 분들한테 도움이 됐으면 해요.

[React 실전] Cursor AI로 포트폴리오 홈페이지 만들기
설치부터 배포까지 직접 해봤습니다

1. 시작 전에 — Vite로 React 설치하기

Cursor를 열고 작업할 폴더를 먼저 열어두세요.

그 다음 Cursor AI에 이렇게 요청합니다.

현재 폴더에, vite를 사용하여, 리액트를 설치해줘.

★★  "현재 폴더에"라고 꼭 써줘야 해요! 

폴더를 지정하지 않으면 AI가 작업 폴더 안에 또 새 폴더를 만들고 그 안에 설치해버려요. 나중에 경로 꼬이면 골치아파지니까 처음부터 명확하게 적어주는 게 좋아요.

설치가 완료되면 AI가 실행 명령어를 알려줘요. 

터미널에 직접 입력합니다.

npm run dev

실행하면 Cursor 안에서 미리보기로 볼 수도 있고, 브라우저가 직접 열리기도 해요. 

설정에 따라 다르게 동작합니다.

내용만 출력되고 아무것도 안일어나면 

터미널에 뜨는 로컬 주소를 Ctrl + 클릭 하면 브라우저에서 바로 열려요.

화면에 "count is 0" 버튼이 보이고, 클릭했을 때 숫자가 올라가면 정상 작동하는 거예요. 👌

⚠️ 여기까지는 내 컴퓨터 안에서만 확인되는 상태예요. 

다른 사람들한테도 보이게 하려면 나중에 빌드(Build) 라는 작업을 해야 해요.

npm run build

빌드하면 소스 파일이 생성되고, 이걸 서버에 올리면 배포가 됩니다. 

이건 뒤에서 다시 나와요!

 

2. 막막할 땐 — 나랑 친한 AI한테 먼저 물어보기

설치는 됐는데... 홈페이지를 어떻게 구성해야 할지 막막하잖아요.

이럴 때 저는 Cursor AI 말고, 평소에 자주 대화하던 AI한테 먼저 물어봤어요.

나는 커서AI를 사용해서 Vite를 통해 리액트를 설치했어.
이 기술로 한 페이지짜리 개인 포트폴리오 홈페이지를 만들고 싶은데
어떻게 홈페이지를 구성해야 할지 모르겠네?
대중적으로 자주 이용되는 홈페이지 구성을 추천해줘.

그랬더니 추천 구성부터 각 섹션에 들어갈 항목들, 실제 코딩 구조, 폴더 설정 방법, 기술 조합까지 다 알려줬어요.

※이때 추천받은내용을 토대로 샘플이미지를 보여달라고 하세요. 

자동으로 보여주는 경우도 있지만.
샘플 이미지를 보며 디자인을 좀 더 수정해서 내용을 정리하시면 

추후 작업하실때 조금 더 수월합니다.

아니면 원하는 디자인의 사이트주소 또는 이미지를 주고 비슷하게 구성해달라 요청.

자주 대화하던 AI다 보니 저를 어느 정도 알아서 저한테 어울리는 디자인 스타일까지 추천해주더라고요. 그 부분이 특히 좋았어요.

💡 왜 Cursor AI 말고 다른 AI한테 먼저 물어봤냐면요  

Cursor AI랑 이런 긴 기획 대화를 하다 보면 무료 사용자 기준으로 진행 중에 짤릴 가능성이 있어요. 그리고 Cursor AI는 저에 대한 정보가 없는 상태라 제 스타일을 반영해주기가 어렵거든요. 그래서 기획은 나를 잘 아는 AI랑 하고, 실제 코딩은 Cursor AI한테 맡기는 방식이 더 효율적인거 같아요.

 

3. PRD 문서 만들기 — AI한테 코딩 시키기 전에 설계도부터

구성이 잡히면 바로 코딩 요청하지 않고, PRD 문서를 먼저 만들어요.

PRD는 내가 만들려는 것을 구체화해서 정리해둔 설계 문서예요. 

이걸 Cursor AI한테 주고 코딩을 시키는 거예요.

AI한테 이렇게 요청합니다

지금 추천해준 섹션 구조와 리액트 프로젝트 구조를
PRD.md 파일로 작성해줘.
커서AI에게 주고 코딩을 시킬 예정이야.

PRD 파일을 받으면 두 가지 방법으로 저장할 수 있어요

• 방법 1 — 작성된 내용을 복사해서 작업 폴더에 빈 파일 만들고 붙여넣기 → PRD.md로 저장
• 방법 2 — 파일로 만들어주면 다운로드 받아서 작업 폴더에 옮겨놓기

4. Git 연결하기 — 작업 전에 꼭 해두세요

PRD 파일 작업 폴더에 넣었으면 Git 연결을 먼저 해두는 게 좋아요.

Cursor 왼쪽 패널에서 동그라미 두개 연결된 아이콘 누르면 버튼 2개가 보여요. 

Git 연결 아이콘모양 - 연동 후 작업도중 모습, 중간중간 커밋합시다.

위에 Init 버튼 누르면 Git 연동 리스트로 넘어가요.

연동되면 <프로젝트 설정> 이라고 커밋 메시지 적고 Commit 눌러서 첫 저장!

※ Git을 미리 연결해두는 이유

나중에 AI가 작업하다 뭔가 꼬여도 이전 상태로 되돌릴 수 있어요. 

안전망이라고 생각하면 됩니다.

 

5. Cursor AI에 PRD 넘기고 프로젝트 구조 잡기

Cursor AI 새 창을 열어요. 

 +  버튼 누르면 새 창이 생겨요.

PRD.md 파일을 클릭해서 창을 열어놓은 상태에서 새 대화를 시작하면 AI가 그 파일을 참조해요. 

파일이 자동으로 안 잡히면 왼쪽 파일 목록에서 파일명을 클릭하고 AI 대화창으로 끌어다 놓으면 됩니다.

그리고 이렇게 요청해요

PRD 문서를 참고해서, 프로젝트 구조만 먼저 생성해줘.
프로젝트 구조 속의 컴포넌트는 지금 작성하면 안돼!

 

💡 왜 구조만 먼저 잡냐면요  

한 번에 다 만들어달라고 하면 AI가 멋대로 내용까지 다 채워버려요. 

골격부터 잡고, 내용은 내가 원하는 방향으로 단계별로 채우는 게 훨씬 깔끔합니다.

그 다음 TailwindCSS 추가 설치도 요청하고, 로컬 주소에서 새로고침해서 확인해요.

골격만 만들었으니 화면이 하얀 빈 화면이에요. 

구별이 안 되니까 AI한테 재요청했더니 샘플 느낌으로 표시를 만들어줬어요.

6. 섹션 내용 수정하기 — 내가 원하는 내용으로 바꾸기

PRD 파일 안에 AI가 정해준 섹션 내용들이 있는데, 이걸 내가 원하는 내용으로 수정할 필요가 있어요.

수정하고 싶은 구간을 마우스로 드래그 하면 두 가지 방법을 쓸 수 있어요.

• Ctrl + I 누르면 AI 대화창에 해당 구간이 인식돼요
• 드래그하면 마우스 옆에 팝업바가 뜨는데 Add to Chat 누르면 채팅창으로 옮겨져요

수정 방향이 잡히면 우선 이렇게 요청해봤어요.

임의로 내용을 채워줘, 실존하는 사람의 정보처럼

근데 AI가 텍스트 파일만 수정하는 게 아니라 필요한 파일까지 설치하면서 홈페이지를 통째로 만들어버렸어요 😅

이럴 땐...

1. 채팅창 안에 Stop 버튼 (정지 버튼) 눌러서 멈추기
2. 상단 내가 요청했던 멘트 아래 되돌리기 버튼 눌러서 이전으로 돌리기
• 설치된 파일은 어쩔 수 없지만, 작성된 내용은 삭제돼요

그리고 다시 요청

샘플 홈페이지라 파일만 수정하고 싶어.
실제 존재하는 사람 같은 느낌이 들도록 파일만 우선 수정해줘.

이렇게 명확하게 "파일만" 이라고 써줘야 AI가 범위를 넘어서지 않아요.

임의로 정보가 채워지면 그 후 내가 진짜로 작성할 내용들로 수정하는 작업을 하시면 됩니다.

직접 파일에서 수정을 해도 되고, 

잘 모르겠으면 해당부분을 복+붙 또는 이런내용을 추가하거나 수정하고 싶은데

해당위치를 알려달라 또는 해줘! 하면 되요. 

참고로 저는 해줘! 했을때 자꾸 딴짓을 해서.. 

위치 알려달라해서 직접 수정하는 편입니다.

다만..... 직접하다 스스로 오류를 생산(ㅋ;) 하는 경우가 많아서 

결국 부분코드 복사 -> 정리해줘 로 진행되는 경우도 많아요 😅

7. 전체 디자인 적용하기

내용 수정이 됐으면 이제 디자인을 입혀달라고 요청해요.

PRD 문서를 기준으로 전체 섹션 배치와 디자인을 진행해줘.
비즈니스에 적합한 포트폴리오 구성이면 좋겠다.

실행해봤을 때 화면이 정상 출력되면 오케이! 

근데 오류 메시지가 나오면 그 메시지를 복사해서 그대로 AI한테 붙여넣고 수정 요청하면 돼요.

정상 출력됬지만 세세한 부분이 맘에안든다 하면 

해당부분 캡쳐 또는 자연어로 풀어서 또는 비슷한 디자인이미지를 첨부해 

적용할 방법을 안내 또는 해줘! 로 바로 적용 할수 있습니다.

8. TailwindCSS 오류 — CSS 라이브러리 갈아타기

저는 TailwindCSS 설치 초반에 오류가 많이 났어요.

(오류문제로 계속 AI와 대화하며 해결시도, 오류메세지 출력본 복+붙 -> 이거왜이래 반복)

TailwindCSS는 설치 초반에 오류가 꽤 많이 나는 편이라고 합니다. 

잘못 세팅된 경우 오류가 계속 안 잡히는 경우가 많거든요.

그럴 때 대체할 수 있는 CSS 라이브러리들이 있어요.

라이브러리	특징
Bulma	단순하지만 가볍고 오류가 적음, 대체제로 무난
Bootstrap	무겁지만 오래되어 안정적

저는 Bulma로 갈아타기로 했어요.

CSS 라이브러리를 바꿀 때는 실제 파일 먼저 수정하면 안 되고, PRD 문서부터 수정해야 해요. 

설계도가 먼저 바뀌어야 실제 파일이 그걸 기준으로 바뀌거든요.

기존의 TailwindCSS를 사용하지 않고
Bulma를 사용하려고 하는데
우선 PRD.md 파일만 수정해줘.

PRD 수정 확인 후 Git에 커밋 해두고.

Bulma를 사용해서 기존에 만들어져 있던 모든 컴포넌트를 수정해줘.

실제 파일 수정 요청!

수정이 완료되면 Git에 커밋하고, TailwindCSS 관련 파일 삭제도 요청했어요.

★수정 요청할 때 팁 

AI가 수정할 때 어느 파일의 어느 부분이 수정되는지 실시간으로 출력해줘요. 

(작은글씨로 머라 머라 작업명 적혀있는데 그거 클릭하면 되요)

그걸 같이 보면서 "이게 맞나?" 확인하고, 이상하면 멈추고 재수정 요청하면 됩니다. 

그 과정 자체가 공부가 되더라고요.

 

9. 이미지 넣기

샘플용 이미지를 다운로드 받아두고 AI한테 물어봐요.

내가 샘플 이미지를 <파일명.확장자>로 다운받았는데
어느 위치에 이미지를 배치하면 될까?

알려주는 위치에 이미지를 저장해두고.

이 파일을 샘플로 사용해서 전체 이미지 교체해줘.

샘플로 이미지 위치 및 사이즈 등을 확인한 후에 실제 사용할 이미지로 대체작업

또는 위치 수정, 사이즈 수정 등 진행하면 됩니다.

10. 배포하기 — 드디어 세상에 공개!

여기까지 다 됐으면 이제 배포할 차례예요.

처음에는 GitHub에 Push + 릴리즈 방식으로 시도했는데 오류가 났었어요.

그래도 GitHub에 코드가 올라가 있는 건 확인됐고, 결국 Vercel 연동으로 배포에 성공했어요! 🎉

Vercel은 GitHub 저장소를 연결하면 자동으로 빌드하고 배포해주는 서비스예요. 

설정이 생각보다 간단하고, 무료로 쓸 수 있어서 개인 프로젝트 배포할 때 정말 편해요.

배포 흐름을 정리하면

npm run build  →  GitHub Push  →  Vercel 연동  →  배포 완료!

전체 흐름 한눈에 정리

오늘 진행한 순서를 한 번에 정리해볼게요

1. Vite로 React 설치 — 현재 폴더에 라고 꼭 명시
2. 기획은 나를 잘 아는 AI랑 — Cursor가 아닌 평소 쓰던 AI랑 구성 잡기
3. PRD 문서 작성 — 설계도 먼저, 코딩은 나중
4. Git 연결 — 안전망 먼저 깔아두기
5. 구조 먼저, 내용은 나중 — 한 번에 다 시키면 AI가 멋대로 만들어버림
6. Stop + 되돌리기 — AI가 범위 넘어가면 바로 멈추고 돌리기
7. CSS 오류 나면 갈아타기 — PRD 먼저 수정 → 실제 파일 수정 순서
8. 수정 과정 같이 보기 — 뭐가 바뀌는지 보면서 공부도 됨
9. Vercel로 배포 — GitHub 연동하면 자동 빌드

해보고 나서 느낀 점

처음엔 React 설치부터 배포까지 뭔가 엄청 복잡할 것 같았는데, 

막상 해보니까 "AI한테 어떻게 말하냐"가 제일 중요하더라고요.

너무 포괄적으로 요청하면 AI가 내 의도랑 다른 방향으로 쭉 진행해버리고, 

명확하게 단계별로 시키니까 훨씬 깔끔하게 돼더라고요.

그리고 오류 나도 무서워할 필요 없어요. 

오류 메시지 복사해서 AI한테 주면 대부분 해결됩니다. 

저도 TailwindCSS 오류 때문에 한참 헤맸는데, 

결국 Bulma로 갈아타면서 1차 해결로 작업마무리하고,

이후에 각잡고 대화하며 완전 해결해서 지금은 TailwindCSS를 사용합니다.

직접 해보면서 막히고 해결하는 게 제일 빠른 공부같습니다. 열공하세요! 🙌