node-config: config/default.json, production.json va config iyerarxiyasi

Qisqacha: node-config (config paketi) sozlamalarni config/ papkasidagi fayllardan qatlam-qatlam yig'adi: default.json → production.json (muhit nomi bo'yicha) → local.json → custom-environment-variables.json (env'dan). Har qatlam oldingisini chuqur birlashtiradi — faqat o'zida bor kalitlarni bosadi. config.get("server.port") — yo'q kalitda xato tashlaydi, obyekt o'zgartirib bo'lmaydi. Katta loyihalarda standart, lekin u qiymatlarni tekshirmaydi: kanon tajribasida PORT=yuz bilan port maydoni jim yo'qoldi. Shuning uchun vazifalar-api ga kirmadi.

Bu darsda

• config/ papkasidagi fayllar qaysi tartibda o'qilishini va qanday birlashishini tushuntira olasiz.
• custom-environment-variables.json bilan env'ni ulaysiz (__name, __format).
• NODE_ENV va NODE_CONFIG_ENV farqini, strict mode ogohlantirishini bilasiz.
• config.get, config.has, o'zgarmaslik va fayl formatlarini (JSON5, YAML, TS) ishlatasiz.
• node-config qachon kerak va qachon ortiqcha ekanini o'lchov bilan ayta olasiz.

Oldin bilishingiz kerak: Environment o'zgaruvchilar va .env, Obyekt nusxalash: shallow va deep, CommonJS va require.

1. Nega bu kerak?

Oldingi darsda hamma sozlama — env'da, tekis ro'yxatda: PORT, HOST, CORS_ORIGINS, LOG_LEVEL. 12 ta kalit — yaxshi. Endi katta loyihani tasavvur qiling: to'lov tizimlari (Click, Payme), uchta tashqi API, kesh, navbat, email shablonlari... 150 ta kalit. Ularning 120 tasi hamma muhitda bir xil, faqat 30 tasi farq qiladi.

150 ta qatorni har serverga env qilib yozish — xatolarning manbai. Bunday loyihalarda boshqa yondashuv ishlatiladi: sukut qiymatlar fayllarda, ierarxiya bilan, env esa faqat farq qiladigan va maxfiy narsalar uchun. Node ekotizimidagi eng mashhur vosita — node-config (npm'da config paketi, 2011 yildan).

O'xshatish: kiyim. Hamma kuni kiyadigan asosiy kiyim (default.json), ustiga ob-havoga qarab kurtka (production.json), uyda o'zingizga qulay tapochka (local.json), va eshikdan chiqayotganda kimdir qo'lingizga bergan soyabon (env). Har qatlam faqat o'z narsasini qo'shadi — kurtka kiyganingiz uchun shimingiz yo'qolib qolmaydi.

2. Papka va fayllar

2.1 Tuzilma

loyiha/
  config/
    default.json                        hamma muhit uchun asos
    production.json                     NODE_ENV=production bo'lsa
    test.json                           NODE_ENV=test bo'lsa
    local.json                          shu kompyuter (git'da EMAS)
    custom-environment-variables.json   env → config xaritasi
  src/

Kodda:

import config from "config";

const port = config.get("server.port");
const host = config.get("server.host");

config — CommonJS paket, lekin ESM'dan import bilan ham ishlaydi (CJS va ESM interop darsi).

2.2 Kanon tajribasi: to'rt qatlam

Kanon config@5.0.1 bilan (bog'liqligi bitta — json5) shunday fayllarni sinadi (t36-config.txt):

{ "server": { "port": 3000, "host": "127.0.0.1" },
  "saqlash": "xotira", "cors": [] }

Bu — default.json. production.json: { "server": { "host": "0.0.0.0" }, "saqlash": "fayl" }. local.json: { "server": { "port": 4100 } }. custom-environment-variables.json:

{ "server": { "port": { "__name": "PORT", "__format": "number" } } }

Natijalar (server qismi va saqlash):

NODE_ENV yo'q:    exit 0: {"port":4100,"host":"127.0.0.1"} xotira
NODE_ENV=production: exit 0: {"port":4100,"host":"0.0.0.0"} fayl
production + PORT=5000: exit 0: {"port":5000,"host":"0.0.0.0"} fayl
NODE_CONFIG_ENV=production (NODE_ENV=development): exit 0: {"port":4100,"host":"0.0.0.0"} fayl

Har qatorni o'qiymiz:

1. NODE_ENV yo'q: default + local → port 4100 (local dan), host default dan.
2. production: production.json host'ni almashtirdi, portga tegmadi (unda port yo'q) — port baribir local dan 4100.
3. PORT=5000: env eng kuchli — 5000.
4. NODE_CONFIG_ENV — NODE_ENV dan ustun (pastda).

2.3 Biz kengroq sinadik: qaysi fayllar o'qildi

config.util.getConfigSources() — qaysi fayllar, qaysi tartibda yuklanganini aytadi. Biz production.json5 (JSON5 formatda), test.yaml (YAML) va log.daraja uchun LOG_LEVEL qo'shib sinadik (config 5.0.1, Node 24.21.0). Har rejimda ikki narsaga qarang: host va log.daraja qiymatlari hamda manbalar qatoridagi ikkinchi fayl:

== NODE_ENV yo'q
{"server":{"port":4100,"host":"127.0.0.1"},"saqlash":"xotira","log":{"daraja":"info"}}
manbalar: config/default.json → config/local.json → config/custom-environment-variables.json
== NODE_ENV=production
{"server":{"port":4100,"host":"0.0.0.0"},"saqlash":"fayl","log":{"daraja":"info"}}
manbalar: config/default.json → config/production.json5 → config/local.json → config/custom-environment-variables.json
== NODE_ENV=test
{"server":{"port":4100,"host":"127.0.0.1"},"saqlash":"xotira","log":{"daraja":"silent"}}
manbalar: config/default.json → config/test.yaml → config/local.json → config/custom-environment-variables.json
== production + PORT=5000 LOG_LEVEL=warn
{"server":{"port":5000,"host":"0.0.0.0"},"saqlash":"fayl","log":{"daraja":"warn"}}
manbalar: config/default.json → config/production.json5 → config/local.json → config/custom-environment-variables.json

Nima bo'ldi? manbalar qatorida faqat ikkinchi fayl almashdi: NODE_ENV qaysi bo'lsa, o'sha nomdagi fayl (production.json5 yoki test.yaml) o'qildi — format (JSON5, YAML) muhim emas. Port to'rt holatdan uchtasida 4100: uni local.json bosib turibdi. Faqat oxirgi holatda env (PORT=5000) uni yengdi.

flowchart LR
  A[default.json] --> B["NODE_ENV fayli<br/>production.json5"]
  B --> C[local.json]
  C --> D["custom-environment-<br/>variables.json"]
  D --> E["config obyekti<br/>(muzlatilgan)"]

Diagrammadagi tartib — hujjatdagi to'liq ro'yxatning soddalashtirilgani. Hujjatda oraliq fayllar ham bor: default-{instance}, {hostname}, local-{deployment} va boshqalar. Ular kam ishlatiladi; kerak bo'lsa NODE_APP_INSTANCE va hostname bo'yicha qo'shimcha qatlamlar mumkin.

Tekshirib ko'ring: local.json da port 4100. Serverda ham local.json bo'lsa nima bo'ladi?

3. Chuqur birlashtirish (deep merge)

3.1 Model

node-config qatlamlarni chuqur birlashtiradi: ichma-ich obyektda faqat berilgan kalit almashadi. Oddiy { ...a, ...b } esa sayoz — nusxalash darsida ko'rgan farq. Brauzerda farqni ko'ramiz:

function chuqur(asos, ustki) {
  const natija = { ...asos };
  for (const [k, v] of Object.entries(ustki)) {
    const ikkalasiObyekt = typeof v === "object" && v !== null &&
      !Array.isArray(v) && typeof natija[k] === "object";
    natija[k] = ikkalasiObyekt ? chuqur(natija[k], v) : v;
  }
  return natija;
}

const sukut = { server: { port: 3000, host: "127.0.0.1" },
  cors: ["http://localhost:5173"] };
const prod = { server: { host: "0.0.0.0" },
  cors: ["https://example.com"] };

console.log("sayoz:", { ...sukut, ...prod }.server);
console.log("chuqur:", chuqur(sukut, prod).server);
console.log("massiv:", chuqur(sukut, prod).cors);

Konsolda:

sayoz: { host: '0.0.0.0' }
chuqur: { port: 3000, host: '0.0.0.0' }
massiv: [ 'https://example.com' ]

Sayoz birlashtirishda server.port yo'qoldi — prod.server butun obyektni almashtirdi. Chuqurda — faqat host. Uchinchi qatorga qarang: massivlar birlashtirilmaydi, almashtiriladi. node-config ham massivni shunday qiladi — production.json dagi cors ro'yxati default.json dagini to'liq bosadi.

4. Env'ni ulash: custom-environment-variables.json

4.1 Xarita

Bu fayl qiymat emas, xarita: "config'ning shu yo'li — shu env o'zgaruvchisidan".

{
  "server": {
    "port": { "__name": "PORT", "__format": "number" }
  },
  "log": { "daraja": "LOG_LEVEL" }
}

• Oddiy satr ("LOG_LEVEL") — env qiymati satr sifatida.
• __name + __format — env qiymatini aylantirish: number, boolean, json, yaml va boshqalar.
• Env o'zgaruvchisi yo'q bo'lsa — bu qatlam o'sha kalitga tegmaydi, oldingi qiymat qoladi.

4.2 Topilma: jim yo'qolgan maydon

Endi asosiy savol: env'da yaroqsiz qiymat bo'lsa nima bo'ladi? Kanon PORT=yuz bilan sinadi:

PORT=yuz (format number): exit 0: {"host":"127.0.0.1"} xotira has(yoq): false

exit 0 — ilova bemalol ishga tushdi. server obyektida esa port umuman yo'q: na 4100 (local), na 3000 (default). Xato yo'q, ogohlantirish yo'q. Number("yuz") — NaN, node-config uni "qiymat" sifatida qabul qilmadi va kalitni o'chirib yubordi.

Keyin kodda config.get("server.port") xato tashlaydi — lekin ishga tushishda emas, birinchi ishlatilgan joyda. Yomonroq holat: config.server.port ni to'g'ridan o'qisangiz — undefined, listen(undefined) esa tasodifiy port ochadi. env darsidagi PORT= tuzog'ining yana bir ko'rinishi.

Diqqat: node-config — yig'uvchi, tekshiruvchi emas. U "qaysi qiymat qayerdan" ni hal qiladi, lekin "qiymat to'g'rimi" ni so'ramaydi. Tekshiruvni alohida qo'shish kerak — keyingi darsda Zod bilan.

5. API: get, has va o'zgarmaslik

Kanon tajribasidan (har uch rejimda bir xil):

get(yoq) → Configuration property "yoq" is not defined
o'zgartirish → Error: Can not update runtime configuration property: "port". Configuration objects are

get ning xato tashlashi — yaxshi: noto'g'ri yozilgan kalit (config.get("sever.port")) darhol ko'rinadi. To'g'ridan o'qish esa xatoni yashiradi.

O'zgarmaslik (immutability): birinchi get chaqiruvidan keyin config obyekti muzlatiladi. Ikkinchi qator — config.server.port = 1 ga urinish natijasi: "ishlash paytidagi sozlamani o'zgartirib bo'lmaydi". Bu ataylab: ilova o'rtasida kimdir sozlamani "vaqtincha" o'zgartirib, keyin qaytarishni unutsa — butun ilova boshqacha ishlaydi. Testda boshqa qiymat kerak bo'lsa — NODE_ENV=test va test.json, kodda o'zgartirish emas.

Tekshirib ko'ring: Nega config.server.port o'rniga config.get("server.port") tavsiya qilinadi?

6. NODE_ENV, NODE_CONFIG_ENV va strict mode

6.1 Ikki o'zgaruvchi

node-config qaysi muhit faylini o'qishni NODE_ENV dan oladi. Lekin env darsida ko'rdik: NODE_ENV ni kutubxonalar ham o'qiydi (Express, npm). Ba'zan ularni ajratish kerak: "kutubxonalar production rejimida ishlasin, lekin config staging.json dan olinsin".

Buning uchun NODE_CONFIG_ENV — u faqat node-config uchun va NODE_ENV dan ustun. Kanon tajribasining to'rtinchi qatori: NODE_ENV=development, NODE_CONFIG_ENV=production → host 0.0.0.0 (production fayli).

6.2 Biz topdik: xato yozilgan muhit nomi

NODE_ENV=prod (to'g'risi — production) bilan sinadik:

== NODE_ENV=prod (xato yozilgan)
{"server":{"port":4100,"host":"127.0.0.1"},"saqlash":"xotira","log":{"daraja":"info"}}
manbalar: config/default.json → config/local.json → config/custom-environment-variables.json
WARNING: NODE_ENV value of 'prod' did not match any deployment config file names.
WARNING: See https://github.com/node-config/node-config/wiki/Strict-Mode

Ilova ishga tushdi — development sozlamalari bilan (host 127.0.0.1, saqlash: xotira). Production serverda bu ma'lumot xotirada saqlanib, qayta ishga tushganda yo'qolishi demak. Faqat ogohlantirish chiqdi — u log ichida yo'qolib ketishi oson. Hujjatdagi "Strict Mode" sozlamasi (NODE_CONFIG_STRICT_MODE=1) bu ogohlantirishni xatoga aylantiradi — production'da yoqib qo'yishga arziydi.

6.3 Boshqa o'zgaruvchilar

7. Formatlar

node-config ko'p formatni o'qiy oladi. Paketning parser.js faylidagi ro'yxat (5.0.1): js, cjs, mjs, ts, json, jsonc, json5, hjson, toml, coffee, yaml, yml, cson, properties, xml. Lekin hammasi "qutidan" emas:

JS formatining afzalligi — hisoblangan qiymatlar (port: Number(process.env.PORT) || 3000). Kamchiligi — config fayli endi kod: unda xato bo'lishi va sir yashirinishi mumkin. Formatlarning o'zi (YAML'ning no tuzog'i, TOML, INI) — keyingi darslardan birida.

config/default.json5 — izohli sozlama uchun yaxshi tanlov:

{
  server: {
    // Docker ichida 0.0.0.0 (33-qism)
    host: "127.0.0.1",
    port: 3000,
  },
}

8. Nega vazifalar-api ga kirmadi

Kanon qarori (QADAMLAR.md): node-config kirmadi — env + Zod yetarli (12-factor). Sabablar o'lchovdan:

Bu "node-config yomon" degani emas. U fayllar ierarxiyasini zo'r yechadi va ko'p yirik loyihalarda bor — begona repoda config/default.json ni ko'rsangiz, endi uni o'qiy olasiz. Faqat uni ishlatsangiz, ustiga tekshiruv qo'shing: config.util.toObject() ni olib, Zod sxemasidan o'tkazing.

9. API qadami: tajriba (holat 40, 2-qism)

Bu dars vazifalar-api ga kod qo'shmaydi — kanon qarori bo'yicha node-config kirmadi. Hali commit qilmang.

O'zingiz takrorlab ko'ring — loyihadan tashqarida, alohida papkada:

mkdir nc-tajriba && cd nc-tajriba
npm init -y
npm i --save-exact config@5.0.1
mkdir config

config/ ga yuqoridagi to'rt faylni yozing va chiq.mjs:

import config from "config";
console.log(JSON.stringify(config.util.toObject()));

Uch marta ishga tushiring: node chiq.mjs, NODE_ENV=production node chiq.mjs, PORT=yuz node chiq.mjs. Uchinchisida port qayerga ketganini o'z ko'zingiz bilan ko'ring.

10. Ko'p uchraydigan xatolar

11. Mashqlar

Yechimlar kurs/mashqlar/25/36-node-config/ da.

1-mashq (oson): natijani ayting

default.json: { "db": { "host": "localhost", "port": 5432 }, "kesh": true }. production.json: { "db": { "host": "db.ichki" }, "kesh": false }. custom-environment-variables.json: { "db": { "port": { "__name": "DB_PORT", "__format": "number" } } }. NODE_ENV=production DB_PORT=6432 bilan:

• config.get("db.host") —
• config.get("db.port") —
• config.get("kesh") —
• config.has("db.parol") —

2-mashq (o'rta): qatlamli yig'uvchi

Darsdagi chuqur funksiyasidan foydalanib yigma(qatlamlar) yozing: qatlamlar massivini chapdan o'ngga birlashtiradi va natijani chuqur muzlatadi (har ichki obyektga Object.freeze). Ichki qiymatni o'zgartirishga urinish qat'iy rejimda xato bersin.

"use strict";
function chuqur(asos, ustki) {
  const natija = { ...asos };
  for (const [k, v] of Object.entries(ustki)) {
    const ikkalasiObyekt = typeof v === "object" && v !== null &&
      !Array.isArray(v) && typeof natija[k] === "object";
    natija[k] = ikkalasiObyekt ? chuqur(natija[k], v) : v;
  }
  return natija;
}
function muzlat(o) {
  for (const v of Object.values(o)) {
    if (typeof v === "object" && v !== null) muzlat(v);
  }
  return Object.freeze(o);
}
function yigma(qatlamlar) {
  return muzlat(qatlamlar.reduce((a, q) => chuqur(a, q), {}));
}

const c = yigma([
  { server: { port: 3000, host: "127.0.0.1" } },
  { server: { host: "0.0.0.0" } },
  { server: { port: 4100 } },
]);
console.log(c.server);
try {
  c.server.port = 1;
} catch (x) {
  console.log(x.constructor.name);
}
console.log(c.server.port);

{ port: 4100, host: '0.0.0.0' }
TypeError
4100

3-mashq (qiyin): __format ni xavfsiz qiling

envniUla(xarita, env) yozing: custom-environment-variables.json shaklidagi xaritani oladi va obyekt qaytaradi. __format: "number" da qiymat butun son bo'lmasa — jim o'chirish o'rniga xatolar ro'yxatiga "server.port: PORT butun son emas" qo'shsin. Natija: { qiymat, xatolar }. Qiymatning o'zini xabarga qo'shmang.

function envniUla(xarita, env, yol = []) {
  const qiymat = {};
  const xatolar = [];
  for (const [k, v] of Object.entries(xarita)) {
    const joy = [...yol, k];
    if (typeof v === "string") {
      if (env[v] !== undefined) qiymat[k] = env[v];
    } else if ("__name" in v) {
      const xom = env[v.__name];
      if (xom === undefined) continue;
      if (v.__format === "number") {
        const son = Number(xom);
        if (xom.trim() === "" || !Number.isInteger(son)) {
          const nom = joy.join(".");
          xatolar.push(`${nom}: ${v.__name} butun son emas`);
        } else qiymat[k] = son;
      } else qiymat[k] = xom;
    } else {
      const ichki = envniUla(v, env, joy);
      if (Object.keys(ichki.qiymat).length) qiymat[k] = ichki.qiymat;
      xatolar.push(...ichki.xatolar);
    }
  }
  return { qiymat, xatolar };
}

const xarita = {
  server: { port: { __name: "PORT", __format: "number" } },
  log: { daraja: "LOG_LEVEL" },
};
console.log(JSON.stringify(envniUla(xarita, { PORT: "5000" })));
console.log(JSON.stringify(envniUla(xarita, { PORT: "yuz" })));
console.log(JSON.stringify(envniUla(xarita, { LOG_LEVEL: "warn" })));

{"qiymat":{"server":{"port":5000}},"xatolar":[]}
{"qiymat":{},"xatolar":["server.port: PORT butun son emas"]}
{"qiymat":{"log":{"daraja":"warn"}},"xatolar":[]}

4-mashq: API qadami

«API qadami» bo'limidagi tajribani loyihadan tashqarida bajaring. Uch rejim natijasini yozib qo'ying va o'zingizga javob bering: vazifalar-api ning 12 ta sozlamasi uchun node-config nima beradi va nima oladi? Commit yo'q — loyiha o'zgarmaydi.

12. Real ishda

• Ko'p yillik Express loyihalarida config/ papkasi odatiy — ularni o'qish va o'zgartirish ishning bir qismi.
• NestJS'ning @nestjs/config moduli ham shunga o'xshash g'oyani boshqa shaklda beradi (30-qism).
• Strict mode va sxema tekshiruvi — mavjud loyihaga qo'shsangiz katta foyda beradigan ikki o'zgarish.
• Intervyu savollari: "Config fayllari qaysi tartibda birlashadi?", "local.json nima uchun git'da yo'q?", "Config'ni ishlash paytida o'zgartirsa bo'ladimi?"

Xulosa

• node-config: default → muhit fayli → local → env xaritasi; har qatlam chuqur birlashtiradi, massivlar almashtiriladi.
• custom-environment-variables.json — env → config yo'li; __format bilan tur.
• config.get — yo'q kalitda xato (yaxshi); config muzlatilgan; NODE_CONFIG_ENV > NODE_ENV.
• Tuzoqlar: yaroqsiz env qiymat jim yo'qoladi; muhit nomidagi xato faqat ogohlantirish (strict mode bilan xato).
• vazifalar-api ga kirmadi: 12 sozlama uchun env + Zod soddaroq va qat'iyroq.

Keyingi dars: Env validatsiyasi va tipli config obyekti — src/config.ts: Zod bilan bitta sxema, muzlatilgan tipli obyekt va noto'g'ri sozlamada exit 78.

Manbalar

• node-config wiki — Configuration Files (fayllar tartibi), Environment Variables, Strict Mode: https://github.com/node-config/node-config/wiki
• npm — config@5.0.1: https://www.npmjs.com/package/config
• Kanon: natijalar/tajriba/t36-config.txt (config 5.0.1: to'rt qatlam, NODE_CONFIG_ENV, get/o'zgartirish xatolari, PORT=yuz da jim yo'qolish), QADAMLAR.md qarori. JSON5/YAML fayllari, getConfigSources, LOG_LEVEL va NODE_ENV=prod strict mode ogohlantirishi — biz ishga tushirdik (config 5.0.1, yaml 2.9.1, Node 24.21.0, Windows 11).