Downloading and exploring ChatGPT App (Next.js 16)

1. Introduction

The goal of this lecture is simple but vital: take you from zero to “I have a working ChatGPT App running locally, I see the page in my browser, and nothing crashed.”

We will not dig deep into Next.js code, we will not configure Dev Mode in ChatGPT, and we will not set up a tunnel yet—those are the next lectures in the module. Today we focus on three things:

1. Prepare the environment: Node.js, npm, Git, editor, basic checks so that Next.js 16 doesn’t die on your Node version.
2. Download a working ChatGPT App on Next.js 16: either via git clone or through a GitHub template/CLI.
3. Install dependencies, set up .env with OPENAI_API_KEY, and run npm run dev, ensuring your http://localhost:3000 is up and healthy.

If by the end of the lecture you see the template’s start page in the browser and the dev server in the terminal without red errors—consider that you already have your own working ChatGPT App.

2. Minimal developer environment

Let’s start with infrastructure. Without it, no trendy LLMs will help—Next.js simply won’t run.

Node.js and npm

The modern Apps SDK template on Next.js 16 requires a current Node. Aim for the LTS line—right now, for example, Node 24 LTS. The minimally acceptable version is 20.9; Next.js 16 is officially supported from there.

Check versions in the terminal:

node -v
npm -v

If instead of a neat v24.x.x you see, say, v16.13.0, there’s a good chance the template won’t even install dependencies or Next.js will complain: that Node version is not supported.

You can update “the simple way”—via the official Node.js installer for your OS—or, if you’re already a more advanced Linux/macOS user, via nvm/fnm. Within this course we won’t go deep into version managers; the main thing is to get a live LTS version.

Git

We’ll need Git to obtain the template and later commit your changes. Check:

git --version

If the command isn’t found, install Git (Windows installer, Homebrew on macOS, a package manager on Linux). Git isn’t critical just to run the App, but working without it in 2025 is like writing TypeScript without knowing what an interface is.

Code editor

Default recommendation—WebStorm. JavaRush has a special plugin for it so you can solve tasks in a couple of clicks. It’s effectively the de facto standard for frontend and Node.

You can use VS Code as well; in that case, it’s advisable to install basic extensions:

• TypeScript/JavaScript support;
• ESLint (the template is often already configured for the linter).

This will make your life easier when we start editing the template’s code.

OpenAI / ChatGPT account and API key

For this lecture, it’s enough to have access to ChatGPT in the browser (under your account). We’ll connect Dev Mode later, but it’s good to make sure now that you can log into the web interface and that there is a tab with Developer features (Plus/Team/Enterprise depending on OpenAI’s current policy).

In the future you’ll need an OpenAI API key (OPENAI_API_KEY). Our first project can start without it: the initial UI is fully static. But we’ll still use the key in this lecture and place it into an .env file—we’ll cover how to do this and why it’s safer.

You get the key in the OpenAI dashboard, store it as a secret, don’t commit it, and treat it like a passport number—only stricter.

3. Where to get a working ChatGPT App

Now the fun part: take a ready starter that’s already set up as a ChatGPT App.

Why this project

It’s a very simple Next.js 16 project that combines two roles in one repository: a UI widget and an MCP server.

The structure is already prepared:

• there’s a React page that will render as a widget;
• there’s an MCP server endpoint that ChatGPT will hit for tools;
• there’s a ready Next.js configuration (including important details like assetPrefix for correct asset loading inside the ChatGPT iframe).

That’s much better than building everything from scratch.

Option 1: clone the Git repository

The most straightforward way:

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

The repository name may differ slightly in the future, so before copying the command, it’s worth checking the current link in the official documentation or the comments under this lecture.

The git clone command will create a my-chatgpt-app folder with the full template content and an already configured Git repository.

Option 2: the “Use this template” button on GitHub

If you want to immediately have your own repository on GitHub, you can:

1. Open the template’s page on GitHub.
2. Click the “Use this template” button.
3. Create your own repository based on the template, for example username/study-buddy-chatgpt-app.
4. Then clone your repository.

Essentially, the result is the same: locally you’ll have a folder with the template code, but the Git remote will point not to the CodeGym repository, but to your own.

Option 3: CLI template

Most likely, an official CLI tool from OpenAI will appear in the future, something like:

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

It isn’t there yet, because ChatGPT apps have only begun to evolve. But by the time you read this, something like that may already exist. Be sure to look for such a command in the official Apps SDK documentation.

The logic is the same: the CLI just downloads and unpacks the same or a very similar template. That’s how it worked for creating ChatGPT plugins, so I think an app generator will appear over time as well.

4. Installing dependencies and a first look at the project

