Como usar Variáveis de Ambiente com Vite (ReactJS)

É muito comum em projetos de software web que existam configurações para que a aplicação funcione como a porta HTTP, chaves de API e outras. Mais comum ainda é que tais configurações possuam divergências entre os ambientes de desenvolvimento, testes e produção. Por causa disso, tais configurações não devem ser escritas diretamente no código das aplicações, o que chamamos de “hard code”, mas sim definidas em variáveis/configurações de ambiente.

Estas variáveis de ambiente podem ser configuradas diretamente no PATH do SO com comandos como SET, o que é bem comum em ambientes produtivos, mas também podem ser utilizados arquivos .env para isso, principalmente em ambientes de desenvolvimento.

No tutorial de hoje eu vou lhe ensinar como configurar o seu projeto Vite/ReactJS para usar variáveis de ambiente, tanto no client side quanto no server side e as implicações de cada abordagem. Obviamente parto do pressuposto que você já sabe o básico de Vite/React, mas se não souber, comece por este outro tutorial aqui.

Vamos lá!

#1 – Setup do Projeto

Vamos começar criando um novo projeto ReactJS com Vite, com o comando abaixo.


npm create vite@latest

npm create vite@latest

O CLI vai lhe fazer algumas perguntas, vou chamar o meu projeto de “vite-dotenv” e as demais mais importantes são a escolha de React e de JavaScript (ou TypeScript, como preferir).

O próximo passo é criar seu arquivo .env na raiz do projeto, sendo esse o nome convencionado e que será procurado pelo Vite automaticamente no start do servidor dele. Dentro desse arquivo você coloca as configurações que você precisa e que variam enormemente de projeto para projeto. Abaixo, coloco apenas dois exemplos que já usei e que são comuns.


API_URL=http://xpto.com/api
API_KEY=abc123

API_URL=http://xpto.com/api

API_KEY=abc123

Também é comum que a gente crie um arquivo .env.example onde você documente as variáveis de ambiente para ajudar os outros devs do projeto a entenderem para quê elas servem e como devem ser configuradas. Abaixo um exemplo bobo, apenas para ilustrar:


# The API URL
API_URL=

# The API Key
API_KEY=

# The API URL

API_URL=

# The API Key

API_KEY=

Recomendo que inclua o arquivo .env no arquivo .gitignore da sua aplicação, que deve ficar na raiz do projeto, se ainda não existir.


.env

.env

E com isso temos tudo configurado para o tutorial.

#2 – Usando as Configurações

Se você subir seu projeto agora, verá que no Vite tem um detalhe importante a respeito de variáveis de ambiente que é o fato de que, por padrão e por segurança, somente as variáveis de ambiente com o prefixo VITE_ são carregadas e disponibilizadas no client-side da sua aplicação.

Assim, se você precisar usar essas variáveis de ambiente no lado do cliente você precisa nomear elas usando o prefixo VITE_, como abaixo.


VITE_API_URL=http://xpto.com/api

VITE_API_URL=http://xpto.com/api

Assim, nos seus arquivos JSX/TSX que for usar essa variável, basta chamá-la como abaixo (exemplo).


fetch(import.meta.env.VITE_API_URL)
   .then(data => console.log(data))

fetch(import.meta.env.VITE_API_URL)

.then(data => console.log(data))

Um ponto muito importante aqui é que você não deve expor TODAS as variáveis de ambiente sempre, mas somente aquelas que você deseja usar no client side. Isso porque se você expor uma variável sensível, como uma senha ou chave de API, ela estará disponível a qualquer um utilizar, mesmo que não seja você, pois em tempo de compilação elas serão injetadas no JS client-side e consequentemente estarão no browser dos usuários para inspeção.

Mas Luiz, e se eu precisar usar variáveis de ambiente “sensíveis” no client side, por causa de uma chamada de API, por exemplo?

Neste caso você deve fazer com que sua página/componente client-side chame o seu backend e ele sim terá acesso a “variável sensível”.

Uma última dica, caso deseje utilizar variáveis de ambiente no arquivo de configuração do Vite, faça como abaixo.


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

export default defineConfig(({ mode }) => {
  process.env = { ...process.env, ...loadEnv(mode, process.cwd()) };

  return {
    plugins: [react()],
    server: {
      port: process.env.VITE_PORT
    }
  };
});