Como adicionar arquivo .env em projeto de React JS

Neste artigo você aprenderá a como incluir o arquivo .env em projeto de React, e utilizar as variáveis de ambiente no seu código

Resposta rápida: pra usar .env em projeto React, crie o arquivo .env na raiz do projeto e nomeie a variável com o prefixo que a SUA ferramenta exige

Create React App: REACT_APP_API_URL=valor, lido no código com process.env.REACT_APP_API_URL

Vite: VITE_API_URL=valor, lido com import.meta.env.VITE_API_URL (não é process.env)

Next.js: NEXT_PUBLIC_API_URL=valor pra variável que precisa chegar no navegador, e o valor é embutido no bundle durante o next build

Sem o prefixo certo a variável não chega no código do cliente

No Create React App, depois de mudar o .env é preciso reiniciar o servidor de desenvolvimento

E vale pros três: nada disso é segredo, tudo termina no bundle que o usuário baixa

Fala programador(a), beleza? Bora aprender mais sobre React JS!

Quando estamos desenvolvendo aplicações web modernas, muitas vezes nos deparamos com a necessidade de utilizar variáveis de ambiente para gerenciar configurações que não devem ser hardcoded ou expostas publicamente.

No React JS, essa gestão pode ser feita com a ajuda de arquivos .env. Neste artigo, abordaremos como implementar e utilizar esse recurso em seu projeto.

O que são Variáveis de Ambiente?

Variáveis de ambiente são essencialmente valores externos que seu código pode consultar para executar uma tarefa específica.

Elas são particularmente úteis para:

• Separar configurações de desenvolvimento, teste e produção;
• Armazenar chaves de API sem expô-las no código-fonte;
• Definir configurações de conexão com banco de dados.

Iniciando com .env no React

O Create React App (CRA) já tem suporte embutido para a leitura de arquivos .env, facilitando o processo.

1. Criando seu arquivo .env

Na raiz do seu projeto React, crie um arquivo chamado .env. Dentro deste arquivo, você pode definir suas variáveis de ambiente usando a seguinte convenção:

REACT_APP_NOME_DA_VARIAVEL=valor_da_variavel

Por exemplo:

REACT_APP_API_URL=https://api.meusite.com.br

Nota: É crucial prefixar suas variáveis com REACT_APP_ para que elas sejam incorporadas em sua aplicação React.

2. Utilizando a variável no seu componente

Para acessar a variável de ambiente no seu código, você pode usar process.env seguido do nome da sua variável.

import React from 'react';

const App = () => {
  return (
    <div>
      <h1>URL da API: {process.env.REACT_APP_API_URL}</h1>
    </div>
  );
}

export default App;

Variáveis .env para Diferentes Ambientes

Para ambientes distintos, como desenvolvimento, teste e produção, é comum ter diferentes configurações. O React permite que você tenha arquivos .env específicos para cada situação:

• .env: Padrão
• .env.local: Configurações locais
• .env.development: Desenvolvimento
• .env.test: Testes
• .env.production: Produção

Quando você executa o comando npm start, por exemplo, o React irá utilizar as variáveis definidas em .env.development.

Boas Práticas e Cuidados

Nunca exponha informações sensíveis:

Mesmo que o prefixo REACT_APP_ faça com que a variável esteja disponível em sua aplicação React, lembre-se de que tudo que é construído no front-end pode ser visto por usuários.

Portanto, nunca coloque informações sensíveis, como senhas ou chaves privadas, em arquivos .env que serão usados no cliente.

Utilize .gitignore:

Para evitar que suas configurações sejam enviadas para o repositório git, adicione qualquer arquivo .env (exceto o .env.example, se você tiver um) ao seu arquivo .gitignore.

Variáveis padrão com .env.example:

É uma boa prática ter um arquivo .env.example que descreva todas as variáveis necessárias sem fornecer os valores reais.

Isso ajuda outros desenvolvedores a entenderem quais configurações são necessárias.

Utilizando .env no Vite

Se o seu projeto React utiliza o Vite, a maneira de lidar com variáveis de ambiente é um pouco diferente.

No Vite, para expor variáveis de ambiente ao código frontend, você deve prefixar suas variáveis com VITE_.

