레슨
시작
학습 시작
CodeGym /행동 /ChatGPT Apps /ChatGPT App 다운로드 및 분석 (Next.js 16)

ChatGPT App 다운로드 및 분석 (Next.js 16)

ChatGPT Apps
레벨 2 , 레슨 0
사용 가능

1. 소개

이 강의의 목표는 단순하지만 매우 중요합니다. “로컬에서 ChatGPT App이 정상 실행되고, 브라우저에서 페이지가 보이며, 아무것도 깨지지 않는다”는 상태까지 여러분을 이끄는 것입니다.

오늘은 Next.js 코드를 깊게 파지도, ChatGPT에서 Dev Mode를 설정하지도, 터널을 띄우지도 않습니다 — 그건 다음 강의에서 다룹니다. 오늘은 세 가지에 집중합니다:

  1. 환경 준비: Node.js, npm, Git, 에디터, 기본 점검을 통해 Next.js 16이 여러분의 Node 버전에서 문제없이 동작하도록 합니다.
  2. Next.js 16 기반의 작동하는 ChatGPT App을 받기: git clone 또는 GitHub 템플릿/CLI를 사용합니다.
  3. 의존성 설치, .env에 OPENAI_API_KEY를 설정하고 npm run dev로 실행하여 http://localhost:3000이 정상 동작하는지 확인합니다.

강의가 끝날 때 브라우저에서 템플릿의 시작 페이지가 보이고, 터미널의 dev 서버가 빨간 오류 없이 돌아간다면 — 이미 여러분만의 작동하는 ChatGPT App이 생긴 것입니다.

2. 최소 개발 환경

인프라부터 시작합니다. 이것 없이는 어떤 멋진 LLM도 도움이 되지 않습니다 — Next.js는 아예 실행되지 않습니다.

Node.js 및 npm

Next.js 16 기반의 최신 Apps SDK 템플릿은 최신 Node를 요구합니다. LTS 릴리스를 사용하세요 — 현재 예: Node 24 LTS. 최소 허용 버전은 20.9이며, 이 버전부터 Next.js 16이 공식 지원됩니다.

터미널에서 버전 확인:

node -v
npm -v

만약 깔끔한 v24.x.x 대신 v16.13.0 같은 버전이 보인다면, 템플릿이 의존성을 설치하지 못하거나 Next.js가 “지원되지 않는 Node 버전”이라며 불평할 가능성이 큽니다.

업데이트는 “간단하게” — OS용 공식 Node.js 설치 프로그램을 사용하거나, 리눅스/맥 사용자라면 nvm/fnm으로도 가능합니다. 강의 범위를 벗어나는 버전 매니저 얘기는 생략하고, 최신 LTS 버전을 준비하는 데 집중합니다.

Git

템플릿을 가져오고, 앞으로 변경 사항을 커밋하기 위해 Git이 필요합니다. 확인 방법: 

git --version

명령이 인식되지 않는다면 Git을 설치하세요(Windows 설치 프로그램, macOS의 Homebrew, Linux의 패키지 매니저 등). App 자체 실행에는 Git이 필수는 아니지만, 2025년에 Git 없이 일하는 것은 인터페이스도 모르고 TypeScript를 쓰는 것과 비슷합니다.

코드 에디터

기본 추천 — WebStorm. JavaRush 전용 플러그인이 있어 과제를 몇 번의 클릭으로 풀 수 있습니다. 사실상 프런트엔드와 Node의 “사실상 표준”입니다.

VS Code를 사용해도 됩니다. 이 경우 다음과 같은 기본 확장을 권장합니다:

  • TypeScript/JavaScript 지원;
  • ESLint(템플릿이 린터 설정을 포함하는 경우가 많습니다).

템플릿 코드를 수정할 때 작업이 한결 수월해집니다.

OpenAI / ChatGPT 계정과 API 키

이번 강의에서는 브라우저에서 ChatGPT에 로그인할 수 있으면 충분합니다. Dev Mode 연결은 나중에 진행하겠지만, 지금 웹 인터페이스에 접속해 개발자 기능 탭(Plus/Team/Enterprise 등, OpenAI 정책에 따라)이 보이는지 확인해 두면 좋습니다.

앞으로는 OpenAI API 키(OPENAI_API_KEY)가 필요합니다. 첫 프로젝트는 키 없이도 뜰 수 있습니다. 시작 UI는 전적으로 정적이기 때문이죠. 그래도 이번 강의에서 키를 사용해보고 .env 파일에 넣겠습니다 — 왜 이렇게 하는 게 더 안전한지도 곧 설명합니다.

