Neste artigo, você aprenderá a gerenciar variáveis de ambiente no Next.js usando arquivos .env. Vamos abordar variáveis públicas vs. privadas, hierarquia de arquivos de variáveis de ambiente, limitações de tempo de execução e melhores práticas para configuração segura em desenvolvimento e produção.

O que são variáveis de ambiente no Next.js?

As variáveis de ambiente no Next.js são valores de configuração definidos fora do código-fonte e injetados na aplicação durante a construção ou execução. Elas são carregadas de arquivos .env ou do ambiente do sistema e acessadas usando process.env.

O Next.js suporta múltiplos arquivos de ambiente: .env, .env.local, .env.development, .env.production e .env.test. Esses arquivos são avaliados com base no modo de ambiente atual (NODE_ENV), e o Next.js prioriza .env.local para substituições locais.

O Next.js restringe quais variáveis de ambiente são expostas ao navegador. Apenas variáveis prefixadas com NEXT_PUBLIC_ são incorporadas no pacote do lado do cliente. Variáveis sem esse prefixo permanecem apenas no servidor, acessíveis exclusivamente no backend do Node.js. Essa divisão permite que dados sensíveis, como credenciais de banco de dados, permaneçam no servidor, enquanto a configuração voltada para o público, como flags de funcionalidades ou URLs base de API possam ser expostas com segurança ao frontend.

As variáveis de ambiente estão disponíveis tanto no código do lado do servidor (rotas de API, getServerSideProps, getStaticProps) quanto no código do lado do cliente (via NEXT_PUBLIC_*). No entanto, qualquer variável usada no código do lado do cliente deve ser prefixada adequadamente, ou não será incluída no JavaScript compilado enviado para o navegador.

Por que as variáveis de ambiente são importantes?

As variáveis de ambiente permitem a separação entre código e configuração. Isso garante que o mesmo código-fonte possa ser executado em vários ambientes (desenvolvimento, homologação, produção) sem mudanças nos arquivos de origem. Em vez de codificar URLs base, chaves de API, toggles de funcionalidades ou tokens de análise, eles são abstraídos por meio de variáveis de ambiente que são injetadas no momento da construção ou execução, dependendo da configuração de implantação.

Essa separação torna-se importante em pipelines de CI/CD. Durante o processo de construção, o arquivo .env.production ou variáveis de execução definidas na plataforma de nuvem definem valores como a URL do serviço de backend, flags de funcionalidades e credenciais de serviços de terceiros. Modificar esses valores não requer reconstruir o código, a menos que a variável seja necessária no momento da construção (como aquelas usadas durante a geração estática).

Começando com variáveis de ambiente

As variáveis de ambiente consistem em pares de nome-valor, como no exemplo abaixo:

API_KEY=1234
DB_CONN_STRING="http://localhost:3000"

Uma aplicação pode ter diferentes requisitos ao executar em ambientes de desenvolvimento, teste e produção. Em vez de ter diferentes códigos para a mesma aplicação, onde cada código é voltado para um ambiente específico, uma aplicação pode ter um único código cujo comportamento nos diferentes ambientes é determinado usando as configurações de variáveis de ambiente.

A aplicação pode ler as configurações das variáveis de ambiente e modificar seu comportamento para atender aos requisitos desse ambiente específico. Isso mantém o código curto, limpo e organizado:

process.env.API_KEY;
process.env.DB_CONN_STRING;

Em um ambiente de desenvolvimento, ferramentas para formatação de código, linting e teste são essenciais.

No entanto, essas ferramentas não são necessárias na etapa de produção. Ao trabalhar com ferramentas como npm, definir o valor da variável de ambiente embutida NODE_ENV para production instalará dependências que a aplicação precisa em produção, excluindo aquelas necessárias na etapa de desenvolvimento. Esse comportamento é configurável, se necessário.

Suporte embutido para variáveis de ambiente no Next.js

Como mencionado anteriormente, o Next.js tem suporte embutido para variáveis de ambiente. Para começar a usá-las, você pode declarar .env.local na raiz do seu diretório de projeto:

API_KEY=123456789
USERNAME=username
PASSWORD=password

O Next.js carregará as variáveis de ambiente acima no objeto process.env automaticamente para que você possa acessá-las no ambiente Node.js:

export async function getStaticProps() {
  console.log(process.env.API_KEY); 
  console.log(process.env.USERNAME);
  console.log(process.env.PASSWORD);
}

As variáveis de ambiente acima estão disponíveis apenas no ambiente Node.js e são referidas como variáveis de ambiente privadas. Prefixar o nome da variável com NEXT_PUBLIC_ as transforma em variáveis de ambiente públicas:

NEXT_PUBLIC_API_KEY=123456789
NEXT_PUBLIC_USERNAME=username
NEXT_PUBLIC_PASSWORD=password

Variáveis de ambiente públicas estão disponíveis tanto no navegador quanto nos ambientes Node.js. Exploraremos variáveis de ambiente públicas e privadas mais adiante neste artigo.

Variáveis de ambiente públicas e privadas no Next.js

Como introduzimos anteriormente, as variáveis de ambiente do Next.js podem ser categorizadas em variáveis de ambiente públicas e privadas, mas elas são privadas por padrão.

Variáveis de ambiente privadas são acessíveis apenas a partir do ambiente Node.js. Você pode declarar variáveis de ambiente privadas em qualquer um dos seus arquivos .env* assim:

ENV_VARIABLE=env_variable

Para tornar uma variável de ambiente pública, prefixe seu nome com NEXT_PUBLIC_ como no exemplo abaixo:

NEXT_PUBLIC_ENV_VARIABLE=nex_public_env_variable

Em tempo de construção, o Next.js acessará e substituirá referências às variáveis de ambiente públicas com seus valores reais no código-fonte empacotado para o ambiente do navegador.

Usando variáveis de ambiente em desenvolvimento local vs. produção

Os requisitos de uma aplicação durante o desenvolvimento podem não ser os mesmos que em produção. Portanto, algumas variáveis de ambiente podem ser necessárias apenas no desenvolvimento, outras na produção, e algumas em ambos os ambientes.

Por exemplo, se você declarar as variáveis de ambiente abaixo no arquivo .env.production, elas estarão disponíveis apenas no ambiente de produção:

BASE_URL='http://localhost:3000'
NEXT_PUBLIC_BASE_URL='http://localhost:3000'

Independentemente do arquivo em que você declara as variáveis de ambiente acima, a variável de ambiente BASE_URL estará disponível no ambiente Node.js porque é uma variável privada. E NEXT_PUBLIC_BASE_URL estará disponível tanto no navegador quanto nos ambientes Node.js porque é uma variável de ambiente pública.

Manipulando variáveis de ambiente com next.config.js

O Next.js oferece maneiras flexíveis de trabalhar com variáveis de ambiente. Você pode usar a propriedade env legada do arquivo next.config.js para configurar variáveis de ambiente, ou os arquivos .env* descritos acima, mais novos, intuitivos e ergonômicos.