Migrando do CRA para Vite

O tão amado (ou odiado) pacote Create React App (CRA) deixou de ser mantido desde 2023, confira mais aqui. Isso significa que não irá mais receber nenhuma atualização, tornando-o cada dia mais obsoleto. Embora ainda seja uma opção válida para alguns casos, não é mais recomendado para novas aplicações, assim como para aplicações existentes. A própria documentação do React não recomenda mais o uso do Create React App. O time do React recomenda fortemente meta-frameworks como Next.js ou Remix para novos projetos.

Caso não faça sentido ou sua equipe não tenha recursos suficientes para migrar para um framework mais complexo, como Next.js, pode ser mais interessante considerar opções mais simples, como o Vite.

O que é Vite?

Vite, "rápido" ou "rapidamente" em francês, é uma ferramenta de construção moderna e rápida que se integra com o React. Ele oferece uma experiência de desenvolvimento mais rápida, eficiente e fácil de usar do que o Create React App. Saiba mais sobre o Vite aqui.

1. Instalando dependências e atualizando package.json

Primeiro, precisamos instalar algumas dependências necessárias para utilizar o Vite.

npm install --save-dev vite @vitejs/plugin-react vite-ts-config-paths vite-plugin-svgr

Em seguida, atualize os scripts do seu package.json para utilizar o Vite.

{
  "scripts": {
    "start": "vite",
    "build": "tsc && vite build",
    "serve": "vite preview"
  }
}

2. Removendo o Create React App

Agora precisamos remover completamente o Create React App do seu projeto. Para isso, podemos simplesmente desinstalar o pacote react-scripts usando o comando:

npm uninstall react-scripts

Caso esteja utilizando TypeScript, remova também o arquivo react-app-env.d.ts que deve estar na pasta raiz do seu projeto ou na pasta src.

3. Configurando o Vite

Para configurar o Vite, crie um arquivo chamado vite.config.ts na raiz do seu projeto e adicione o seguinte código:

// vite.config.ts
import { defineConfig } from "vite";
import react from "@vitejs/plugin-react";
import svgr from "vite-plugin-svgr";
import tsconfigPaths from "vite-ts-config-paths";

export default defineConfig({
  plugins: [react(), svgr(), tsconfigPaths()],
  // Caso deseje manter um ambiente similar ao Create React App, pode adicionar as seguintes configurações:
  server: {
    host: "localhost",
    port: 3000,
  },
  base: "/",
  build: {
    outDir: "build", // O Vite por padrão gera o build na pasta "dist"
  },
});

Caso esteja utilizando TypeScript, crie um arquivo vite-env.d.ts na sua pasta src para definir as declarações do Vite no TypeScript:

// ./src/vite-env.d.ts
/// <reference types="vite/client" />

4. Atualizando o index.html

Por último, é necessário mover o arquivo index.html para a raiz do seu projeto. Provavelmente, ele está na pasta public, como é padrão no Create React App. É necessário também remover todas as referências à variável %PUBLIC_URL%.

Por exemplo, no caso do link do favicon:

<!-- Remova -->
<link rel="icon" href="%PUBLIC_URL%/favicon.ico" />

<!-- Adicione -->
<link rel="icon" href="favicon.ico" />

Com isso, você já tem o necessário para rodar seu projeto React com Vite. Porém, é comum encontrar alguns erros caso esteja migrando uma aplicação maior e mais complexa. A seguir, alguns dos problemas mais comuns e como resolvê-los.

Variáveis de ambiente

Por padrão, quando criamos um projeto React utilizando CRA, conseguimos acessar as variáveis através do objeto process.env. No entanto, quando utilizamos Vite, não conseguimos acessar essas variáveis da mesma forma, pois o Vite expõe suas variáveis no objeto import.meta.env. Para resolver este problema, basta adicionar o seguinte código ao seu vite.config.ts:

// vite.config.ts
export default defineConfig({
  ...
  define: {
    'process.env': {},
    'process.env.NODE_ENV': JSON.stringify(mode),
  },
  ...
});

Além disso, no CRA geralmente declaramos variáveis de ambiente com o prefixo REACT_APP_, algo que não é esperado no Vite. O Vite espera que as variáveis de ambiente sejam declaradas com o prefixo VITE_. Para resolver este problema, é necessário adicionar o vite-plugin-environment.

npm install --save-dev vite-plugin-environment

E adicioná-lo no seu vite.config.ts:

// vite.config.ts
import EnvironmentPlugin from "vite-plugin-environment";

export default defineConfig({
  plugins: [
    ...
    EnvironmentPlugin('all', { prefix: 'REACT_APP_' }),
  ],
  ...
});

No entanto, é recomendado utilizar a maneira que o Vite define, usando import.meta.env para acessar as variáveis e o prefixo VITE_. Mas, caso seu projeto seja muito grande e o esforço para fazer essa mudança seja elevado, então é possível usar das opções acima.

Arquivos .js ou .ts

Talvez você encontre alguns erros ao migrar para o Vite caso seu projeto tenha componentes React com extensão .js ou .ts. O Vite espera que seus arquivos com JSX tenham a extensão .jsx ou .tsx. É recomendado renomear os arquivos para evitar problemas, porém é possível ignorar esse problema com o seguinte plugin:

// vite.config.ts
import { defineConfig, Plugin, transformWithEsbuild } from 'vite';

export default defineConfig(() => ({
  plugins: [
    ...
    {
      name: 'treat-js-files-as-jsx',
      async transform(code, id) {
        if (!id.match(/src\/.*\.js$/)) return null;

        return transformWithEsbuild(code, id, {
          loader: 'jsx',
          jsx: 'automatic',
        });
      },
    },
  ],
  ...
}));

Conclusão

Migrar uma aplicação CRA para Vite pode parecer um desafio inicialmente, mas os benefícios em termos de desempenho e simplicidade no desenvolvimento valem o esforço. Seguindo os passos desse guia, você conseguirá realizar a migração de forma mais tranquila e aproveitar as vantagens que o Vite oferece.

Espero que este guia tenha sido útil para ajudar na migração do seu projeto CRA para o Vite. Boa sorte!