0Pricing
TypeScript Academy · Aula

Tipagem de ambiente e configuração

Valide e tipifique variáveis de ambiente; exponha variáveis seguras para o cliente com NEXT_PUBLIC; centralize a configuração do servidor e do cliente.

Tipagem de ambiente e configuração é uma aula grátis de TypeScript Academy no CoddyKit. Esta é a aula 3 de 3. 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 3 aulas no total.

Introdução

Objetivo: centralizar variáveis de ambiente validadas e manter os tipos sincronizados. Você analisará process.env com zod, exportará um objeto env tipado e exporá somente NEXT_PUBLIC_* ao cliente.

  • Validação em tempo de execução
  • Exposição ao servidor e ao cliente
  • Fonte única da verdade

Esquemas e analisador

Crie esquemas separados para o servidor e o cliente. Falhe rapidamente com uma configuração inválida durante a inicialização.

// app/lib/env.ts
import { z } from "zod"

const serverSchema = z.object({
  NODE_ENV: z.enum(["development", "test", "production"]),
  DATABASE_URL: z.string().url(),
  API_SECRET: z.string().min(1)
})

const clientSchema = z.object({
  NEXT_PUBLIC_API_BASE: z.string().url()
})

function parseEnv<T extends z.ZodTypeAny>(schema: T, source: Record<string, unknown>) {
  const r = schema.safeParse(source)
  if (!r.success) {
    console.error(r.error.format())
    throw new Error("Invalid environment variables")
  }
  return r.data as z.infer<T>
}

export const serverEnv = parseEnv(serverSchema, process.env)
export const clientEnv = parseEnv(clientSchema, process.env)

Uso no servidor

Os arquivos do servidor (manipuladores de rotas, componentes do servidor) podem acessar segredos de serverEnv. Nunca os exponha ao cliente.

// app/api/users/route.ts
import { NextResponse } from "next/server"
import { serverEnv } from "@/app/lib/env"

export async function GET() {
  // Safe to read secrets on the server
  const db = serverEnv.DATABASE_URL
  return NextResponse.json({ ok: true, dbConfigured: Boolean(db) })
}

Uso no cliente

Os componentes do cliente importam somente clientEnv, que contém variáveis NEXT_PUBLIC_*. Os segredos nunca são enviados ao navegador.

"use client"
import { clientEnv } from "@/app/lib/env"

export default function ApiBaseNotice() {
  return <small>API base: {clientEnv.NEXT_PUBLIC_API_BASE}</small>
}

Tipagens ambientais

As tipagens ambientais melhoram o DX para process.env, mas não fazem validação em tempo de execução — mantenha as verificações do zod.

// env.d.ts (optional hints; runtime validation still required)
/// <reference types="node" />

declare namespace NodeJS {
  interface ProcessEnv {
    NODE_ENV: "development" | "test" | "production"
    DATABASE_URL?: string
    API_SECRET?: string
    NEXT_PUBLIC_API_BASE?: string
  }
}

Boas práticas

Boas práticas:

  • Nunca leia segredos em arquivos do cliente.
  • Valide uma vez na inicialização; faça o processo falhar rapidamente fora da produção para detectar problemas.
  • Agrupe o acesso ao ambiente atrás de um módulo pequeno para manter a consistência e facilitar os testes.

Verificação da tipagem do ambiente

Verificação rápida: qual é um padrão seguro para tipar e expor o ambiente?

Recapitulação

Recapitulação: analise process.env com zod, exporte serverEnv/clientEnv tipados e dependa de NEXT_PUBLIC_* para uma exposição segura ao cliente.

Perguntas Frequentes

A aula “Tipagem de ambiente e configuração” é grátis?

Sim — o texto completo de “Tipagem de ambiente e configuração” é 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 3 aulas no total.

O que vou aprender em “Tipagem de ambiente e configuração”?

Valide e tipifique variáveis de ambiente; exponha variáveis seguras para o cliente com NEXT_PUBLIC; centralize a configuração do servidor e do cliente. 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 3 de 3.

Quanto tempo leva a aula “Tipagem de ambiente e configuração”?

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

  1. Tipos de App Router; componentes de servidor versus cliente
  2. Busca de dados e tipagem de ações
  3. Tipagem de ambiente e configuração
← Voltar para TypeScript Academy