مدیریت فایل tsconfig.json: بهینه‌سازی و سفارشی‌سازی کامپایلر تایپ اسکریپت

در دنیای توسعه نرم‌افزار مدرن، تایپ‌اسکریپت (TypeScript) به سرعت به یکی از پرکاربردترین زبان‌های برنامه‌نویسی تبدیل شده است. این زبان که یک ابرمجموعه از جاوااسکریپت است، با افزودن قابلیت‌های تایپ استاتیک، به توسعه‌دهندگان امکان می‌دهد تا کدهای قوی‌تر، قابل نگهداری‌تر و مقیاس‌پذیرتری بنویسند. اما قلب تپنده هر پروژه تایپ‌اسکریپتی، فایل tsconfig.json است. این فایل، تنظیمات و پیکربندی‌های لازم را برای کامپایلر تایپ‌اسکریپت (tsc) فراهم می‌کند و نحوه تبدیل کد تایپ‌اسکریپت (.ts) به جاوااسکریپت (.js) را کنترل می‌کند.

مدیریت کارآمد tsconfig.json فقط به معنای فعال یا غیرفعال کردن چند گزینه نیست؛ بلکه یک هنر است که می‌تواند به طور چشمگیری بر عملکرد، کیفیت و بهره‌وری پروژه شما تأثیر بگذارد. پیکربندی صحیح این فایل می‌تواند سرعت کامپایل را افزایش دهد، باگ‌های احتمالی را در زمان توسعه شناسایی کند، به یکپارچگی کد کمک کند و حتی تعامل پروژه شما را با ابزارهای دیگر در اکوسیستم جاوااسکریپت بهبود بخشد. از طرف دیگر، یک پیکربندی نادرست می‌تواند منجر به زمان کامپایل طولانی، خطاهای عجیب و غریب و تجربه‌ای ناخوشایند برای توسعه‌دهندگان شود.

هدف از این مقاله، ورود به عمق فایل tsconfig.json است. ما به بررسی جامع گزینه‌های مختلف، کاربردهای آن‌ها، و نحوه بهینه‌سازی پیکربندی برای سناریوهای مختلف پروژه خواهیم پرداخت. از تنظیمات پایه گرفته تا سناریوهای پیشرفته مانند مونوریپوها و ادغام با ابزارهای دیگر، ما مسیر را برای تبدیل شما به یک متخصص در مدیریت tsconfig.json روشن خواهیم کرد. با درک دقیق این فایل، شما قادر خواهید بود پروژه‌های تایپ‌اسکریپت خود را به سطحی جدید از کارایی، پایداری و نگهداری‌پذیری برسانید.

آماده‌اید تا کنترل کامپایلر تایپ‌اسکریپت را به دست بگیرید و آن را مطابق با نیازهای دقیق پروژه خود سفارشی‌سازی کنید؟ بیایید شروع کنیم.

پایه و اساس tsconfig.json: درک ساختار و گزینه‌های کلیدی

هر سفر موفقی با درک اصول آغاز می‌شود. فایل tsconfig.json نیز از این قاعده مستثنی نیست. درک ساختار اصلی و گزینه‌های بنیادین آن، اولین قدم برای تسلط بر پیکربندی کامپایلر تایپ‌اسکریپت است. این فایل معمولاً در ریشه پروژه تایپ‌اسکریپت شما قرار می‌گیرد و به کامپایلر می‌گوید که چه فایل‌هایی را شامل شود، چه فایل‌هایی را نادیده بگیرد و چگونه کد را کامپایل کند.

ساختار اصلی tsconfig.json

یک فایل tsconfig.json پایه از چند بخش اصلی تشکیل شده است:

• compilerOptions: مهم‌ترین بخش که شامل تمام تنظیمات کامپایلر است. این بخش تعیین می‌کند که چگونه کد تایپ‌اسکریپت شما به جاوااسکریپت تبدیل شود.
• include: آرایه‌ای از الگوهای مسیر (Glob patterns) که مشخص می‌کند کدام فایل‌ها و پوشه‌ها باید توسط کامپایلر پردازش شوند.
• exclude: آرایه‌ای از الگوهای مسیر که مشخص می‌کند کدام فایل‌ها و پوشه‌ها باید توسط کامپایلر نادیده گرفته شوند، حتی اگر در include مشخص شده باشند. این برای حذف پوشه‌هایی مانند node_modules یا dist ضروری است.
• files: آرایه‌ای از مسیرهای نسبی یا مطلق به فایل‌های خاصی که باید کامپایل شوند. این گزینه کمتر از include و exclude استفاده می‌شود و معمولاً برای پروژه‌های کوچک با تعداد محدود فایل کاربرد دارد.

یک مثال پایه از tsconfig.json می‌تواند به شکل زیر باشد:

{
  "compilerOptions": {
    "target": "es2020",
    "module": "commonjs",
    "outDir": "./dist",
    "rootDir": "./src",
    "strict": true,
    "esModuleInterop": true
  },
  "include": [
    "src/**/*.ts"
  ],
  "exclude": [
    "node_modules",
    "**/*.spec.ts"
  ]
}

گزینه‌های کلیدی در compilerOptions

بخش compilerOptions شامل صدها گزینه است که هر کدام جنبه‌ای از فرایند کامپایل را کنترل می‌کنند. در اینجا به برخی از حیاتی‌ترین و پرکاربردترین آن‌ها می‌پردازیم:

target: نسخه استاندارد ECMAScript هدف

این گزینه مشخص می‌کند که کد جاوااسکریپت خروجی باید برای کدام نسخه از ECMAScript (ES) تولید شود. انتخاب صحیح target بسیار مهم است زیرا بر سازگاری کد شما با محیط‌های مختلف (مرورگرها، Node.js نسخه‌های قدیمی‌تر) تأثیر می‌گذارد. تایپ‌اسکریپت به طور خودکار قابلیت‌های جدیدتر ES را (مانند async/await، for-of) به نسخه‌های قدیمی‌تر تبدیل (downlevel) می‌کند تا اطمینان حاصل شود که کد شما در محیط‌های هدف قابل اجرا است.

• مقادیر رایج: "es3"، "es5"، "es2015" (ES6), "es2016"، "es2017"، "es2018"، "es2019"، "es2020"، "esnext".
• توصیه: معمولاً "es2017" یا بالاتر برای Node.js و مرورگرهای مدرن مناسب است. برای مرورگرهای قدیمی‌تر یا محیط‌های محدودتر، ممکن است نیاز به "es5" داشته باشید. استفاده از "esnext" به معنای استفاده از جدیدترین ویژگی‌های استاندارد است که کامپایلر پشتیبانی می‌کند.

"target": "es2020" // کد خروجی با ویژگی‌های ES2020

module: سیستم ماژول هدف

این گزینه مشخص می‌کند که کد جاوااسکریپت خروجی از کدام سیستم ماژول استفاده کند. سیستم‌های ماژول نحوه سازماندهی، وارد کردن (import) و صادر کردن (export) کد را کنترل می‌کنند و برای ساخت برنامه‌های بزرگ و ماژولار حیاتی هستند.