키는 OpenAI 콘솔에서 발급받아 비밀로 보관하며, 저장소에 올리지 않습니다. 여권번호보다 더 엄격히 다룬다고 생각하세요.

3. 작동하는 ChatGPT App 얻기

이제 가장 즐거운 단계입니다. 이미 ChatGPT App으로 설정된 시작 프로젝트를 그대로 가져옵니다.

C++

왜 이 프로젝트인가

이 프로젝트는 Next.js 16 기반의 매우 단순한 예제로, 하나의 저장소에서 UI 위젯과 MCP 서버 두 가지 역할을 함께 다룹니다.

구조는 이미 준비되어 있습니다:

  • 위젯으로 렌더링될 React 페이지가 있고;
  • ChatGPT가 도구를 호출할 때 접근하는 MCP 서버 endpoint가 있으며;
  • Next.js 설정이 준비되어 있습니다(특히 ChatGPT의 iframe에서 에셋을 올바르게 불러오기 위한 assetPrefix 같은 중요한 옵션 포함).

처음부터 모든 것을 직접 조립하는 것보다 훨씬 낫습니다.

옵션 1: Git 리포지토리 클론

가장 직접적인 방법:

git clone https://github.com/codegym-cc/chatgpt-apps-examples/helloworld my-chatgpt-app
cd my-chatgpt-app/01-chatgpt-app-helloworld

리포지토리 이름은 나중에 조금 달라질 수 있으니, 명령을 복사하기 전에 공식 문서나 이 강의 댓글의 최신 링크를 확인하는 것이 좋습니다.

git clone은 my-chatgpt-app 폴더를 만들고 템플릿의 모든 내용을 내려받아 Git 저장소로 구성합니다.

옵션 2: GitHub의 “Use this template” 버튼

처음부터 GitHub에 본인 저장소를 만들고 싶다면 다음을 수행하세요:

  1. GitHub에서 템플릿 페이지를 엽니다.
  2. “Use this template” 버튼을 클릭합니다.
  3. 템플릿을 기반으로 본인 저장소를 만듭니다. 예: username/study-buddy-chatgpt-app.
  4. 그다음 본인 저장소를 클론합니다.

결과는 사실 같습니다. 로컬에는 템플릿 코드 폴더가 생기지만, Git remote는 CodeGym 리포지토리가 아닌 여러분의 저장소를 가리키게 됩니다.

옵션 3: CLI 템플릿

앞으로 OpenAI에서 공식 CLI 도구가 나올 가능성이 큽니다. 예를 들면: 

npx create-openai-app@latest my-chatgpt-app

아직은 없습니다. ChatGPT 앱이 이제 막 발전하기 시작했기 때문입니다. 하지만 여러분이 이 강의를 읽는 시점에는 이미 나왔을 수도 있습니다. 이런 명령은 공식 Apps SDK 문서에서 꼭 확인해 보세요.

논리는 동일합니다. CLI가 동일하거나 매우 유사한 템플릿을 내려받아 전개해 줍니다. ChatGPT 플러그인 생성 도구도 이와 비슷했기에, 시간이 지나면 앱용 도구도 나올 가능성이 큽니다.

4. 의존성 설치 및 첫인상

이미 my-chatgpt-app 폴더에 작동 가능한 프로젝트가 있다고 가정합니다. 이제 의존성을 설치할 차례입니다.

npm install

프로젝트 폴더로 이동해 의존성을 설치합니다:

cd my-chatgpt-app
npm install

스크립트는 package.json을 읽어 필요한 패키지(Next.js, React, Tailwind, Apps SDK 및 MCP SDK(@modelcontextprotocol/sdk))를 설치합니다.

결과로 node_modules 디렉터리가 생깁니다 — 수백 MB짜리 “괴물”로, 절대 Git에 커밋하지 않습니다. 템플릿의 .gitignore에 이미 포함되어 있으므로 추가 설정은 필요 없습니다.

의존성 설치 중 문제가 발생하더라도 당황하지 마세요. 아래에서 흔한 문제를 정리합니다.

간단한 구조 둘러보기