Essa prática é uma salvaguarda do Vite para garantir que as variáveis de ambiente que não deveriam ser expostas no frontend não sejam incluídas acidentalmente.

Passo 1: No diretório raiz do seu projeto, crie um arquivo chamado .env. Dentro deste arquivo, defina suas variáveis de ambiente, prefixando-as com VITE_. Por exemplo:

VITE_API_URL=https://api.meusite.com.br
VITE_CHAVE_SECRETA=12345678

Passo 2: No seu código, você pode acessar estas variáveis através de process.env.NOME_DA_VARIAVEL. Por exemplo:

const apiUrl = process.env.VITE_API_URL;
console.log(apiUrl);  // Output: https://api.meusite.com.br

Nota Importante: Apenas as variáveis prefixadas com VITE_ estarão disponíveis no código frontend. Qualquer outra variável definida no .env, mas sem este prefixo, não estará acessível.

Passo 3: Sempre que adicionar novas variáveis ou fizer alterações, é uma boa prática reiniciar o servidor de desenvolvimento do Vite para garantir que as novas variáveis sejam reconhecidas.

Quer aprender mais sobre programação? Conheça nosso canal no YouTube:

Conclusão

Chegamos ao fim do artigo sobre o arquivo .env em projeto de React!

Tanto o Create React App quanto o Vite oferecem maneiras robustas de gerenciar variáveis de ambiente em projetos React JS.

O Vite, com sua abordagem de construção mais rápida, é certamente uma opção atraente para muitos desenvolvedores.

Ao seguir este guia, você pode facilmente integrar e gerenciar suas configurações usando arquivos .env em qualquer uma dessas ferramentas.

Está buscando em evoluir como Programador? Confira o nossos cursos de programação.

O que é o arquivo .env, na prática?

O .env é só um arquivo de texto que fica na raiz do projeto e guarda pares de chave e valor, um por linha

Nada de mágica aqui: ele existe pra tirar do código aquilo que muda de máquina pra máquina, ou de ambiente pra ambiente

MINHA_VARIAVEL=valor

Se tu conhece o arquivo de configuração de qualquer projeto backend, é a mesma ideia, só que num projeto React tem uma pegadinha a mais

O navegador não lê arquivo do teu disco, então a ferramenta de build (Create React App, Vite, Next.js) é quem pega o valor do .env e coloca dentro do JavaScript que vai pro usuário

E cada ferramenta faz isso de um jeito, com um prefixo diferente e uma forma de acesso diferente

É exatamente aí que a maioria trava, beleza? 🙂

Antes de tudo: o Create React App foi descontinuado

Se tu chegou aqui pra criar um projeto novo, se liga nisso primeiro

Em 14 de fevereiro de 2025 o time do React publicou o anúncio "Sunsetting Create React App": o CRA entrou em modo de manutenção e a recomendação oficial é migrar

Inclusive, ao rodar o comando de criação do CRA o próprio terminal já cospe um aviso de descontinuação com link pra lista de frameworks atualizados no react.dev

E o que usar no lugar?

Pra quem não quer um framework completo, a recomendação oficial é uma build tool moderna: Vite, Parcel ou Rsbuild

Pra quem quer framework, a página oficial "Creating a React App" lista hoje Next.js (App Router), React Router (v7) e Expo (apps nativos), com o TanStack Start citado como em desenvolvimento (beta)

O React 19 segue como a linha major atual

Então a seção de CRA logo abaixo continua valendo pra quem MANTÉM um projeto que já existe (e olha, é MUITA gente)

Pra projeto novo, pula direto pra parte do Vite 😀

CRA, Vite e Next.js lado a lado: o prefixo e a forma de acesso

Create React App: prefixo REACT_APP_ e acesso por process.env.REACT_APP_MINHA_VAR

Vite: prefixo VITE_ e acesso por import.meta.env.VITE_MINHA_VAR

Next.js: prefixo NEXT_PUBLIC_ pra variável que precisa chegar no navegador, e o valor é embutido (inlined) no bundle JavaScript durante o next build

Repara no padrão: os três exigem um prefixo e os três fazem o valor virar texto dentro do bundle

