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

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

tsconfig.json چیست؟

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

ایجاد یک فایل tsconfig.json

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

tsc --init

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

گزینه‌های ضروری کامپایلر

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

target

گزینه target نسخه هدف ECMAScript را برای کد جاوااسکریپت تولید شده مشخص می‌کند. مقادیر رایج شامل ES5، ES6 (ES2015)، ES2016، ES2017، ES2018، ES2019، ES2020، ES2021، ES2022، ESNext هستند. انتخاب هدف مناسب برای اطمینان از سازگاری با محیط اجرایی مورد نظر، مانند مرورگرها یا نسخه‌های Node.js، حیاتی است.

مثال:

{
  "compilerOptions": {
    "target": "ES2020"
  }
}

module

گزینه module سبک تولید کد ماژول را مشخص می‌کند. مقادیر رایج شامل CommonJS، AMD، System، UMD، ES6 (ES2015)، ES2020 و ESNext هستند. انتخاب سیستم ماژول به محیط هدف و باندلر ماژول مورد استفاده (مانند Webpack، Rollup، Parcel) بستگی دارد. برای Node.js، اغلب از CommonJS استفاده می‌شود، در حالی که برای برنامه‌های وب مدرن، ES6 یا ESNext همراه با یک باندلر ماژول ترجیح داده می‌شود. استفاده از ESNext به توسعه‌دهندگان اجازه می‌دهد از جدیدترین ویژگی‌ها و بهینه‌سازی‌ها بهره ببرند، در حالی که به باندلر برای مدیریت فرمت نهایی ماژول تکیه می‌کنند.

مثال:

{
  "compilerOptions": {
    "module": "ESNext"
  }
}

lib

گزینه lib لیستی از فایل‌های کتابخانه‌ای را که باید در کامپایل گنجانده شوند، مشخص می‌کند. این فایل‌های کتابخانه‌ای تعاریف تایپ را برای APIهای داخلی جاوااسکریپت و APIهای مرورگر فراهم می‌کنند. مقادیر رایج شامل ES5، ES6، ES2015، ES2016، ES2017، ES2018، ES2019، ES2020، ES2021، ES2022، ESNext، DOM، WebWorker، ScriptHost، ES2015.Core، ES2015.Collection، ES2015.Iterable، ES2015.Promise، ES2015.Proxy، ES2015.Reflect، ES2015.Generator، ES2015.Symbol، ES2015.Symbol.WellKnown، ES2016.Array.Include، ES2017.object، ES2017.Intl، ES2017.SharedMemory، ES2017.String، ES2017.TypedArrays، ES2018.Intl، ES2018.Promise، ES2018.RegExp، ES2019.Array، ES2019.Object، ES2019.String، ES2019.Symbol، ES2020.BigInt، ES2020.Promise، ES2020.String، ES2020.Symbol.WellKnown، ES2021.Promise، ES2021.String، ES2021.WeakRef، ES2022.Error، ES2022.Object، ES2022.String، و بسیاری دیگر هستند. انتخاب کتابخانه‌های مناسب تضمین می‌کند که کامپایلر تایپ‌اسکریپت اطلاعات تایپ لازم برای محیط هدف را داشته باشد. استفاده از کتابخانه DOM به پروژه اجازه می‌دهد کدی که از APIهای مختص مرورگر استفاده می‌کند را بدون خطاهای تایپ کامپایل کند.

مثال:

{
  "compilerOptions": {
    "lib": ["ES2020", "DOM"]
  }
}

allowJs

گزینه allowJs به کامپایلر تایپ‌اسکریپت اجازه می‌دهد تا فایل‌های جاوااسکریپت را به همراه فایل‌های تایپ‌اسکریپت کامپایل کند. این برای انتقال تدریجی پروژه‌های جاوااسکریپت موجود به تایپ‌اسکریپت مفید است. تنظیم این گزینه به true کامپایلر را قادر می‌سازد تا فایل‌های .js را پردازش کند، که امکان پذیرش تدریجی تایپ‌اسکریپت در یک پروژه را فراهم می‌کند.

مثال:

{
  "compilerOptions": {
    "allowJs": true
  }
}

jsx

گزینه jsx نحوه مدیریت سینتکس JSX را مشخص می‌کند. مقادیر رایج شامل preserve، react، react-native و react-jsx هستند. preserve سینتکس JSX را در خروجی حفظ می‌کند، در حالی که react سینتکس JSX را به فراخوانی‌های React.createElement تبدیل می‌کند. react-jsx از تبدیل جدید JSX که در React 17 معرفی شده استفاده می‌کند و نیازی به وارد کردن React ندارد. انتخاب گزینه JSX صحیح برای پروژه‌هایی که از React یا کتابخانه‌های مبتنی بر JSX دیگر استفاده می‌کنند، حیاتی است.

مثال:

{
  "compilerOptions": {
    "jsx": "react-jsx"
  }
}

declaration

