TypeScript Academy · Aula

Definindo Tipos de Variáveis de Ambiente

Atribua a process.env um tipo preciso e validado.

Definindo Tipos de Variáveis de Ambiente é uma aula grátis de TypeScript Academy no CoddyKit. Esta é a aula 1 de 4. Você pode ler a aula completa abaixo gratuitamente — depois pratica ao vivo no navegador com um editor de código integrado e um tutor de IA 24/7. Faz parte do caminho de aprendizado de TypeScript Academy, e seu progresso é sincronizado entre a web e o app CoddyKit. O curso de TypeScript Academy inclui 4 aulas no total.

O problema de process.env

No Node, process.env é tipado como Record<string, string | undefined>. Toda variável pode estar ausente, e tudo é um texto, portanto o acesso direto é inseguro e não tipado.

Declarando uma interface Env tipada

Comece descrevendo a configuração de que seu aplicativo realmente precisa como uma interface precisa, com tipos corretos e campos obrigatórios e opcionais.

interface Env {
  PORT: number;
  NODE_ENV: "development" | "production";
  DATABASE_URL: string;
  DEBUG?: boolean; // optional
}

Lendo valores brutos

Todos os valores chegam como textos ou undefined. Você precisa lê-los de forma defensiva, pois as chaves podem simplesmente não estar presentes.

const rawPort = process.env.PORT; // string | undefined
const rawEnv = process.env.NODE_ENV; // string | undefined

Variáveis obrigatórias e opcionais

Algumas variáveis precisam existir para que o aplicativo seja executado; outras têm alternativas sensatas. Um auxiliar para valores obrigatórios falha de forma explícita quando um deles está ausente.

function required(name: string): string {
  const v = process.env[name];
  if (v === undefined) throw new Error("Missing env: " + name);
  return v;
}

Analisando números

Variáveis numéricas precisam de conversão e validação, pois parseInt pode produzir NaN. Envolva a análise para que entradas inválidas sejam rejeitadas imediatamente.

function num(name: string): number {
  const n = Number(required(name));
  if (Number.isNaN(n)) throw new Error(name + " is not a number");
  return n;
}

Analisando valores booleanos

Valores booleanos chegam como textos, como "true". Normalize-os explicitamente em vez de depender da veracidade de um texto não vazio.

function bool(name: string, def = false): boolean {
  const v = process.env[name];
  if (v === undefined) return def;
  return v === "true" || v === "1";
}

Criando a configuração tipada

Reúna os valores analisados em um único objeto que corresponda à interface Env. A partir daqui, o restante do aplicativo usa a configuração tipada e nunca acessa process.env diretamente.

const env: Env = {
  PORT: num("PORT"),
  NODE_ENV: required("NODE_ENV") as Env["NODE_ENV"],
  DATABASE_URL: required("DATABASE_URL"),
  DEBUG: bool("DEBUG"),
};

Restringindo uniões de textos

Para variáveis com um conjunto fixo de valores, valide-as em relação a esse conjunto para que um valor inesperado não seja aceito como o tipo literal incorreto.

function oneOf<T extends string>(name: string, allowed: readonly T[]): T {
  const v = required(name) as T;
  if (!allowed.includes(v)) throw new Error(name + " invalid");
  return v;
}

Centralize o acesso

Exporte o único objeto env a partir de um módulo. Cada consumidor o importa, obtendo tipagem completa e um único local para alterar a lógica de análise.

export const config = env;
// elsewhere: import { config } from "./config";

Aumentando ProcessEnv (opcional)

Você pode declarar uma extensão de módulo para NodeJS.ProcessEnv a fim de tipar o acesso bruto, mas um objeto de configuração analisado é mais seguro, pois também valida e converte os valores.

// declare global { namespace NodeJS { interface ProcessEnv { PORT: string } } }

Por que um objeto de configuração tipado é melhor

Uma configuração analisada e validada fornece tipos corretos (números, booleanos e uniões), presença garantida das variáveis obrigatórias e uma única importação para todo o aplicativo, em vez de leituras inseguras e dispersas de process.env.

Verificação rápida

Verificação rápida desta lição.

Recapitulação

Declare uma interface Env tipada e analise process.env com auxiliares que convertem e validam valores (números, booleanos e uniões de textos), falhando quando variáveis obrigatórias estão ausentes. Exporte um único objeto config tipado para que o aplicativo nunca toque em process.env bruto.

Perguntas Frequentes

A aula “Definindo Tipos de Variáveis de Ambiente” é grátis?

Sim — o texto completo de “Definindo Tipos de Variáveis de Ambiente” é grátis para ler aqui na web. Para praticá-la interativamente (um editor de código integrado e um tutor de IA 24/7) e desbloquear o restante do curso de TypeScript Academy, atualize para CoddyKit PRO. O curso de TypeScript Academy inclui 4 aulas no total.

O que vou aprender em “Definindo Tipos de Variáveis de Ambiente”?

Atribua a process.env um tipo preciso e validado. Você pratica TypeScript Academy com código prático que executa diretamente no navegador, e um tutor de IA 24/7 responde suas dúvidas enquanto trabalha na aula.

Preciso ter experiência prévia para começar TypeScript Academy?

Nenhuma experiência prévia é necessária. TypeScript Academy no CoddyKit é estruturado para alunos iniciantes até avançados, então você pode começar aqui ou desde o início e aprender no seu ritmo. Esta é a aula 1 de 4.

Quanto tempo leva a aula “Definindo Tipos de Variáveis de Ambiente”?

A maioria das aulas CoddyKit leva cerca de 5–10 minutos. Cada uma é compacta e interativa, então você faz progresso constante e retoma exatamente de onde parou entre web e app.

Posso escrever e executar código nesta aula de TypeScript Academy?

Sim. Cada aula de TypeScript Academy inclui um editor de código integrado, então você escreve e executa código real direto no navegador e recebe feedback de IA instantaneamente — nenhuma configuração local necessária.

Todas as aulas deste curso

Definindo Tipos de Variáveis de Ambiente
Configuração Validada por Esquema
Camadas e Valores Padrão de Configuração
Segredos e Segurança de Tipos

← Voltar para TypeScript Academy