レッスン
開始
勉強を始める
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 を設定したり、トンネルを立てたりはしません—それらは次の講義で扱います。今日は次の 3 点に集中します。

  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 が未対応と怒る可能性が高いです。

更新は簡単です—OS 用の公式 Node.js インストーラーを使うか、すでに上級の Linux/macOS ユーザーなら nvm/fnm を使っても構いません。本講義ではバージョンマネージャーの細かい話はしません。重要なのは LTS が動いていることです。

Git

テンプレートの取得や、今後の変更のコミットに Git が必要です。確認: 

git --version

コマンドが見つからない場合は Git をインストールしてください（Windows インストーラー、macOS は Homebrew、Linux はパッケージマネージャーなど）。アプリの起動自体には必須ではありませんが、2025 年に Git なしで開発するのは、TypeScript でインターフェースを知らずに書くようなものです。

コードエディター

デフォルトのおすすめは WebStorm です。JavaRush には、課題を数クリックで解ける専用プラグインがあります。実質、フロントエンドや Node の「デファクトスタンダード」です。

もちろん VS Code でも構いません。その場合は基本的な拡張機能を入れておくとよいでしょう:

  • TypeScript/JavaScript のサポート;
  • ESLint（テンプレートにはすでにリンター設定が入っていることが多い）。

テンプレートのコードを編集し始めたときに役立ちます。

OpenAI / ChatGPT アカウントと API キー

今回の講義では、ブラウザーから ChatGPT にアクセスできれば十分です（自分のアカウントで）。Dev Mode の接続は後で行いますが、今のうちに Web インターフェースへログインでき、Developer 機能のタブがあるか（Plus/Team/Enterprise など、OpenAI のポリシーに依存）確認しておくとよいでしょう。

今後は OpenAI の API キー（OPENAI_API_KEY）が必要になります。最初のプロジェクトはキーなしでも起動できます。初期 UI は完全に静的だからです。ただし本講義でもキーを使い、.env ファイルに保存します—どのように安全に設定するかは後ほど説明します。

キーは OpenAI のコンソール で発行し、秘密として保管します。リポジトリには入れません。扱いはパスポート番号以上に慎重に。

3. 動作する ChatGPT App はどこから入手するか

では一番楽しいところです。すでに ChatGPT App として設定済みのスタータープロジェクトを使います。

なぜこのプロジェクトなのか

これは Next.js 16 上の非常にシンプルなプロジェクトで、1 つのリポジトリで UI ウィジェットと MCP サーバーの 2 つの役割を兼ねています。

すでに構成が用意されています:

  • ウィジェットとしてレンダリングされる React ページがある;
  • ChatGPT がツール用にアクセスする MCP サーバーのエンドポイントがある;
  • Next.js の設定が整っている（ChatGPT の iframe でアセットが正しく読み込まれるよう、assetPrefix などの重要な設定を含む）。

ゼロから全部組み立てるよりはるかに良いです。

方法 1: Git リポジトリを clone する

最も手っ取り早い方法:

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. その後は自分のリポジトリを clone する。

結果は同じですが、ローカルのフォルダーはテンプレートのコードを含み、Git のリモートは 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- で始まります。以下の IT 衛生の基本に従いましょう:

  • キーを 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

ではいよいよ、ビルドと起動を確認します。

開発サーバーを起動

プロジェクトのルートで実行します:

npm run dev

このコマンドで Next.js が開発モードで起動します。ターミナルには次のような表示が出ます:

  • プロジェクトのビルド（開発モードでは Turbopack を使用）;
  • Ready in Xs のような行と、サーバーがポート 3000 をリッスンしている旨;
  • ローカル URL としての http://localhost:3000。

赤いエラーメッセージが出たときは、すぐスクロールせずに内容を読みましょう。Next は足りないもの（Node のバージョンや依存など）を比較的親切に教えてくれます。

ブラウザーで開く

次を開きます:

http://localhost:3000

成功すれば、スターターページが表示されます。バージョンにより見た目は少し異なりますが、多くの場合「Your ChatGPT App」のような見出しや、最小限のウィジェット説明が表示されます。

