خلفية صغيرة

إذا كنت تقوم بالبرمجة لفترة من الوقت، فأنت تعرف أهمية متغيرات البيئة والدور الذي تلعبه، وكذلك الألم الناتج عن اكتشاف الخطأ الذي حدث لمجرد عدم تعيين متغير env اللعين في مشروعك ، مضحك جداً!

في وقت سابق من هذا العام، عملت في شركة ناشئة قائمة على المنتجات كمتدرب مطور مكدس كامل. ومع نمو المشروع، زاد أيضًا عدد متغيرات البيئة. وكان الجميع يعملون على ميزات منفصلة في فروع منفصلة، ​​لذلك لم تكن لدينا أي فكرة عما إذا كان شخص ما قد قدم بعض متغيرات البيئة الجديدة في فرعهم والتي تم دمجها لاحقًا في الفرع الرئيسي. أدى هذا إلى حدوث مشكلات عندما حاولت نشر فروعي، وكنت أعرف فكرة إضافة env var جديد إلى المشروع.

ثم تعرفت لاحقًا على مكدس T3 وكان لديه حل رائع لإضافة أمان النوع إلى متغيرات البيئة. لم أكن أعلم حتى بوجود مثل هذا الحل. من الجيد دائمًا أن تتعلم شيئًا جديدًا عندما لا تتوقعه. يستخدم مكدس T3 حزمة zod و@t3-oss/env-nextjs لإضافة نوع الأمان إلى تطبيقاتك التي أعجبتني كثيرًا. بعد ذلك، التزمت دائمًا بتأمين متغيرات البيئة الخاصة بي مهما حدث.

إذا كنت تبدأ مشروعًا جديدًا، أو تعمل بالفعل ضمن فريق، فإنني أنصحك بشدة بإضافة نوع الأمان إلى بيئاتك. ستؤدي إضافة هذا فقط إلى توفير جهودك في اكتشاف المشكلات في قاعدة التعليمات البرمجية الخاصة بك.

إليك كيف يمكنك إضافته إلى مشروعك. إنها بسيطة إلى حد ما.

ما هو زود؟

Zod عبارة عن مكتبة للإقرار والتحقق من المخططات خفيفة الوزن وسريعة. يمكن أن يكون المخطط أي شيء بدءًا من سلسلة بسيطة أو رقم إلى نوع كائن معقد.

الاستخدام الأساسي

import {z} from 'zod';

const myBoolean = z.boolean();

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

إنشاء مخطط كائن متداخل

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

يمكنك إنشاء مخطط كائن بسيط أو إنشاء مخطط كائنات متداخلة.

ما هو t3-oss/env-nextjs؟

إنها ببساطة حزمة ستساعدنا على إضافة نوع الأمان إلى متغيرات البيئة

لنقم بإنشاء متغيرات env آمنة للنوع

قم بإنشاء ملف env.js في جذر مشروعك.

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

الاستخدام

import {env} from '@/env';

const CLERK_PUBLISHABLE_KEY = env.NEXT_PUBLISHABLE_KEY;

إذا قمت بتمرير مؤشر الماوس فوق NEXT_PUBLISHABLE_KEY، فيمكنك أن ترى أن هذه القيمة مكتوبة كسلسلة، وهذا يعني أن متغيرات env الخاصة بنا مكتوبة الآن.

لقد أضفنا متغيرات النوع الآمن للبيئة، لكن هذا لن يعمل في كل مرة إنشاء. يتعين علينا استيراد ملفنا الذي تم إنشاؤه حديثًا إلى ملف next.config.js الخاص بنا. يمكنك استخدام حزمة unjs/jiti لذلك.

أولاً، قم بتثبيت jiti pacakge من npm.

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

jiti("./app/env");

عند العمل مع import.meta.url، فإنه يوفر عنوان URL للملف الذي تعمل فيه حاليًا. ومع ذلك، فهو يتضمن بادئة file:///، والتي قد لا تريدها. لإزالة هذه البادئة، يمكنك استخدام الدالة fileURLToPath من وحدة العقدة:url.

على سبيل المثال:

import {fileURLToPath} from 'node:url';

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

الآن، إذا لم يكن لديك متغيرات البيئة المطلوبة، فسوف ترى خطأ مثل هذا -

كيفية إضافة أمان النوع إلى متغيرات env في مشاريع 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;

في مشاريع Node.js، سنقوم ببساطة بإنشاء مخطط zod وتحليله مقابل العملية.env الخاصة بنا للتحقق مما إذا تم تعيين جميع متغيرات env أم لا.

الاستخدام

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

هذه هي الطريقة التي تضيف بها أمان النوع إلى متغيرات البيئة الخاصة بك. أتمنى أن تكون قد تعلمت شيئًا جديدًا في هذا البرنامج التعليمي.

سعيد بالبرمجة!! ?