PRD는 "절대문서"?.. 놉! — 앱 만들며 깨달은 것들

 

지난 글에서 PRD가 뭔지, 어떻게 작성하는지 정리했었다. 

이번엔 그 PRD를 

실제로 "개발자 영어 학습 앱(Developer English)" 프로젝트에 

써먹으면서 겪은 얘기를 해보려고 한다.

사실 이전까지 나는 

기획 내용을 그냥 메모장에 띄어쓰기로 구분해서 정리해놓고 

커서AI한테 보여주는 식이었다. 

그럴 때마다 "아... 이거 좀 짜치는데" 싶었는데, 

딱히 어떻게 해야 제대로 된 건지 몰라서 계속 그렇게 해왔다. 

이번에 처음으로 제대로 된 PRD 파일을 만들어서 프로젝트를 진행해봤는데, 

생각보다 배운 게 많았다.

PRD만 있으면 알아서 다 해줄 줄 알았다

PRD를 다 쓰고 나서 처음 든 생각은 

"이제 이 파일만 던져주면 AI가 알아서 척척 만들어주겠지?"였다. 

완전 착각이었다.

내 PRD를 보면 

4.5 퀴즈 기능처럼 오답 보기 생성 규칙, 예외 처리까지 꼼꼼하게 적어둔 항목이 있는가 하면, 

6.5 오답노트 화면처럼 제목만 달랑 적혀있고 세부 내용이 하나도 없는 항목도 있다. 

이 두 항목을 각각 커서AI한테 "이 부분 구현해줘"라고 요청했을 때 반응이 완전히 달랐다.

퀴즈 기능은 PRD에 적힌 규칙 그대로 술술 진행됐는데, 

오답노트 화면은 

AI가 "화면 구성은 어떻게 할까요? 리스트 형태인가요, 카드 형태인가요?" 같은 질문을 계속 던졌다.

결국 PRD에 적혀있다고 해서 AI가 알아서 빈틈을 채워주는 게 아니라, 

내가 얼마나 구체적으로 적어놨느냐에 따라 AI와의 대화량이 달라진다는 걸 몸으로 느꼈다.

 

PRD는 "절대 문서"가 아니었다

또 하나 크게 깨달은 건, 

PRD는 한 번 쓰고 끝나는 문서가 아니라는 거다.

나는 처음에 "이거 다 썼으니까 이제 이대로만 따라가면 되겠지"라고 생각했는데, 

실제로는 계속 고쳐야 했다.

예를 들어 내 PRD의 12.2 제외할 기능에는 로그인, 서버, 결제 같은 게 처음부터 빠져있었다. 

근데 14. 향후 확장 계획을 보면 Google 로그인을 나중에 붙이겠다는 내용이 있다. 

이게 그냥 처음부터 계획했던 게 아니라, 

프로젝트 진행하면서 "아, 이건 나중에 필요하겠다" 싶은 게 생길 때마다 

PRD를 열어서 그 항목을 추가하거나 수정한 결과였다.

데이터 구조 도 마찬가지였다. 

처음엔 단순하게 생각했다가, 

앱 업데이트할 때 사용자 학습 기록은 유지하면서 

새 단어만 추가하는 마이그레이션 정책이 필요하다는 걸 나중에 깨닫고 

그 부분을 통째로 다시 채워 넣었다.

중요한 항목이 하나 정리되거나(클리어되거나), 

기능 범위가 넓어질 때마다 PRD도 같이 업데이트해줘야 한다. 

이걸 안 하면 PRD랑 실제 코드가 따로 놀기 시작하고, 

AI한테 "PRD 참고해줘"라고 해도 예전 정보만 참고하게 된다.

 

그럼 "중요 항목"이라는 게 정확히 뭘까

이 부분 정리하면서 나 스스로도 헷갈렸던 지점이라 한번 짚어보고 싶다.

PRD에 적힌 모든 문장이 다 똑같이 중요한 건 아니었다.

내 경험상 두 종류로 나뉘었다.

구분	설명	내 PRD 예시
맥락형 항목	방향성과 배경을 설명, 코드로 직접 안 옮겨짐	1.5 기대 효과, 2.1 사용자가 겪는 문제
실행형 항목	실제 로직·구조로 그대로 옮겨가는 항목	4.5 퀴즈 오답 보기 생성 규칙, 5.2 데이터 구조, 6.3 오답 발생 시 흐름

맥락형 항목은 한 번 정리해두면 잘 안 바뀐다. 

근데 실행형 항목은 개발하다가

 "어? 이 부분 이렇게 하면 안 되는데?" 

싶은 순간마다 계속 손이 갔다. 

결국 내가 "중요 항목이 클리어됐다"고 느꼈던 순간들은 

대부분 이 실행형 항목 중 하나를 확정 짓고 PRD에 반영한 순간들이었다.

★ 신기했던 점 ★ 

AI한테 파일만 인지시켜두면 

내가 그 파일을 볼 일은 별로 없다.

이건 진짜 예상 못 했던 부분인데, 

PRD.md 파일을 프로젝트에 넣어두고 

"이 파일 참고해서 진행해줘"라고 한 번 말해두니까, 

그다음부터는 내가 직접 PRD 파일을 다시 열어보는 일이 생각보다 적었다. 

커서AI가 알아서 그 파일을 계속 참고하면서 작업을 이어갔기 때문이다.

만약 PRD 없이 작업했다면 어땠을까 생각해봤다. 아마 작업하는 내내

• "어? 이 기능 어떻게 하기로 했더라?"
• "다음에 뭐 만들기로 했었지?"

이러면서 예전 채팅 기록을 계속 위아래로 스크롤하며 뒤졌을 거다. 

실제로 예전에 띄어쓰기로만 정리해서 작업했을 땐 딱 이런 식이었다. 

꿀 발라놓은 것도 아닌데 채팅창만 계속 쳐다보고 있었던 기억이 난다.

오늘의 정리

• PRD를 만들었다고 AI가 알아서 다 채워주는 건 아니다. 구체적으로 적은 항목일수록 AI와의 왔다갔다가 줄어든다.
• PRD는 한 번 쓰고 끝이 아니라, 프로젝트가 진행되면서 계속 업데이트해야 하는 살아있는 문서다.
• PRD 안의 모든 항목이 똑같이 중요한 건 아니다. 실제 로직으로 옮겨가는 "실행형 항목"이 특히 자주 손이 간다.
• AI한테 PRD 파일 자체를 인지시켜두면, 오히려 내가 그 파일을 계속 들여다볼 필요가 줄어든다.
• PRD 없이 작업했다면 계속 예전 대화를 뒤지고 있었을 텐데, PRD 덕분에 그 시간을 많이 아꼈다.

PRD가 뭐길래? AI 협업할 때 자꾸 만들라는 그 문서

PRD가 뭐길래

바이브 코딩 하면서 커서AI한테 이것저것 물어보다 보면 꼭 한 번은 듣는 말이 있다.

"PRD부터 작성하시는 게 좋을 것 같습니다."

나도 처음엔 그냥 하라니까.. 

"네네" 하고 시키는 대로 했다. 

근데 정작 "PRD가 뭔데요?"라고 물으면 나 스스로도 대답을 못 하겠더라고요?

 

