Um pouco de fundo

Se você já codifica há algum tempo, sabe a importância das variáveis ​​de ambiente e o papel que elas desempenham, e também a dor de descobrir um bug que foi causado apenas porque uma maldita variável de ambiente não foi definida em seu projeto , lol!

No início deste ano, trabalhei em uma startup baseada em produtos como estagiário de desenvolvedor Full stack. À medida que o projeto crescia, o número de variáveis ​​ambientais também crescia. E todo mundo estava trabalhando em recursos separados em ramificações separadas, então não tínhamos ideia se alguém introduziu alguma nova variável env em sua ramificação, que mais tarde foi mesclada na ramificação principal. Isso criou problemas quando tentei implantar minhas ramificações, eu sabia que um novo env var foi adicionado ao projeto.

Mais tarde, fui apresentado à pilha T3 e ela tinha uma solução brilhante para adicionar segurança de tipo a variáveis ​​de ambiente. Eu nem sabia que tal solução existia. É sempre bom aprender algo novo quando você menos espera. A pilha T3 usa o pacote zod e @t3-oss/env-nextjs para adicionar segurança de tipo aos seus aplicativos, o que eu gostei muito. Depois disso, assumi o compromisso de sempre proteger a digitação de minhas variáveis ​​de ambiente, não importa o que aconteça.

Se você está iniciando um novo projeto ou já trabalha em equipe, recomendo fortemente que você adicione segurança de tipo aos seus ambientes. Adicionar apenas isso poupará seus esforços para descobrir problemas em sua base de código.

Aqui está como você pode adicioná-lo ao seu projeto. É bastante simples.

O que é zod?

Zod é uma biblioteca leve e rápida de declaração e validação de esquema. Um esquema pode ser qualquer coisa, desde uma simples string, número até um tipo de objeto complexo.

Uso básico

import {z} from 'zod';

const myBoolean = z.boolean();

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

Criando um esquema de objeto aninhado

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(),
    })
});

Você pode criar um esquema de objeto simples ou criar um esquema de objetos aninhados.

O que é t3-oss/env-nextjs?

É simplesmente um pacote que nos ajudará a adicionar segurança de tipo às variáveis ​​​​env

Vamos criar variáveis ​​​​env com segurança de tipo

Crie um arquivo env.js na raiz do seu projeto.

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;

Se você passar o cursor acima de NEXT_PUBLISHABLE_KEY, poderá ver que esse valor é digitado como string, o que significa que nossas variáveis ​​​​env são digitadas agora.

Adicionamos variáveis ​​​​env de tipo seguro, mas isso não será executado em todos os tempos de compilação. temos que importar nosso arquivo recém-criado para nosso arquivo next.config.js. Você pode usar o pacote unjs/jiti para isso.

Primeiro, instale o pacote jiti do npm.

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

jiti("./app/env");

Ao trabalhar com import.meta.url, ele fornece a URL do arquivo em que você está trabalhando no momento. No entanto, inclui um prefixo file:///, que você pode não querer. Para remover esse prefixo, você pode usar a função fileURLToPath do módulo node:url.

Por exemplo:

import {fileURLToPath} from 'node:url';

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

Agora, se você não tiver as variáveis ​​​​env necessárias, verá um erro como este -

Como adicionar segurança de tipo a variáveis ​​de ambiente em projetos 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;

Em projetos Node.js, vamos simplesmente criar um esquema zod e analisá-lo em nosso process.env para verificar se todas as variáveis ​​​​env estão definidas ou não.

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();
});

É assim que você adiciona segurança de tipo às suas variáveis ​​de ambiente. Espero que você tenha aprendido algo novo neste tutorial.

Boa codificação!! ?