Como usar Variáveis de Ambiente com Next.js

Web

Como usar Variáveis de Ambiente com Next.js

Luiz Duarte
Escrito por Luiz Duarte em 28/12/2023
Junte-se a mais de 34 mil devs

Entre para minha lista e receba conteúdos exclusivos e com prioridade

É 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 Next.js 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 Next.js, mas se não souber, comece por este outro tutorial aqui.

Vamos lá!

Curso Node.js e MongoDB

#1 – Setup do Projeto

Vamos começar criando um novo projeto Next.js, com o comando abaixo.

O CLI vai lhe fazer algumas perguntas, sendo que nenhuma realmente importa para este tutorial, então pode avançar com os valores padrões ou com o que você preferir.

O próximo passo é criar seu arquivo .env.local na raiz do projeto, sendo esse o nome convencionado e que será procurado pelo Next 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.

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:

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

E com isso temos tudo configurado para o tutorial.

Curso Beholder
Curso Beholder

#2 – Usando as Configurações

Se você subir seu projeto agora, vai reparar inclusive que o arquivo das variáveis de ambiente consta como carregado.

Só que no Next.js tem um detalhe importante que é o fato de que, por padrão e por segurança, as variáveis de ambiente somente são carregadas no server side da aplicação, não ficando disponíveis no client side, ou seja, páginas com a diretiva “use client” ou ainda children components dessas páginas.

Assim, se você precisar usar essas variáveis de ambiente no lado do cliente, você tem duas opções. A primeira é através da convenção de nomes, onde se uma variável for nomeada com o prefixo NEXT_PUBLIC_ antes do nome da variável, ela vai automaticamente ser carregada no client-side também, como abaixo.

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

A outra opção, caso você ache feia essa convenção, é mapear as variáveis de ambiente que você deseja acessar no client-side através do arquivo next.config.js, como abaixo.

Basta que você mapeie, inclusive podendo renomear as variáveis depois de mapeadas, cada uma das variáveis que você deseja expor no browser do cliente e ela estará lá, pronta para ser usada após o build do projeto. Abaixo o mesmo exemplo de antes, em uma página “use client”, mas agora após o mapeamento.

Um ponto muito importante aqui é que você não deve mapear TODAS as variáveis de ambiente sempre, mas somente aquelas que você deseja expor no client side. Isso porque se você mapear (ou colocar o prefixo NEXT_PUBLIC_) em 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 server side de alguma forma, como por exemplo através de Route Handlers. Assim o seu client-side vai chamar o seu server-side e ele vai ter acesso às variáveis “secretas” sem expô-las no browser. Em outro tutorial quero falar a respeito de Route Handlers, mas por enquanto, segue um código exemplo, que deve ser colocado em src/app/api/route.ts (crie este arquivo):

Note que acima estou usando a variável de ambiente API_KEY que não foi mapeada no next.config.js e que não possui o prefixo de variável pública. Desta forma ela não está exposta no frontend/client-side, somente no server side e todo Route Handler roda no server side. E para chamar este Route Handler, você faz um fetch normalmente, como abaixo.

E com isso finalizo mais este tutorial, espero que você tenha gostado.

Até a próxima!

Olá, tudo bem?

O que você achou deste conteúdo? Conte nos comentários.

O seu endereço de e-mail não será publicado. Campos obrigatórios são marcados com *