Implantar um aplicativo Vite/React nas páginas do GitHub é um marco emocionante, mas o processo às vezes pode vir com desafios inesperados, especialmente ao lidar com imagens e ativos. Esta postagem do blog orientará você por todo o processo, desde a implantação inicial até a solução de problemas comuns e a obtenção de soluções eficazes.

Seja você um iniciante ou alguém com experiência, este guia o ajudará a evitar armadilhas comuns e a implantar com sucesso seu aplicativo Vite/React com todos os ativos renderizados corretamente.

Pré-requisitos

Antes de começarmos, certifique-se de ter o seguinte:

• Um projeto Vite/React: Este guia pressupõe que você configurou seu projeto usando Vite como ferramenta de construção e React como estrutura.
• Repositório GitHub: você deve ter um repositório GitHub existente onde enviará seu aplicativo para implantação.
• Páginas do GitHub habilitadas: certifique-se de que o GitHub Pages esteja habilitado nas configurações do seu repositório para implantação.

Etapa 1: inicializar o projeto e a implantação das páginas do GitHub

Primeiro, certifique-se de que seu aplicativo Vite/React esteja inicializado corretamente e funcione no host local. Você pode criar um projeto Vite básico da seguinte maneira:

npm create vite@latest

Instalar dependências:

npm install

Execute o projeto localmente para confirmar que tudo funciona:

npm run dev

Quando seu projeto estiver pronto, envie-o para seu repositório GitHub.

Crie um vite.config.js para páginas do GitHub

O GitHub Pages espera que o aplicativo seja servido a partir de uma URL base específica, que normalmente é o nome do seu repositório. Atualize o arquivo vite.config.js para refletir isto:

import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'

export default defineConfig({
  base: process.env.NODE_ENV === 'production' ? '/your-repo-name/' : '/',
  plugins: [react()],
})

A opção base garante que o aplicativo use o caminho base correto quando implantado.

Etapa 2: construir e implantar o projeto

Você precisará instalar o pacote gh-pages para lidar com a implantação.

npm install gh-pages --save-dev

Em seu package.json, adicione os seguintes scripts para automatizar o processo de implantação:

"scripts": {
  "predeploy": "npm run build",
  "deploy": "gh-pages -d dist"
}

Execute a implantação:

npm run deploy

Neste ponto, seu projeto deve estar ativo em https://.github.io//, mas se você for como eu, poderá ter alguns problemas com o aplicativo não sendo renderizado corretamente ou as imagens não aparecendo.

Etapa 3: Problemas e Soluções Comuns

Problema 1: página em branco após implantação

Após a implantação, você poderá perceber que o aplicativo carrega uma página em branco. Isso geralmente é causado por problemas de roteamento. Por padrão, é usado o BrowserRouter do react-router-dom, que depende do roteamento do lado do servidor, mas o GitHub Pages serve arquivos estáticos e não lida com rotas do lado do cliente.

Solução: use HashRouter

Para resolver isso, mude de BrowserRouter para HashRouter em seu arquivo index.js ou main.jsx.

Nota: Não é necessário que você tenha, é apenas uma biblioteca de UI conveniente que uso com frequência em meus projetos.

import { HashRouter } from 'react-router-dom';

createRoot(document.getElementById('root')).render(
  
);

HashRouter usa um símbolo de hash (#) na URL para acompanhar o estado de navegação, permitindo que GitHub Pages atenda rotas diferentes de maneira adequada sem retornar um 404.

Problema 2: Erro 404 na atualização ou em outras rotas

Depois de corrigir o problema da página em branco, outro problema que você pode enfrentar é o aplicativo funcionar na página inicial, mas mostrar um erro 404 ao navegar para outras rotas, especialmente se você acessar diretamente uma rota como /blogs ou /projects.

Isso acontece porque o GitHub Pages só sabe como servir o arquivo index.html e não reconhece rotas gerenciadas pelo React Router.

Solução: lidar com erros 404 nas configurações de páginas do GitHub

Para corrigir isso, você precisa criar um arquivo 404.html em sua pasta public/. Este arquivo garantirá que o GitHub Pages forneça seu arquivo index.html para quaisquer rotas que ele não reconheça, permitindo que o React Router lide com o roteamento:

1. Copie seu index.html para um novo arquivo chamado 404.html.
2. Coloque este arquivo em sua pasta public/.
3. Reconstrua e reimplante o projeto.

Problema 3: imagens não são carregadas na produção

Um dos problemas de implantação mais comuns é que as imagens não carregam corretamente. Embora funcionem bem no host local, você pode notar links de imagens quebrados após a implantação nas páginas do GitHub.

Por exemplo, você pode fazer referência a uma imagem como esta em seus componentes:

Problema: caminhos de imagem incorretos

O problema aqui é que caminhos absolutos (começando com /) não funcionam bem quando o aplicativo é implantado em um subdiretório (por exemplo, /nome-do-seu-repo/). GitHub Pages tenta encontrar a imagem em https://.github.io/Images/myImage.png em vez de https://.github.io/your-repo-name/Images/myImage.png , resultando em um erro 404.

Solução: use BASE_URL

Para corrigir isso, mova todas as suas imagens para Pública/Imagens, embora isso seja opcional, eu recomendo fortemente que você faça isso. Você acrescentará dinamicamente o BASE_URL aos caminhos da imagem com base no ambiente:

1. Defina uma constante BASE_URL que depende do ambiente:

   const BASE_URL = import.meta.env.BASE_URL;

1. Use este BASE_URL ao referenciar imagens:

NOTA: Não se esqueça de remover o / da frente de Imagens, caso contrário você terá ele duplicado, um do BASE_URL e outro do /Imagens que você esqueceu de remover.

Isso garante que o caminho correto seja usado tanto no desenvolvimento (localhost) quanto na produção (páginas do GitHub).

Etapa 4: implantação final

Depois de implementar as correções para roteamento e caminhos de imagem, reconstrua e reimplante seu aplicativo:

npm run build
npm run deploy

Seu aplicativo Vite/React agora deve estar totalmente implantado com todas as imagens renderizadas corretamente e todas as rotas tratadas corretamente.

Resumindo:

1. Problemas de roteamento: Use HashRouter para roteamento adequado em implantações estáticas como GitHub Pages.
2. Erros 404 em rotas: Crie um arquivo 404.html para garantir que o GitHub Pages sirva seu aplicativo corretamente.
3. Imagens que não carregam: Mova todas as imagens para Pública/Imagens e anexe dinamicamente BASE_URL aos caminhos dos seus ativos para lidar com ambientes de desenvolvimento e produção.

Com essas etapas, seu aplicativo Vite/React deve estar ativo e funcionando perfeitamente nas páginas do GitHub. Boa codificação e implantação!