• مقادیر رایج: "commonjs" (برای Node.js), "esnext" (ES Modules برای مرورگرها و Node.js مدرن), "amd"، "umd"، "system".
• توصیه: برای Node.js، "commonjs" یک انتخاب استاندارد است. برای پروژه‌های فرانت‌اند که از باندلرهایی مانند Webpack یا Rollup استفاده می‌کنند، "esnext" یا "es2015" معمولاً بهترین گزینه است، زیرا باندلرها به خوبی با ES Modules کار می‌کنند.

"module": "commonjs" // استفاده از CommonJS برای ماژول‌ها

outDir و rootDir: سازماندهی ساختار پروژه

• outDir: مسیر پوشه‌ای که فایل‌های جاوااسکریپت کامپایل شده در آن قرار می‌گیرند. این گزینه به حفظ تمیزی پروژه و جداسازی کدهای منبع از کدهای خروجی کمک می‌کند.
• rootDir: مسیر ریشه فایل‌های منبع تایپ‌اسکریپت. کامپایلر از این مسیر برای بازسازی ساختار پوشه‌ای مشابه در outDir استفاده می‌کند. اگر rootDir مشخص نشود، تایپ‌اسکریپت به طور پیش‌فرض مشترک‌ترین مسیر ریشه بین همه فایل‌های ورودی را در نظر می‌گیرد.

"outDir": "./dist",
"rootDir": "./src" // فایل‌های src/**/*.ts به dist/**/*.js کامپایل می‌شوند

strict: فعال‌سازی تمام بررسی‌های سخت‌گیرانه نوع

این گزینه یک پرچم ترکیبی است که فعال کردن آن معادل فعال کردن مجموعه‌ای از گزینه‌های بررسی نوع سخت‌گیرانه دیگر است. strict: true به شدت توصیه می‌شود زیرا به شناسایی خطاهای احتمالی در زمان توسعه کمک می‌کند و به طور قابل توجهی کیفیت و پایداری کد را افزایش می‌دهد. اگرچه ممکن است در ابتدا منجر به خطاهای بیشتری شود، اما در بلندمدت از شما در برابر باگ‌های پنهان محافظت می‌کند.

• گزینه‌هایی که با strict: true فعال می‌شوند: noImplicitAny، strictNullChecks، strictFunctionTypes، strictPropertyInitialization، noImplicitThis، alwaysStrict. ما در بخش‌های بعدی به تفصیل به این گزینه‌ها خواهیم پرداخت.

"strict": true // فعال‌سازی تمام بررسی‌های نوع سخت‌گیرانه

lib: کتابخانه‌های تعریف نوع پیش‌فرض

این گزینه مشخص می‌کند که کدام کتابخانه‌های تعریف نوع (type declaration files) باید در محیط کامپایل موجود باشند. تایپ‌اسکریپت به طور پیش‌فرض مجموعه‌ای از تعریف‌ها را بر اساس target و module شما شامل می‌شود (مثلاً "dom" برای مرورگرها و "es2017"). با این حال، شما می‌توانید این مجموعه را سفارشی کنید.

• مثال: اگر در حال توسعه برای مرورگر هستید و نیاز به دسترسی به APIهای DOM دارید، باید "dom" را شامل کنید. اگر از ویژگی‌های جدیدتر جاوااسکریپت مانند Promise یا Map استفاده می‌کنید، باید نسخه‌های مربوطه ES را شامل کنید (مثلاً "es2015" یا "es2017").

"lib": ["es2020", "dom"] // شامل تعریف‌های ES2020 و DOM

esModuleInterop: قابلیت همکاری با ماژول‌های ES

این گزینه نحوه برخورد کامپایلر تایپ‌اسکریپت با وارد کردن ماژول‌های CommonJS/AMD/UMD را در یک ماژول ES (ES Module) تغییر می‌دهد. هنگامی که esModuleInterop روی true تنظیم شود، تایپ‌اسکریپت به طور خودکار کدهای کمکی را تزریق می‌کند تا وارد کردن پیش‌فرض (default imports) از ماژول‌های CommonJS مانند وارد کردن ماژول‌های ES رفتار کند. این به رفع تفاوت‌های رایج بین سیستم‌های ماژول و آسان‌تر کردن انتقال کد بین آن‌ها کمک می‌کند.

"esModuleInterop": true // بهبود قابلیت همکاری بین ماژول‌های ES و CommonJS

با تسلط بر این گزینه‌های پایه، شما گامی مهم در جهت پیکربندی موثر پروژه تایپ‌اسکریپت خود برداشته‌اید. در بخش‌های بعدی، به سراغ بهینه‌سازی عملکرد و سناریوهای پیشرفته‌تر خواهیم رفت.

بهینه‌سازی عملکرد کامپایلر: سرعت و کارایی در tsconfig.json

زمان کامپایل، به ویژه در پروژه‌های بزرگ، می‌تواند به یک گلوگاه جدی تبدیل شود و بهره‌وری توسعه‌دهنده را کاهش دهد. خوشبختانه، tsconfig.json گزینه‌های متعددی را برای بهینه‌سازی سرعت و کارایی فرایند کامپایل فراهم می‌کند. با استفاده هوشمندانه از این گزینه‌ها، می‌توانید زمان انتظار را به حداقل برسانید و یک چرخه بازخورد سریع‌تر داشته باشید.

incremental: کامپایل افزایشی

یکی از قدرتمندترین ویژگی‌ها برای تسریع کامپایل در تایپ‌اسکریپت، قابلیت کامپایل افزایشی است. هنگامی که incremental روی true تنظیم شود، کامپایلر یک فایل وضعیت (معمولاً .tsbuildinfo) را در کنار فایل‌های خروجی شما (مثلاً در outDir) تولید می‌کند. در کامپایل‌های بعدی، تایپ‌اسکریپت از این فایل وضعیت برای تشخیص اینکه کدام فایل‌ها تغییر کرده‌اند و فقط آن فایل‌ها و وابستگی‌هایشان را کامپایل مجدد می‌کند، استفاده می‌کند.

• مزایا: کاهش چشمگیر زمان کامپایل در دفعات بعدی، به خصوص در پروژه‌های بزرگ.
• معایب: ایجاد فایل .tsbuildinfo که باید در سیستم کنترل نسخه (مثل Git) نادیده گرفته شود.

"incremental": true,
"tsBuildInfoFile": "./.tsbuildinfo" // اختیاری: مسیر فایل وضعیت

watch: حالت نظارت (Watch Mode)

گرچه watch یک گزینه در tsconfig.json نیست (بلکه یک پرچم برای دستور tsc است: tsc --watch)، اما ارتباط نزدیکی با بهینه‌سازی عملکرد توسعه دارد. زمانی که در حالت نظارت اجرا می‌شود، کامپایلر تایپ‌اسکریپت پس از اولین کامپایل کامل، در پس‌زمینه فعال می‌ماند و تغییرات فایل‌ها را رصد می‌کند. با هر بار ذخیره یک فایل، کامپایلر به صورت افزایشی (با بهره‌گیری از همان مکانیزم incremental) فقط فایل‌های تغییر یافته را مجدداً کامپایل می‌کند.

• مزایا: بازخورد فوری در حین توسعه، بدون نیاز به اجرای مجدد دستور کامپایل.
• نحوه استفاده: tsc --watch در ترمینال.

