استفاده از TypeScript برای Cloud Functions

برای توسعه‌دهندگانی که ترجیح می‌دهند توابع را در TypeScript بنویسند، Cloud Functions دو نوع پشتیبانی ارائه می‌دهد:

  • پروژه‌های TypeScript را برای ترجمه مبدأ به مبدأ خودکار در مقداردهی اولیه (firebase init functions) ایجاد و پیکربندی کنید.
  • Transpile existing TypeScript source to JavaScript at deploy time via a predeploy hook.

با دنبال کردن دستورالعمل‌های این راهنما، می‌توانید پروژه JavaScript موجود را به TypeScript منتقل کنید و بااستفاده از قلاب پیش‌از استقرار برای ترجمه مبدأ به مبدأ کد منبع، به استقرار توابع ادامه دهید. TypeScript مزایای زیادی نسبت به جاوا اسکریپت وانیلی هنگام نوشتن توابع ارائه می‌دهد:

  • TypeScript از جدیدترین ویژگی‌های جاوا اسکریپت مانند async/await پشتیبانی می‌کند و مدیریت promise را ساده می‌کند
  • خطایاب نحوی Cloud Functions مشکلات رایج را هنگام کدنویسی برجسته می‌کند
  • ایمنی تایپی به شما کمک می‌کند از خطاهای زمان اجرا در توابع مستقرشده جلوگیری کنید

اگر با TypeScript آشنایی ندارید، TypeScript در ۵ دقیقه را ببینید.

درحال مقداردهی اولیه پروژه Cloud Functions جدید با TypeScript

firebase init functions را در دایرکتوری جدیدی اجرا کنید. این ابزار گزینه‌هایی برای ساختن پروژه با JavaScript یا TypeScript دراختیارتان قرار می‌دهد. TypeScript را برای برونداد ساختار پروژه زیر انتخاب کنید:

myproject
 +- functions/     # Directory containing all your functions code
      |
      +- package.json  # npm package file describing your Cloud Functions code
      |
      +- tsconfig.json
      |
      +- .eslintrc.js # Optional file if you enabled ESLint
      +- tsconfig.dev.json # Optional file that references .eslintrc.js
      |
      +- src/     # Directory containing TypeScript source
      |   |
      |   +- index.ts  # main source file for your Cloud Functions code
      |
      +- lib/
          |
          +- index.js  # Built/transpiled JavaScript code
          |
          +- index.js.map # Source map for debugging

پس‌از تکمیل مقداردهی اولیه، نمونه را در index.ts از حالت توضیح خارج کنید و npm run serve را اجرا کنید تا عملکرد تابع «Hello World» را ببینید.

استفاده از پروژه TypeScript موجود

اگر پروژه TypeScript موجودی دارید، می‌توانید قلاب پیش‌از استقرار اضافه کنید تا مطمئن شوید پروژه شما هربار که کدتان را در Cloud Functions for Firebase مستقر می‌کنید ترجمه مبدأ به مبدأ می‌شود. به فایل tsconfig.json با قالب‌بندی مناسب و پروژه Firebase نیاز دارید و باید اصلاحات زیر را در پیکربندی Firebase خود اعمال کنید:

  1. package.json را ویرایش کنید تا اسکریپت bash برای ساخت پروژه TypeScript اضافه شود. برای مثال:

     {
   "name": "functions",
   "scripts": {
     "build": "npm run lint && tsc"
   }
 ...

  2. firebase.json را ویرایش کنید تا قلاب پیش‌از استقرار برای اجرای اسکریپت ساخت اضافه شود. برای مثال:

     {
   "functions": {
     "predeploy": "npm --prefix functions run build",
   }
 }

با این پیکربندی، فرمان firebase deploy --only functions کد TypeScript شما را می‌سازد و آن را به‌عنوان تابع مستقر می‌کند.

انتقال دادن پروژه جاوا اسکریپت موجود به TypeScript

اگر پروژه Cloud Functions موجودی دارید که آن را در جاوا اسکریپت مقداردهی اولیه و توسعه داده‌اید، می‌توانید آن را به TypeScript منتقل کنید. اکیداً توصیه می‌شود قبل‌از شروع، یک نقطه بازرسی git یا پشتیبان‌گیری دیگری ایجاد کنید.

برای انتقال پروژه جاوا اسکریپت Cloud Functions موجود:

  1. یک نقطه بازرسی git ایجاد کنید و نسخه‌هایی از فایل‌های منبع جاوا اسکریپت موجود خود را ذخیره کنید.
  2. در فهرست راهنمای پروژه، firebase init functions را اجرا کنید و وقتی از شما خواسته شد زبانی را برای نوشتن توابع انتخاب کنید، TypeScript را انتخاب کنید.
  3. وقتی از شما خواسته شد که آیا می‌خواهید فایل package.json موجود را رونویسی کنید، نه را انتخاب کنید، مگراینکه مطمئن باشید نمی‌خواهید فایل موجود را نگه دارید.
  4. index.ts را در دایرکتوری functions/src حذف کنید و آن را با کد منبع موجودتان جایگزین کنید.
  5. در فایل tsconfig.json ایجادشده در مقداردهی اولیه، گزینه‌های کامپایلر را برای مجاز کردن جاوا اسکریپت تنظیم کنید: "allowJs": true.
  6. فایل package.json ذخیره‌شده را در دایرکتوری functions کپی کنید و آن را ویرایش کنید تا "main" روی "lib/index.js" تنظیم شود.

  7. همچنین در package.json، یک اسکریپت ساخت برای TypeScript مانند زیر اضافه کنید:

     {
   "name": "functions",
   "scripts": {
     "build": "npm run lint && tsc"
   }
 ...

  8. با اجرای npm install --save-dev typescript @typescript-eslint/eslint-plugin @typescript-eslint/parser،‏ "typescript" را به‌عنوان وابستگی توسعه اضافه کنید.

  9. برای همه وابستگی‌ها، npm install --save @types/<dependency> را اجرا کنید.

  10. کد منبع را از ‎ .js به ‎ .ts به‌دلخواه بازنویسی کنید.

شبیه‌سازی توابع TypeScript

برای آزمایش کردن توابع TypeScript به‌صورت محلی، می‌توانید از ابزارهای شبیه‌سازی شرح‌داده‌شده در اجرای توابع به‌صورت محلی استفاده کنید. مهم است که کد خود را قبل‌از استفاده از این ابزارها کامپایل کنید، بنابراین مطمئن شوید که npm run build را درون دایرکتوری توابع خود قبل‌از اجرای firebase emulators:start یا firebase functions:shell اجرا کنید. به‌جای‌آن، npm run serve یا npm run shell را به‌عنوان میان‌بر اجرا کنید؛ هر دوی این فرمان‌ها ساخت را اجرا می‌کنند و پوسته توابع را ارائه/شروع می‌کنند.

گزارش‌های Functions برای پروژه‌های TypeScript

درطول firebase deploy، index.ts پروژه شما به index.js ترجمه مبدأ به مبدأ می‌شود، یعنی گزارش Cloud Functions شماره خطوط را از فایل index.js خروجی می‌دهد و نه کدی که شما نوشته‌اید. برای اینکه راحت‌تر بتوانید مسیرها و شماره خط‌های مربوطه را در index.ts پیدا کنید، firebase deploy functions/lib/index.js.map را ایجاد می‌کند. می‌توانید از این نقشه منبع در IDE دلخواهتان یا ازطریق ماژول گره استفاده کنید.