この段階で重要なのは 1 点だけです。ページが開き、500 エラーで落ちたり巨大なスタックトレースを表示しないこと。

後でわかりますが、プロジェクトには「ランディングページ」と、ChatGPT に iframe として実際に埋め込まれるページ（ウィジェット）の違いがあるかもしれません。とはいえ今は、サイト全体がとてもぜいたくな「Hello, world」表示装置だと思って構いません。

全体像のイメージ

全体像をつかむため、簡略化した図を見ておきましょう:

+-----------------------------+
|      あなたのコンピューター  |
|                             |
|  +-----------------------+  |
|  |  Next.js dev サーバー |  |
|  |  (npm run dev)        |  |
|  +----------+------------+  |
|             |               |
|   http://localhost:3000     |
|             |               |
|     ブラウザー (Chrome)     |
+-------------+---------------+

ChatGPT とトンネルは後で登場します—いまはブラウザー経由でローカルの Next.js と直接やり取りしています。

ここではまだ ChatGPT は一切関与しません。これは良いことです。動く部品が少ないほどデバッグが簡単だからです。

7. ミニ診断: うまくいかなかったときは

経験上、最初からすべてがうまくいく人は、同じ構成で過去に 3 回は失敗しています。そこで、典型的な問題を見ていきます。

ポート 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 はその Node をサポートしていないと伝えてきたり、npm install が互換性エラーで失敗するかもしれません。Next 16 のドキュメントでは Node 20.9 以上（できれば最新の LTS）が必要です。

この場合は選択肢はありません。Node を更新しましょう。これは Next.js 16 の制限を回避しようとするよりずっと速いです。更新後は、node_modules とロックファイル（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 になっている（タイプミスがない）。

とりあえずページだけ見たいなら、キーを要求するコードを一時的にコメントアウトしても構いませんが、本講義では秘密情報を正しく保管する習慣を身につけましょう。

ログとエラーの見方

開発モードの Next.js では、ビルドエラーや実行時エラーは、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（または好きな名前）というフォルダーに clone。
  4. そのフォルダーで npm install を実行。
  5. .env.local を作成し、OPENAI_API_KEY=... を設定。
  6. npm run dev を実行し、ブラウザーで http://localhost:3000 を開く。

すべてうまくいったなら、最もシンプルな ChatGPT App がもう手元にあります（まだ ChatGPT には接続していませんが）。

コードに少し触れてみたい場合は、エディターでページのメイン 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 のバージョン要件を無視する。
「Node 16 で 3 年間ずっと動いているのに、なぜ更新が必要なの？」—そして 1 時間、奇妙なビルドエラーを読むことになります。Next.js 16 と最新の Apps SDK は新しい Node を必要とします。これは講義の都合ではなく、Next.js のドキュメントに明記されています。

エラー3：.env と node_modules をリポジトリにコミットしてしまう。
開発あるあるです。誤って .gitignore から .env や node_modules を外し、すべてを GitHub にコミットしてしまうと、最良でもレビューで叱られ、最悪では OPENAI_API_KEY が漏洩します。テンプレート側で防止設定はされていますが、.gitignore の内容を確認し、不要な修正はしないようにしましょう。

エラー4：.env を変更したのに dev サーバーを再起動し忘れる。
Next.js はプロセス起動時に環境変数を読み込みます。.env.local に OPENAI_API_KEY を追加しても、npm run dev を再起動しなければ、サーバーは古い空の値のまま動き続けます。「キーが見えない」原因の筆頭なので、.env を変更したら dev サーバーを再起動することを忘れないでください。

エラー5：同期やポートの問題を IDE の「魔法の」再起動で解決しようとする。
ポート競合や Node のバージョン違いに遭遇すると、エディターを閉じたり開いたり、PC を再起動したり、祈ったりしがちです。ですが、たいていの問題はずっと単純に解決できます。ポート 3000 を空ける、Node を更新する、ターミナルのエラーメッセージを読む。dev サーバーはかなり正直に「何が気に入らないか」を出力してくれます。あとはそれを読めばよいだけです。

コメント
TO VIEW ALL COMMENTS OR TO MAKE A COMMENT,
GO TO FULL VERSION