کنترل خروجی کامپایلر

declaration و declarationMap: تولید فایل‌های تعریف نوع

• declaration: اگر true باشد، کامپایلر فایل‌های تعریف نوع (.d.ts) را در کنار فایل‌های جاوااسکریپت تولید می‌کند. این فایل‌ها برای پروژه‌هایی که به عنوان کتابخانه منتشر می‌شوند یا در پروژه‌های دیگر تایپ‌اسکریپت مورد استفاده قرار می‌گیرند، حیاتی هستند تا مصرف‌کنندگان بتوانند از قابلیت‌های تایپ بهره‌مند شوند.
• declarationMap: اگر true باشد، یک فایل map برای فایل‌های .d.ts تولید می‌کند که امکان ناوبری (go-to-definition) در محیط‌های توسعه (IDE) را بهبود می‌بخشد.

"declaration": true,
"declarationMap": true,
"outDir": "./dist" // فایل‌های .d.ts در کنار .js در dist قرار می‌گیرند

sourceMap: تولید Source Map

اگر true باشد، کامپایلر فایل‌های source map (.map) را در کنار فایل‌های جاوااسکریپت تولید می‌کند. Source mapها امکان اشکال‌زدایی کد کامپایل شده جاوااسکریپت را در مرورگر یا محیط Node.js فراهم می‌کنند، در حالی که اشاره‌گرها به کد اصلی تایپ‌اسکریپت شما باز می‌گردند. این برای اشکال‌زدایی بسیار مهم است.

"sourceMap": true

removeComments: حذف کامنت‌ها

اگر true باشد، تمام کامنت‌ها از کد جاوااسکریپت خروجی حذف می‌شوند. این می‌تواند حجم فایل‌های خروجی را کمی کاهش دهد، اما معمولاً تأثیر کمی بر عملکرد کلی دارد.

"removeComments": true

noEmit: فقط بررسی نوع، بدون تولید خروجی

اگر true باشد، کامپایلر فقط عملیات بررسی نوع را انجام می‌دهد و هیچ فایل جاوااسکریپتی تولید نمی‌کند. این گزینه برای سناریوهایی مفید است که شما از یک باندلر مانند Webpack یا Babel برای ترانسپایل نهایی کد استفاده می‌کنید و فقط به قابلیت‌های بررسی نوع تایپ‌اسکریپت نیاز دارید.

"noEmit": true

گزینه‌های بهبود دهنده عملکرد کامپایل

skipLibCheck: نادیده گرفتن بررسی نوع فایل‌های کتابخانه‌ای

اگر true باشد، کامپایلر از بررسی نوع تمام فایل‌های .d.ts (فایل‌های تعریف نوع) که بخشی از node_modules هستند، صرف‌نظر می‌کند. این می‌تواند زمان کامپایل را به طور قابل توجهی کاهش دهد، به خصوص در پروژه‌های بزرگ با تعداد زیادی وابستگی. این گزینه به طور کلی امن است زیرا فرض می‌شود که کتابخانه‌های شخص ثالث از قبل به درستی تایپ شده‌اند.

"skipLibCheck": true

forceConsistentCasingInFileNames: اجبار به سازگاری در نام‌گذاری فایل‌ها

این گزینه در واقع بیشتر یک بررسی برای جلوگیری از مشکلات احتمالی در سیستم‌های فایل حساس به حروف بزرگ و کوچک (مانند لینوکس و macOS) است. اگر true باشد، کامپایلر اطمینان حاصل می‌کند که تمام ارجاعات به فایل‌ها از نام‌گذاری یکسانی (از نظر حروف بزرگ و کوچک) استفاده می‌کنند. اگر این گزینه فعال نباشد و نام‌گذاری ناسازگار باشد، ممکن است پروژه در یک سیستم فایل کار کند اما در دیگری دچار مشکل شود. فعال کردن آن به طور پیش‌فرض توصیه می‌شود.

"forceConsistentCasingInFileNames": true

مدیریت ماژول‌ها و حل مسیرها (Module Resolution)

نحوه حل ماژول‌ها توسط کامپایلر می‌تواند بر زمان کامپایل و حتی صحت برنامه شما تأثیر بگذارد.

moduleResolution: استراتژی حل ماژول

این گزینه نحوه پیدا کردن ماژول‌ها توسط کامپایلر را تعیین می‌کند.

• "node": رایج‌ترین استراتژی که شبیه به نحوه عمل Node.js برای پیدا کردن ماژول‌ها است (پوشه node_modules را جستجو می‌کند).
• "classic": استراتژی قدیمی‌تر و ساده‌تر.
• توصیه: معمولاً "node" بهترین انتخاب است، مگر اینکه دلیل خاصی برای استفاده از "classic" داشته باشید.

"moduleResolution": "node"

baseUrl و paths: ایجاد نام‌های مستعار برای مسیرها

این دو گزینه در کنار هم به شما امکان می‌دهند تا نام‌های مستعار (aliases) برای مسیرهای طولانی یا پیچیده در پروژه خود ایجاد کنید. این کار هم خوانایی کد را بهبود می‌بخشد و هم می‌تواند به کامپایلر کمک کند تا ماژول‌ها را سریع‌تر پیدا کند (به جای جستجوی نسبی در چندین سطح پوشه).

• baseUrl: مسیری را مشخص می‌کند که تمام مسیرهای ماژول غیر نسبی (non-relative) از آن شروع می‌شوند.
• paths: یک نگاشت (mapping) بین الگوهای ماژول و آرایه‌ای از مسیرهای جایگزین را تعریف می‌کند.

{
  "compilerOptions": {
    "baseUrl": "./src", // تمام importهای غیر نسبی از src شروع می‌شوند
    "paths": {
      "@components/*": ["./components/*"], // @components/Button به src/components/Button نگاشت می‌شود
      "@utils/*": ["./utils/*"]
    }
  }
}

با استفاده از baseUrl و paths، به جای import { Button } from '../../components/Button'; می‌توانید بنویسید: import { Button } from '@components/Button';. این نه تنها کد را تمیزتر می‌کند، بلکه در پروژه‌های بزرگ می‌تواند به حل ماژول سریع‌تر کمک کند.

استفاده موثر از exclude

بخش exclude به کامپایلر می‌گوید که کدام فایل‌ها را کاملاً نادیده بگیرد. استفاده صحیح از این گزینه برای عملکرد بسیار مهم است:

• همیشه "node_modules" را در exclude قرار دهید.
• پوشه‌هایی که شامل کدهای کامپایل شده یا خروجی هستند (مانند "dist" یا "build") را exclude کنید.
• فایل‌های تستی ("**/*.spec.ts" یا "**/*.test.ts") را در صورتی که نمی‌خواهید بخشی از کامپایل تولیدی باشند، exclude کنید. اگرچه برای بررسی نوع در زمان توسعه مهم هستند، اما شاید برای کامپایل نهایی لازم نباشند و می‌توانند زمان کامپایل را افزایش دهند.

{
  "exclude": [
    "node_modules",
    "dist",
    "build",
    "**/*.spec.ts",
    "**/*.test.ts"
  ]
}

