Validación de Variables de Entorno usando Zod

En este tutorial, aprenderás cómo validar variables de entorno en un proyecto Node.js utilizando Zod, una librería de validación de esquemas con TypeScript. Validar las variables de entorno es una buena práctica para asegurarse de que los valores necesarios para el funcionamiento de la aplicación estén presentes y sean correctos.

Instalación

Primero, instala las dependencias necesarias. Necesitarás zod para la validación y dotenv para cargar las variables de entorno desde un archivo .env.

npm install zod dotenv

Configuración de .env

Crea un archivo .env en la raíz de tu proyecto para definir tus variables de entorno. Aquí hay un ejemplo:

PORT=3000
DATABASE_URL=mongodb://localhost:27017/mydb
NODE_ENV=development

Validación con Zod

A continuación, creamos un archivo env.js donde validaremos las variables de entorno usando Zod.

// env.js
import { z } from 'zod';
import dotenv from 'dotenv';

// Cargar las variables del archivo .env
dotenv.config();

// Definir el esquema Zod
const envSchema = z.object({
  PORT: z.string().regex(/^\d+$/).transform(Number), // Verifica que PORT sea un número
  DATABASE_URL: z.string().url(), // Verifica que DATABASE_URL sea una URL válida
  NODE_ENV: z.enum(['development', 'production', 'test']), // Acepta solo estos valores para NODE_ENV
});

// Validar las variables de entorno
const parsedEnv = envSchema.safeParse(process.env);

if (!parsedEnv.success) {
  console.error('❌ Invalid environment variables:', parsedEnv.error.format());
  process.exit(1); // Detener la aplicación si las variables no son válidas
}

// Exportar las variables validadas
export const env = parsedEnv.data;

Explicación del código:

  1. Carga de variables: Usamos dotenv.config() para cargar las variables de entorno desde el archivo .env.
  2. Esquema Zod: Definimos un esquema con las validaciones requeridas para las variables de entorno.
    • PORT: Debe ser un string que contenga solo dígitos, luego lo convertimos a número con .transform(Number).
    • DATABASE_URL: Verificamos que sea una URL válida.
    • NODE_ENV: Solo aceptamos los valores development, production o test usando z.enum.
  3. Validación: Usamos safeParse para validar process.env. Si alguna variable no es válida, se muestra un error y la aplicación se detiene con process.exit(1).

Uso en la aplicación

Ahora que las variables han sido validadas, puedes utilizarlas en tu aplicación importando el objeto env:

import { env } from './env';

console.log(`Servidor corriendo en el puerto ${env.PORT}`);
console.log(`Conectando a la base de datos en ${env.DATABASE_URL}`);

De esta manera, siempre sabrás que las variables de entorno están presentes y son válidas antes de que tu aplicación intente utilizarlas.

Consideraciones

  • Detener la aplicación en caso de error: Si alguna variable de entorno no es válida o falta, la aplicación se detendrá. Esto es útil en entornos de producción donde valores incorrectos podrían causar fallos inesperados.
  • Tipos de datos: Puedes transformar las variables de entorno a diferentes tipos (por ejemplo, números o booleanos) usando el método .transform() de Zod.

Conclusión

Zod es una herramienta poderosa para validar datos y, en este caso, es muy útil para asegurarse de que las variables de entorno tengan los valores correctos. Al integrar esta validación en tu aplicación, evitarás errores difíciles de rastrear debido a configuraciones incorrectas.

Creacion de Esquema

Dependiendo del framework querras importarlo al inicio antes que toda la aplicación Luego el lugar para importar el archivo seria en layout.ts o en middleware.ts