Baixando e explorando o ChatGPT App (Next.js 16)

1. Introdução

O objetivo desta aula é simples, mas essencial: levar você do zero até o estado “tenho um ChatGPT App funcionando localmente, vejo a página no navegador e nada quebrou”.

Não vamos nos aprofundar no código do Next.js, não vamos configurar o Dev Mode no ChatGPT e ainda não vamos levantar um túnel — isso fica para as próximas aulas do módulo. Hoje, focamos em três coisas:

1. Preparar o ambiente: Node.js, npm, Git, editor, checagens básicas, para que o Next.js 16 não “morra” na sua versão do Node.
2. Baixar um ChatGPT App funcional em Next.js 16: via git clone ou por meio de um template/CLI do GitHub.
3. Instalar dependências, configurar o .env com OPENAI_API_KEY e executar npm run dev, garantindo que seu http://localhost:3000 esteja vivo e saudável.

Se ao final da aula você vir a página inicial do template no navegador e o servidor de desenvolvimento no terminal sem erros em vermelho — considere que você já tem seu ChatGPT App funcional.

2. Ambiente mínimo de desenvolvimento

Vamos começar pela infraestrutura. Sem ela, nenhuma LLM da moda vai ajudar — o Next.js simplesmente não vai iniciar.

Node.js e npm

O template atual do Apps SDK em Next.js 16 exige um Node atualizado. Mire na linha LTS — neste momento, por exemplo, Node 24 LTS. A versão mínima aceitável é 20.9, a partir da qual o Next.js 16 é oficialmente suportado.

Verifique as versões no terminal:

node -v
npm -v

Se, em vez de um v24.x.x bonitinho, você vê, digamos, v16.13.0, é bem provável que o template nem consiga instalar as dependências ou que o Next.js reclame: essa versão do Node não é suportada.

A atualização pode ser “de forma simples” — pelo instalador oficial do Node.js para o seu SO — ou, se você já é um usuário avançado de Linux/macOS, via nvm/fnm. No âmbito do curso, não vamos nos aprofundar em gerenciadores de versões; o principal é ter uma versão LTS funcional.

Git

Precisaremos do Git para obter o template e, no futuro, commitar suas mudanças. Verificação:

git --version

Se o comando não for encontrado, é preciso instalar o Git (instalador para Windows, Homebrew no macOS, gerenciador de pacotes no Linux). Para rodar o App em si, o Git não é crítico, mas trabalhar sem ele em 2025 é mais ou menos como escrever em TypeScript sem saber o que é uma interface.

Editor de código

A recomendação padrão é o WebStorm. Existe um plugin especial do JavaRush para ele, para você resolver tarefas em poucos cliques. Na prática, é o “padrão de fato” para frontend e Node.

Você também pode usar o VS Code; nesse caso, é bom instalar extensões básicas:

• suporte a TypeScript/JavaScript;
• ESLint (o template geralmente já vem configurado para o linter).

Isso facilitará sua vida quando começarmos a ajustar o código do template.

Conta OpenAI / ChatGPT e chave de API

Para esta aula, basta ter acesso ao ChatGPT no navegador (na sua conta). Vamos conectar o Dev Mode depois, mas já é bom garantir que você consegue entrar na interface web e que existe uma aba com funções de desenvolvedor (Plus/Team/Enterprise, dependendo da política atual da OpenAI).

No futuro, você vai precisar de uma chave de API da OpenAI (OPENAI_API_KEY). Nosso primeiro projeto pode subir até sem ela: a UI inicial é totalmente estática. Mas ainda assim vamos usar a chave nesta aula e colocá‑la no arquivo .env — abaixo veremos como fazer isso e por que é mais seguro.

A chave é obtida no painel da OpenAI, é armazenada como segredo, não vai para o repositório e, no geral, tratamos dela como se fosse o número do passaporte — só que com mais cuidado ainda.

3. Onde obter um ChatGPT App funcional

Agora — a parte mais agradável: vamos pegar um projeto inicial pronto, já configurado como ChatGPT App.

Por que exatamente este projeto

É um projeto bem simples em Next.js 16, que combina dois papéis em um único repositório: um widget de UI e um servidor MCP.

A estrutura já está preparada:

• há uma página React que será renderizada como widget;
• há um endpoint do servidor MCP ao qual o ChatGPT vai se conectar para ferramentas;
• há uma configuração pronta do Next.js (incluindo detalhes importantes como assetPrefix para carregar assets corretamente dentro do iframe do ChatGPT).