با ترکیب این گزینه‌ها، می‌توانید فرایند کامپایل تایپ‌اسکریپت خود را به طور قابل توجهی سریع‌تر و کارآمدتر کنید. این امر به خصوص در چرخه توسعه روزانه و همچنین در محیط‌های CI/CD (Continuous Integration/Continuous Deployment) که زمان کامپایل می‌تواند به طور مستقیم بر زمان استقرار تأثیر بگذارد، بسیار مهم است.

پیکربندی پیشرفته و سناریوهای خاص: tsconfig.json برای پروژه‌های پیچیده

هنگامی که پروژه‌های تایپ‌اسکریپت از یک برنامه کوچک به یک سیستم بزرگ و پیچیده تکامل می‌یابند، نیاز به قابلیت‌های پیکربندی پیشرفته‌تری در tsconfig.json پیدا می‌شود. این بخش به بررسی گزینه‌هایی می‌پردازد که برای مدیریت پروژه‌های در مقیاس بزرگ، مونوریپوها، و ادغام با تکنولوژی‌های خاص مانند دکوراتورها طراحی شده‌اند.

مونوریپوها و Project References: مقیاس‌پذیری با تایپ‌اسکریپت

مونوریپوها (Monorepos) ساختاری هستند که در آن چندین پروژه مستقل (مانند یک کتابخانه UI، یک API بک‌اند و یک برنامه فرانت‌اند) در یک مخزن Git واحد مدیریت می‌شوند. تایپ‌اسکریپت از طریق “Project References” پشتیبانی قوی از مونوریپوها ارائه می‌دهد که به شما امکان می‌دهد پروژه‌های فرعی را به یکدیگر ارجاع دهید.

references: ارجاع به پروژه‌های دیگر

این گزینه یک آرایه از اشیاء است که هر کدام به یک پروژه تایپ‌اسکریپت دیگر در مونوریپو اشاره می‌کنند. وقتی یک پروژه به دیگری ارجاع می‌دهد، کامپایلر تایپ‌اسکریپت می‌تواند به طور هوشمندانه وابستگی‌ها را مدیریت کند، به این معنی که اگر یک پروژه فرعی تغییر کند، فقط پروژه‌های وابسته به آن مجدداً کامپایل می‌شوند. این کار سرعت کامپایل را در مونوریپوها به شدت افزایش می‌دهد.

// tsconfig.json در ریشه monorepo
{
  "files": [],
  "references": [
    { "path": "./packages/core" },
    { "path": "./packages/ui" },
    { "path": "./apps/web" }
  ]
}

// packages/core/tsconfig.json
{
  "compilerOptions": {
    "composite": true, // برای استفاده با references الزامی است
    "outDir": "../../dist/core"
    // ... سایر گزینه‌ها
  }
}

// apps/web/tsconfig.json
{
  "compilerOptions": {
    "composite": true, // برای استفاده با references الزامی است
    "outDir": "../../dist/web"
    // ... سایر گزینه‌ها
  },
  "references": [
    { "path": "../../packages/core" }, // وب به core وابسته است
    { "path": "../../packages/ui" }   // وب به ui وابسته است
  ]
}

composite: فعال‌سازی حالت کامپایل ترکیبی

این گزینه باید true باشد در هر tsconfig.json که توسط یک پروژه دیگر ارجاع داده می‌شود. composite: true به کامپایلر اطلاع می‌دهد که این پروژه بخشی از یک ساختار پروژه‌های ترکیبی است و باید فایل‌های .tsbuildinfo و .d.ts را تولید کند تا پروژه‌های دیگر بتوانند به درستی به آن وابسته شوند.

"composite": true // الزامی برای پروژه مرجع

Extending Configurations: ارث‌بری تنظیمات

گزینه extends به شما امکان می‌دهد تا یک فایل tsconfig.json دیگر را به عنوان پایه برای پیکربندی فعلی خود استفاده کنید. این برای موارد زیر بسیار مفید است:

• پیکربندی‌های مشترک: تعریف یک tsconfig.json پایه در ریشه مونوریپو یا برای تمام پروژه‌های مشابه.
• قابلیت نگهداری: جلوگیری از تکرار تنظیمات در فایل‌های مختلف.
• پیکربندی‌های تخصصی: ایجاد یک پیکربندی پایه و سپس ایجاد نسخه‌های خاص برای محیط‌های مختلف (مثلاً توسعه، تولید، تست).

// tsconfig.base.json
{
  "compilerOptions": {
    "target": "es2020",
    "module": "esnext",
    "strict": true,
    "esModuleInterop": true
    // ...
  }
}

// tsconfig.json در یک پروژه فرعی
{
  "extends": "../../tsconfig.base.json", // ارث‌بری از پیکربندی پایه
  "compilerOptions": {
    "outDir": "./dist",
    "rootDir": "./src"
    // ... گزینه‌های خاص این پروژه که overrides می‌شوند یا اضافه می‌شوند
  },
  "include": [
    "src"
  ]
}

زمانی که از extends استفاده می‌کنید، تنظیمات در فایل گسترش یافته (فایل فعلی) بر تنظیمات فایل پایه ارجحیت دارند.

مدیریت تعریف‌های نوع (Type Definitions)

typeRoots و types: کنترل مکان و انتخاب تعریف‌های نوع

تایپ‌اسکریپت به طور خودکار فایل‌های .d.ts را از node_modules/@types پیدا می‌کند. با این حال، گاهی اوقات نیاز به کنترل بیشتری بر این فرایند دارید:

• typeRoots: یک آرایه از مسیرها را مشخص می‌کند که کامپایلر باید برای پیدا کردن پکیج‌های تعریف نوع (با پوشه‌های @types) جستجو کند. اگر این گزینه مشخص شود، فقط مسیرهای ذکر شده جستجو می‌شوند، نه node_modules/@types پیش‌فرض.
• types: یک آرایه از نام‌های پکیج‌های تعریف نوع را مشخص می‌کند که باید شامل شوند. اگر این گزینه مشخص شود، فقط پکیج‌های ذکر شده شامل می‌شوند. این می‌تواند برای محدود کردن تعریف‌های نوعی که در دامنه جهانی قابل دسترسی هستند، مفید باشد و زمان کامپایل را کمی کاهش دهد.

{
  "compilerOptions": {
    "typeRoots": ["./node_modules/@types", "./typings"], // جستجو در node_modules/@types و پوشه typings سفارشی
    "types": ["jest", "node"] // فقط شامل تعریف‌های Jest و Node.js
  }
}

ویژگی‌های خاص زبان

jsx: پشتیبانی از JSX/TSX

این گزینه نحوه کامپایل کد JSX/TSX را مشخص می‌کند.

• مقادیر رایج: "preserve" (JSX را دست‌نخورده نگه می‌دارد، برای استفاده با باندلرها مانند Babel), "react" (JSX را به React.createElement تبدیل می‌کند), "react-jsx" (JSX را به فرمت جدیدتر JSX Transform تبدیل می‌کند).
• توصیه: برای پروژه‌های React، "react-jsx" (از TypeScript 4.1 به بعد) یا "react" (برای نسخه‌های قدیمی‌تر) رایج است. اگر از Babel یا ابزار دیگری برای ترانسپایل JSX استفاده می‌کنید، "preserve" مناسب است.