Let’s assume you already have a my-chatgpt-app folder with a working project. Time to install dependencies.

npm install

Go to the project folder and install dependencies:

cd my-chatgpt-app
npm install

The script will read package.json, which already lists the required packages: Next.js, React, Tailwind, Apps SDK, and MCP SDK (@modelcontextprotocol/sdk).

As a result, a node_modules directory will appear—the very monster of hundreds of megabytes that we never commit to Git. It’s usually already added to .gitignore in the template, so you don’t need to configure anything extra.

If something fails during installation, don’t panic: we’ll cover typical issues a bit later.

Mini tour of the contents

Right now you don’t need to dive into the folder structure—that’s the topic of the next lecture, where we’ll go over what’s where in detail. But it’s useful to at least glance at the project root:

• package.json — the list of dependencies and scripts.
• next.config.ts — the Next.js config with extra settings for running inside ChatGPT.
• tsconfig.json — TypeScript configuration.
• app/ — where the main UI code and MCP routes live.

Next time we’ll turn this “dark forest” into a readable map.

5. Setting up .env and OPENAI_API_KEY

We mentioned earlier that the first template doesn’t require OPENAI_API_KEY, but it will be used in the future, so let’s do it properly right away: via .env. Normal people don’t hardcode secrets—and we’ll try to be normal too.

Why you need .env

The template uses an environment file .env.local, from which Next.js picks up environment variables.

Usually the repository either contains .env.example or the README describes which variables to set. In our case, the minimum will be OPENAI_API_KEY:

OPENAI_API_KEY=sk-your-openai-key

It’s recommended to use .env.local so that local secrets don’t get mixed with production settings.

Importantly, .env.local is already added to .gitignore, meaning Git won’t see it and accidentally add it to a commit. Still, double-check that .gitignore really has a line .env*.

Where to get and how to store the OpenAI API key

The API key is created in the OpenAI panel; it usually starts with sk-. Then follow the classic IT hygiene rules:

• don’t publish the key on GitHub or send it in chats;
• don’t paste it into code samples on forums;
• if you suspect a leak—rotate it (key rotation is a topic for the security modules).

For this lecture it’s only important that the key is correctly placed in .env.local and available via process.env.OPENAI_API_KEY on the server side when needed.

Notes for different OSes

There are a few small gotchas that are easy to step on:

• On Windows, if you decide to set environment variables not via .env but directly in the command line, you’ll need to use set VAR=VALUE && command, not export.
• Make sure .env.local is in the project root and named correctly: .env or .env.local, without .txt or other “improvements” from the editor.

6. First run: npm run dev and localhost:3000

Now the pleasant part: let’s check that everything builds and the project starts.

Start the dev server

In the project root, run:

npm run dev

This command starts Next.js in development mode. In the terminal you’ll see roughly the following:

• project build (using Turbopack for a fast dev mode);
• a line like Ready in Xs and a message that the server is listening on port 3000;
• the address http://localhost:3000 as the local URL.

If red error messages appear—don’t immediately scroll them away, try to read them: Next is pretty good at telling you what it’s missing (Node version, dependencies, etc.).

Open in the browser

Then open in a browser:

http://localhost:3000

If everything went well, you’ll see the project’s start page. In different versions it may look slightly different, but there’s usually some header like “Your ChatGPT App” or a minimal widget description.

At this stage we only care about one thing: the page opens, doesn’t crash with a 500 error, and doesn’t show a giant stack trace.

Later we’ll see that the project may have a distinction between the “home page” (landing) and the widget page that’s actually embedded into ChatGPT via an iframe. For now, the whole site is just a very expensive way to show “Hello, world.”

The picture of what’s happening

To understand the big picture, it’s helpful to look at a simplified diagram:

+-----------------------------+
|      Your computer          |
|                             |
|  +-----------------------+  |
|  |  Next.js dev server   |  |
|  |  (npm run dev)        |  |
|  +----------+------------+  |
|             |               |
|   http://localhost:3000     |
|             |               |
|      Browser (Chrome)       |
+-------------+---------------+

ChatGPT and the tunnel will come later—so far you interact directly with the local Next.js via the browser.

ChatGPT isn’t involved here at all yet. And that’s good: fewer moving parts—easier to debug.

7. Mini diagnostics: what to do if something goes wrong

Experience shows: if someone got everything running on the first try, they probably failed three times before on the same setup. So let’s cover common problems.

Port 3000 is in use

One of the most frequent errors: you run npm run dev, and Next.js complains about something like EADDRINUSE: address already in use 0.0.0.0:3000. This means port 3000 is already in use by another process.

Possible causes:

• in another terminal there’s already an npm run dev running from this or another project;
• there’s another server running on the same port (less common, but it happens).

Solutions:

• find and kill the old process (often it’s enough to close the other terminal with the dev server);
• start the dev server on another port, for example:

PORT=3001 npm run dev

On Windows it would look like this:

set PORT=3001 && npm run dev

Don’t forget to open http://localhost:3001 in the browser then.

Node.js is too old

If you have Node 16 or early 18, Next.js 16 may clearly say that such a Node isn’t supported, or npm install will fail with an incompatibility error. Next 16 docs require Node no lower than 20.9, and preferably the latest LTS.

In this case there are no options: you’ll have to update Node. That’s faster than trying to work around Next.js 16 constraints. After updating, it can help to delete the node_modules folder and the lock file (package-lock.json) and run npm install again so dependencies match the new version.

Errors during npm install

If installing dependencies fails:

• make sure the internet is working and registry.npmjs.org isn’t blocked by local settings;
• check your Node version (see above);
• when switching Node versions, it’s worth rebuilding node_modules from scratch.

In most cases the terminal error text tells you which package broke things and often says explicitly: “requires Node >= X.Y.Z”.

An environment variable isn’t being picked up

Sometimes everything starts, but the server complains that OPENAI_API_KEY isn’t set. Check against the checklist below:

• the file is named .env or .env.local, it’s in the project root, and Next.js can see it;
• after adding/changing .env you need to restart the dev server; otherwise it will keep living with old environment values;
• the variable is named exactly OPENAI_API_KEY, without typos.

If you just want to see the project’s page, you can temporarily comment out or disable code that requires the key, but within the course it’s better to learn to store secrets properly right away.

Where to view logs and errors

All build errors and Next.js runtime errors in dev mode are printed to the same terminal where you ran npm run dev. At this stage there isn’t much code, so typical problems are a missing dependency, a wrong .env, or too old a Node.

Also open DevTools in the browser (F12):

• the Console tab will hint if something is wrong on the frontend;
• Network will show if any requests to /mcp or static assets fail (this will be useful later when we connect ChatGPT).

Now that you know where to look for errors and logs, let’s put it all together as a short practical scenario.

8. A little practice: your first ChatGPT App is already running

Let’s put it all together as a short practical scenario.

1. Verify that node -v shows at least 20.9, preferably 22+.
2. Verify that git --version and npm -v respond at all.
3. Clone the official template into a study-buddy-app folder (or whatever you want to name your future App).
4. Run npm install in that folder.
5. Create .env.local with OPENAI_API_KEY=....
6. Run npm run dev and open http://localhost:3000 in the browser.

If everything worked—you can consider that you already have the simplest ChatGPT App, even if it isn’t connected to ChatGPT yet.

To “feel” the code a bit, you can open the main React component of the page in the editor (usually app/page.tsx) and see something very close to:

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>
  );
}

You don’t have to touch it yet—we’ll carefully review the project structure in one of the next lectures and start adapting it to our learning scenario.

9. Typical mistakes when downloading and running the template

Error #1: using some random repository instead of the official project.
Sometimes students find a “cool ChatGPT starter” on GitHub and start the course with it. The problem is that the structure, Next.js versions, and Apps SDK versions there can differ greatly from the official project the course is based on. In this course we first master the official project, and only then experiment with other templates.

Error #2: ignoring the Node.js version requirements.
“I’ve been running fine on Node 16 for three years; why update?” says a developer, and then spends an hour reading strange build errors. Next.js 16 and the modern Apps SDK require a current Node, and this isn’t the course authors’ whim: Next.js documentation says so explicitly.

Error #3: committing .env and node_modules to the repository.
A classic. If you accidentally remove .env or node_modules from .gitignore and commit all of this to GitHub, at best you’ll be scolded in review; at worst your OPENAI_API_KEY will leak. The template is already set up to prevent this, but it’s always useful to check the contents of .gitignore and not change it unless necessary.

Error #4: forgetting to restart the dev server after changing .env.
Next.js reads environment variables at process start. If you added OPENAI_API_KEY to .env.local but didn’t restart npm run dev, the server will continue to live with old empty values, and you’ll wonder why the key “isn’t visible.” In practice this is one of the most common causes of confusion, so don’t forget to restart the dev server after edits to .env.

Error #5: trying to solve sync and port problems with “magical” IDE restarts.
Sometimes when a port conflict or wrong Node version happens, developers start closing/opening the editor, rebooting the computer, praying, etc. The problem is usually solved much more prosaically: free up port 3000, update Node, and read the error text in the terminal. The dev server is quite honest about what it doesn’t like—you just need to take the time to read it.