‏Commander؛ پالت فرمانِ تایپ‌سیف برای Backstage

Allegro، یکی از بزرگ‌ترین پلتفرم‌های تجارت الکترونیک اروپا، بعد از مهاجرت به Backstage (فریم‌ورک متن‌بازِ Spotify برای پرتال توسعه‌دهنده) یه مشکل حل‌نشده داشت: کشف‌پذیری و جست‌وجو. به گفتهٔ نویسنده، جست‌وجوی داخلیِ Backstage کند و پر از نتایج اشتباه بود و با بیش از ۱۵۰ هزار انتیتی، یه نمای جدولیِ ساده اصلاً کافی نبود.

راه‌حلشون ابزاری به‌اسم Commander بود؛ یه پالت فرمانِ کیبورد-محور که با ⌘+K (یا Ctrl+K) به‌شکل یه مودال باز می‌شه و می‌ذاره کاتالوگ رو سریع بگردی، دیپلوی رو تریگر کنی و ابزارها رو بدون ترک صفحه مدیریت کنی. نکتهٔ جالب اینه که Commander کاملاً یه پلاگینِ فرانت‌اندیه و هیچ بک‌اندی نداره.

تصمیم معماریِ اصلی این بود که پالت رو مثل یه روتر ببینن، نه یه switch بزرگ روی حالت‌های UI. به گفتهٔ نویسنده، Commander از یه «پشتهٔ صفحه» (page stack) استفاده می‌کنه: یه آرایهٔ مرتب از آبجکت‌های صفحه که هر کدوم یه type و یه dataی تایپ‌دار دارن. صفحهٔ فعلی همیشه بالای پشته‌ست؛ push یعنی جلو رفتن و pop (مثلاً با Backspace رو ورودیِ خالی) یعنی برگشتن.

هر صفحه به‌شکل یه رکورد static تو یه فایل کانفیگ تعریف می‌شه و به گفتهٔ نویسنده، اضافه‌کردنِ یه صفحهٔ جدید هیچ تغییری تو روتر یا شل لازم نداره، فقط یه ورودیِ کانفیگِ تازه:

export const pagesConfiguration = createPagesConfig({
  myFeature: {
    label: 'My Feature',
    placeholder: 'Search...',
    condition: (pages) => !!pages.findLast(p => p.type === 'myFeature'),
    render: MyFeaturePage,
    schema: z.enum(['foo', 'bar']),
  },
});

اینجا condition تعیین می‌کنه صفحه کی رندر شه و schema (یه اسکیمای zod) باعث می‌شه push کردنِ داده به اون صفحه سرتاسر تایپ‌سیف باشه.

هوشمندانه‌ترین بخش از نگاه نویسنده، مشتق‌کردنِ ابزارهای تایپ‌سیفِ صفحه مستقیماً از خودِ آبجکت کانفیگ در زمان کامپایله، بدون تعریف دستیِ تایپ. این کار با ترکیب سه تکنیک TypeScript انجام می‌شه: conditional typeها، mapped typeها و استنتاج تایپ از اسکیمای zod. نتیجه اینه که تایپ داده رو یه‌بار با zod می‌نویسی و TypeScript خودش بقیه رو درمیاره.

نکات کلیدی:

• Commander یه پالت فرمانِ ⌘+K برای Backstage با بیش از ۱۵۰ هزار انتیتیه.
• معماریش یه روترِ مبتنی‌بر «پشتهٔ صفحه»ست، نه switch روی حالت‌های UI.
• اضافه‌کردنِ صفحهٔ جدید فقط یه ورودیِ کانفیگ می‌خواد، بدون تغییر روتر.
• تایپ‌سیفیِ سرتاسری از روی اسکیمای zod و تایپ‌های TypeScript مشتق می‌شه.