"jsx": "react-jsx"

experimentalDecorators و emitDecoratorMetadata: پشتیبانی از دکوراتورها

دکوراتورها (Decorators) یک ویژگی پیشنهادی در جاوااسکریپت هستند که امکان افزودن متادیتا یا تغییر رفتار کلاس‌ها، متدها، Propertyها و پارامترها را فراهم می‌کنند. تایپ‌اسکریپت پشتیبانی اولیه از دکوراتورها را ارائه می‌دهد، اما برای فعال‌سازی آن‌ها باید این دو گزینه را فعال کنید:

• experimentalDecorators: برای فعال‌سازی پشتیبانی از سینتکس دکوراتورها.
• emitDecoratorMetadata: برای تولید متادیتا برای دکوراتورها. این متادیتا معمولاً توسط کتابخانه‌هایی مانند InversifyJS (برای Dependency Injection) یا TypeORM (برای ORM) استفاده می‌شود. نیاز به پکیج reflect-metadata دارد.

"experimentalDecorators": true,
"emitDecoratorMetadata": true // نیاز به import "reflect-metadata"

isolatedModules: تضمین سازگاری با ترانسپایلرها

اگر true باشد، هر فایل ماژول در پروژه به صورت مستقل کامپایل می‌شود، بدون اینکه اطلاعاتی در مورد فایل‌های دیگر داشته باشد. این گزینه برای سناریوهایی که از ترانسپایلرهای تک-فایلی مانند Babel یا ts-loader در حالت transpileOnly استفاده می‌کنید، حیاتی است. این گزینه اطمینان می‌دهد که کدی که تایپ‌اسکریپت تولید می‌کند، توسط این ترانسپایلرها به درستی پردازش می‌شود، حتی اگر این ترانسپایلرها قادر به انجام بررسی‌های نوع کامل نباشند (چون فقط یک فایل را در یک زمان می‌بینند). این می‌تواند سرعت ترانسپایل را در باندلرهای وب افزایش دهد، اما ممکن است برخی ویژگی‌های تایپ‌اسکریپت را که به اطلاعات متقابل فایل‌ها نیاز دارند، غیرممکن کند (مانند const enum یا namespace).

"isolatedModules": true

دیگر گزینه‌های پیشرفته

allowJs و checkJs: ادغام جاوااسکریپت

• allowJs: اگر true باشد، کامپایلر به شما اجازه می‌دهد تا فایل‌های .js را در پروژه تایپ‌اسکریپت خود شامل کنید. این برای مهاجرت تدریجی یک پروژه جاوااسکریپت به تایپ‌اسکریپت مفید است.
• checkJs: اگر true باشد و allowJs نیز true باشد، کامپایلر بررسی‌های نوعی را بر روی فایل‌های جاوااسکریپت (با استفاده از JSDoc annotations) اعمال می‌کند. این به شما امکان می‌دهد بدون نیاز به بازنویسی کامل، از مزایای بررسی نوع تایپ‌اسکریپت در کدهای جاوااسکریپت موجود خود بهره‌مند شوید.

"allowJs": true,
"checkJs": true

با درک و کاربرد این گزینه‌های پیشرفته، می‌توانید پروژه تایپ‌اسکریپت خود را برای پیچیده‌ترین سناریوها پیکربندی کنید، خواه یک مونوریپو بزرگ باشد یا یک برنامه که از دکوراتورها یا ادغام قوی با جاوااسکریپت استفاده می‌کند.

مدیریت خطا و کنترل نوع: سخت‌گیری‌های tsconfig.json

یکی از اصلی‌ترین دلایل محبوبیت تایپ‌اسکریپت، توانایی آن در شناسایی خطاهای مربوط به نوع در زمان توسعه، قبل از اجرای کد است. tsconfig.json مجموعه‌ای از گزینه‌ها را برای کنترل میزان سخت‌گیری کامپایلر در بررسی نوع فراهم می‌کند. هر چه این بررسی‌ها سخت‌گیرانه‌تر باشند، احتمال وجود باگ‌های مربوط به نوع در زمان اجرا کمتر می‌شود، اما در عین حال ممکن است نیاز به دقت بیشتری در نوشتن کد و رفع خطاهای بیشتر در زمان کامپایل باشد.

همانطور که قبلاً اشاره شد، گزینه "strict": true پرچم ترکیبی است که تمامی گزینه‌های ذکر شده در این بخش را (به جز noUnusedLocals و noUnusedParameters) فعال می‌کند. توصیه می‌شود همیشه "strict": true را فعال نگه دارید و در صورت نیاز، گزینه‌های خاصی را غیرفعال کنید، نه برعکس. این رویکرد “پذیرش سخت‌گیری به صورت پیش‌فرض” منجر به کدهای با کیفیت‌تر و پایدارتر در بلندمدت می‌شود.

خانواده گزینه‌های Strict

noImplicitAny: جلوگیری از نوع‌دهی ضمنی any

اگر true باشد، تایپ‌اسکریپت برای هر متغیر، پارامتر تابع یا ویژگی که نتواند نوع آن را به طور ضمنی تشخیص دهد و به any اختصاص دهد، خطا صادر می‌کند. استفاده از any می‌تواند قابلیت‌های بررسی نوع تایپ‌اسکریپت را دور بزند و شما را در معرض خطاهای زمان اجرا قرار دهد. فعال‌سازی این گزینه شما را مجبور می‌کند که صراحتاً نوع‌ها را مشخص کنید یا از unknown (که ایمن‌تر است) استفاده کنید.

"noImplicitAny": true

strictNullChecks: بررسی‌های سخت‌گیرانه null و undefined

اگر true باشد، null و undefined به طور پیش‌فرض قابل انتساب به هیچ نوع دیگری به جز any یا خودشان نیستند، مگر اینکه به صراحت با استفاده از Union Type (مانند string | null) مشخص شده باشند. این گزینه یکی از مهم‌ترین بررسی‌ها برای جلوگیری از خطاهای رایج “Cannot read property of undefined” در زمان اجرا است.

"strictNullChecks": true

strictFunctionTypes: بررسی‌های سخت‌گیرانه تر در نوع توابع

اگر true باشد، تایپ‌اسکریپت بررسی می‌کند که پارامترهای توابع در انتساب تابع (function assignment) سازگار باشند. این به جلوگیری از باگ‌های ظریفی کمک می‌کند که در آن توابعی با امضای ناسازگار به یکدیگر اختصاص داده می‌شوند. این گزینه فقط بر پارامترهای توابع اعمال می‌شود، نه بر مقادیر بازگشتی یا Propertyهای تابع.

"strictFunctionTypes": true

strictPropertyInitialization: بررسی مقداردهی اولیه Property کلاس‌ها

اگر true باشد و strictNullChecks نیز true باشد، کامپایلر اطمینان حاصل می‌کند که تمام Propertyهای کلاس که نوع آن‌ها null | undefined نیست، در سازنده (constructor) کلاس یا با یک مقداردهی اولیه به درستی مقداردهی شوند. این از ایجاد Propertyهایی که ممکن است در زمان اجرا undefined باشند، جلوگیری می‌کند.

"strictPropertyInitialization": true

noImplicitThis: جلوگیری از نوع‌دهی ضمنی this