지금은 폴더 구조를 깊게 파고들 필요는 없습니다 — 다음 강의에서 자세히 다룹니다. 다만 프로젝트 루트는 잠깐 훑어보면 좋습니다:

  • package.json — 의존성과 스크립트 목록.
  • next.config.ts — ChatGPT 내에서 동작하도록 추가 설정이 포함된 Next.js 구성.
  • tsconfig.json — TypeScript 구성.
  • app/ — UI 코드와 MCP 라우트의 위치.

다음 시간에는 이 “깜깜한 숲”을 이해 가능한 지도로 바꿔 보겠습니다.

5. .env와 OPENAI_API_KEY 설정

앞서 처음 템플릿에는 OPENAI_API_KEY가 꼭 필요하지 않을 수 있다고 했지만, 앞으로 사용할 예정이므로 처음부터 제대로 해 보겠습니다: .env를 사용합니다. 비밀값을 코드에 하드코딩하지 않는 것이 정상적인 개발 습관입니다.

왜 .env가 필요한가

템플릿은 .env.local 환경 파일을 사용하며, Next.js가 여기에서 환경 변수를 로드합니다.

일반적으로 저장소에는 .env.example이 있거나 README에 필요한 변수 목록이 적혀 있습니다. 우리 경우 최소한으로 필요한 것은 OPENAI_API_KEY입니다: 

OPENAI_API_KEY=sk-your-openai-key

로컬 비밀이 프로덕션 설정과 섞이지 않도록 .env.local 사용을 권장합니다.

또한 .env.local은 이미 .gitignore에 포함되어 있어 Git이 이를 감지하거나 커밋에 포함하지 않습니다. 그래도 .gitignore에 .env* 라인이 있는지 한 번 더 확인하세요.

OpenAI API 키 발급 및 보관

API 키는 OpenAI 콘솔에서 생성하며 보통 sk-로 시작합니다. 이후에는 다음 보안 위생을 지킵니다:

  • 키를 GitHub에 공개하거나 채팅에 공유하지 않는다;
  • 포럼 코드 예시에 그대로 붙여넣지 않는다;
  • 유출이 의심되면 즉시 교체한다(키 로테이션은 보안 모듈에서 다룹니다).

이번 강의에서는 키가 .env.local에 올바르게 저장되어 있고, 서버 측에서 process.env.OPENAI_API_KEY로 접근 가능하기만 하면 충분합니다.

OS별 주의사항

사소하지만 실수하기 쉬운 부분들:

  • Windows에서 .env 대신 명령줄로 환경 변수를 직접 지정하려면 export가 아닌 set VAR=VALUE && 명령을 사용해야 합니다.
  • .env.local이 프로젝트 루트에 있고, 파일명이 정확한지 확인하세요: .env 또는 .env.local. .txt 같은 에디터의 “도움”은 금지입니다.

6. 첫 실행: npm run dev 및 localhost:3000

이제 가장 즐거운 순간입니다. 모든 것이 빌드되고 프로젝트가 실행되는지 확인해 봅시다.

dev 서버 실행

프로젝트 루트에서 다음을 실행합니다:

npm run dev

이 명령은 Next.js를 개발 모드로 실행합니다. 터미널에는 대략 다음이 표시됩니다:

  • 프로젝트 빌드(Turbopack을 사용한 빠른 개발 모드);
  • Ready in Xs와 함께 서버가 3000 포트를 리스닝 중이라는 메시지;
  • 로컬 URL http://localhost:3000.

빨간 오류 메시지가 보이면 바로 스크롤 올리지 말고 일단 읽어보세요. Next는 필요한 것(노드 버전, 의존성 등)을 꽤 잘 힌트해 줍니다.

브라우저에서 열기

이제 브라우저에서 열어봅니다:

http://localhost:3000

모든 것이 잘 되었다면 시작 페이지가 보일 것입니다. 버전에 따라 모양이 조금씩 다를 수 있지만, 보통 “Your ChatGPT App” 같은 제목이나 간단한 위젯 설명이 표시됩니다.

이 단계에서 중요한 것은 단 하나입니다. 페이지가 열리고, 500 오류로 떨어지지 않으며, 거대한 스택 트레이스를 보이지 않는 것.

나중에 프로젝트에는 “랜딩 페이지”와 실제로 ChatGPT에 iframe으로 삽입되는 위젯 페이지가 구분될 수 있음을 보게 됩니다. 하지만 지금은 사이트 전체가 “Hello, world”를 보여주는 비싼 방법일 뿐입니다.

구성도

