0Pricing
TypeScript Academy · Lección

Tipado del entorno y configuración

Valide y tipifique las variables de entorno; exponga variables de cliente seguras con NEXT_PUBLIC; centralice la configuración para servidor y cliente.

Tipado del entorno y configuración es una lección gratuita de TypeScript Academy en CoddyKit. Esta es la lección 3 de 3. Puedes leer la lección completa abajo gratuitamente — luego la practicas en el navegador con un editor de código integrado y un tutor de IA 24/7. Forma parte de la ruta de aprendizaje de TypeScript Academy, y tu progreso se sincroniza en la web y la app de CoddyKit. El curso de TypeScript Academy incluye 3 lecciones en total.

Introducción

Objetivo: Centralizar las variables de entorno validadas y mantener los tipos sincronizados. Analizará process.env con zod, exportará un objeto env tipado y expondrá solo NEXT_PUBLIC_* al cliente.

  • Validación en tiempo de ejecución
  • Exposición al servidor frente al cliente
  • Única fuente de verdad

Esquemas y analizador

Cree esquemas independientes para el servidor y el cliente. Falle rápidamente si la configuración no es válida durante el arranque.

// 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 en el servidor

Los archivos del servidor (controladores de ruta y componentes de servidor) pueden acceder a los secretos desde serverEnv. Nunca los exponga al 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 en el cliente

Los componentes de cliente solo importan clientEnv, que contiene las variables NEXT_PUBLIC_*. Los secretos nunca se envían al navegador.

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

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

Tipados ambientales

Los tipados ambientales mejoran la experiencia de desarrollo para process.env, pero no validan en tiempo de ejecución; mantenga las comprobaciones de 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
  }
}

Buenas prácticas

Buenas prácticas:

  • Nunca lea secretos en archivos de cliente.
  • Valide una vez al inicio; falle rápidamente en entornos que no sean de producción para detectar problemas.
  • Agrupe el acceso al entorno detrás de un módulo pequeño para mantener la coherencia y facilitar las pruebas.

Comprobación del tipado de variables de entorno

Comprobación rápida: ¿Cuál es un patrón seguro para tipar y exponer variables de entorno?

Repaso

Repaso: Analice process.env con zod, exporte serverEnv/clientEnv tipados y confíe en NEXT_PUBLIC_* para exponer variables de forma segura al cliente.

Preguntas frecuentes

¿La lección «Tipado del entorno y configuración» es gratis?

Sí — el texto completo de «Tipado del entorno y configuración» es gratis para leer aquí en la web. Para practicarla de forma interactiva (editor de código integrado y tutor de IA 24/7) y desbloquear el resto del curso de TypeScript Academy, actualiza a CoddyKit PRO. El curso de TypeScript Academy incluye 3 lecciones en total.

¿Qué aprenderé en «Tipado del entorno y configuración»?

Valide y tipifique las variables de entorno; exponga variables de cliente seguras con NEXT_PUBLIC; centralice la configuración para servidor y cliente. Practicas TypeScript Academy con código real que ejecutas directamente en el navegador, y un tutor de IA 24/7 responde tus preguntas mientras trabajas en la lección.

¿Necesito experiencia previa para empezar TypeScript Academy?

No se requiere experiencia previa. TypeScript Academy en CoddyKit está estructurado para principiantes hasta estudiantes avanzados, así que puedes empezar aquí o desde el inicio y avanzar a tu ritmo. Esta es la lección 3 de 3.

¿Cuánto tiempo toma la lección «Tipado del entorno y configuración»?

La mayoría de las lecciones de CoddyKit toman alrededor de 5–10 minutos. Cada una es compacta e interactiva, así que avanzas constantemente y retomas exactamente por donde dejaste en la web y la app.

¿Puedo escribir y ejecutar código en esta lección de TypeScript Academy?

Sí. Cada lección de TypeScript Academy incluye un editor de código integrado, así que escribes y ejecutas código real directamente en tu navegador y obtienes retroalimentación instantánea de IA — sin configuración local necesaria.

Todas las lecciones de este curso

  1. Tipos de handlers del App Router y componentes de servidor frente a cliente
  2. Obtención de datos y tipado de acciones
  3. Tipado del entorno y configuración
← Volver a TypeScript Academy