اگر true باشد، تایپ‌اسکریپت برای هر عبارت this که نوع آن به طور ضمنی any تشخیص داده شود، خطا صادر می‌کند. این شما را مجبور می‌کند که صراحتاً نوع this را در توابع و متدها مشخص کنید، که به ویژه در توابع callback یا متدهایی که در خارج از کلاس خود استفاده می‌شوند، مفید است.

"noImplicitThis": true

alwaysStrict: انتشار ‘use strict’ در خروجی جاوااسکریپت

اگر true باشد، کامپایلر "use strict"; را در بالای هر فایل جاوااسکریپت خروجی قرار می‌دهد. این اطمینان حاصل می‌کند که کد شما در “حالت strict” جاوااسکریپت اجرا می‌شود، که برخی از رفتارهای ناخواسته جاوااسکریپت را غیرفعال می‌کند و خطاهای بیشتری را در زمان اجرا به وجود می‌آورد.

"alwaysStrict": true

دیگر گزینه‌های کنترل نوع و خطا

noUnusedLocals: تشخیص متغیرهای محلی استفاده نشده

اگر true باشد، کامپایلر برای هر متغیر محلی (local variable) که اعلام شده اما هرگز استفاده نشده است، یک هشدار صادر می‌کند. این به پاکیزگی کد و حذف کدهای مرده کمک می‌کند.

"noUnusedLocals": true

noUnusedParameters: تشخیص پارامترهای استفاده نشده

اگر true باشد، کامپایلر برای هر پارامتر تابعی که اعلام شده اما هرگز استفاده نشده است، یک هشدار صادر می‌کند. مانند noUnusedLocals، این به پاکیزگی کد و بهبود خوانایی کمک می‌کند. (توجه: برای پارامترهایی که با علامت _ شروع می‌شوند، هشدار نمی‌دهد، این یک convention برای پارامترهای استفاده نشده است).

"noUnusedParameters": true

noFallthroughCasesInSwitch: جلوگیری از “fall-through” در دستورات switch

اگر true باشد، کامپایلر برای هر case در یک دستور switch که به case بعدی “fall-through” می‌کند (یعنی بدون break، return یا throw پایان می‌یابد)، یک خطا صادر می‌کند. این به جلوگیری از باگ‌های رایج ناشی از فراموشی break در دستورات switch کمک می‌کند.

"noFallthroughCasesInSwitch": true

noImplicitReturns: اطمینان از بازگشت مقادیر در تمام مسیرها

اگر true باشد، کامپایلر برای هر تابع که ممکن است در برخی از مسیرهای کد خود مقداری را بازنگرداند، در حالی که امضای نوع آن نشان می‌دهد که همیشه باید مقداری را بازگرداند، یک خطا صادر می‌کند. این به جلوگیری از توابعی که به طور غیرمنتظره undefined را بازمی‌گردانند، کمک می‌کند.

"noImplicitReturns": true

allowUnreachableCode و allowUnusedLabels: کنترل کد غیرقابل دسترس و لیبل‌های استفاده نشده

• allowUnreachableCode: اگر false باشد (پیش‌فرض true است)، کامپایلر برای کدی که پس از یک دستور return یا throw قرار گرفته و هرگز اجرا نمی‌شود، هشدار می‌دهد.
• allowUnusedLabels: اگر false باشد (پیش‌فرض true است)، کامپایلر برای لیبل‌هایی که هرگز استفاده نمی‌شوند، هشدار می‌دهد.

"allowUnreachableCode": false,
"allowUnusedLabels": false

با فعال‌سازی و درک این گزینه‌های کنترل نوع و خطا، شما می‌توانید محیط توسعه‌ای ایجاد کنید که به طور فعال به شما در نوشتن کدهای قوی‌تر، ایمن‌تر و با کیفیت‌تر کمک کند. این سرمایه‌گذاری اولیه در زمان، در بلندمدت با کاهش زمان اشکال‌زدایی و بهبود نگهداری‌پذیری کد جبران خواهد شد.

ادغام tsconfig.json با ابزارهای اکوسیستم جاوااسکریپت

تایپ‌اسکریپت به تنهایی یک زبان و کامپایلر قدرتمند است، اما قدرت واقعی آن زمانی آشکار می‌شود که به طور یکپارچه با ابزارهای دیگر در اکوسیستم جاوااسکریپت همکاری کند. tsconfig.json نقش محوری در این ادغام ایفا می‌کند، زیرا بسیاری از ابزارها از این فایل برای درک ساختار پروژه، تنظیمات کامپایلر و مسیرهای فایل استفاده می‌کنند. درک این تعاملات برای پیکربندی یک گردش کار توسعه روان و کارآمد ضروری است.

ESLint و Prettier: یکپارچگی کد و فرمتینگ

ESLint و Prettier به ترتیب برای تحلیل کد (linting) و فرمت‌بندی (formatting) استفاده می‌شوند و هر دو به شدت به تنظیمات تایپ‌اسکریپت شما وابسته هستند.

ESLint

ESLint از یک parser و parserOptions برای درک کد شما استفاده می‌کند. برای تایپ‌اسکریپت، معمولاً از @typescript-eslint/parser استفاده می‌شود. این پارسر نیاز دارد بداند که فایل tsconfig.json شما کجاست تا بتواند تحلیل‌های دقیق‌تری بر اساس اطلاعات نوع تایپ‌اسکریپت انجام دهد (مثلاً بررسی‌های نوعی در قوانین Lint). شما project را در parserOptions ESLint به فایل tsconfig.json خود اشاره می‌دهید.

// .eslintrc.js
module.exports = {
  parser: '@typescript-eslint/parser',
  parserOptions: {
    project: './tsconfig.json', // ESLint از این tsconfig.json برای تحلیل استفاده می‌کند
    tsconfigRootDir: __dirname,
    ecmaFeatures: {
      jsx: true
    },
    ecmaVersion: 2020,
    sourceType: 'module'
  },
  plugins: [
    '@typescript-eslint'
  ],
  extends: [
    'eslint:recommended',
    'plugin:@typescript-eslint/recommended',
    'plugin:@typescript-eslint/recommended-requiring-type-checking' // نیاز به تحلیل نوع
  ],
  root: true,
  env: {
    node: true,
    jest: true
  },
  rules: {
    // ... قوانین سفارشی
  }
};

compilerOptions.jsx و compilerOptions.target در tsconfig.json می‌توانند بر نحوه پیکربندی ecmaVersion و jsx در ESLint تأثیر بگذارند. اطمینان از همسانی این تنظیمات برای جلوگیری از تضادها و خطاهای Linting حیاتی است.

Prettier

Prettier یک فرمت‌کننده کد است که به طور معمول مستقیماً از tsconfig.json استفاده نمی‌کند، اما هماهنگی بین تنظیمات target در tsconfig.json و قابلیت‌های فرمت‌بندی Prettier برای اطمینان از خروجی یکدست و زیبا مهم است. Prettier صرفاً فرمت کد را تغییر می‌دهد و به مسائل مربوط به نوع کاری ندارد. با این حال، استفاده همزمان از Prettier و ESLint (معمولاً با پلاگین‌هایی مانند eslint-config-prettier) یک جریان کاری قدرتمند برای کیفیت کد ایجاد می‌کند.