그냥 AI가 하라니까 하고, 

어떻게든 그럴싸한 문서 하나 뽑아내고, 

그걸로 다음 단계로 넘어가고... 

이러면 안 될 것 같아서 오늘은 제대로 정리해보려고 한다.

PRD가 대체 뭔데?

PRD는 Product Requirements Document의 줄임말이다. 

우리말로 하면 "제품 요구사항 정의서" 정도.

말이 어려운데, 

쉽게 비유하면 집 짓기 전에 그리는 설계도라고 생각하면 된다. 

설계도 없이 그냥 벽돌부터 쌓기 시작하면 어떻게 될까? 

방이 몇 개인지, 

화장실은 어디 넣을지, 

창문 크기는 얼마로 할지 

매번 즉흥적으로 정하다가 결국 이상한 집이 완성된다.

PRD도 똑같다.

 "내가 만들 앱(또는 기능)이 뭘 해야 하고, 왜 필요하고, 어떻게 생겨야 하는지"

를 미리 글로 정리해두는 문서다.

근데 나 혼자 코딩할 건데 이게 왜 필요해?

나도 이 부분이 제일 궁금했다. 

팀 프로젝트도 아니고 혼자 바이브 코딩 하는데 

왜 이런 문서까지 만들어야 하나.

이유는 명확했다. 

AI는 내 머릿속을 못 본다.

내가 "회원가입 기능 만들어줘"라고만 던지면,

AI는 그럴싸하게 뭔가를 만들어주긴 한다. 

근데

이메일로 가입할지, 

소셜 로그인도 넣을지, 

닉네임 중복 체크는 어떻게 할지 

같은 세부사항은 AI가 임의로 정해버린다. 

그리고 그 결과물이 내가 원하던 것과 다르면? 

처음부터 다시 설명하고, 

다시 수정 요청하고, 

이 과정이 반복된다.

PRD는 이 왔다갔다 헤매는 과정을 줄여주는 역할을 한다. 

미리 방향을 정해두면 AI가 그 안에서 일관성 있게 작업할 수 있고, 

나도 매번 처음부터 설명 안 해도 된다.

PRD에는 뭘 담아야 할까

내가 실제로 커서AI랑 대화하면서 정리했던 항목들이다.

항목	내용
목적 (Why)	이 앱/기능을 왜 만드는지, 어떤 문제를 해결하는지
타겟 유저	누가 쓸 건지 (예: 개발 초보자, 특정 언어 학습자 등)
핵심 기능	꼭 있어야 하는 기능 리스트
비핵심 기능	나중에 넣어도 되는 것들 (초반엔 욕심 안 부리기)
화면/UX 방향	대략적인 화면 구성, 사용자 흐름
기술 스택	어떤 언어/프레임워크로 만들 건지
성공 기준	뭘 완성하면 "됐다"고 볼 건지

AI한테 PRD 작성 요청할 때 실제로 이렇게 물어봤다

처음엔 그냥 "PRD 작성해줘"라고만 했더니 

너무 뻔하고 형식적인 문서가 나왔다.

 몇 번 시행착오 끝에 이렇게 요청하니까 훨씬 쓸만한 결과가 나오더라.

나는 [개발자 영어 단어 학습 앱]을 만들려고 해.
타겟 유저는 [한국어를 쓰는 개발자 취준생/주니어]이고,
핵심 기능은 [플래시카드 학습, 퀴즈, 오답노트]야.

이 정보를 바탕으로 PRD를 작성해줘.
단, 한 번에 다 만들지 말고
목적 → 타겟 유저 → 핵심 기능 → 화면 구성 순서로
하나씩 나한테 물어보면서 같이 채워나가자.

포인트는 

"한 번에 다 만들지 말고 하나씩 물어보면서 같이 채워나가자"

는 부분이었다.

이렇게 요청하니까 AI가 각 항목마다 나한테 되물어봐서, 

나도 뭘 빠뜨렸는지 자연스럽게 체크하게 되더라.

PRD 다 쓰고 나서는 어떻게 활용해?

PRD를 완성했다고 끝이 아니다. 나는 이렇게 활용하고 있다.

• 커서AI 프로젝트 안에 PRD 파일을 넣어둔다 (예: PRD.md)
• 새로운 기능 요청할 때마다 "PRD.md 참고해서 진행해줘"라고 언급한다
• 진행하다가 PRD랑 다른 방향으로 가고 있으면 AI가 먼저 "PRD랑 다른데 괜찮으신가요?"라고 되물어주기도 한다
• 기능이 추가되거나 방향이 바뀌면 PRD도 같이 업데이트한다 (문서는 한 번 쓰고 끝이 아니라 계속 살아있는 문서)

PRD 있을 때 vs 없을 때, 진짜 다르다

	PRD 없이 시작	PRD 먼저 작성
요청 방식	매번 처음부터 설명	"PRD 참고해서 진행해줘" 한 마디로 끝
AI 결과물	내 생각과 다른 방향으로 자주 튐	정해둔 방향 안에서 일관성 있게 진행
수정 횟수	왔다갔다 반복	상대적으로 적음
나의 이해도	"일단 되긴 되네"	"내가 뭘 만들고 있는지" 명확함

오늘의 정리

• PRD는 개발 시작 전에 "무엇을, 왜, 어떻게 만들지" 정리한 문서다
• 혼자 바이브 코딩 해도 AI와의 소통 비용을 줄여주기 때문에 필요하다
• 목적, 타겟 유저, 핵심 기능, 화면 방향, 성공 기준 정도만 채워도 충분하다
• AI한테 요청할 땐 "한 번에 다 말고 하나씩 물어보면서 같이 채워달라"고 하는 게 훨씬 효과적이다
• 다 쓰고 끝이 아니라 프로젝트 진행하면서 계속 참고하고 업데이트하는 문서다

이제 나도 "PRD가 뭔지도 모르면서 시키니까 하는" 단계는 벗어난 것 같다. 

다음엔 실제로 개발자 영어 앱 프로젝트에서 썼던 PRD를 예시로 들면서, 

어떻게 활용했는지 경험담으로 풀어볼 예정이다.

[웹개발 기초] Django란 무엇인가? — 파이썬으로 백엔드까지 다 되는 프레임워크

안녕하세요!

지금까지 React, Next.js처럼 프론트엔드 쪽 개념을 주로 정리했었는데,

이번엔 반대편, 백엔드 프레임워크인 Django를 한번 다뤄볼게요.

저도 포트폴리오 사이트 만들 때 Django로 작업해본 적이 있는데,

처음엔 "파이썬으로 웹사이트를 만든다고?" 하는 게 잘 안 와닿더라고요.

근데 막상 써보니까 왜 초보자한테 백엔드 입문용으로 많이 추천되는지 알겠더라고요.

이 글에서는 Django가 뭔지, 왜 만들어졌는지, 핵심 구조가 어떻게 되는지까지 정리해볼게요.

 [웹개발 기초] Django란 무엇인가?
파이썬으로 백엔드까지 다 되는 프레임워크

1. Django가 뭔지, 진짜 쉽게 설명하면

Django는 파이썬(Python)으로 만들어진 웹 백엔드 프레임워크예요.