Isso é bem melhor do que montar tudo do zero.

Opção 1: clonar o repositório Git

O caminho mais direto:

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

O nome do repositório pode mudar no futuro, então, antes de copiar o comando, vale a pena conferir o link mais atual na documentação oficial ou nos comentários desta aula.

O comando git clone criará a pasta my-chatgpt-app com todo o conteúdo do template e um repositório Git já configurado.

Opção 2: botão “Use this template” no GitHub

Se você quer ter seu próprio repositório no GitHub desde já, você pode:

1. Abrir a página do template no GitHub.
2. Clicar no botão “Use this template”.
3. Criar seu repositório com base no template, por exemplo username/study-buddy-chatgpt-app.
4. Depois, clonar o seu repositório.

No fim, o resultado é o mesmo: localmente você terá uma pasta com o código do template, mas o Git‑remote apontará para o seu repositório, e não para o do CodeGym.

Opção 3: template via CLI

É provável que, no futuro, apareça uma ferramenta oficial de CLI da OpenAI, algo como:

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

Ainda não existe, pois os aplicativos para o ChatGPT começaram a evoluir recentemente. Mas é bem possível que, quando você estiver lendo esta aula, algo assim já tenha surgido. Procure por esse comando na documentação oficial do Apps SDK.

A lógica é a mesma: o CLI só baixa e monta o mesmo template (ou um muito parecido). Já foi assim na criação de plugins para o ChatGPT, então é bem provável que surja o equivalente para aplicativos.

4. Instalando dependências e primeira olhada no projeto

Vamos supor que você já tenha a pasta my-chatgpt-app com o projeto funcional. Hora de instalar as dependências.

npm install

Entre na pasta do projeto e instale as dependências:

cd my-chatgpt-app
npm install

O script vai ler o package.json, no qual já estão listados os pacotes necessários: Next.js, React, Tailwind, Apps SDK e MCP SDK (@modelcontextprotocol/sdk).

Como resultado, surgirá a pasta node_modules — aquele “monstro” de centenas de megabytes que nunca commitamos no Git. Normalmente ela já está no .gitignore do template, então não é preciso configurar nada extra.

Se algo falhar durante a instalação das dependências, não entre em pânico: veremos os problemas típicos um pouco mais abaixo.

Mini‑inspeção do conteúdo

Agora não é necessário se aprofundar na estrutura de pastas — esse é o tema da próxima aula, onde vamos detalhar o que fica onde. Mas é útil dar uma olhada na raiz do projeto:

• package.json — lista de dependências e scripts.
• next.config.ts — config do Next.js com ajustes extras para funcionar dentro do ChatGPT.
• tsconfig.json — configuração do TypeScript.
• app/ — aqui fica o código principal da UI e as rotas do MCP.

Na próxima vez, vamos transformar essa “floresta escura” em um mapa compreensível.

5. Configuração de .env e OPENAI_API_KEY

Já mencionamos que, para o primeiro template, a OPENAI_API_KEY não é obrigatória, mas será usada depois; portanto, vamos fazer tudo do jeito certo desde já: via .env. Pessoas cuidadosas não “hardcodam” segredos no código — e nós também vamos evitar isso.

Por que usar o .env

O template usa o arquivo de ambiente .env.local, de onde o Next.js lê as variáveis de ambiente.

Geralmente o repositório traz um .env.example ou o README descreve quais variáveis você precisa definir. No nosso caso, o mínimo é a OPENAI_API_KEY:

OPENAI_API_KEY=sk-sua-chave-da-OpenAI

Recomenda‑se usar .env.local para que segredos locais não se misturem com as configurações de produção.

Importante: .env.local já está adicionado ao .gitignore, ou seja, o Git não vai enxergar esse arquivo nem adicioná‑lo por engano ao commit. Ainda assim, vale conferir se no .gitignore existe a linha .env*.

Onde obter e como armazenar a chave de API da OpenAI

A chave de API é criada no painel da OpenAI; normalmente começa com sk-. Depois, siga as regras clássicas de higiene de TI:

• não publique a chave no GitHub nem a envie em chats;
• não a inclua em exemplos de código em fóruns;
• se suspeitar de vazamento — faça a rotação (troque a chave; o tema de rotação entra nos módulos de segurança).

Nesta aula, o importante é que a chave esteja corretamente no .env.local e acessível via process.env.OPENAI_API_KEY no lado do servidor quando for necessário.

Nuances por sistema operacional

Há alguns detalhes em que é fácil tropeçar:

• No Windows, se você quiser definir variáveis de ambiente não via .env, mas diretamente na linha de comando, use set VAR=VALUE && comando, e não export.
• Garanta que o .env.local esteja na raiz do projeto e com o nome correto: .env ou .env.local, sem .txt ou outras “melhorias” do editor.

6. Primeiro lançamento: npm run dev e localhost:3000

Agora vem a parte mais legal: vamos verificar se tudo foi compilado e o projeto inicia.

Iniciando o servidor de desenvolvimento

No diretório raiz do projeto, execute:

npm run dev

Esse comando inicia o Next.js no modo de desenvolvimento. No terminal, você verá algo como:

• build do projeto (usando Turbopack para um dev‑mode rápido);
• uma linha do tipo Ready in Xs e uma mensagem dizendo que o servidor está ouvindo na porta 3000;
• o endereço http://localhost:3000 como URL local.

Se aparecerem mensagens de erro em vermelho — não role a tela para cima imediatamente; tente ler: o Next costuma indicar bem o que está faltando (versão do Node, dependências etc.).

Abrindo no navegador

Em seguida, abra no navegador:

http://localhost:3000

Se tudo deu certo, você verá a página inicial do projeto. Em versões diferentes, ela pode variar um pouco, mas geralmente há algum título como “Your ChatGPT App” ou uma descrição mínima do widget.

Nesta etapa, só importa uma coisa: a página abre, não cai com erro 500 e não mostra um stack trace gigante.

Mais adiante, veremos que o projeto pode ter diferença entre a “página principal” (landing) e a página do widget, que é a que realmente é incorporada ao ChatGPT via iframe. Mas, por enquanto, para nós o site inteiro é só um jeito bem caro de mostrar “Hello, world”.

Figura do que está acontecendo

Para entender o quadro geral, vale olhar um esquema simplificado:

+-----------------------------+
|      Seu computador          |
|                             |
|  +-----------------------+  |
|  |  servidor dev Next.js |  |
|  |  (npm run dev)        |  |
|  +----------+------------+  |
|             |               |
|   http://localhost:3000     |
|             |               |
|      Navegador (Chrome)     |
+-------------+---------------+

O ChatGPT e o túnel virão depois — por enquanto você se comunica diretamente com o Next.js local via navegador.

O ChatGPT ainda não participa aqui. E isso é ótimo: menos partes móveis — mais fácil de depurar.

7. Mini‑diagnóstico: o que fazer se algo der errado

A experiência mostra: se alguém conseguiu subir tudo de primeira, provavelmente já caiu três vezes naquela mesma configuração antes. Então, vamos ver os problemas típicos.

Porta 3000 ocupada

Um dos erros mais comuns: você executa npm run dev, e o Next.js reclama com algo como EADDRINUSE: address already in use 0.0.0.0:3000. Isso significa que a porta 3000 já está em uso por outro processo.

Possíveis causas:

• em outro terminal já está rodando um npm run dev deste ou de outro projeto;
• algum outro servidor está usando a mesma porta (menos comum, mas acontece).

Soluções:

• encontrar e encerrar o processo antigo (muitas vezes basta fechar o outro terminal com o servidor em dev);
• iniciar o servidor de desenvolvimento em outra porta, por exemplo:

PORT=3001 npm run dev

No Windows, a variante fica assim:

set PORT=3001 && npm run dev

Não se esqueça de abrir no navegador http://localhost:3001.

Node.js muito antigo

Se você usa Node 16 ou um 18 muito inicial, o Next.js 16 pode simplesmente dizer que essa versão do Node não é suportada, ou o npm install pode falhar com erro de incompatibilidade. A documentação do Next 16 exige Node a partir de 20.9; melhor ainda usar o LTS mais recente.

Nesse caso, não há alternativa: é preciso atualizar o Node. Isso é mais rápido do que tentar contornar as limitações do Next.js 16. Após atualizar, às vezes é útil apagar a pasta node_modules e o lock file (package-lock.json) e executar novamente npm install, para que as dependências se adequem à nova versão.

Erros durante o npm install

Se a instalação das dependências falhar:

• garanta que a internet está funcionando e que registry.npmjs.org não está bloqueado por configurações locais;
• verifique a versão do Node (veja acima);
• ao trocar a versão do Node, pode ser interessante reconstruir o node_modules do zero.

Na maioria dos casos, o texto do erro no terminal indica em qual pacote tudo quebrou e muitas vezes escreve algo como: “precisa do Node >= X.Y.Z”.

Variável de ambiente não é carregada