Bundlers (Webpack, Rollup, Vite): بهینه‌سازی برای تولید

باندلرها (Bundle) ابزارهایی هستند که ماژول‌های جاوااسکریپت، تایپ‌اسکریپت و دیگر دارایی‌ها را جمع‌آوری کرده و آن‌ها را به یک یا چند فایل برای استقرار در محیط‌های مرورگر یا Node.js تبدیل می‌کنند. نحوه استفاده باندلرها از tsconfig.json بسته به ابزار و تنظیمات آن متفاوت است:

• Webpack (با ts-loader یا awesome-typescript-loader): این لودرها از tsconfig.json برای انجام کامپایل تایپ‌اسکریپت استفاده می‌کنند. شما می‌توانید با استفاده از گزینه transpileOnly: true در لودرها، فقط ترانسپایل بدون بررسی نوع را انجام دهید تا سرعت ساخت را بالا ببرید. در این حالت، بررسی نوع را به ESLint یا اجرای جداگانه tsc --noEmit واگذار می‌کنید.
• Rollup (با @rollup/plugin-typescript): مشابه Webpack، این پلاگین نیز از tsconfig.json برای ترانسپایل استفاده می‌کند.
• Vite: Vite از Esbuild یا Babel برای ترانسپایل سریع تایپ‌اسکریپت استفاده می‌کند و در ابتدا فقط بررسی نوع را نادیده می‌گیرد. با این حال، تنظیمات tsconfig.json مانند paths، target و jsx همچنان توسط Vite (یا پلاگین‌های آن) برای اطمینان از ترانسپایل صحیح کد شما در نظر گرفته می‌شوند. Vite همچنین می‌تواند به صورت جداگانه tsc --noEmit را برای بررسی نوع در زمان ساخت اجرا کند.

تنظیماتی مانند compilerOptions.target، compilerOptions.module، compilerOptions.baseUrl، compilerOptions.paths، و compilerOptions.jsx در tsconfig.json به طور مستقیم بر نحوه عملکرد باندلرها و خروجی نهایی تأثیر می‌گذارند. به عنوان مثال، اگر module را روی "esnext" تنظیم کنید، باندلر شما انتظار دارد که ورودی آن ماژول‌های ES باشند و آن‌ها را به درستی پردازش خواهد کرد.

// webpack.config.js
module.exports = {
  // ...
  module: {
    rules: [
      {
        test: /\.tsx?$/,
        use: [
          {
            loader: 'ts-loader',
            options: {
              transpileOnly: true, // فقط ترانسپایل، بدون بررسی نوع
              configFile: 'tsconfig.json' // اشاره به فایل tsconfig.json
            }
          }
        ],
        exclude: /node_modules/
      }
    ]
  },
  resolve: {
    extensions: ['.tsx', '.ts', '.js'],
    // ... مطمئن شوید paths در tsconfig.json نیز در webpack resolve شوند
    alias: {
      '@components': path.resolve(__dirname, 'src/components'),
      '@utils': path.resolve(__dirname, 'src/utils')
    }
  }
};

Testing Frameworks (Jest, Vitest): محیط تست تایپ‌اسکریپت

فریم‌ورک‌های تست مانند Jest و Vitest نیز باید قادر به اجرای کدهای تایپ‌اسکریپت باشند. آن‌ها معمولاً از یک ترانسپایلر داخلی یا یک بسته کمکی برای این کار استفاده می‌کنند که tsconfig.json شما را در نظر می‌گیرد.

• Jest: برای Jest، معمولاً از ts-jest استفاده می‌شود که یک پری‌ست (preset) برای Jest است و فایل‌های .ts و .tsx را قبل از اجرای تست‌ها به جاوااسکریپت تبدیل می‌کند. ts-jest به طور پیش‌فرض tsconfig.json پروژه شما را می‌خواند. تنظیماتی مانند jsx و paths (از طریق گزینه moduleNameMapper در Jest) برای تست‌های شما مهم هستند.
• Vitest: Vitest به طور بومی از تایپ‌اسکریپت پشتیبانی می‌کند و نیازی به پیکربندی اضافی ندارد، زیرا از Esbuild برای ترانسپایل سریع استفاده می‌کند. با این حال، تنظیمات tsconfig.json شما (مانند paths و jsx) برای اطمینان از حل صحیح ماژول‌ها و ترانسپایل کد شما در محیط تست استفاده می‌شوند.

// jest.config.js
module.exports = {
  preset: 'ts-jest',
  testEnvironment: 'node',
  moduleNameMapper: {
    '^@components/(.*)$': '/src/components/$1', // نگاشت paths از tsconfig.json
    '^@utils/(.*)$': '/src/utils/$1'
  },
  globals: {
    'ts-jest': {
      tsconfig: 'tsconfig.json' // اطمینان از استفاده از tsconfig.json صحیح
    }
  }
};

Build Tools و Task Runners

ابزارهایی مانند Gulp، Grunt یا حتی اسکریپت‌های ساده در package.json شما نیز می‌توانند از tsconfig.json برای اجرای کامپایل تایپ‌اسکریپت استفاده کنند. استفاده از دستور tsc با پرچم‌های مناسب (مثلاً --build برای Project References، --watch برای توسعه) در این اسکریپت‌ها، به طور مستقیم به tsconfig.json شما وابسته است.

// package.json
{
  "scripts": {
    "build": "tsc --build", // استفاده از tsconfig.json با references
    "dev": "tsc --watch", // استفاده از tsconfig.json در حالت watch
    "lint": "eslint \"{src,apps,libs,test}/**/*.ts\"",
    "test": "jest"
  }
}

در نهایت، هدف این است که تمام ابزارهای شما به طور سازگار با tsconfig.json شما کار کنند. این شامل اطمینان از اینکه target، module، paths و jsx در تمام ابزارهایی که کد تایپ‌اسکریپت شما را پردازش می‌کنند (کامپایلر، باندلر، تست‌کننده، لینتر) همسو باشند. یک tsconfig.json با تنظیمات خوب، نقش یک منبع حقیقت را برای پروژه تایپ‌اسکریپت شما ایفا می‌کند و پایه و اساس یک اکوسیستم توسعه یکپارچه و کارآمد را فراهم می‌آورد.

عیب‌یابی و بهترین شیوه‌ها در tsconfig.json

حتی با بهترین نیت‌ها، پیکربندی tsconfig.json می‌تواند چالش‌برانگیز باشد، به خصوص در پروژه‌های بزرگ یا پیچیده. آگاهی از مشکلات رایج و بهترین شیوه‌ها برای نگهداری و عیب‌یابی، می‌تواند زمان زیادی را از شما ذخیره کند و پروژه شما را در مسیر درست نگه دارد.

مشکلات رایج و راه‌حل‌ها

خطاهای “Could not find module” یا “Cannot find name”