"프레임워크"라는 말이 좀 막연하게 느껴질 수 있는데, 이렇게 생각하면 편해요.

"회원가입, 로그인, 데이터베이스 저장, 관리자 페이지... 웹사이트에 거의 무조건 필요한 기능들을 미리 다 만들어둔 도구 상자"

비유를 하나 들어볼게요.

백엔드를 처음부터 직접 만드는 게 재료 하나하나 사서 집을 짓는 것이라면,

Django는 기초 골조, 배관, 전기 배선까지 이미 다 되어있는 집이에요.

거기에 내가 원하는 방 구조랑 인테리어만 얹으면 되는 거죠.

Django는 "Batteries included(배터리 포함)" 철학으로 유명해요.

필요한 기능 대부분을 프레임워크 자체에 이미 내장해뒀다는 뜻이에요.

2. Django가 왜 만들어졌냐면

Django는 2003년, 

미국의 한 신문사(Lawrence Journal-World)에서 

뉴스 사이트를 빠르게 만들어야 하는 상황에서 탄생했어요.

기자들이 마감 시간에 쫓기듯이, 

개발자들도 빠르게 웹사이트를 찍어내야 하는 상황이었대요.

그러다 보니 자연스럽게 이런 목표를 가지게 됐어요.

첫째, 반복 작업을 줄이자.

회원가입, 로그인, 게시글 CRUD(생성/조회/수정/삭제)... 

웹사이트마다 매번 똑같이 만들어야 하는 기능들이 있잖아요.

이걸 매번 처음부터 짜지 않도록, 미리 다 준비해두자는 거였어요.

둘째, 보안을 기본으로 챙기자.

SQL 인젝션, XSS 같은 흔한 보안 취약점을 

개발자가 일일이 신경 쓰지 않아도, 

프레임워크 차원에서 기본 방어가 되게 만들었어요.

셋째, 관리자 페이지를 자동으로 만들어주자.

이게 Django의 제일 유명한 기능인데, 뒤에서 자세히 설명할게요.

3. 핵심 개념 1 — MTV 패턴

Django를 검색하면 꼭 나오는 용어가 MTV 패턴이에요. 

(MVC 패턴이랑 비슷한데 이름만 달라요)

• Model — 데이터베이스 구조를 정의하는 부분
• Template — 사용자한테 보여지는 화면(HTML)
• View — Model에서 데이터를 가져와서 Template에 넘겨주는 로직

이 세 가지가 역할을 나눠서 맡는 구조예요.

# models.py — 데이터베이스 구조 정의
class Post(models.Model):
    title = models.CharField(max_length=100)
    content = models.TextField()
    created_at = models.DateTimeField(auto_now_add=True)

# views.py — 데이터 가져와서 화면에 전달
def post_list(request):
    posts = Post.objects.all()
    return render(request, 'post_list.html', {'posts': posts})

<!-- post_list.html — 실제로 보여지는 화면 -->
{% for post in posts %}
  <h2>{{ post.title }}</h2>
  <p>{{ post.content }}</p>
{% endfor %}

Model에서 데이터 형태를 정하고, View가 그 데이터를 가져와서, Template이 화면에 뿌려주는 흐름이에요.

이렇게 역할을 나눠두면 나중에 코드가 많아져도 어디를 고쳐야 할지 헷갈리지 않아요.

4. 핵심 개념 2 — ORM (데이터베이스를 파이썬 코드로)

Django에서 제일 편하다고 느껴지는 부분이 **ORM(Object-Relational Mapping)**이에요.

원래 데이터베이스를 다루려면 SQL 문법을 알아야 해요.

SELECT * FROM post WHERE title = '공지사항';

근데 Django는 이걸 파이썬 코드로 그대로 쓸 수 있게 해줘요.

Post.objects.filter(title='공지사항')

SQL을 몰라도 파이썬 문법만으로 데이터베이스를 조회, 추가, 수정, 삭제할 수 있는 거예요.

물론 실무에서 SQL을 아예 안 배워도 되는 건 아니지만, 

입문 단계에서는 이 부분이 진입 장벽을 정말 많이 낮춰줘요.

5. 핵심 개념 3 — 자동 생성되는 관리자 페이지

Django의 시그니처 기능이에요.

models.py에 데이터 구조만 정의해두면, 

관리자 페이지가 자동으로 만들어져요.

# admin.py
from django.contrib import admin
from .models import Post

admin.site.register(Post)

이 코드 몇 줄만 추가하면, /admin 주소로 들어갔을 때

게시글을 추가하고, 수정하고, 삭제할 수 있는 화면이 자동으로 생성돼요.

화면 디자인이나 버튼 하나 직접 만든 적 없는데도요.

보통 다른 프레임워크에서는 이런 관리자 기능을 직접 다 만들어야 하는데, 

Django는 이게 기본으로 딸려있는 거예요.

6. 핵심 개념 4 — URL 라우팅

Django도 라우팅 방식이 있는데, 

Next.js처럼 폴더 구조로 자동 결정되는 게 아니라 

직접 파일에 명시하는 방식이에요.

# urls.py
from django.urls import path
from . import views

urlpatterns = [
    path('', views.post_list, name='home'),
    path('post/<int:id>/', views.post_detail, name='post_detail'),
]




/ 주소로 오면 post_list 함수를, 

/post/1/처럼 숫자가 붙은 주소로 오면 post_detail 함수를 

실행하라고 직접 정의해주는 거예요.

<int:id> 부분이 동적인 값(게시글 번호)을 받는 부분이에요.

7. Django로 뭘 만들 수 있냐면

게시판 / 커뮤니티 사이트

CRUD 기능이 핵심인 서비스에 최적화되어 있어요. 

ORM이랑 관리자 페이지 덕분에 개발 속도가 빨라요.

사내 관리 시스템

직원 정보, 재고 관리처럼 데이터를 조회/수정하는 게 중심인 내부 도구를 만들 때 특히 유리해요. 

관리자 페이지를 그대로 내부 툴로 써버리는 경우도 많아요.

API 서버

Django REST Framework(DRF)라는 확장 도구를 쓰면, 

프론트엔드(React, Next.js 등)와 분리된 API 전용 서버로도 만들 수 있어요.

빠른 프로토타입

아이디어를 빠르게 검증해야 할 때,

 회원가입/로그인/게시판 같은 기본 기능을 며칠 만에 갖춘 서비스를 만들 수 있어요.

실제로 Instagram 초기 버전, Spotify, Pinterest 같은 서비스들도 Django 기반으로 시작했어요.

8. Django 배우기 전에 알아둘 것

① 파이썬 기초는 필수

Django는 파이썬 문법 위에서 동작해요. 

함수, 클래스, 딕셔너리 정도는 익숙해야 코드가 읽혀요.

② SQL을 아예 몰라도 되는 건 아니에요

ORM이 편하긴 하지만,

 데이터베이스가 어떻게 동작하는지 

기본 개념(테이블, 관계) 정도는 알고 시작하는 게 좋아요.

③ 프로젝트 구조에 익숙해지기

Django는 project와 app이라는 두 단위로 구조가 나뉘어요. 

하나의 project 안에 여러 개의 app을 만드는 방식인데, 

