왜 하는가: 오늘은 '내 화면이 떴다'를 경험합니다
이번 장의 목표는 아주 분명합니다.
내 컴퓨터 브라우저에 내가 만든 웹 서비스의 첫 화면을 띄우는 것입니다.
아직 AI가 상품 설명을 써주지는 않습니다. 로그인도 없고, 저장도 없습니다. 그래도 괜찮습니다. 오늘은 집을 짓기 전에 빈 가게 문을 열어보는 날입니다.
웹 서비스 만들기는 멀리서 보면 어렵지만, 처음 성공은 생각보다 작습니다.
AI에게 Next.js 프로젝트를 만들라고 시킵니다.
내 컴퓨터에서 실행합니다.
브라우저에서
localhost주소로 들어갑니다.화면의 글자를 바꿔봅니다.
여기까지 되면 정말 중요한 감각이 생깁니다.
"아, 내가 말하면 AI가 만들고, 내가 실행하면 화면이 뜨는구나."
이 감각이 앞으로 서버, AI, DB, 로그인, 배포까지 가는 힘이 됩니다.
Next.js 공식 문서에서도 새 앱을 만든 뒤 개발 서버를 실행하고 http://localhost:3000에서 확인하는 흐름을 안내합니다.1 우리는 그 흐름을 비개발자 버전으로 천천히 따라가겠습니다.
AI 생성 이미지
따라하기 1: AI에게 Next.js 프로젝트를 만들어달라고 하기
이제 AI에게 일을 시킬 차례입니다.
여기서 중요한 점이 있습니다. 우리는 AI에게 그냥 "웹사이트 만들어줘"라고 하지 않습니다. 그러면 AI가 너무 넓게 해석할 수 있습니다.
대신 이렇게 말해 보세요.
"어떤 기술로, 어떤 이름의 프로젝트를, 어떤 조건으로 만들어줘."
아래 지시문을 AI 코딩 도구에 그대로 붙여넣으세요.
"나는 코딩을 모르는 초보자입니다. Next.js로 새 웹 프로젝트를 만들고 싶습니다.
프로젝트 이름은 ai-shop로 해주세요.
목표는 나중에 AI 쇼핑몰을 만드는 것입니다.
지금은 첫 화면만 뜨면 됩니다.
조건:
- TypeScript를 사용해도 괜찮습니다.
- App Router를 사용해주세요.
- Tailwind CSS를 사용할 수 있으면 사용해주세요.
- src 폴더는 만들지 말고, app 폴더가 프로젝트 루트에 오게 해주세요.
- npm을 사용해주세요.
제가 VS Code 터미널에서 어떤 명령어를 입력해야 하는지, 한 단계씩 알려주세요.
명령어를 실행하기 전에 왜 필요한지도 짧게 설명해주세요."이렇게 하면 AI가 계획을 이렇게 보여줄 것입니다.
여기서 계획을 전부 이해하려고 애쓰지 않으셔도 됩니다. 지금은 딱 네 가지만 보세요.
프로젝트 이름이 맞는가?
ai-shop여야 합니다.Next.js를 만든다고 하는가?
다른 프레임워크 이름이 나오면 멈추고 다시 지시하세요.실행 주소가
http://localhost:3000인가?
가끔 3000번이 이미 사용 중이면 다른 번호가 나올 수 있습니다. 그때는 AI의 안내를 따라도 됩니다.
따라하기 2: 터미널에서 프로젝트 생성하기
AI가 안내하는 명령어는 다음과 같을 것입니다.
npx create-next-app@latest ai-shop --typescript --tailwind --app --no-src-dir --use-npm --eslint이 명령은 이렇게 이해하면 됩니다.
npx: 인터넷에서 필요한 도구를 잠깐 불러와 실행합니다. (Node Package eXecute의 약자로 Node.js 패키지를 설치하지 않고도 일회성으로 다운로드하여 실행할 수 있게 해주는 도구입니다.)create-next-app: Next.js 프로젝트를 자동으로 만들어주는 도구입니다. 이게 중요합니다. 이 도구가 처음 Next 프로젝트를 세팅을 해줍니다.@latest: 최신 버전을 사용하겠다는 뜻입니다.ai-shop: 새로 만들 프로젝트 폴더 이름입니다.
즉, 한 문장으로 말하면 이렇습니다.
"Next.js 프로젝트 제작 도구를 불러와서,
ai-shop라는 새 폴더를 만들어줘."
처음 실행하면 create-next-app을 설치해도 되는지 묻는 안내가 나올 수 있습니다. 이때는 설치를 허용해야 다음 단계로 넘어갈 수 있습니다.
--typescript --tailwind --app --no-src-dir --use-npm --eslint 부분은 지금은 완전히 이해하지 않으셔도 괜찮습니다. 기본적으로 아래와 같은 의미입니다. 만약 이 옵션 없이 설치하신다면 아래와 같이 세팅해 주시면 됩니다.
TypeScript: Yes (자바스크립트의 슈퍼셋인 타입스크립트 사용)
ESLint: Yes 또는 기본값
Tailwind CSS: Yes (Tailwind 라는 CSS 라이브러리 사용)
src directory: No (예전 src 디렉토리 사용 안함.)
App Router: Yes (app 디렉토리를 루트로 사용)
import alias: 기본값 사용
그 밖의 새 질문: 잘 모르겠다면 기본값 또는 추천값 사용여기서 중요한 것은 우리가 쓰는 기준을 파악하는 것입니다.
우리는
npm을 씁니다.우리는
App Router를 씁니다. (app 디렉토리가 기본 디렉토리)우리는
Tailwind CSS를 쓸 수 있게 만듭니다.우리는
src폴더를 만들지 않습니다.잘 모르는 새 질문은 일단 기본값이나 추천값을 고릅니다.
이제 터미널을 열고 위의 명령어를 입력해 줍니다. vscode 에서 터미널이 안보인다면 메뉴에서 Terminal 을 선택한 후 New terminal 을 선택하세요.
그러면 하단에 이렇게 터미널 창이 나오게 됩니다.
여기에 위의 설치 명령어를 복사해서 넣어주면 됩니다.
npx create-next-app@latest ai-shop --typescript --tailwind --app --no-src-dir --use-npm --eslint설치가 시작되면 여러 줄의 글자가 빠르게 지나갑니다. 처음 보면 무섭지만, 대부분은 "필요한 부품을 내려받는 중"이라는 뜻입니다.
여기서 node_modules라는 말이 나올 수 있습니다. 이건 나중에 설명하겠지만, 지금은 프로젝트에 필요한 부품 창고라고 생각하면 됩니다.
설치가 끝나면 vibecoding-projects 안에 새 폴더가 생겼을 겁니다. 터미널에서 ls 라고 입력해 보세요.
vibecoding-projects
└─ ai-shop이제 터미널에서 실제 서비스 폴더 안으로 들어갑니다.
cd ai-shopcd는 "그 폴더 안으로 들어가기"입니다. 엘리베이터를 타고 프로젝트 작업실 안으로 들어간다고 생각하시면 됩니다.
여기서 정말 중요합니다.
앞으로 npm run dev 같은 명령어는 프로젝트 폴더 안에서 실행해야 합니다. 터미널 위치가 vibecoding-projects에 머물러 있으면 명령어가 실패할 수 있습니다.
잘 들어왔는지 확인하고 싶다면 다시 pwd를 입력해보세요.
pwdai-shop폴더 안이면 됩니다!
이제 프로젝트의 폴더를 다시 잡아주기 위해 VS Code에서 ai-shop 폴더를 다시 열어주세요.
이제 프로젝트 폴더가 준비되었습니다. 이제 프로젝트를 진행할 때는 이 ai-shop 폴더를 열어서 시작하면 됩니다.
따라하기 3: 내 컴퓨터에서 웹사이트 실행하기
이제 프로젝트를 실행합니다.
먼저 터미널 위치가 ai-shop 안인지 확인하세요. (터미널이 안보이면 Terminal -> New Terminal)
그다음 아래 명령어를 실행합니다.
npm run dev이 명령은 "개발용 서버를 켜줘"라는 뜻입니다. Next.js 공식 문서에서도 개발 서버 실행 명령으로 npm run dev를 안내합니다.2
서버라는 말이 갑자기 나와서 놀라셨을 수 있습니다.
여기서 서버는 거창한 회사 장비가 아닙니다. 지금은 내 컴퓨터 안에서 잠깐 켜는 임시 가게 직원이라고 보면 됩니다.
브라우저가 "화면 보여줘"라고 요청하면, 이 개발 프론트 서버가 "여기 첫 화면입니다" 하고 건네주는 구조입니다.
터미널에 실행 안내가 나오면 브라우저를 열고 아래 주소로 들어갑니다.
http://localhost:3000localhost는 쉽게 말해 내 컴퓨터 안에서만 열리는 임시 주소입니다.
친구에게 이 주소를 보내도 친구 컴퓨터에서는 열리지 않습니다. 친구의 localhost는 친구 컴퓨터를 뜻하기 때문입니다.
비유하면 이렇습니다.
localhost: 내 집 안에 차린 임시 매장실제 배포 주소: 길거리에 간판 달고 누구나 찾아올 수 있는 매장
오늘은 내 집 안의 임시 매장을 열어보는 단계입니다.
화면이 떴나요?
잠깐 멈추고 확인해 주세요.
이게 첫 성공입니다.
아직 아무 기능이 없어도 괜찮습니다. 내 컴퓨터에서 웹 서비스가 실제로 실행되고 있습니다.
따라하기 4: 화면 글자 바꿔보기
이제 "내가 바꾸면 화면도 바뀐다"를 경험해보겠습니다.
VS Code 왼쪽 파일 목록에서 아래 파일을 찾으세요.
app/page.tsx
파일을 열면 영어 문구와 코드가 보일 겁니다. 전부 이해하려고 하지 마세요. 지금은 화면에 보이는 문구를 찾는 게 목표입니다.
AI에게 이렇게 지시하세요.
"app/page.tsx 파일의 첫 화면을 아주 단순하게 바꿔주세요.
화면 가운데에 다음 문구가 보이면 됩니다.
AI 쇼핑몰
상품을 올리면 AI가 판매용 설명을 만들어드립니다.
아직 버튼이나 입력칸은 만들지 마세요.
초보자가 이해할 수 있게 변경한 부분을 짧게 설명해주세요."AI가 파일을 수정하거나, 수정할 코드를 제안할 겁니다.
브라우저로 돌아가세요. 보통은 자동으로 화면이 바뀝니다. 안 바뀌면 새로고침을 눌러보세요.
이 문구가 보이면 성공입니다.
AI 쇼핑몰
상품을 올리면 AI가 판매용 설명을 만들어드립니다.이 순간이 중요합니다.
여러분은 방금 코드를 직접 다 이해하지 않고도, AI에게 요청해서 웹 화면을 바꿨습니다. 이 책에서 말하는 바이브코딩의 첫 감각이 바로 이것입니다.
나중에 쇼핑몰 대신 다른 서비스를 만들고 싶다면 이 문구부터 바꾸면 됩니다.
예를 들어:
자소서 첨삭기
문장을 입력하면 더 자연스럽게 다듬어드립니다.이메일 답장기
상황을 입력하면 정중한 답장을 작성해드립니다.리뷰 요약기
고객 리뷰를 붙여넣으면 핵심 불만과 장점을 정리해드립니다.오늘 만든 것은 작지만, 구조는 같습니다. 입력받고, 처리하고, 결과를 보여주는 서비스로 자라날 수 있습니다.
이제 AI 쇼핑몰이라는 문구를 이렇게 바꿔보세요.
AI 쇼핑몰 - 시작
그리고 ctrl + s 로 에디터에서 저장을 해보세요. 그리고 브라우저를 다시 보세요. 어때요? 변화가 되었나요?
이렇게 에디터에서 내용이 변화되면 Next.js 가 바로 변경 내용을 브라우저에 반영해서 리프레쉬 해줍니다. 개발을 편하게 하는 장치이죠?
지금 알아야 할 폴더 구조만 보기
프로젝트 폴더 안을 보면 파일과 폴더가 많습니다. 처음 보면 "벌써 망했다"는 생각이 들 수 있습니다.
아닙니다. 지금은 네 가지만 알면 됩니다.
app 폴더
사용자가 보는 화면이 들어가는 곳입니다.
식당으로 비유하면 손님이 앉는 홀에 가깝습니다. 오늘 바꾼 app/page.tsx가 첫 화면입니다.
이 앱 폴더가 프론트엔드에서 보이는 파일들의 중심이 된다고 생각하시면 됩니다.
package.json
프로젝트의 설명서이자 주문서입니다.
이 프로젝트가 어떤 부품(패키지)을 쓰는지, 어떤 명령어로 실행되는지가 적혀 있습니다. 우리가 입력한 npm run dev도 이 파일에 적힌 실행 규칙을 따라 움직입니다.
node_modules 폴더
프로젝트에 필요한 부품 창고입니다.
용량이 크고 파일이 아주 많습니다. 절대 하나씩 열어볼 필요 없습니다. 직접 수정하지도 않습니다.
나중에 GitHub에 올릴 때도 이 폴더는 보통 제외합니다. 부품 창고 자체를 들고 다니는 대신, package.json이라는 주문서만 있으면 다시 받을 수 있기 때문입니다.
public 폴더
이미지나 아이콘처럼 그대로 꺼내 쓰는 파일을 넣는 곳입니다.
지금은 몰라도 됩니다. 나중에 로고나 예시 이미지를 넣고 싶을 때 다시 만납니다.
✅ 확인: 여기까지 됐나요?
아래 항목을 하나씩 체크해보세요.
vibecoding-projects안에ai-shop폴더가 생겼다.VS Code에서
ai-shop프로젝트 폴더를 열었다.터미널 위치가
ai-shop안이다.터미널에서
npm run dev를 실행했다.브라우저에서
http://localhost:3000에 접속했다.Next.js 첫 화면이 떴다.
app/page.tsx를 수정했다.화면에
AI 쇼핑몰문구가 보인다.
이 중 마지막 항목까지 됐다면, 오늘 목표는 끝났습니다.
축하드립니다. 이제 여러분은 "내 컴퓨터에서 돌아가는 웹 서비스"를 하나 갖고 있습니다.
⚠️ 막히면: 여기서 많이 만나는 문제들
npx 명령어가 안 된다고 나와요
대부분 Node.js 또는 npm 설치 문제입니다.
터미널에서 확인해보세요.
node -v
npm -v둘 중 하나라도 버전이 나오지 않으면 작업실 차리기 — 환경 세팅으로 돌아가 Node.js LTS 설치를 다시 확인하세요.
버전이 나오더라도 너무 낮으면 최신 Next.js가 실행되지 않을 수 있습니다. Next.js 공식 문서는 최신 버전 기준으로 Node.js 최소 요구 버전을 안내합니다.1 이럴 때도 Node.js LTS를 새로 설치하는 쪽이 안전합니다.
설치 중에 질문이 너무 많아요
정상입니다. 도구 버전이 바뀌면 질문이 조금씩 달라질 수 있습니다.
이럴 때는 멈추고 AI에게 현재 화면을 그대로 설명하세요.
"create-next-app 설치 중에 이런 질문이 나왔습니다.
[여기에 터미널 질문을 그대로 붙여넣기]
이 책의 기준인 npm, App Router, Tailwind CSS, src 폴더 없음에 맞게 무엇을 선택해야 하나요?"npm run dev를 입력했는데 에러가 나요
먼저 지금 터미널 위치가 프로젝트 폴더 안인지 확인하세요.
pwd경로 끝에 ai-shop가 보여야 합니다. 만약 아직 vibecoding-projects에 있다면 아래 명령어로 들어가세요.
cd ai-shop그다음 다시 실행합니다.
npm run devpackage.json을 찾을 수 없다는 식의 에러가 나왔다면, 거의 항상 "명령어를 실행한 위치가 잘못됐다"는 뜻입니다.
localhost:3000이 안 열려요
먼저 터미널에서 npm run dev가 계속 실행 중인지 확인하세요.
개발 서버는 전원을 켜둔 가게 직원과 같습니다. 터미널을 꺼버리면 브라우저가 요청해도 대답할 사람이 없습니다.
또, 3000번 주소가 이미 사용 중이면 Next.js가 다른 주소를 안내할 수 있습니다.
터미널에 http://localhost:3001처럼 다른 주소가 보이면 그 주소로 접속해보세요.
화면을 바꿨는데 브라우저가 그대로예요
다음 순서로 확인합니다.
파일을 저장했나요?
Ctrl + S또는Cmd + S수정한 파일이
app/page.tsx가 맞나요?브라우저를 새로고침했나요?
터미널에 에러가 떠 있나요?
에러가 보이면 겁먹지 말고 그대로 복사해서 AI에게 물어보세요.
"Next.js 화면을 수정했는데 브라우저에 에러가 나옵니다.
아래는 터미널/브라우저에 나온 에러입니다.
원인을 초보자도 이해할 수 있게 설명하고, 수정해 주세요.
[에러 메시지 붙여넣기]"터미널이 멈춘 것 같아요
npm run dev를 실행한 뒤 터미널이 멈춘 것처럼 보이는 건 정상입니다. 개발 서버가 켜져서 계속 기다리는 중입니다.
명령을 새로 입력하고 싶다면 터미널을 하나 더 열거나, 현재 서버를 끄고 싶을 때는 다음 키를 누릅니다.
Ctrl + C그러면 "종료할까요?" 같은 질문이 나올 수 있습니다. 그때는 화면 안내에 따라 진행하세요.
프론트에서 에러가 나와요.
때로는 다음과 같이 Next 에서 에러가 나올 때가 있습니다.
이럴 때는 어려워 하지 말고 에러 메시지를 복사한 뒤 AI 에게 다음과 같이 말하세요.
다음과 같은 에러가 났다. 원인을 쉽게 설명하고 해결해줘.
[에러 메시지 붙여넣기] 한 줄 정리 + 다음 예고
이번 장에서는 AI의 도움으로 Next.js 프로젝트를 만들고, localhost에서 첫 화면을 띄운 뒤, 문구까지 바꿔봤습니다.
한 줄 정리: localhost는 내 컴퓨터 안에서만 열리는 임시 주소이고, 오늘 우리는 그 주소에 첫 웹 화면을 띄웠습니다.
다음 장에서는 안전벨트를 맵니다. 바로 Git과 GitHub입니다.
앞으로 우리는 계속 고치고, 실험하고, 가끔 망칠 겁니다. 괜찮습니다. Git을 쓰면 "잘 되던 시점"으로 돌아갈 수 있습니다. 다음 장에서 그 되돌아가기 버튼을 만들어두겠습니다.
참고
이 노트는 보도·비평·교육·연구 목적으로 작성되었습니다. 저작권 문의가 있으시면 에서 알려주세요.