Jump to content

Vari√°veis de Ambiente

O Create-T3-App usa Zod↗ para validar suas variáveis de ambiente em runtime e buildtime fornecendo alguns arquivos adicionais no diretório env:

ūüďĀ src/env

‚Ē£ ūüďĄ client.mjs

‚Ē£ ūüďĄ schema.mjs

‚Ē£ ūüďĄ server.mjs

O conte√ļdo desses arquivos pode parecer assustador √† primeira vista, mas n√£o se preocupe, n√£o √© t√£o complicado quanto parece. Vamos dar uma olhada neles um por um e percorrer o processo de adi√ß√£o de vari√°veis de ambiente adicionais.

Muito longo, não li; Se você quiser adicionar uma nova variável de ambiente, você deve adicioná-la tanto ao seu .env quanto definir o validador em env/schema.mjs.

schema.mjs

Este é o arquivo que você realmente tocará. Ele contém dois esquemas, um para variáveis de ambiente do lado do servidor e outro para o lado do cliente, bem como um objeto clientEnv.

env/schema.mjs
export const serverSchema = z.object({
  // DATABASE_URL: z.string().url(),
});

export const serverEnv = {
  // DATABASE_URL: process.env.DATABASE_URL,
};

export const clientSchema = z.object({
  // NEXT_PUBLIC_WS_KEY: z.string(),
});

export const clientEnv = {
  // NEXT_PUBLIC_WS_KEY: process.env.NEXT_PUBLIC_WS_KEY,
};

Schema do Servidor

Defina seu esquema de vari√°veis de ambiente do lado do servidor aqui.

Certifique-se de não prefixar as chaves aqui com NEXT_PUBLIC. A validação falhará se você fizer isso para ajudá-lo a detectar uma configuração inválida.

Schema do Cliente

Defina seu esquema de vari√°veis de ambiente do lado do cliente aqui.

Para exp√ī-los ao cliente, voc√™ precisa prefix√°-los com NEXT_PUBLIC. A valida√ß√£o falhar√° se voc√™ n√£o o ajudar a detectar uma configura√ß√£o inv√°lida.

Objeto clientEnv

Desestruture o process.env aqui.

Precisamos de um objeto JavaScript com o qual possamos analisar nossos esquemas Zod e devido à maneira como o Next.js lida com as variáveis de ambiente, você não pode destruir process.env como um objeto normal, então precisamos fazer isso manualmente.

O TypeScript ajudará você a garantir que inseriu as chaves em clientEnv e também em clientSchema.

// ‚ĚĆ This doesn't work, we need to destruct it manually
const schema = z.object({
  NEXT_PUBLIC_WS_KEY: z.string(),
});

const validated = schema.parse(process.env);

server.mjs & client.mjs

√Č aqui que a valida√ß√£o acontece e exporta os objetos validados. Voc√™ n√£o precisa modificar esses arquivos.

Usando Vari√°veis Ambiente

Quando você quiser usar suas variáveis de ambiente, você pode importá-las de env/client.mjs ou env/server.mjs dependendo de onde você deseja usá-las:

pages/api/hello.ts
import { env } from "../../env/server.mjs";

// `env` is fully typesafe and provides autocompletion
const dbUrl = env.DATABASE_URL;

.env.example

Como o arquivo .env padrão não está comprometido com o controle de versão, também incluímos um arquivo .env.example, no qual você pode, opcionalmente, manter uma cópia de seu arquivo .env com quaisquer segredos removidos. Isso não é necessário, mas recomendamos manter o exemplo atualizado para tornar mais fácil para os contribuidores começarem a usar seu ambiente.

Adicionando Vari√°veis Ambiente

Para garantir que sua compilação nunca seja concluída sem as variáveis de ambiente de que o projeto precisa, você precisará adicionar novas variáveis de ambiente em dois locais:

ūüďĄ .env: Insira sua vari√°vel de ambiente como faria normalmente em um arquivo .env, ou seja, CHAVE=VALOR

ūüďĄ schema.mjs: Adicione a l√≥gica de valida√ß√£o apropriada para a vari√°vel de ambiente definindo um esquema Zod, por exemplo TECLA: z.string()

Opcionalmente, você também pode manter .env.example atualizado:

ūüďĄ .env.example: Insira sua vari√°vel de ambiente, mas certifique-se de n√£o incluir o valor se for secreto, ou seja, CHAVE=VALOR ou CHAVE=

Exemplo

Quero adicionar meu token de API do Twitter como uma vari√°vel de ambiente do lado do servidor

  1. Adicione a vari√°vel de ambiente a .env:
TWITTER_API_TOKEN=1234567890
  1. Adicione a vari√°vel de ambiente a schema.mjs:
export const serverSchema = z.object({
  // ...
  TWITTER_API_TOKEN: z.string(),
});

export const serverEnv = {
  // ...
  TWITTER_API_TOKEN: process.env.TWITTER_API_TOKEN,
};

NOTA: Uma string vazia ainda é uma string, então z.string() aceitará uma string vazia como um valor válido. Se você quiser ter certeza de que a variável de ambiente não está vazia, você pode usar z.string().min(1).

  1. opcional: adicione a vari√°vel de ambiente a .env.example, mas n√£o inclua o token
TWITTER_API_TOKEN=