처음엔 이 구조가 좀 낯설 수 있어요.

myproject/          ← project (전체 설정)
├── manage.py
├── myapp/          ← app (기능 단위, 예: 게시판, 회원)
│   ├── models.py
│   ├── views.py
│   └── urls.py

④ 바이브코딩으로 만들어보기

Cursor한테 "Django로 간단한 게시판 만들어줘" 요청해서, 

models.py, views.py, urls.py가 어떻게 연결되는지 직접 눈으로 확인해보는 게 제일 빨라요.

9. Next.js vs Django, 뭐가 다를까

같은 "풀스택"이라는 말을 쓰긴 하지만 결이 좀 달라요.

구분	Next.js	Django
언어	JavaScript/TypeScript	Python
정체	React 기반 프론트+백엔드 프레임워크	파이썬 기반 백엔드 프레임워크
화면(UI)	React 컴포넌트로 직접 구성	Template 또는 별도 프론트엔드 연동
데이터베이스	별도 라이브러리 필요 (Prisma 등)	ORM 기본 내장
관리자 페이지	없음 (직접 구현)	자동 생성
적합한 상황	화면 중심 서비스, SEO 중요한 사이트	데이터 중심 서비스, 관리 기능 필요한 서비스

정리하면 이래요.

화면(UI) 완성도가 중요하고 프론트엔드 위주라면 → Next.js 

데이터베이스, 관리자 기능, 백엔드 로직이 중요하다면 → Django

실제로는 React/Next.js로 화면을 만들고, 

Django(또는 DRF)로 API 서버만 따로 두는 조합도 정말 많이 쓰여요.

Django, 겁낼 필요 없어요

MTV 패턴, ORM, 관리자 페이지... 처음엔 낯선 용어들이 많지만, 핵심은 하나예요.

"웹사이트에 거의 항상 필요한 기능들을, 파이썬 코드 몇 줄로 빠르게 갖출 수 있게 해주는 프레임워크"

오늘 정리한 내용만 기억해도 됩니다.

• Django = 파이썬 기반 백엔드 프레임워크, "배터리 포함" 철학
• MTV 패턴 = Model(데이터) - Template(화면) - View(로직) 역할 분리
• ORM = SQL 없이 파이썬 코드로 데이터베이스 다루기
• 관리자 페이지 = models.py 정의만으로 자동 생성
• URL 라우팅 = urls.py에 주소와 실행 함수를 직접 명시
• Django REST Framework를 쓰면 API 전용 서버로도 활용 가능

열공하세요! 🙌

[웹개발 기초] Next.js란 무엇인가? — React만으론 부족했던 것들, 초보자도 이해되게 정리 완

안녕하세요!

지난 글에서 React 개념을 정리하면서 마지막에 잠깐 언급했었죠.

"Next.js가 React 기반으로 만들어진 프레임워크"라고요.

근데 막상 "그래서 Next.js가 정확히 뭔데?" 라는 생각이???

바이브코딩으로 뭔가 만들려고 AI한테 물어보면 요즘은 거의 무조건 "React보다 Next.js 추천드려요" 하고 나오는데,

왜 굳이 React 두고 Next.js를 쓰라는 건지...

이 글에서는 Next.js가 왜 나왔는지, React랑 뭐가 다른지, 핵심 기능이 뭔지까지 한 번에 정리해놨습니다.

 [웹개발 기초] Next.js란 무엇인가?
React만으론 부족했던 것들, 초보자도 이해되게 정리 완

1. Next.js가 뭔지, 진짜 쉽게 설명하면

Next.js는 React를 기반으로 만들어진 풀스택 프레임워크예요.

Vercel이라는 회사가 만들었고, 공식 설명은 "프로덕션급 React 프레임워크"인데,

이걸 더 쉽게 풀면

"React로 화면 만드는 것 + 서버 기능 + 자동 라우팅 + 배포까지 한 번에 되는 도구"

비유를 하나 들어볼게요.

React가 레고 블록 그 자체라면,

Next.js는 그 레고 블록에 설명서, 받침대, 진열장까지 세트로 딸려오는 완제품 키트예요.

레고 블록만 있으면 집을 지을 순 있지만, 

어디에 뭘 세워야 하는지, 

받침대는 어떻게 만드는지 다 직접 정해야 하잖아요.

Next.js는 그 부분을 미리 다 준비해둔 거예요.

React로 컴포넌트를 만드는 방식은 똑같이 가져가면서, 

그 위에 페이지 라우팅, 서버 사이드 렌더링, API 만들기, 이미지 최적화 같은 것들을 기본으로 얹어줍니다.

2. Next.js가 왜 만들어졌냐면 — React만으론 부족했던 것들

React 자체는 정말 훌륭한 도구인데, 실제 서비스를 만들다 보면 아쉬운 부분들이 있었어요.

첫째, 라우팅이 없어요.

React는 화면(컴포넌트)을 만드는 라이브러리일 뿐, "/about 페이지로 이동" 같은 기능은 없어요.

react-router-dom 같은 라이브러리를 따로 설치하고 직접 설정해야 했어요.

둘째, SEO에 약해요.

일반 React 앱은 브라우저에서 JavaScript가 실행돼야 화면이 완성되는 구조예요.

그런데 구글 같은 검색엔진 봇이 페이지를 읽으러 왔을 때, 

JS가 실행되기 전 빈 화면만 보고 지나가는 경우가 있었어요.

블로그나 쇼핑몰처럼 검색 노출이 중요한 서비스에는 치명적인 약점이었죠.

셋째, 초기 로딩이 느려요.

React 앱은 처음 접속하면 JS 파일 전체를 다운받고 실행한 다음에야 화면이 뜨는 방식이 많았어요.

이걸 "화면이 하얗게 떴다가 나중에 채워진다"고 표현하기도 해요.

Next.js는 이 세 가지 문제를 해결하려고 나온 프레임워크예요.

"라우팅도 자동으로, 검색엔진에도 잘 잡히게, 처음부터 빠르게 뜨도록 해줄게"

3. 핵심 개념 1 — 파일 기반 라우팅

Next.js에서 제일 먼저 체감되는 차이가 파일 기반 라우팅이에요.

일반 React는 라우터 설정 파일에 "이 주소는 이 컴포넌트 보여줘" 하고 직접 코드를 짜야 해요.

Next.js는 폴더 구조 자체가 곧 URL 주소예요.

app/
├── page.jsx          → / (메인 페이지)
├── about/
│   └── page.jsx      → /about
└── blog/
    └── [id]/
        └── page.jsx  → /blog/1, /blog/2 ... (동적 라우팅)




about 폴더 안에 page.jsx 파일 하나만 만들면, 그게 곧 /about 페이지가 돼요.

라우터 설정 파일을 따로 만들 필요가 없어요.

대괄호로 감싼 [id] 같은 폴더명은 동적 라우팅이라고 하는데,

블로그 게시물처럼 번호나 값에 따라 페이지가 계속 늘어나는 경우에 씁니다.

/blog/1, /blog/2, /blog/100... 다 같은 파일 하나로 처리돼요.

4. 핵심 개념 2 — 렌더링 방식 (SSR / SSG / CSR)