Acontece de tudo iniciar, mas o servidor reclamar que a OPENAI_API_KEY não está definida. Verifique o checklist abaixo:

• o arquivo se chama .env ou .env.local, está na raiz do projeto e o Next.js consegue vê‑lo;
• após adicionar/alterar o .env, é preciso reiniciar o servidor de desenvolvimento; caso contrário, ele continuará com os valores antigos;
• a variável está escrita exatamente como OPENAI_API_KEY, sem erros de digitação.

Se você só quer ver a página do projeto, pode comentar temporariamente partes do código que exigem a chave; mas, dentro do curso, é melhor já aprender a armazenar segredos do jeito certo.

Onde ver logs e erros

Todos os erros de build e de runtime do Next.js em modo de desenvolvimento aparecem no mesmo terminal onde você executou npm run dev. Nesta fase, há pouco código, então os problemas típicos são dependência ausente, .env incorreto ou Node muito antigo.

Também vale abrir as DevTools no navegador (F12):

• a aba Console ajuda se houver algo errado no frontend;
• a aba Network mostra se alguma requisição para /mcp ou estáticos está falhando (isso será útil depois, quando conectarmos o ChatGPT).

Agora que você sabe onde procurar erros e logs, vamos reunir tudo em um pequeno roteiro prático.

8. Pequena prática: seu primeiro ChatGPT App já está no ar

Vamos juntar tudo em um pequeno roteiro prático.

1. Verifique se node -v mostra pelo menos 20.9, idealmente 22+.
2. Verifique se git --version e npm -v respondem algo.
3. Clone o template oficial para a pasta study-buddy-app (ou como preferir nomear seu futuro App).
4. Nessa pasta, execute npm install.
5. Crie .env.local com OPENAI_API_KEY=....
6. Execute npm run dev e abra http://localhost:3000 no navegador.

Se tudo deu certo — você já tem o ChatGPT App mais simples, embora ainda não conectado ao ChatGPT.

Para “sentir” um pouco o código, você pode abrir no editor o componente React principal da página (geralmente app/page.tsx) e ver algo muito parecido com este código:

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

Ainda não é necessário mexer — em uma das próximas aulas, vamos analisar cuidadosamente a estrutura do projeto e começar a adaptá‑lo ao nosso cenário didático.

9. Erros típicos ao baixar e iniciar o template

Erro nº 1: usar um repositório “aleatório” em vez do projeto oficial.
Às vezes, alunos encontram no GitHub algum “starter incrível para ChatGPT” e começam o curso por ele. O problema é que a estrutura, as versões do Next.js e do Apps SDK podem ser bem diferentes do projeto oficial em que o curso se baseia. Dentro deste curso, primeiro dominamos o projeto oficial e só depois experimentamos templates de terceiros.

Erro nº 2: ignorar os requisitos de versão do Node.js.
“Está tudo funcionando no Node 16 há três anos, por que atualizar?” — diz o desenvolvedor e depois passa uma hora lendo erros estranhos de build. O Next.js 16 e o Apps SDK moderno exigem Node recente, e isso não é capricho do autor do curso: está explícito na documentação do Next.js.

Erro nº 3: commitar .env e node_modules no repositório.
Clássico. Se você, por engano, remover .env ou node_modules do .gitignore e commitar tudo no GitHub, no melhor cenário vão te puxar a orelha no review; no pior — sua OPENAI_API_KEY vaza. O template já está configurado para evitar isso, mas é sempre bom conferir o conteúdo do .gitignore e não alterá‑lo sem necessidade.

Erro nº 4: esquecer de reiniciar o servidor de desenvolvimento após mudar o .env.
O Next.js lê variáveis de ambiente na inicialização do processo. Se você adicionou OPENAI_API_KEY ao .env.local mas não reiniciou o npm run dev, o servidor continuará com os valores antigos, e você vai se perguntar por que a chave “não é vista”. Na prática, essa é uma das causas mais comuns de confusão; então não esqueça de reiniciar o servidor de desenvolvimento após alterações no .env.

Erro nº 5: tentar resolver problemas de sincronização e portas com “reinícios mágicos” da IDE.
Às vezes, diante de conflito de porta ou versão incorreta do Node, desenvolvedores começam a fechar/abrir o editor, reiniciar o computador, rezar etc. O problema geralmente se resolve de maneira muito mais prosaica: liberar a porta 3000, atualizar o Node e ler a mensagem de erro no terminal com atenção. O servidor de desenvolvimento é bem honesto ao dizer o que não gostou — basta não ter preguiça de ler.