Dotenv

يُفعِّل الخيار dotenv ميزة تحميل متغيّرات البيئة المدمجة في webpack من ملفّات .env.

boolean object

فعِّل plugin الـ Dotenv المدمج واضبطه ليُحمِّل متغيّرات البيئة من ملفّات .env.

webpack.config.js

export default {
  // ...
  dotenv: true,
};

ضبط dotenv على true يُفعِّل الـ plugin بخياراته الافتراضية. أمّا إن أردت تخصيصاً أعمق فمرِّر كائن خيارات:

export default {
  // ...
  dotenv: {
    prefix: "WEBPACK_",
    dir: true,
    template: [".env", ".env.local", ".env.[mode]", ".env.[mode].local"],
  },
};

الخيارات

prefix

string string[]

الافتراضي: 'WEBPACK_'

لا تُكشف من متغيّرات البيئة إلا تلك التي تبدأ بالبادئة (أو البادئات) المُحدَّدة. وهذا يحول دون كشفك المتغيّرات الحسّاسة بغير قصد.

webpack.config.js

export default {
  // ...
  dotenv: {
    prefix: "APP_", // اكشف فقط متغيّرات APP_*
  },
};

عدّة بادئات:

export default {
  // ...
  dotenv: {
    prefix: ["APP_", "CONFIG_"], // اكشف متغيّرات APP_* و CONFIG_* كلتيهما
  },
};

dir

boolean string

الافتراضي: true

المجلَّد الذي تُحمَّل منه ملفّات .env.

• true — التحميل من جذر المشروع (السياق).
• false — تعطيل تحميل ملفّات .env.
• string — مسار نسبي من جذر المشروع، أو مسار مطلق.

webpack.config.js

export default {
  // ...
  dotenv: {
    dir: "./config", // التحميل من مجلَّد ./config
  },
};

تعطيل التحميل:

export default {
  // ...
  dotenv: {
    dir: false, // الاكتفاء بمتغيّرات process.env
  },
};

template

string[]

الافتراضي: ['.env', '.env.local', '.env.[mode]', '.env.[mode].local']

أنماط قوالب لأسماء ملفّات .env. استعمل [mode] بوصفه عنصراً نائباً لـ webpack mode (مثل development و production).

تُحمَّل الملفّات بالترتيب المُحدَّد، والملفّات اللاحقة تُلغي ما سبقها من قيم متطابقة.

webpack.config.js

export default {
  // ...
  mode: "production",
  dotenv: {
    template: [".env", ".env.production"], // اكتفِ بتحميل هذين الملفّين فقط
  },
};

أنماط مخصَّصة:

export default {
  // ...
  dotenv: {
    template: [
      ".env",
      ".env.local",
      ".env.[mode]",
      ".env.[mode].local",
      ".env.override", // يُحمَّل دائماً في الأخير
    ],
  },
};

أولوية الملفّات

تُحمَّل ملفّات البيئة بحسب الترتيب، والملفّات اللاحقة لها الأولوية الأعلى:

1. .env — يُحمَّل في كلّ الأوضاع.
2. .env.local — يُحمَّل في كلّ الأوضاع، ويُتجاهَل من git (عُرفاً).
3. .env.[mode] — لا يُحمَّل إلا في الوضع المُحدَّد (مثل .env.production).
4. .env.[mode].local — لا يُحمَّل إلا في الوضع المُحدَّد، ويُتجاهَل من git.

تُلغي متغيّرات الملفّات اللاحقة قيمَ الملفّات السابقة. وفوق ذلك، تأخذ المتغيّرات المضبوطة فعلاً في process.env الأولوية القصوى.

توسيع المتغيّرات

تُوسَّع متغيّرات البيئة تلقائياً وفق صياغة dotenv-expand:

.env

WEBPACK_API_BASE=https://api.example.com
WEBPACK_API_URL=${WEBPACK_API_BASE}/v1
WEBPACK_PORT=${WEBPACK_PORT:-3000}  # استعمل WEBPACK_PORT من process.env، وإلا اعتمد 3000 افتراضياً

في شيفرتك:

console.log(process.env.WEBPACK_API_URL); // "https://api.example.com/v1"
console.log(process.env.WEBPACK_PORT); // قيمة process.env.WEBPACK_PORT إن وُجدت، وإلا "3000"

مثال على سلوك التوسيع:

# ملفّ .env
WEBPACK_API_URL=${API_BASE:-https://default.com}/api

# شغِّل مع متغيّر بيئة
API_BASE=https://custom.com npm run build

النتيجة: ستصبح process.env.WEBPACK_API_URL هي "https://custom.com/api"، لأنّ API_BASE من process.env يُستعمَل في أثناء التوسيع، وإن كان API_BASE نفسه لن يُكشف في الحزمة (لأنّه لا يحمل البادئة WEBPACK_).

أمثلة على الاستخدام

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

أنشئ ملفّ .env في جذر مشروعك:

.env

WEBPACK_API_URL=https://api.example.com
WEBPACK_FEATURE_FLAG=true
SECRET_KEY=should-not-be-exposed  # لن يُكشف (لا يحمل البادئة WEBPACK_)

webpack.config.js

export default {
  // ...
  dotenv: true, // يستعمل البادئة الافتراضية "WEBPACK_"
};

في تطبيقك:

console.log(process.env.WEBPACK_API_URL); // "https://api.example.com"
console.log(process.env.WEBPACK_FEATURE_FLAG); // "true"
console.log(process.env.SECRET_KEY); // undefined (غير مكشوف)

تخصيص خاصّ بكلّ وضع

أنشئ ملفّات خاصّة بكلّ وضع:

.env

WEBPACK_API_URL=https://api.example.com
WEBPACK_DEBUG=false

.env.production

WEBPACK_API_URL=https://prod-api.example.com
WEBPACK_DEBUG=false

.env.development

WEBPACK_API_URL=https://dev-api.example.com
WEBPACK_DEBUG=true

حين تبني مع --mode production، ستكون WEBPACK_API_URL مساوية لـ "https://prod-api.example.com".

عدّة بادئات

اكشف متغيّرات ذات بادئات مختلفة:

.env

APP_NAME=MyApp
APP_VERSION=1.0.0
CONFIG_TIMEOUT=5000
CONFIG_RETRY=3
PRIVATE_KEY=secret  # لن يُكشف

webpack.config.js

export default {
  // ...
  dotenv: {
    prefix: ["APP_", "CONFIG_"],
  },
};

مجلَّد وقالب مخصَّصان

حمِّل ملفّات البيئة من موقع مخصَّص وبأسماء مخصَّصة:

webpack.config.js

export default {
  // ...
  dotenv: {
    dir: "./environments",
    template: [".env.base", ".env.[mode]"],
  },
};

سيُحمَّل من هذا التخصيص:

• ./environments/.env.base
• ./environments/.env.production (في وضع production)

اعتبارات أمنية

• استعمل .gitignore لاستبعاد ملفّات .env.local و .env.[mode].local.
• اكشف فقط متغيّرات البيئة ذات البادئات المُحدَّدة.
• لا تستعمل النصّ الفارغ '' بادئةً.
• فكِّر في استعمال ملفّات .env منفصلة لكلّ بيئة.
• خزِّن أسرار الإنتاج في متغيّرات البيئة الخاصّة بمنصّة النشر لديك.

.gitignore

# ملفّات البيئة المحلية
.env.local
.env.*.local