Muda o nome do prefixo e muda o objeto de onde tu lê

No CRA, fora o NODE_ENV, qualquer variável sem o prefixo REACT_APP_ é simplesmente ignorada

No Vite, só o que tem VITE_ chega no código do cliente, e o prefixo é configurável pela opção envPrefix

No Next.js, o valor congela no momento do build, então trocar a variável depois pede build novo

Agora a parte que dói: nenhum dos três guarda segredo

A própria doc do Vite avisa que as variáveis expostas terminam no bundle do cliente, ou seja, VITE_* não pode conter informação sensível

Chave secreta de verdade fica no servidor, ponto

Minha variável do .env está undefined: o que checar

Tome cuidado, porque quase sempre é um destes quatro

1. Falta o prefixo

No CRA tem que ser REACT_APP_, no Vite tem que ser VITE_, no Next.js tem que ser NEXT_PUBLIC_ pra chegar no navegador

No Vite, uma variável sem prefixo (tipo DB_PASSWORD) volta undefined de propósito, é uma proteção, não um bug

2. Tu está lendo do objeto errado

Atenção nesse aqui, é o erro mais comum de quem migrou de CRA pra Vite: no Vite NÃO é process.env

A doc oficial do Vite expõe as variáveis do cliente em import.meta.env, sempre como string

Ou seja, VITE_SOME_KEY=123 no arquivo vira import.meta.env.VITE_SOME_KEY no código

Se tu escreveu process.env.VITE_ALGUMA_COISA num projeto Vite, é por isso que vem undefined

3. Tu não reiniciou o servidor de desenvolvimento

No Create React App, mudou variável, reinicia o servidor, não tem jeito

4. O arquivo carregado não é o que tu acha

No Vite, o modo é definido pelo comando: vite (ou vite dev) roda em modo development e vite build roda em modo production, e dá pra forçar com a flag –mode

Se a variável está no .env.production e tu está rodando o dev, ela não vai aparecer 😛

Quais arquivos .env o Vite carrega, e quem ganha de quem:

O Vite não lê só um arquivo, ele lê uma pilha

.env: carregado sempre

.env.local: carregado sempre e ignorado pelo git

E tem uma regra que pega muita gente em deploy: variável que já existe no ambiente na hora de executar o Vite tem prioridade máxima e não é sobrescrita pelo arquivo

A doc também pede pra colocar *.local no .gitignore, porque esses arquivos podem carregar coisa sensível

Além das suas, o Vite ainda entrega constantes prontas em import.meta.env: MODE, BASE_URL, PROD, DEV e SSR

Dá pra fazer um if (import.meta.env.DEV) e ligar log só em desenvolvimento, por exemplo, MUITO útil

E se tu ainda vai criar o projeto, o comando é npm create vite@latest

No npm 7 ou superior o template precisa do duplo hífen: npm create vite@latest — –template react

Entre os templates disponíveis tem react, react-ts, react-compiler e react-compiler-ts

Ah, e o Vite 8 saiu em 12 de março de 2026 trazendo o Rolldown, escrito em Rust, como bundler único no lugar do par esbuild + Rollup

Topzera 😀

Um detalhe que eu carrego de gravar os cursos de React aqui do canal

No curso eu faço questão de começar do zero mesmo: instalar o Node pelo site oficial, abrir o terminal e testar com node -v e npm -v antes de escrever qualquer linha, depois abrir o VS Code com a extensão de snippets de React

Parece bobo, mas é aquele next, next e finish que salva horas depois

Porque a maior parte do "não funciona" que chega pra mim não é código, é ambiente

E com .env é exatamente a mesma família de problema: o arquivo está certo, o nome está certo, e mesmo assim vem undefined

No Create React App a causa clássica é não ter reiniciado o servidor de desenvolvimento depois de mexer no arquivo

No Vite, é a mão viciada digitando process.env quando o objeto certo é import.meta.env

Então o meu conselho de bastidor é o mesmo do curso: antes de sair caçando bug no componente, imprime o objeto inteiro no console e confirma se a variável sequer chegou

Se ela não chegou, o problema é prefixo, arquivo ou servidor, e não o teu React 🙂