전체 그림을 이해하는 데 도움이 되는 간단한 도식입니다:

+-----------------------------+
|      여러분의 컴퓨터        |
|                             |
|  +-----------------------+  |
|  |  Next.js dev 서버     |  |
|  |  (npm run dev)        |  |
|  +----------+------------+  |
|             |               |
|   http://localhost:3000     |
|             |               |
|      브라우저(Chrome)       |
+-------------+---------------+

ChatGPT와 터널은 나중에 등장합니다 — 지금은 브라우저로 로컬 Next.js에 직접 접속합니다.

ChatGPT는 여기서 아직 전혀 관여하지 않습니다. 이건 좋은 일입니다. 움직이는 부품이 적을수록 디버깅이 쉬워지니까요.

7. 간단 진단: 문제가 생기면

경험상 누군가 처음부터 한 번에 성공했다면, 아마 그전에 같은 설정으로 세 번은 실패해 봤을 겁니다. 자주 발생하는 문제를 정리해 봅시다.

포트 3000이 이미 사용 중

자주 보이는 오류: npm run dev를 실행했는데 Next.js가 EADDRINUSE: address already in use 0.0.0.0:3000 같은 오류를 냅니다. 포트 3000을 다른 프로세스가 이미 쓰고 있다는 의미입니다.

가능한 원인:

  • 다른 터미널 어딘가에서 이미 이 프로젝트(또는 다른 프로젝트)의 npm run dev가 돌아가고 있음;
  • 동일 포트에서 다른 서버가 동작 중(드물지만 존재).

해결 방법:

  • 기존 프로세스를 찾아 종료(대개 dev 서버가 떠 있는 터미널을 닫으면 충분);
  • 다른 포트로 dev 서버 실행:
PORT=3001 npm run dev

Windows에서는 다음과 같습니다:

set PORT=3001 && npm run dev

그때는 브라우저에서 http://localhost:3001을 여는 것을 잊지 마세요.

Node.js 버전이 너무 낮음

Node 16 또는 초기 18 버전을 쓰면, Next.js 16이 해당 버전을 지원하지 않는다고 말하거나 npm install에서 호환성 오류로 실패할 수 있습니다. Next 16 문서는 Node 20.9 이상을 요구하며, 가능하면 최신 LTS를 권장합니다.

이 경우 방법은 하나입니다. Node를 업데이트하세요. Next.js 16의 제한을 우회하려고 애쓰기보다 훨씬 빠릅니다. 업데이트 후에는 node_modules와 lock 파일(package-lock.json)을 삭제하고 npm install을 다시 실행해 새 버전에 맞게 의존성을 정리하는 것이 좋습니다.

npm install 중 오류

의존성 설치가 실패하면:

  • 인터넷 연결이 정상이고 registry.npmjs.org가 로컬 설정으로 차단되지 않았는지 확인;
  • Node 버전을 확인(위 참조);
  • Node 버전을 바꿨다면 node_modules를 처음부터 다시 구성해 보세요.

대부분의 경우 터미널의 오류 메시지가 어떤 패키지에서 문제가 났는지 알려주며, 종종 “Node >= X.Y.Z 필요”라고 명시합니다.

환경 변수가 로드되지 않음

모든 것이 실행되는데 서버가 OPENAI_API_KEY가 설정되지 않았다고 불평할 때가 있습니다. 아래 체크리스트를 확인하세요:

  • 파일명이 .env 또는 .env.local이며 프로젝트 루트에 있고, Next.js가 이를 읽는지;
  • .env를 추가/수정한 뒤에는 dev 서버를 재시작해야 함. 그렇지 않으면 이전 환경값으로 계속 실행됨;
  • 변수명이 정확히 OPENAI_API_KEY인지(오타 없음).

단지 프로젝트 페이지만 보고 싶다면, 당장 키가 필요한 코드 부분을 임시로 주석 처리할 수도 있습니다. 하지만 강의에서는 처음부터 비밀값을 올바르게 관리하는 습관을 들이는 편을 권장합니다.

로그와 오류는 어디에서 확인하나

개발 모드에서 빌드 및 런타임 오류는 모두 npm run dev를 실행한 터미널에 출력됩니다. 이 단계에서는 코드가 많지 않으므로, 흔한 문제는 누락된 의존성, 잘못된 .env, 또는 너무 낮은 Node 버전입니다.

또한 브라우저에서 DevTools(F12)를 열어보세요:

  • Console 탭: 프런트엔드 문제를 알려줍니다;
  • Network 탭: /mcp나 정적 자원 요청이 실패하는지 확인할 수 있습니다(나중에 ChatGPT를 연결할 때 유용).

이제 오류와 로그를 어디서 확인할지 알았으니, 간단한 실습 시나리오로 정리해 봅시다.

8. 작은 실습: 첫 ChatGPT App 가동

짧은 실습 시나리오로 모두 묶어 봅니다.

  1. node -v가 최소 20.9 이상(가능하면 22+)인지 확인.
  2. git --version과 npm -v가 정상적으로 응답하는지 확인.
  3. 공식 템플릿을 study-buddy-app 폴더(또는 여러분이 정한 이름)로 클론.
  4. 해당 폴더에서 npm install 실행.
  5. .env.local을 만들고 OPENAI_API_KEY=... 설정.
  6. npm run dev 실행 후 브라우저에서 http://localhost:3000 열기.

모두 성공했다면 — 아직 ChatGPT에 연결되지는 않았더라도 — 가장 간단한 ChatGPT App이 이미 준비된 것입니다.

코드를 조금 “느껴보고” 싶다면, 에디터에서 페이지의 메인 React 컴포넌트(보통 app/page.tsx)를 열어 아래와 유사한 코드를 확인해 보세요: 

export default function Page() {
  return (
    <main>
      <h1>HelloWorld — ChatGPT App</h1>
      <p>Two actions only: fetch data from <code>/api/time</code> and open an external link.</p>
    </main>
  );
}

지금은 굳이 수정하지 않아도 됩니다 — 다음 강의에서 프로젝트 구조를 차근차근 살펴보고 우리의 학습 시나리오에 맞게 커스터마이즈해 보겠습니다.

9. 템플릿 다운로드·실행 시 흔한 실수

오류 №1: 공식 프로젝트 대신 “아무 리포지토리”를 사용.
가끔 학생들이 GitHub에서 “근사한 ChatGPT 스타터”를 찾아 그걸로 강의를 시작합니다. 문제는 그 프로젝트의 구조, Next.js/Apps SDK 버전이 강의가 기반으로 삼는 공식 프로젝트와 크게 다를 수 있다는 점입니다. 이 강의에서는 먼저 공식 프로젝트를 익힌 뒤에 다른 템플릿을 시도합니다.

오류 №2: Node.js 버전 요구 사항을 무시.
“난 3년째 Node 16으로 잘 쓰고 있는데, 왜 업데이트하지?” — 라고 했다가 한 시간 동안 난해한 빌드 오류를 읽게 됩니다. Next.js 16과 최신 Apps SDK는 최신 Node를 요구합니다. 강의자의 고집이 아니라 Next.js 문서에 명확히 적혀 있습니다.

오류 №3: .env와 node_modules를 저장소에 커밋.
고전입니다. 실수로 .env나 node_modules를 .gitignore에서 빼고 GitHub에 올리면, 잘해야 코드 리뷰에서 지적받고, 최악의 경우 OPENAI_API_KEY가 유출됩니다. 템플릿이 이미 이를 방지하도록 설정되어 있지만, .gitignore 내용을 확인하고 불필요하게 수정하지 마세요.

오류 №4: .env 수정 후 dev 서버 재시작을 잊음.
Next.js는 프로세스 시작 시 환경 변수를 읽습니다. .env.local에 OPENAI_API_KEY를 추가했지만 npm run dev를 재시작하지 않으면, 서버는 이전의 빈 값으로 계속 실행됩니다. 실제로 매우 자주 일어나는 혼선이므로, .env를 바꾼 뒤에는 dev 서버를 꼭 재시작하세요.

오류 №5: 포트/동기화 문제를 IDE “마법 재시작”으로 해결하려 함.
포트 충돌이나 잘못된 Node 버전 문제에서, 일부 개발자는 에디터를 껐다 켰다 하거나 컴퓨터를 재부팅하며 기도(?)합니다. 그러나 보통 문제는 훨씬 단순합니다. 3000 포트를 비우고, Node를 업데이트하고, 터미널의 오류 메시지를 읽으세요. dev 서버는 무엇이 불만인지 비교적 솔직하게 말해줍니다 — 읽기만 하면 됩니다.

코멘트
TO VIEW ALL COMMENTS OR TO MAKE A COMMENT,
GO TO FULL VERSION