Un poco de historia

Si ha estado codificando por un tiempo, sabrá la importancia de las variables de entorno y el papel que desempeñan, y también el dolor de descubrir un error que fue causado simplemente porque no se configuró una maldita variable env en su proyecto. , ¡jajaja!

A principios de este año, trabajé en una startup basada en productos como pasante de desarrollador Full Stack. A medida que el proyecto crecía, también crecía el número de variables ambientales. Y todos estaban trabajando en funciones separadas en ramas separadas, por lo que no teníamos idea de si alguien introdujo alguna nueva variable env en su rama que luego se fusionó con la rama principal. Esto creó problemas cuando intenté implementar mis ramas. Tenía la idea de que se había agregado una nueva variable de entorno al proyecto.

Luego, más tarde me presentaron la pila T3 y tenía una solución brillante para agregar seguridad de tipos a las variables env. Ni siquiera sabía que existía tal solución. Siempre es bueno aprender algo nuevo cuando menos lo esperas. La pila T3 usa zod y el paquete @t3-oss/env-nextjs para agregar seguridad de tipos a sus aplicaciones, lo cual me gustó mucho. Después de eso, me comprometí a escribir siempre con seguridad mis variables de entorno sin importar nada.

Si está comenzando un nuevo proyecto o ya está trabajando en un equipo, le recomiendo encarecidamente que agregue seguridad de tipos a sus entornos. Agregar solo esto le ahorrará esfuerzos para descubrir problemas en su código base.

A continuación te explicamos cómo puedes agregarlo a tu proyecto. Es bastante simple.

¿Qué es Zod?

Zod es una biblioteca de validación y declaración de esquemas ligera y rápida. Un esquema puede ser cualquier cosa, desde una simple cadena, un número hasta un tipo de objeto complejo.

Uso básico

import {z} from 'zod';

const myBoolean = z.boolean();

myBoolean.parse('true'); // throws error
myBoolean.parse(true) // valid

Crear un esquema de objetos anidados

import { z } from 'zod';

const userSchema = z.object({
    name: z.string(),
    age: z.number(),
    address: z.object({
        house_no: z.string(),
        locality: z.string(),
        city: z.string(),
        state: z.string(),
    })
});

Puedes crear un esquema de objetos simple o crear un esquema de objetos anidados.

¿Qué es t3-oss/env-nextjs?

Es simplemente un paquete que nos ayudará a agregar seguridad de tipos a las variables de entorno

Creemos variables env con seguridad de tipos

Crea un archivo env.js en la raíz de tu proyecto.

import {createEnv} from "@t3-oss/env-nextjs"; import {z} from "zod";

export const env = createEnv({
  /*
   * Serverside Environment variables, not available on the client.
   * Will throw if you access these variables on the client.
   */
  server: {
    DB_URI: z.string().url(),
  },
  /*
   * Environment variables available on the client (and server).
   *
   * You'll get type errors if these are not prefixed with NEXT_PUBLIC_.
   */
  client: {
    NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY: z.string().min(1),
  },
  /*
   * Due to how Next.js bundles environment variables on Edge and Client,
   * we need to manually destructure them to make sure all are included in bundle.
   *
   * You'll get type errors if not all variables from `server` & `client` are included here.
   */
  runtimeEnv: {
    DB_URI: process.env.DATABASE_URL,
    NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY:
      process.env.NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY,
  },
});

Uso

import {env} from '@/env';

const CLERK_PUBLISHABLE_KEY = env.NEXT_PUBLISHABLE_KEY;

Si pasa el cursor sobre NEXT_PUBLISHABLE_KEY, puede ver que ese valor está escrito como una cadena, eso significa que nuestras variables env están escritas ahora.

Hemos agregado variables de entorno de tipo seguro, pero esto no se ejecutará en cada momento de compilación. Tenemos que importar nuestro archivo recién creado a nuestro archivo next.config.js. Puedes usar el paquete unjs/jiti para eso.

Primero, instale el paquete jiti desde npm.

import { fileURLToPath } from "node:url";
import createJiti from "jiti";
const jiti = createJiti(fileURLToPath(import.meta.url));

jiti("./app/env");

Cuando se trabaja con import.meta.url, proporciona la URL del archivo en el que está trabajando actualmente. Sin embargo, incluye un prefijo file:///, que quizás no desee. Para eliminar ese prefijo, puede usar la función fileURLToPath del módulo node:url.

Por ejemplo:

import {fileURLToPath} from 'node:url';

// Convert the file URL to a path
const filename = fileURLToPath(import.meta.url);

Ahora, si no tiene las variables de entorno requeridas, verá un error como este:

¿Cómo agregar seguridad de tipos a las variables env en proyectos Node.js?

import dotenv from "dotenv";
import { z } from "zod";

dotenv.config();

const schema = z.object({
  MONGO_URI: z.string(),
  PORT: z.coerce.number(),
  JWT_SECRET: z.string(),
  NODE_ENV: z
    .enum(["development", "production", "test"])
    .default("development"),
});

const parsed = schema.safeParse(process.env);

if (!parsed.success) {
  console.error(
    "❌ Invalid environment variables:",
    JSON.stringify(parsed.error.format(), null, 4)
  );
  process.exit(1);
}

export default parsed.data;

En los proyectos de Node.js, simplemente crearemos un esquema zod y lo analizaremos con nuestro proceso.env para verificar si todas las variables env están configuradas o no.

Uso

import express from "express";
import env from "./env";

const app = express();
const PORT = env.PORT || 5000; // PORT is type safe here....

app.listen(PORT, () => {
console.log("Connected to server on PORT ${PORT}");
connectDB();
});

Así es como agrega seguridad de tipos a sus variables de entorno. Espero que hayas aprendido algo nuevo en este tutorial.

¡¡Feliz codificación!! ?