• علت: معمولاً به دلیل پیکربندی نادرست baseUrl و paths، یا عدم پوشش مناسب فایل‌ها توسط include و exclude. همچنین می‌تواند به دلیل عدم نصب یا عدم تشخیص فایل‌های تعریف نوع (.d.ts) باشد.
• راه‌حل:
  • بررسی کنید که baseUrl و paths به درستی تنظیم شده‌اند و با ساختار پوشه‌ای شما مطابقت دارند.
  • مطمئن شوید که فایل‌های شما در include هستند و در exclude نیستند.
  • برای کتابخانه‌های شخص ثالث، مطمئن شوید که @types/<package-name> نصب شده است. اگر کتابخانه‌ای تعریف نوع ندارد، می‌توانید یک فایل .d.ts سفارشی ایجاد کنید.
  • بررسی کنید که moduleResolution به درستی تنظیم شده است (معمولاً "node").

کامپایل بسیار کند

• علت: معمولاً به دلیل عدم استفاده از incremental، یا بررسی نوع فایل‌های غیرضروری (مانند node_modules) یا تست‌ها.
• راه‌حل:
  • "incremental": true را فعال کنید.
  • "skipLibCheck": true را فعال کنید.
  • اطمینان حاصل کنید که node_modules، dist و فایل‌های تست (اگر لازم نیستند) در exclude هستند.
  • در محیط‌های CI/CD، از کامپایل افزایشی با tsc --build استفاده کنید.

تضاد در خروجی جاوااسکریپت (مثلاً مشکل در CommonJS/ESM)

• علت: عدم همسویی target و module در tsconfig.json با محیط اجرایی (Node.js/مرورگر) یا باندلر شما.
• راه‌حل:
  • برای Node.js، معمولاً "target": "es2020" یا بالاتر و "module": "commonjs".
  • برای فرانت‌اند با باندلر، معمولاً "target": "es2020" یا بالاتر و "module": "esnext" (و اجازه دهید باندلر آن را به فرمت نهایی تبدیل کند).
  • "esModuleInterop": true را فعال کنید تا مشکلات وارد کردن ماژول‌های CommonJS در ESM برطرف شود.

خطاهای Strict Type Checks بیش از حد

• علت: فعال بودن گزینه‌های Strict و عادت نداشتن به تایپ‌دهی دقیق.
• راه‌حل:
  • این‌ها خطا نیستند، بلکه هشدارها و بهترین شیوه‌ها هستند! تلاش کنید آن‌ها را برطرف کنید.
  • برای موارد خاص و موقت، می‌توانید از //@ts-ignore یا //@ts-expect-error استفاده کنید (با احتیاط).
  • در موارد نادر، می‌توانید یک یا دو گزینه خاص از خانواده strict را غیرفعال کنید، اما این کار به طور کلی توصیه نمی‌شود.

بهترین شیوه‌ها برای مدیریت tsconfig.json

۱. شروع با "strict": true

همیشه پروژه جدید تایپ‌اسکریپت خود را با "strict": true آغاز کنید. این کار به شما کمک می‌کند از همان ابتدا کدهای قوی‌تر و ایمن‌تری بنویسید. افزودن strict به یک کدبیس موجود می‌تواند یک چالش باشد.

۲. استفاده از extends برای پیکربندی‌های مشترک

در مونوریپوها یا پروژه‌هایی با چندین زیرپروژه، یک tsconfig.base.json یا tsconfig.json مشترک ایجاد کنید و اجازه دهید سایر فایل‌ها از آن ارث‌بری کنند. این کار نگهداری را آسان‌تر می‌کند و اطمینان می‌دهد که تمام پروژه‌ها از یک سری تنظیمات پایه یکسان پیروی می‌کنند.

۳. مدیریت include و exclude با دقت

فقط فایل‌هایی که نیاز به کامپایل یا بررسی نوع دارند را در include قرار دهید. همیشه پوشه‌های خروجی (dist، build) و node_modules را در exclude قرار دهید. این به کاهش زمان کامپایل کمک می‌کند.

۴. همگام‌سازی با ابزارهای اکوسیستم

اطمینان حاصل کنید که تنظیمات tsconfig.json شما (مانند target، module، jsx، paths) با تنظیمات باندلرها (Webpack, Rollup, Vite), لینترها (ESLint) و فریم‌ورک‌های تست (Jest, Vitest) شما همسو هستند. ناسازگاری می‌تواند منجر به خطاهای عجیب و غریب یا مشکلات عملکردی شود.

۵. استفاده از Project References برای مونوریپوها

اگر در حال کار روی یک مونوریپو هستید، از references و composite برای مدیریت وابستگی بین پروژه‌ها استفاده کنید. این به کامپایلر اجازه می‌دهد تا فقط قسمت‌های لازم را کامپایل مجدد کند و سرعت ساخت را به شدت بهبود بخشد.

۶. استفاده از sourceMap و declaration (در صورت نیاز)

همیشه sourceMap: true را در محیط توسعه و تولید خود فعال کنید تا اشکال‌زدایی آسان‌تر شود. اگر کتابخانه منتشر می‌کنید، declaration: true را برای تولید فایل‌های .d.ts فعال کنید.

۷. نگهداری tsconfig.json در سیستم کنترل نسخه

tsconfig.json بخشی جدایی‌ناپذیر از کدبیس شماست و باید در سیستم کنترل نسخه (مانند Git) نگهداری شود تا تمام توسعه‌دهندگان از یک پیکربندی یکسان استفاده کنند.

۸. استفاده از tsc --showConfig برای بررسی تنظیمات نهایی

اگر در مورد اینکه کامپایلر دقیقاً کدام تنظیمات را اعمال می‌کند شک دارید (به خصوص با extends و references)، دستور tsc --showConfig را در ترمینال اجرا کنید. این دستور خروجی نهایی tsconfig.json را پس از اعمال تمام ارث‌بری‌ها و حل و فصل‌ها نمایش می‌دهد.

tsc --showConfig

۹. بروزرسانی منظم تایپ‌اسکریپت

با هر نسخه جدید تایپ‌اسکریپت، بهبودهایی در عملکرد، ویژگی‌ها و گزینه‌های پیکربندی جدید اضافه می‌شود. بروزرسانی منظم به شما امکان می‌دهد از این پیشرفت‌ها بهره‌مند شوید و با اکوسیستم هماهنگ بمانید.

نتیجه‌گیری

مدیریت tsconfig.json یک مهارت اساسی برای هر توسعه‌دهنده تایپ‌اسکریپت است. این فایل دروازه کنترل کامپایلر و بهینه‌سازی پروژه شماست. از طریق درک عمیق گزینه‌های آن و کاربرد بهترین شیوه‌ها، می‌توانید اطمینان حاصل کنید که پروژه‌های تایپ‌اسکریپت شما نه تنها عملکرد بالا و زمان کامپایل سریع دارند، بلکه کدهای آن‌ها نیز از لحاظ نوعی ایمن، قابل نگهداری و با کیفیت هستند.

هدف از این مقاله، ارائه یک راهنمای جامع و کاربردی برای کمک به شما در تسلط بر tsconfig.json بود. با بکارگیری دانش کسب شده، شما آماده‌اید تا پروژه‌های تایپ‌اسکریپت خود را با اطمینان و کارایی بیشتری توسعه دهید. به یاد داشته باشید که tsconfig.json یک فایل زنده است که باید متناسب با نیازهای پروژه و تکامل آن، به طور منظم مورد بازبینی و بهینه‌سازی قرار گیرد.