O GitHub Pages oferece uma maneira simples e gratuita de hospedar sites estáticos, sendo uma excelente opção para publicar aplicações React. Este guia orienta você no processo de publicar um projeto Create React App no GitHub Pages, personalizar seu domínio e automatizar implantações com GitHub Actions.

Início Rápido: Publique seu App React em 3 passos

Se você já tem um projeto Create React App e um repositório no GitHub, pode publicar seu app com esses três passos rápidos:

1. Instalar o pacote gh-pages

npm install gh-pages --save-dev

2. Atualizar seu package.json

{"homepage": "https://seuusuario.github.io/nome-do-repo", "scripts": {"predeploy": "npm run build", "deploy": "gh-pages -d build", // outros scripts...}}

3. Publicar seu app

npm run deploy

Pronto! Seu app estará disponível em https://seuusuario.github.io/nome-do-repo.

Nota: Este guia é focado em projetos Create React App. Se estiver usando Vite, Next.js ou outro framework, o processo será diferente. Para projetos Vite, confira o guia oficial de deployment do Vite. Para Next.js, consulte a documentação de deployment do Next.js.

Problemas comuns e soluções

Ao publicar apps React no GitHub Pages, você pode enfrentar alguns problemas comuns. Veja como diagnosticá-los e resolvê-los:

Página em branco após publicação

Se você vê uma página em branco em vez do seu app:

1. Verifique a URL do homepage — Certifique-se de que a propriedade homepage no package.json corresponda exatamente ao formato da URL do GitHub Pages (https://username.github.io/repo-name).

2. Verifique erros no console do navegador — Abra as ferramentas de desenvolvedor no seu navegador para ver se há erros relacionados ao carregamento de recursos.

Adicionando um domínio personalizado

Podemos publicar nosso app React no domínio do GitHub gratuitamente, mas o GitHub Pages também suporta subdomínios personalizados e domínios apex. Aqui estão exemplos de como cada tipo de subdomínio se parece:

Atualmente, se navegarmos para https://seuusuario.github.io/nome-do-repo/, veremos nosso site recém-publicado. Mas também podemos usar um subdomínio personalizado ou um domínio apex. Aqui estão os passos para configurá-los:

Publicando em um subdomínio personalizado do GitHub

1. Compre um nome de domínio de um provedor de serviços de domínio de sua escolha (por exemplo, Namecheap ou GoDaddy).
2. Conecte o domínio personalizado ao GitHub Pages. Para fazer isso, clique no menu Pages na aba Settings. Em seguida, role para baixo até o campo Custom domain e insira o nome do domínio recém-adquirido. Isso criará automaticamente um commit com um arquivo CNAME na raiz do seu repositório: