tsconfig app va node: Vite loyihasida ikki tsconfig, references va tsc -b

Qisqacha: Vite loyihasida kod ikki xil muhitda ishlaydi: src/ — brauzerda (DOM bor, Node yo'q), vite.config.ts va skriptlar — Node'da (DOM yo'q). Shuning uchun ikki tsconfig: tsconfig.app.json va tsconfig.node.json. Ildizdagi tsconfig.json ularni references bilan birlashtiradi, tsc -b esa ikkalasini tekshiradi. vazifalar da bu ajratish birinchi marta tekshirilgan Node kodida 26 ta xato topdi.

Bu darsda

• Nega bitta tsconfig yetmasligini va qaysi xatoni yashirishini ko'rsatasiz.
• tsconfig.json + tsconfig.app.json + tsconfig.node.json uchligini o'qiy va yoza olasiz.
• references, files: [] va tsc -b qanday ishlashini tushuntirasiz.
• vazifalar ni ikki tsconfig'ga bo'lib, 26 ta xatoni JSDoc bilan tuzatasiz.
• React shablonidagi bayroqlarni (jsx, skipLibCheck, moduleDetection) o'qiysiz — 17-qismda shu fayllar bilan ishlaymiz.

Oldin bilishingiz kerak: tsconfig.json chuqur, Build: tsc, bundler'lar va tsgo, JSDoc va @ts-check.

1. Nega bu kerak?

vazifalar ning hozirgi tsconfig.json ida "include": ["src"] yozilgan. Ya'ni tsc faqat src/ ni tekshiradi. Loyihada esa boshqa kod ham bor:

Sardor so'radi: "Unda include ga vite.config.ts va skriptlar ni qo'shamiz-da?" Urinib ko'ramiz. Lekin bitta muammo bor: src/ uchun lib da "dom" turibdi — document, window. Skriptlar uchun esa process va node:fs turlari kerak. Bitta tsconfig'da ikkalasini yoqsak, nima bo'ladi?

Muhit — kod ishlaydigan joy va unda mavjud global narsalar. Brauzerda document bor, process yo'q. Node'da teskarisi. Ikki xil oshxona kabi: biri tandir bilan (somsa), biri qozon bilan (osh). Bitta retsept daftarida "tandirga qo'ying" deb osh yozsangiz — xato faqat oshxonada bilinadi.

2. Bitta tsconfig nimani yashiradi

2.1 Tajriba

Mashq loyihasi: src/main.ts (brauzer — menyuni sahifaga chiqaradi) va skriptlar/hisobot.ts (Node — hisobotni faylga yozadi). Hisobot skriptida atayin xato bor:

// Node: menyu hisobotini faylga yozadi (npm run hisobot)
import { writeFileSync } from "node:fs";

const lines = ["osh: 35000", "manti: 30000"];
writeFileSync("hisobot.txt", lines.join("\n"));
document.title = "Hisobot tayyor";
console.log("Yozildi:", process.cwd());

document.title — Node'da document yo'q, bu qator ishga tushganda ReferenceError beradi. Bitta tsconfig bilan — ikkala muhit birga:

{
  "compilerOptions": {
    "strict": true,
    "noEmit": true,
    "target": "es2024",
    "lib": ["es2024", "dom"],
    "types": ["node"],
    "module": "nodenext"
  },
  "include": ["src", "skriptlar"]
}

npx tsc

Buyruq jim tugaydi (chiqish yo'q, chiqish kodi 0). TypeScript xatoni ko'rmadi: lib da dom bor — demak, document hamma faylda "mavjud". Teskarisi ham: src/main.ts da process.env yozsangiz, u ham jim o'tadi, chunki types: ["node"] hamma faylga tegishli.

2.2 Qoida

lib va types — butun tsconfig uchun. Bitta tsconfig = bitta muhit. Ikki muhit — ikki tsconfig.

Tekshirib ko'ring: Nega tsc bu holatda "xato yo'q" deydi, garchi skript ishga tushganda yiqilsa ham?

3. Uch fayl: solution + app + node

3.1 Tuzilma

flowchart TB
  R["tsconfig.json<br/>files: []<br/>references"] --> A["tsconfig.app.json<br/>src/<br/>lib: dom"]
  R --> N["tsconfig.node.json<br/>vite.config.ts, skriptlar/<br/>types: node"]
  A --> B["brauzer kodi"]
  N --> C["Node kodi"]

Ildizdagi tsconfig.json o'zi hech qanday faylni tekshirmaydi. U — "katalog": qaysi loyihalar borligini aytadi. Bunday fayl solution tsconfig deyiladi.

{
  "files": [],
  "references": [
    { "path": "./tsconfig.app.json" },
    { "path": "./tsconfig.node.json" }
  ]
}

Nega ildizda baribir tsconfig.json kerak? Muharrir (VS Code) va ESLint (projectService) avval aynan shu nomni qidiradi. Ular references orqali har faylning "o'z" tsconfig'ini topadi: src/api.ts uchun — app, vite.config.ts uchun — node.

3.2 tsc -b

Oddiy tsc solution faylni ochadi, files: [] ni ko'radi va... hech narsa qilmaydi. Mashq loyihasida — document xatosi turibdi, lekin:

npx tsc

Jim, chiqish kodi 0. Bu — darsning eng xavfli tuzog'i. references ni faqat build rejimi o'qiydi: tsc -b (--build). Build darsida uni monorepo uchun ko'rgan edingiz. Endi:

npx tsc -b

skriptlar/hisobot.ts(6,1): error TS2584: Cannot find name 'document'. Do you need to change your target library? Try changing the 'lib' compiler option to include 'dom'.

"document nomi topilmadi. lib ga dom qo'shishni xohlaysizmi?" Maslahatga quloq solmang: bu Node kodi, document bu yerda haqiqatan yo'q. To'g'ri tuzatish — qatorni olib tashlash. Teskari tomon ham ishlaydi — src/main.ts ga process.env.NODE_ENV yozdik:

src/main.ts(9,13): error TS2591: Cannot find name 'process'. Do you need to install type definitions for node? Try `npm i --save-dev @types/node` and then add 'node' to the types field in your tsconfig.

"process topilmadi, @types/node o'rnatib, types ga node qo'shing". Yana noto'g'ri maslahat: brauzer kodida process yo'q. Vite'da muhit qiymatlari import.meta.env orqali (Vite III).

Diqqat: Solution tsconfig'li loyihada "tip": "tsc" emas, "tip": "tsc -b". Aks holda npm run tip hech narsani tekshirmay "yashil" bo'ladi.

3.3 composite shartmi?

Build darsida project references uchun "composite": true kerak degan edik. U bir loyiha boshqasidan import qilganda kerak: TypeScript qo'shni loyihaning .d.ts ini o'qiydi. app va node esa bir-biridan import qilmaydi — ular faqat bitta "katalog"da turibdi. Shuning uchun Vite shablonida ham, vazifalar da ham composite yo'q va tsc -b muammosiz ishlaydi.

4. Vazifalar qadami: ikki tsconfig

4.1 tsconfig.app.json

Branch: chore/tsconfig-ajratish. Avvalgi tsconfig.json deyarli o'zgarishsiz tsconfig.app.json ga ko'chadi. Yangi qatorlar — ikkita:

{
  // Brauzer kodi — src/ (16/#42 da tsconfig.json dan ajratildi; Node
  // tomoni — tsconfig.node.json). 15/#45 dan: faqat .ts, allowJs yo'q
  "compilerOptions": {
    "strict": true,
    "noUncheckedIndexedAccess": true,
    "exactOptionalPropertyTypes": true,
    "noImplicitOverride": true,
    "noImplicitReturns": true,
    "noFallthroughCasesInSwitch": true,
    "noUnusedLocals": true,
    "noUnusedParameters": true,
    "erasableSyntaxOnly": true,
    "verbatimModuleSyntax": true,
    "noEmit": true,
    // tsc -b ning holat fayli (tsbuildinfo) — node_modules ichida,
    // git'ga kirmaydi
    "tsBuildInfoFile": "./node_modules/.tmp/tsconfig.app.tsbuildinfo",
    "allowImportingTsExtensions": true,
    "target": "es2024",
    "lib": ["esnext", "dom"],
    "module": "esnext",
    "moduleResolution": "bundler"
  },
  "include": ["src"]
}

(Bayroqlar izohlari Strict bayroqlar darsidagidek — qisqartirdik, faqat yangi qatorning izohi qoldi.) Yangi kalit tsBuildInfoFile — tsc -b o'z hisob-kitobini yozadigan fayl. node_modules/.tmp/ ichida — chunki node_modules allaqachon .gitignore da, repoga tushmaydi. Vite shabloni ham aynan shu yo'lni ishlatadi.

4.2 tsconfig.node.json

{
  // Node'da ishlaydigan kod (16/#42): Vite sozlamasi, plagin va
  // skriptlar. Brauzer kodi — tsconfig.app.json (DOM bor, Node yo'q)
  "compilerOptions": {
    "strict": true,
    "noUnusedLocals": true,
    "noUnusedParameters": true,
    "erasableSyntaxOnly": true,
    "verbatimModuleSyntax": true,
    "noEmit": true,
    // tsc -b ning holat fayli (tsbuildinfo) — node_modules ichida,
    // git'ga kirmaydi
    "tsBuildInfoFile": "./node_modules/.tmp/tsconfig.node.tsbuildinfo",
    // skriptlar/*.js — JSDoc bilan, tsc ularni ham tekshiradi
    "allowJs": true,
    "checkJs": true,
    "target": "es2024",
    // DOM yo'q: document, window bu yerda xato bo'lishi kerak
    "lib": ["es2024"],
    // process, node:fs, import.meta.main... — @types/node
    "types": ["node"],
    "module": "esnext",
    "moduleResolution": "bundler"
  },
  "include": ["vite.config.ts", "skriptlar"]
}

types: ["node"] uchun paket kerak — @types/node. Node 24 qatoriga mos versiya:

npm i -D @types/node@24.19.1

TypeScript 6 va 7 da types sukut bo'yicha bo'sh, shuning uchun "node" ni aniq yozamiz. allowJs + checkJs — .js fayllarni JSDoc izohlari bo'yicha tekshirish.

package.json da: "tip": "tsc -b", "build": "tsc -b && vite build".

4.3 Birinchi tsc -b: 26 ta xato

npx tsc -b

Chiqish uzun, boshi:

skriptlar/ikonlar.js(11,16): error TS7006: Parameter 'tur' implicitly has an 'any' type.
skriptlar/ikonlar.js(11,21): error TS7006: Parameter 'malumot' implicitly has an 'any' type.
skriptlar/ikonlar.js(23,25): error TS7006: Parameter 'olcham' implicitly has an 'any' type.
skriptlar/ikonlar.js(23,33): error TS7006: Parameter 'piksel' implicitly has an 'any' type.
skriptlar/ikonlar.js(44,21): error TS7006: Parameter 'px' implicitly has an 'any' type.
…

Jami 26 ta. Ularni fayl va kod bo'yicha sanadik:

Hammasi Node tomonida — src/ toza. Bu kod 13-qismdan beri ishlab turibdi, lekin uni hech kim tekshirmagan edi. Ko'pchiligi — turi yozilmagan parametrlar (strict dagi noImplicitAny). Ikkitasi esa qiziqroq.

4.4 Ikki qiziq xato

qobiq.js:

skriptlar/qobiq.js(59,25): error TS2339: Property 'replaceAll' does not exist on type 'string | NonSharedBuffer'.

"string | NonSharedBuffer turida replaceAll yo'q". readdirSync(papka, { recursive: true }) — @types/node ga ko'ra natija satr yoki Buffer (baytlar) bo'lishi mumkin. Biz satr deb o'ylaganmiz — amalda shunday ham. Tuzatish — kodlashni aniq aytish: { recursive: true, encoding: "utf8" }. Endi TypeScript natija faqat satr ekanini biladi.

vite.config.ts — eng uzun xabar. Uning oxiri:

            The types of 'server.proxy' are incompatible between these types.
              Type '{ "/api": { target: string; changeOrigin: true; }; } | { "/api"?: undefined; }' is not assignable to type 'Record<string, string | ProxyOptions> | undefined'.
                Type '{ "/api"?: undefined; }' is not assignable to type 'Record<string, string | ProxyOptions>'.
                  Property '"/api"' is incompatible with index signature.

Uzun xabarni TS xato xabarlarini o'qish darsidagidek pastdan o'qiymiz: server.proxy ga {} (bo'sh obyekt) berilganda TypeScript uni { "/api"?: undefined } deb tushundi va bu Record<string, …> ga mos emas. Dev proxy qadamidagi kod: API_PROXY bo'lmasa — {}. Tuzatish: {} o'rniga undefined — "proxy yo'q".

4.5 JSDoc bilan tuzatish

ikonlar.js .js bo'lib qoladi — turlarni JSDoc izohlariga yozamiz. Birinchi xato (tur, malumot):

/**
 * PNG: imzo + IHDR (o'lcham) + IDAT (siqilgan piksellar) + IEND
 * @param {string} tur
 * @param {Buffer} malumot
 */
function bolak(tur, malumot) {

O'q funksiyalarda — parametr oldida:

const qoplam = (/** @type {number} */ masofa) =>
  Math.max(0, Math.min(1, 0.5 - masofa));

Takrorlanadigan turlar — @typedef bilan bir marta:

/** @typedef {[number, number]} Nuqta */
/** @typedef {(x: number, y: number) => number[]} Piksel RGBA, 0–255 */

Xulq o'zgarmaganini isbotlash: npm run ikonlar 4 ta PNG yasaydi — ular eskilari bilan bayt-bayt bir xil. Build hash'lari ham o'zgarmadi (index-C4s8yKGl.js), npm test — 146/146.

npx tsc -b

Jim, chiqish kodi 0. Commit: chore: tsconfig app/node ga ajratildi, tsc -b; skriptlar JSDoc bilan.

Tekshirib ko'ring: Nega ikonlar.js ni .ts ga o'girmadik, JSDoc yozdik?

4.6 tsc -b va .tsbuildinfo: tezlashtirdimi?

tsc -b ni ketma-ket ikki marta ishga tushirdik: 3.3 s va 3.4 s. Ikkinchisi tezlashmadi. Sababini --verbose aytadi:

npx tsc -b --verbose

08:14:26 PM - Project 'tsconfig.app.json' is out of date because output file 'src/api.js' does not exist
08:14:26 PM - Project 'tsconfig.node.json' is out of date because output file 'vite.config.js' does not exist

"Loyiha eskirgan, chunki src/api.js chiqish fayli yo'q". noEmit da chiqish fayli hech qachon bo'lmaydi — TypeScript 7.0.2 tsc -b har safar ikkala loyihani qayta tekshiradi. .tsbuildinfo fayllari yoziladi, lekin bu rejimda vaqt tejalmaydi. Vaqt va soat sizda boshqacha. Muhimi — tekshiruv to'liq.

5. React shablonidagi tsconfig (o'qish)

17-qismda React loyihasini create-vite bilan yaratamiz. Uning tsconfig.app.json i (create-vite 9.2.1):

{
  "compilerOptions": {
    "tsBuildInfoFile": "./node_modules/.tmp/tsconfig.app.tsbuildinfo",
    "target": "es2023",
    "lib": ["ES2023", "DOM"],
    "module": "esnext",
    "types": ["vite/client"],
    "allowArbitraryExtensions": true,
    "skipLibCheck": true,

    /* Bundler mode */
    "moduleResolution": "bundler",
    "allowImportingTsExtensions": true,
    "verbatimModuleSyntax": true,
    "moduleDetection": "force",
    "noEmit": true,
    "jsx": "react-jsx",

    /* Linting */
    "noUnusedLocals": true,
    "noUnusedParameters": true,
    "erasableSyntaxOnly": true,
    "noFallthroughCasesInSwitch": true
  },
  "include": ["src"]
}

Tuzilma — aynan bizniki: tsconfig.json (solution), app va node. Tanish bo'lmagan kalitlar:

skipLibCheck haqida: u kutubxonalarning ichki .d.ts xatolarini yashiradi, sizning kodingizdagini emas. Katta loyihada vaqtni sezilarli tejaydi. vazifalar da u yoqilmagan — kutubxona turlari ham tekshiriladi. strict bu shablonda yo'q — TypeScript 6 dan beri u sukut bo'yicha yoqiq (tsconfig chuqur).

Ikki kutilmagan narsa. Shablon "typescript": "~6.0.2" o'rnatadi — TypeScript 7 emas. Vite jamoasi hali 6 da. Next.js shablonida (create-next-app 16.4.0) esa "typescript": "^5", isolatedModules: true va bitta tsconfig.json (ikki muhit ajratilmagan). Next o'zi Node va brauzer kodini boshqa mexanizm bilan ajratadi — 23-qismda.

isolatedModules — "har faylni alohida o'girsa bo'ladigan kod yoz" talabi. Vite, esbuild va SWC fayllarni bittalab o'giradi va qo'shni faylga qaramaydi. vazifalar da verbatimModuleSyntax bor va u xuddi shu xatolarni beradi. Sinadik: turni export type siz qayta eksport qilsak, ikkala bayroq ham TS1205 beradi (Re-exporting a type when 'verbatimModuleSyntax' is enabled requires using 'export type'). Shuning uchun isolatedModules alohida yozilmagan.

Tekshirib ko'ring: React shablonining tsconfig.node.json ida "include": ["vite.config.ts"] bor. Siz scripts/seed.ts (Node skripti) qo'shdingiz. U qaysi tsconfig bilan tekshiriladi?

6. Ko'p uchraydigan xatolar

Yana biri: xato xabaridagi "Try changing the 'lib'…" va "Try npm i --save-dev @types/node" maslahatlari bir loyiha (bitta muhit) uchun yozilgan. Ikki muhitli loyihada ularni ko'r-ko'rona bajarish ajratishning butun ma'nosini yo'qotadi.

7. Mashqlar

1-mashq (oson): qaysi tsconfig?

vazifalar da har fayl qaysi tsconfig bilan tekshiriladi?

• src/render.ts —
• vite.config.ts —
• skriptlar/qobiq.js —
• tekshiruv/api.test.js —

2-mashq (o'rta): ajrating

kurs/mashqlar/16/42-tsconfig-ajratish/: npm init -y, npm pkg set type=module, npm i -D -E typescript@7.0.2 @types/node@24.19.1. «Bitta tsconfig nimani yashiradi» bo'limidagi skriptlar/hisobot.ts va bitta tsconfig.json. src/main.ts:

// Brauzer: «Bahor» menyusini sahifaga chiqaradi
const prices = { osh: 35000, manti: 30000 };
const list = document.querySelector("#menyu");
for (const [name, price] of Object.entries(prices)) {
  const item = document.createElement("li");
  item.textContent = `${name}: ${price} so'm`;
  list?.append(item);
}

1. npx tsc — natija?
2. Uch faylga ajrating: solution, tsconfig.app.json (src, DOM, types: []), tsconfig.node.json (skriptlar, types: ["node"], lib da DOM yo'q).
3. npx tsc -b va npx tsc — natijalar farqi?
4. Xatoni tuzating.

{
  // Brauzer kodi: DOM bor, Node yo'q
  "compilerOptions": {
    "strict": true,
    "noEmit": true,
    "target": "es2024",
    "lib": ["es2024", "dom"],
    "types": [],
    "module": "esnext",
    "moduleResolution": "bundler",
    "tsBuildInfoFile": "./node_modules/.tmp/app.tsbuildinfo"
  },
  "include": ["src"]
}

{
  // Node kodi: process, node:fs bor, DOM yo'q
  "compilerOptions": {
    "strict": true,
    "noEmit": true,
    "target": "es2024",
    "lib": ["es2024"],
    "types": ["node"],
    "module": "nodenext",
    "tsBuildInfoFile": "./node_modules/.tmp/node.tsbuildinfo"
  },
  "include": ["skriptlar"]
}

3-mashq (o'rta): teskari tekshiruv

2-mashq loyihasida src/main.ts oxiriga console.log(process.env.NODE_ENV); yozing. tsc -b nima deydi? Xabardagi maslahat to'g'rimi?

src/main.ts(9,13): error TS2591: Cannot find name 'process'. Do you need to install type definitions for node? Try `npm i --save-dev @types/node` and then add 'node' to the types field in your tsconfig.

4-mashq (qiyin): Vazifalar qadami

kurs/vazifalar da «Vazifalar qadami» ni bajaring: @types/node@24.19.1, uch tsconfig, tip va build skriptlari. Birinchi npx tsc -b dan keyin xatolarni fayl va kod bo'yicha sanang — 26 ta chiqdimi? Keyin bittadan tuzating: ikonlar.js — JSDoc, qobiq.js — encoding: "utf8" va parametr turi, vite.config.ts — undefined. Oxirida npm run ikonlar va git status — PNG'lar o'zgardimi?

Yordam: sanash uchun npx tsc -b | grep -c "error TS" (grep -c — mos qatorlarni sanaydi).

8. Real ishda

• Har Vite shablonida (React, Vue, Svelte) uchta tsconfig bor. Birinchi marta ochganda chalg'itadi — endi siz har birining vazifasini bilasiz.
• "tsc o'tdi, lekin build yiqildi" yoki aksi — ko'pincha fayl hech qaysi tsconfig'ga tushmaganidan. Birinchi qadam: include larni tekshirish.
• Monorepo larda references yana chuqurroq ishlatiladi: packages/ui, apps/web — har biri o'z tsconfig'i bilan, composite bilan (23-qismdan keyin).
• Intervyu: "Nega Vite'da ikki tsconfig?", "tsc va tsc -b farqi?", "skipLibCheck nima va xavfimi?".

Xulosa

• lib va types butun tsconfig uchun: bitta tsconfig — bitta muhit. Brauzer (src/) va Node (vite.config.ts, skriptlar) — ikki tsconfig.
• tsconfig.json — solution: files: [] + references; o'zi hech narsani tekshirmaydi.
• tsc -b references'ni o'qiydi; oddiy tsc solution faylda jim "yashil" — eng xavfli tuzoq.
• vazifalar: birinchi tsc -b — 26 ta xato, hammasi Node kodida; JSDoc, encoding: "utf8" va undefined bilan tuzatildi, xulq bayt-bayt bir xil.
• React shablonida: jsx: "react-jsx", types: ["vite/client"], skipLibCheck, moduleDetection: "force" — 17-qismda.

Keyingi dars: Path alias: @/ importlarni sozlash — "../../../lib/x" o'rniga @/lib/x: tsconfig paths va Vite resolve.alias; nega vazifalar da alias yo'q va Node testlari unga qanday qaraydi.

Manbalar

• TypeScript: Project References, TSConfig Reference (types, lib, skipLibCheck, isolatedModules, moduleDetection)
• Vite: Features — TypeScript, create-vite shabloni template-react-ts (9.2.1)
• Node: @types/node