Next.js 설명에 꼭 나오는 용어들이 있어요. 

SSR, SSG, CSR.

셋 다 "화면을 언제, 어디서 그리느냐"의 차이예요.

CSR (Client Side Rendering) — 일반 React 방식

브라우저가 JS를 다운받고 실행해서 화면을 그려요.

사용자 접속 → 빈 화면 → JS 다운로드 → 화면 완성

SSR (Server Side Rendering)

서버에서 미리 완성된 HTML을 만들어서 보내줘요.

사용자 접속 → 서버에서 HTML 완성해서 전달 → 바로 화면 보임

접속하자마자 완성된 화면이 보이니까 체감 속도가 빠르고, 검색엔진 봇도 완성된 HTML을 바로 읽을 수 있어요.

SSG (Static Site Generation)

아예 배포하는 시점에 미리 HTML을 다 만들어놔요.

블로그 글처럼 자주 안 바뀌는 페이지에 유리해요. 

매 요청마다 새로 만들 필요가 없으니까 제일 빨라요.

// Next.js에서는 이런 방식들을 페이지 단위로 골라서 쓸 수 있어요

export default async function BlogPage() {
  const posts = await getPosts()  // 서버에서 데이터 미리 가져오기
  return (
    <div>
      {posts.map(post => <h2 key={post.id}>{post.title}</h2>)}
    </div>
  )
}

셋 중 뭐가 제일 좋다기보다, 

페이지 성격에 따라 골라 쓸 수 있다는 것 

자체가 Next.js의 강점이에요.

메인 페이지는 SSG로, 

실시간 데이터가 필요한 대시보드는 CSR로, 

이런 식으로 섞어서 쓸 수 있어요.

5. 핵심 개념 3 — API Routes (백엔드 기능 내장)

Next.js가 "풀스택 프레임워크"로 불리는 이유가 여기 있어요.

화면(프론트엔드)만 만드는 게 아니라,

같은 프로젝트 안에서 서버 API도 만들 수 있어요.

app/
└── api/
    └── hello/
        └── route.js   → /api/hello 라는 API 주소 생성

// app/api/hello/route.js
export async function GET() {
  return Response.json({ message: '안녕하세요!' })
}

이 파일 하나만 만들면 /api/hello로 요청했을 때 저 JSON 데이터를 응답해줘요.

프론트엔드 프로젝트 따로, 백엔드 서버 따로 만들 필요 없이,

한 프로젝트 안에서 화면도 만들고 API도 만드는 거예요.

이전에 정리했던 "풀스택 프레임워크" 개념이 여기서 그대로 적용되는 거예요.

6. 핵심 개념 4 — 자동 이미지 최적화

일반 <img> 태그를 쓰면 이미지 원본 크기를 그대로 불러와요.

이미지가 크면 로딩이 느려지겠죠.

Next.js는 next/image라는 컴포넌트를 제공하는데, 이걸 쓰면 자동으로 처리해줘요.

import Image from 'next/image'

function Profile() {
  return (
    <Image
      src="/profile.jpg"
      width={200}
      height={200}
      alt="프로필 사진"
    />
  )
}

이 컴포넌트를 쓰면 화면 크기에 맞는 이미지 사이즈로 

자동 변환, 늦게 로딩(lazy loading), 최신 이미지 포맷 변환까지 알아서 처리해줘요.

내가 따로 이미지 압축하고 사이즈 맞추는 작업을 안 해도 되는 거예요.

7. Next.js로 뭘 만들 수 있냐면

개인 블로그 / 포트폴리오 사이트

SSG 방식으로 만들면 로딩도 빠르고 SEO도 잘 잡혀서, 개인 사이트에 특히 잘 맞아요.

쇼핑몰 / 커머스 사이트

상품 목록은 SSG로, 재고나 가격처럼 자주 바뀌는 정보는 실시간으로 가져오는 방식(SSR)으로 섞어서 만들 수 있어요.

대시보드 / 관리자 페이지

로그인 후에만 보이는 페이지라 SEO가 중요하지 않으니, 일반 React처럼 CSR로 만들어도 무방해요.

스타트업 MVP

프론트/백을 한 프로젝트에서 처리할 수 있어서, 

빠르게 서비스를 만들어봐야 하는 초기 스타트업들이 정말 많이 선택해요.

실제로 Netflix, TikTok, Twitch, Notion 같은 서비스들도 Next.js를 쓰고 있어요.

8. Next.js 배우기 전에 알아둘 것

Next.js가 처음이라면 순서대로 접근하는 게 좋아요.

① React 기초는 필수

Next.js는 React 위에서 동작해요. 

컴포넌트, State, Props 개념이 안 잡혀있으면 Next.js 문서 자체가 어렵게 느껴져요.

지난 글에서 정리한 React 개념을 먼저 익히고 오시는 걸 추천드려요.

② App Router 이해하기

요즘 Next.js는 app 폴더 구조(App Router)를 기본으로 써요.

예전 버전은 pages 폴더 구조(Pages Router)를 썼는데, 

지금 새로 시작한다면 app 폴더 구조로 배우는 게 맞아요.

③ 폴더 = 주소 감각 잡기

파일 기반 라우팅이 익숙해지기 전까지는 헷갈릴 수 있어요.

간단한 프로젝트를 하나 만들어서 폴더를 이것저것 만들어보고 

주소가 어떻게 바뀌는지 직접 확인해보는 게 좋습니다.

④ 바이브코딩으로 만들어보기

개념이 어느 정도 잡히면 Cursor한테 "Next.js로 간단한 블로그 만들어줘" 요청해보세요.

app 폴더 구조가 어떻게 나오는지, route.js가 어디 생기는지 직접 보면서 익히는 게 제일 빠릅니다.

9. React vs Next.js, 뭘 선택해야 할까

구분	React	Next.js
정체	UI 라이브러리	React 기반 풀스택 프레임워크
라우팅	직접 설정 필요	파일 기반 자동 라우팅
SEO	약함	SSR/SSG로 강함
백엔드	별도 서버 필요	API Routes 내장
배포	직접 설정 필요	Vercel 연동 시 원클릭
적합한 상황	로그인 후 대시보드 등 SEO 필요 없는 앱	블로그, 커머스, 대부분의 웹 서비스

정리하면 이래요.

단순한 웹 앱, SEO 신경 안 써도 되면 → React 

웹 서비스 대부분, SEO나 초기 로딩 속도가 중요하면 → Next.js

 

요즘은 웹 서비스 만든다고 하면 거의 기본값으로 Next.js를 선택하는 분위기라고 합니다.

바이브코딩으로 "웹사이트 만들어줘" 하면 AI가 Next.js를 먼저 제안하는 것도 이런 이유 때문이에요.

Next.js, 겁낼 필요 없어요

처음엔 SSR, SSG, App Router... 용어가 쏟아져서 막막할 수 있어요.

근데 핵심은 딱 하나예요.

"React로 화면 만드는 방식은 그대로 두고, 라우팅·서버·배포까지 알아서 처리해주는 프레임워크"

이 감각 하나만 잡으면, 나머지 용어들은 실제로 만들어보면서 자연스럽게 익혀져요.