گزینه declaration فایل‌های تعریف .d.ts متناظر را برای هر فایل تایپ‌اسکریپت تولید می‌کند. فایل‌های تعریف شامل اطلاعات تایپ هستند و توسط پروژه‌های تایپ‌اسکریپت دیگر برای استفاده از کد کامپایل شده استفاده می‌شوند. تولید فایل‌های تعریف برای ایجاد کتابخانه‌ها و ماژول‌های قابل استفاده مجدد ضروری است. این فایل‌ها به پروژه‌های تایپ‌اسکریپت دیگر اجازه می‌دهند تا تایپ‌ها و اینترفیس‌های ارائه شده توسط کتابخانه را بدون نیاز به کامپایل کد منبع اصلی درک کنند.

مثال:

{
  "compilerOptions": {
    "declaration": true
  }
}

sourceMap

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

مثال:

{
  "compilerOptions": {
    "sourceMap": true
  }
}

outDir

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

مثال:

{
  "compilerOptions": {
    "outDir": "dist"
  }
}

rootDir

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

مثال:

{
  "compilerOptions": {
    "rootDir": "src"
  }
}

strict

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

مثال:

{
  "compilerOptions": {
    "strict": true
  }
}

esModuleInterop

گزینه esModuleInterop قابلیت همکاری بین ماژول‌های CommonJS و ES را فعال می‌کند. این برای پروژه‌هایی که از هر دو نوع ماژول استفاده می‌کنند مهم است. وقتی esModuleInterop فعال باشد، تایپ‌اسکریپت به طور خودکار تفاوت‌های بین ماژول‌های CommonJS و ES را مدیریت می‌کند، که وارد کردن و صادر کردن ماژول‌ها بین دو سیستم را آسان‌تر می‌کند. این گزینه به ویژه هنگام کار با کتابخانه‌های شخص ثالث که ممکن است از سیستم‌های ماژول متفاوتی استفاده کنند، مفید است.

مثال:

{
  "compilerOptions": {
    "esModuleInterop": true
  }
}

moduleResolution

گزینه moduleResolution نحوه حل ایمپورت‌های ماژول توسط تایپ‌اسکریپت را مشخص می‌کند. مقادیر رایج شامل Node و Classic هستند. استراتژی حل ماژول Node پیش‌فرض است و بر اساس الگوریتم حل ماژول Node.js است. استراتژی حل ماژول Classic قدیمی‌تر و کمتر رایج است. استفاده از استراتژی حل ماژول Node تضمین می‌کند که تایپ‌اسکریپت می‌تواند ایمپورت‌های ماژول را در یک محیط Node.js به درستی حل کند.

مثال:

{
  "compilerOptions": {
    "moduleResolution": "Node"
  }
}

baseUrl و paths

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

مثال:

{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@components/*": ["src/components/*"],
      "@utils/*": ["src/utils/*"]
    }
  }
}

گزینه‌های Include و Exclude

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

مثال:

{
  "include": ["src/**/*"],
  "exclude": ["node_modules", "dist"]
}

گزینه Extends

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

مثال:

{
  "extends": "./tsconfig.base.json",
  "compilerOptions": {
    "jsx": "react-jsx"
  },
  "include": ["src/**/*"]
}

پیکربندی‌های پیشرفته

فراتر از گزینه‌های ضروری کامپایلر، tsconfig.json از پیکربندی‌های پیشرفته برای سناریوهای تخصصی پشتیبانی می‌کند.

کامپایل افزایشی (Incremental Compilation)

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

{
  "compilerOptions": {
    "incremental": true,
    "tsBuildInfoFile": ".tsbuildinfo"
  }
}

ارجاعات پروژه (Project References)

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

{
  "compilerOptions": {
    "composite": true
  },
  "references": [
    { "path": "./module1" },
    { "path": "./module2" }
  ]
}

تعاریف تایپ سفارشی (Custom Type Definitions)

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

// custom.d.ts
declare module 'my-library' {
  export function doSomething(x: number): string;
}

بهترین روش‌ها

• استفاده از حالت Strict: گزینه strict را برای بررسی تایپ پیشرفته فعال کنید.
• مشخص کردن Target: نسخه target مناسب را برای محیط اجرایی خود انتخاب کنید.
• سازماندهی خروجی: از outDir برای جدا کردن کد منبع از کد کامپایل شده استفاده کنید.
• مدیریت وابستگی‌ها: از include و exclude برای کنترل فایل‌هایی که کامپایل می‌شوند استفاده کنید.
• بهره‌گیری از Extends: تنظیمات پیکربندی مشترک را با گزینه extends به اشتراک بگذارید.
• قرار دادن پیکربندی در کنترل نسخه: فایل `tsconfig.json` را به git کامیت کنید تا یکپارچگی در محیط‌های توسعه‌دهندگان و خطوط لوله CI/CD حفظ شود.

عیب‌یابی مشکلات رایج

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

مشکلات حل ماژول (Module Resolution Issues)

اگر با خطاهای حل ماژول مواجه شدید، اطمینان حاصل کنید که گزینه moduleResolution به درستی پیکربندی شده و گزینه‌های baseUrl و paths به درستی تنظیم شده‌اند. مسیرهای مشخص شده در گزینه paths را دوباره بررسی کنید تا از صحت آنها اطمینان حاصل کنید. تأیید کنید که تمام ماژول‌های لازم در دایرکتوری node_modules نصب شده‌اند.

خطاهای تایپ (Type Errors)

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

خطاهای کامپایل (Compilation Errors)

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

نتیجه‌گیری

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

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