‏astro-seo: متادیتای سبک Next.js برای Astro

طبق توضیح این مقاله، Astro برای مدیریت متادیتای صفحه‌ها هیچ قرارداد داخلی نداره. معمولاً هر سایت یه layout می‌سازه که فقط title و شاید description می‌گیره، و برای چیزهایی مثل تصویر OpenGraph، کارت توییتر، دستورهای robots یا آدرس canonical هر بار باید از اول کد نوشت. @lucky-media/astro-seo این مشکل رو با آوردن API معروف generateMetadata و Metadata از Next.js App Router به Astro حل می‌کنه.

کار از دو جا شروع می‌شه. اول، integration به اسم defaultSeo() که توی astro.config.mjs اضافه می‌شه و پیش‌فرض‌های کل سایت رو نگه می‌داره. فیلد metadataBase آدرس پایه‌ایه که مسیرهای نسبی تصویرها و آیکون‌ها باهاش کامل می‌شن. بعد، توی یه layout مشترک، resolveMetadata() تنظیمات سایت و صفحه رو با هم ادغام می‌کنه و کامپوننت SEO همهٔ تگ‌های meta و link لازم رو توی head رندر می‌کنه.

یکی از امکانات کاربردیش title template هست، یعنی یه الگو که عنوان هر صفحه خودکار داخلش قرار می‌گیره. مثلاً اگه توی defaultSeo فیلد title به شکل { default: 'Lucky Media', template: '%s | Lucky Media' } تعریف بشه، کافیه صفحه فقط عنوان خودشو بده:

const metadata = generateMetadata({ title: 'About' })
// Resolves to: "About | Lucky Media"

اگه یه صفحه نخواد از الگو پیروی کنه، با absolute عنوان رو دقیق تعیین می‌کنه. یه صفحه هم می‌تونه template جدیدی برای زیرمجموعهٔ خودش تعریف کنه، مثلاً بخش بلاگ با پسوند جدا.

فیلدهای openGraph و twitter فیلد به فیلد با پیش‌فرض‌های سایت ادغام می‌شن (deep merge). یعنی هر چی صفحه تعیین کنه جایگزین می‌شه، بقیه از سایت ارث می‌رسه، و با گذاشتن null می‌شه یه فیلد رو کامل پاک کرد. نوع کارت توییتر هم خودکار انتخاب می‌شه: اگه تصویر باشه summary_large_image و اگه نباشه summary.

تنظیمات سایت می‌تونه یه شیء ثابت باشه که موقع build داخل ماژول جاسازی می‌شه و هزینهٔ زمان اجرا نداره، یا یه تابع (حتی async) که مثلاً پیش‌فرض‌ها رو از یه CMS می‌گیره. این تابع در هر build فقط یه بار صدا زده می‌شه و نتیجه‌ش کش می‌شه. برای SSR هم الگوی جدایی برای گرفتن داده موقع درخواست وجود داره. تایپ‌های TypeScript هم خودکار تزریق می‌شن و لازم نیست به tsconfig.json دست بزنی.

نکات کلیدی:

• پیش‌فرض‌های کل سایت با defaultSeo() توی astro.config.mjs تعریف می‌شن و هر صفحه با generateMetadata() اونا رو override می‌کنه.
• الگوی عنوان با %s کار می‌کنه و با absolute می‌شه یه صفحه رو ازش معاف کرد.
• فیلدهای openGraph و twitter به‌صورت deep merge ادغام می‌شن و null یه فیلد رو کامل پاک می‌کنه.
• کارت توییتر در صورت وجود تصویر خودکار summary_large_image می‌شه، وگرنه summary.
• تابع تنظیمات async در هر build فقط یه بار اجرا و کش می‌شه.