오늘 정리한 내용만 기억해도 됩니다.

• Next.js = React 기반의 풀스택 프레임워크, Vercel이 만듦
• 파일 기반 라우팅 = 폴더 구조가 곧 URL 주소
• SSR/SSG/CSR = 화면을 언제 어디서 그리는지에 따른 렌더링 방식
• API Routes = 같은 프로젝트 안에서 백엔드 API도 함께 개발
• next/image = 이미지 자동 최적화 컴포넌트
• Vercel과 연동하면 배포도 원클릭으로 간단하게

열공하세요! 🙌

[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를 사용합니다.

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

[웹개발 기초] React란 무엇인가? — 컴포넌트부터 상태관리까지, 초보자도 이해되게 정리해봤습니다

안녕하세요!

오늘은 웹 개발 공부하다 보면 정말 빠르게 마주치는 이름, React에 대해 정리해보려고 합니다.

솔직히 처음엔 "React, React" 하길래 그냥 유명한 거겠지 하고 넘어갔어요. 

근데 막상 바이브코딩으로 뭔가 만들려고 하면 AI가 거의 항상 React를 꺼내들더라고요. 

"이게 뭔지도 모르는데 쓰고 있다"는 느낌, 저도 한동안 있었어요.

이 글에서는 React가 왜 생겼는지, 핵심 개념이 뭔지, 그리고 실제로 어디에 쓰이는지까지 한 번에 정리 해놓으려고 합니다.

[웹개발 기초] React란 무엇인가?
컴포넌트부터 상태관리까지, 초보자도 이해되게 정리해봤습니다

1. React가 뭔지, 진짜 쉽게 설명하면

React는 Facebook(현 Meta)이 만든 JavaScript 기반 UI 라이브러리예요.

공식 설명은 "사용자 인터페이스를 만들기 위한 라이브러리"인데, 

이걸 더 쉽게 풀면

"화면을 조각조각 나눠서 만들고, 데이터가 바뀌면 자동으로 화면도 바꿔주는 도구"

 

비유를 하나 들어볼게요.

레고 블록으로 집을 짓는다고 생각해보세요.

지붕 블록, 벽 블록, 창문 블록을 따로따로 만들어두고, 조립해서 집을 완성하는 방식이에요. 

나중에 창문 색을 바꾸고 싶으면? 창문 블록만 교체하면 됩니다. 

집 전체를 다시 지을 필요 없어요.

React가 딱 이 구조예요. 

화면을 블록(컴포넌트) 단위로 만들고, 그걸 조립해서 페이지를 완성합니다. 

데이터가 바뀌면 그 블록만 자동으로 업데이트돼요.

2. React가 왜 만들어졌냐면

React가 나오기 전, 웹 화면을 바꾸는 방법은 이랬어요.

데이터가 바뀔 때마다 JavaScript가 직접 HTML을 찾아가서 바꾸는 방식이었어요.

// 예전 방식 — 직접 DOM을 찾아서 수정

document.getElementById('username').innerText = '홍길동'

document.getElementById('score').innerText = '100점'

document.getElementById('level').innerText = 'Lv.5'

기능이 단순할 땐 괜찮은데, 

화면이 복잡해지고 바꿔야 할 요소가 많아지면 코드가 엄청나게 뒤엉켜요. 

어디서 뭘 바꿨는지 추적도 힘들고, 버그도 많이 생기고요.

Facebook이 이 문제를 해결하려고 만든 게 React예요.

"데이터만 바꾸면 화면은 React가 알아서 업데이트해줄게"

 

이 발상 하나가 웹 개발 방식을 완전히 바꿔놨어요.

3. 핵심 개념 1 — 컴포넌트 (Component)

React에서 제일 중요한 개념이 컴포넌트예요.

컴포넌트는 쉽게 말해 화면을 구성하는 재사용 가능한 조각이에요.

실제 웹페이지를 예로 들면

[헤더 컴포넌트]

[사이드바 컴포넌트]

[카드 컴포넌트] [카드 컴포넌트] [카드 컴포넌트]

[푸터 컴포넌트]

각 영역이 하나의 컴포넌트예요. 

그리고 이 컴포넌트들을 조립해서 전체 페이지를 만드는 거예요.

코드로 보면 이렇게 생겼어요.

// 버튼 컴포넌트

function MyButton() {

  return <button>클릭하세요</button>

}


// 페이지에서 조립해서 사용

function App() {

  return (

    <div>

      <h1>안녕하세요!</h1>

      <MyButton />

      <MyButton />

    </div>

  )

}




<MyButton />을 여러 번 써도 똑같은 버튼이 여러 개 나와요. 한 번 만들어두면 어디서든 재사용할 수 있는 게 컴포넌트의 핵심이에요.

4. 핵심 개념 2 — JSX

위 코드에서 JavaScript 안에 <button>, <div> 같은 HTML이 섞여 있는 게 보이죠?

이게 JSX(JavaScript XML) 라고 해요.

JavaScript 코드 안에 HTML처럼 생긴 문법을 쓸 수 있게 해주는 React만의 문법이에요.

// JSX — JavaScript 안에 HTML처럼 쓰기

function Hello() {

  const name = '티아'

  return <h1>안녕하세요, {name}님!</h1>

}




{} 중괄호 안에 JavaScript 변수나 표현식을 넣을 수 있어요.

처음엔 좀 낯설게 느껴지는데, 쓰다 보면 오히려 화면이랑 로직을 같이 볼 수 있어서 편해져요.

5. 핵심 개념 3 — State (상태)

React에서 두 번째로 중요한 개념이 **State(상태)**예요.

State는 쉽게 말해 **"화면에 영향을 주는 데이터"**예요.

예를 들어 좋아요 버튼이 있다고 해봐요. 

클릭하면 숫자가 올라가고, 버튼 색도 바뀌잖아요. 

이때 "몇 번 눌렸는지", "눌린 상태인지 아닌지" 같은 정보가 State예요.

import { useState } from 'react'


function LikeButton() {

  const [count, setCount] = useState(0)  // 초기값 0


  return (

    <button onClick={() => setCount(count + 1)}>

      ❤️ {count}

    </button>

  )

}




useState를 쓰면 count가 바뀔 때마다 React가 자동으로 화면을 다시 그려줘요. 

내가 직접 "이 숫자 찾아서 바꿔줘" 할 필요 없이요.

이게 React가 편한 이유 중 하나예요. 

데이터(State)만 관리하면 화면은 React가 알아서 해줘요.

6. 핵심 개념 4 — Props (프롭스)

컴포넌트끼리 데이터를 주고받을 때 쓰는 게 Props예요.

부모 컴포넌트가 자식 컴포넌트한테 데이터를 전달하는 방식이에요.

// 자식 컴포넌트 — props로 데이터 받기

function WelcomeCard({ name, score }) {

  return (

    <div>

      <h2>{name}님 환영합니다!</h2>

      <p>현재 점수: {score}점</p>

    </div>

  )

}

// 부모 컴포넌트 — props로 데이터 보내기

function App() {

  return (

    <div>

      <WelcomeCard name="티아" score={100} />

      <WelcomeCard name="홍길동" score={50} />

    </div>

  )

}

같은 컴포넌트인데 넘겨주는 데이터에 따라 다르게 표시돼요.

레고 블록 색깔을 바꾸는 것처럼, 틀은 같은데 내용만 달라지는 거예요.

7. Virtual DOM — React가 빠른 이유

React 얘기 나오면 꼭 나오는 개념이 Virtual DOM이에요.

DOM은 브라우저가 화면을 그리는 구조예요. 기존 방식은 데이터가 바뀔 때마다 이 DOM 전체를 다시 건드려서 느렸어요.

React는 다르게 접근해요.

1. 실제 DOM 말고 가상의 DOM(Virtual DOM) 을 메모리에 따로 만들어둬요
2. 데이터가 바뀌면 가상 DOM에서 먼저 비교해요
3. 실제로 바뀐 부분만 실제 DOM에 업데이트해요

집 전체를 리모델링하는 게 아니라, 바뀐 방 하나만 수리하는 거예요. 그래서 화면이 많이 바뀌는 복잡한 앱에서도 빠르게 동작할 수 있어요.

8. React로 뭘 만들 수 있냐면

React가 실제로 어디에 쓰이는지 보면 감이 잡혀요.

단일 페이지 앱 (SPA) 

페이지 이동할 때 새로고침 없이 화면만 바뀌는 앱이에요. 

Gmail, 트위터 피드 같은 게 이 방식으로 만들어져 있어요.

포트폴리오 사이트 

개인 포트폴리오를 React로 만드는 경우가 많아요. 

컴포넌트 단위로 섹션을 나눠서 깔끔하게 관리할 수 있거든요.

대시보드 / 관리자 페이지 

데이터가 실시간으로 바뀌는 대시보드에 React가 특히 강해요. 

숫자가 바뀌면 화면이 자동으로 업데이트되는 구조가 딱 맞아요.

Next.js의 기반 

이전 글에서 다뤘던 Next.js가 React 기반으로 만들어진 프레임워크예요. 

React를 알면 Next.js 이해도 훨씬 빨라요.

실제로 Netflix, Instagram, Airbnb, 카카오 같은 서비스들도 React를 쓰고 있어요.

9. React, 처음 배울 때 이렇게 접근하세요

React가 처음이라면 한 번에 다 이해하려고 하지 않아도 돼요. 순서대로 접근하면 훨씬 덜 막혀요.

① JavaScript 기초 먼저 

React는 JavaScript 위에서 동작해요. 

변수, 함수, 배열 정도는 알고 시작하는 게 좋아요.

② 컴포넌트부터 익숙해지기 

화면을 쪼개서 컴포넌트로 만드는 사고방식이 제일 중요해요. 

작은 버튼 하나, 카드 하나부터 만들어보세요.

③ State 개념 잡기 

useState로 데이터가 바뀔 때 화면이 자동으로 바뀌는 걸 직접 만들어보면 감이 확 잡혀요.

④ 바이브코딩으로 만들어보기 

개념이 60% 정도 잡히면 Cursor로 "React로 간단한 투두리스트 만들어줘" 해보세요. 

AI가 만들어준 코드를 읽으면서 이해하는 게 제일 빨라요.

React, 겁낼 필요 없어요

처음엔 컴포넌트, JSX, State, Props... 용어가 한꺼번에 쏟아지니까 막막하게 느껴질 수 있어요.

근데 결국 React의 핵심은 딱 하나예요.

"화면을 블록으로 나누고, 데이터가 바뀌면 자동으로 화면이 따라 바뀐다"

이 감각 하나만 잡으면 나머지는 쓰면서 자연스럽게 익혀져요.

오늘 정리한 내용만 기억해도 됩니다.

• React = Facebook이 만든 UI 라이브러리, 화면을 컴포넌트 단위로 만듦
• 컴포넌트 = 재사용 가능한 화면 조각
• JSX = JavaScript 안에 HTML처럼 쓸 수 있는 문법
• State = 화면에 영향을 주는 데이터, 바뀌면 화면 자동 업데이트
• Props = 컴포넌트끼리 데이터를 주고받는 방법
• Virtual DOM = 바뀐 부분만 업데이트해서 빠른 이유

열공하세요! 🙌

[개발환경 기초] Node.js란? 초코라떼로 이해하는 설치방법 + 버전 체크 안 될 때 환경변수 설정까지

안녕하세요!

오늘은 개발 공부를 시작하거나 바이브코딩으로 뭔가 만들어보려다 보면 꼭 한 번은 마주치게 되는 이름, Node.js에 대해 정리할께요.

솔직히 처음에 "Node.js 설치하세요" 소리를 들었을 때 

아 이 작업에 이게 필요하니까 설치하라는건가? 하고 그냥 클릭클릭 대충 설치했어요. 

근데 설치하고 나서 터미널에 node -v 쳤는데 아무것도 안 나오는 경험... 다들 한 번씩 있죠? 

(전 많아요... 왜 많지?... 머 할때마다 찾음 없다고 나옴.....😡)

이 글에서는 Node.js가 뭔지, 설치는 어떻게 하는지, 그리고 설치했는데 버전 체크가 안 될 때 어떻게 해결하는지까지 한 번에 정리해드릴게요.

Node.js란? 초코라떼로 이해하는 설치방법 + 버전 체크 안 될 때 환경변수 설정

1. Node.js가 뭔지, 진짜 쉽게 설명하면

Node.js는 한 마디로 이렇게 설명할 수 있어요.

"JavaScript를 브라우저 밖에서도 실행할 수 있게 해주는 환경"

 

원래 JavaScript는 웹 브라우저 안에서만 돌아가는 언어였어요. 크롬이나 엣지 같은 브라우저가 JS를 읽고 실행해줬던 거예요.

근데 Node.js가 등장하면서 상황이 바뀌었어요. 이제 JavaScript를 내 컴퓨터에서, 서버에서, 어디서든 실행할 수 있게 됐어요.

비유를 하나 들어볼게요.

초코라떼 파우더가 있어요. 원래 이 파우더는 카페에서만 (브라우저에서만) 뜨거운 물에 타서 마실 수 있었어요. 근데 Node.js가 생기면서 집에서도, 사무실에서도, 캠핑장에서도 (어디서든) 같은 파우더로 라떼를 만들 수 있게 됐어요.

파우더(JavaScript)는 똑같아요. 마실 수 있는 환경이 훨씬 넓어진 것뿐이에요.

그래서 Node.js를 쓰면 이런 게 가능해집니다.

• JavaScript로 서버 만들기
• JavaScript로 파일 읽고 쓰기
• npm(패키지 관리자)을 통해 수만 가지 라이브러리 사용하기
• React, Flutter 개발할 때 필요한 빌드 도구 실행하기

마지막 게 사실 초보자한테 제일 중요해요. React 개발하려면 Node.js 설치 필수거든요. 

Cursor AI로 뭔가 만들어달라고 하면 거의 항상 Node.js가 필요합니다.

2. npm이 뭔지도 같이 알아두자

Node.js 얘기 나오면 항상 따라오는 게 npm이에요.

npm (Node Package Manager) = Node.js랑 같이 설치되는 패키지 관리자예요.

패키지는 쉽게 말해 남이 만들어둔 코드 묶음이에요. 내가 직접 만들 필요 없이 "npm으로 설치하면" 바로 쓸 수 있는 도구들이에요.

초코라떼 비유로 다시 설명하면.

초코라떼를 만들 때 파우더만 있으면 안 되잖아요. 우유도 필요하고, 시럽도 필요하고, 컵도 필요하죠.

npm은 "저 우유 가져다 줄게요, 시럽도 가져다 줄게요" 하는 편의점 같은 역할이에요. 내가 필요한 재료(패키지)를 검색하고 가져다 쓸 수 있는 공간이 npm입니다.

실제로 이렇게 씁니다.

npm install react       # React 설치
npm install axios       # axios (API 요청 도구) 설치
npm run dev             # 개발 서버 실행

Cursor로 바이브코딩 하다 보면 이런 명령어들이 자동으로 나오는데, 이제 보이면 "아, npm으로 뭔가 설치하거나 실행하는 거구나" 하고 읽힐 거예요.

3. Node.js 설치방법 — 생각보다 훨씬 간단해요

1단계: 공식 사이트 접속

nodejs.org 에 접속합니다.

메인 화면에 버튼 두 개가 바로 보여요.

• LTS (Long Term Support) — 안정 버전, 이걸 설치하세요
• Current — 최신 기능 버전, 초보자한테는 LTS가 낫습니다

★ LTS를 고르는 이유: 안정적이고 오래 지원되는 버전이에요. 새로운 기능보다 안정성이 중요한 개발 환경용으로는 LTS가 정답입니다.

 

2단계: 설치 파일 다운로드 & 실행

Windows 기준으로 .msi 파일이 다운로드돼요. 

실행하면 설치 마법사가 나오는데, 그냥 Next → Next → Install 눌러서 완료하면 됩니다.

중간에 "Add to PATH" 옵션이 있으면 반드시 체크하세요. 이게 나중에 중요합니다.

3단계: 설치 확인

설치가 끝나면 PowerShell(또는 터미널)을 열고 입력 

node -v
npm -v

이렇게 버전 숫자가 뜨면 설치 성공입니다.

v20.11.0
10.2.4

4. 버전 체크가 안 될 때 — 환경변수 설정하는 법

설치는 했는데 node -v 쳤더니 이런 게 나왔다면...

'node'은(는) 내부 또는 외부 명령, 실행할 수 있는 프로그램, 또는
배치 파일이 아닙니다.

당황하지 마세요. 이건 설치가 안 된 게 아니에요. 

컴퓨터가 node가 어디 있는지 모르는 것뿐이에요.

다시 초코라떼 비유로 설명하면

파우더를 사서 집에 가져왔어요. 

근데 주방 어느 서랍에 넣었는지 잊어버린 거예요. 

라떼를 만들려고 찾는데 "파우더 없는데요?" 소리 나오는 상황이에요.

서랍 위치(경로)를 컴퓨터한테 알려줘야 해요. 그게 환경변수 설정입니다.

Windows에서 환경변수 설정하는 법

① Node.js 설치 경로 확인

PowerShell을 열고

where node

보통 이런 경로가 나와요. 

C:\Program Files\nodejs\node.exe




경로가 나오면 C:\Program Files\nodejs 부분을 복사해두세요.

② 환경변수 창 열기

Windows 검색창에 "환경 변수" 검색 → "시스템 환경 변수 편집" 클릭

또는 단축키: Win + R → sysdm.cpl 입력 → 고급 탭 → 환경 변수 버튼

③ Path에 추가

아래쪽 "시스템 변수" 목록에서 Path 찾아서 더블클릭

→ 새로 만들기 클릭

→ 아까 복사해둔 경로 붙여넣기  C:\Program Files\nodejs

→ 확인 → 확인 → 확인

④ PowerShell 완전히 닫고 다시 열기

이게 중요해요. 환경변수는 터미널을 새로 열어야 적용됩니다. 

열려있던 PowerShell 다 닫고, 새로 열어서 다시 node -v 입력해보세요.

이제 버전 숫자가 뜰 거예요.

그래도 안 된다면? — 재설치 추천

위 방법을 했는데도 안 된다면 한 번 깔끔하게 재설치하는 게 빠릅니다.

1. 제어판 → 프로그램 추가/제거 → Node.js 제거
2. C:\Program Files\nodejs 폴더 남아있으면 삭제
3. nodejs.org에서 다시 다운로드 → 설치
4. 이번엔 설치 중간에 "Add to PATH" 체크 확인
5. PowerShell 새로 열고 node -v 확인

5. Node.js 버전 여러 개 관리하려면 — nvm 소개

개발을 좀 하다 보면 프로젝트마다 필요한 Node.js 버전이 달라요. 

A 프로젝트는 Node 18 필요하고, B 프로젝트는 Node 20 필요하고...

이럴 때 쓰는 도구가 nvm (Node Version Manager) 입니다.

nvm install 20      # Node 20 설치
nvm use 18          # Node 18로 전환
nvm list            # 설치된 버전 목록 확인

당장 필요하진 않지만, 나중에 여러 프로젝트 동시에 관리할 때 알아두면 편해요.

Windows용은 nvm-windows, 

Mac/Linux는 nvm 검색하면 바로 나옵니다.

6. 바이브코딩할 때 Node.js가 왜 필요한지

Cursor AI로 개발할 때 Node.js가 필요한 상황을 정리해볼게요.

React / Next.js 프로젝트 만들 때

npx create-react-app my-app
npx create-next-app my-app

이런 명령어들이 전부 Node.js 기반이에요. Node.js 없으면 실행 자체가 안 됩니다.

★npm vs npx ???

npm은 패키지를 설치할 때, npx는 설치 없이 바로 실행할 때 써요. 

프로젝트 생성은 한 번만 쓰는 명령어라 npx가 맞아요!

패키지 설치할 때 AI가 "이 라이브러리 설치해서 써요" 하면서 npm install 뭔가 명령어를 알려주는데, npm이 Node.js랑 같이 설치되어 있어야 써요.

개발 서버 실행할 때

npm run dev
npm start

이런 거 실행할 때도 Node.js가 깔려있어야 합니다.

즉, JavaScript 계열 프로젝트를 바이브코딩으로 만들 거라면 Node.js는 필수 설치 항목이에요.

정리 — Node.js, 이것만 기억하면 됩니다

처음에 "Node.js가 뭔지도 모르는데 설치해야 하나요?" 싶을 수 있어요.

근데 솔직히 Node.js는 개발 환경을 세팅하는 기초 공사 같은 거예요. 한 번만 제대로 설치해두면 계속 쓰이는 것들이거든요.

오늘 정리한 내용만 기억하면 됩니다.

• Node.js = JavaScript를 브라우저 밖에서 실행할 수 있는 환경
• npm = Node.js랑 같이 설치되는 패키지(라이브러리) 관리자
• 설치 = nodejs.org → LTS 버전 다운로드 → Next Next Install
• 버전 체크 안 될 때 = 환경변수 Path에 Node.js 경로 추가 → 터미널 재시작
• 그래도 안 되면 = 제거 후 재설치, 이번엔 "Add to PATH" 꼭 체크

열공하세요! 🙌