انتشار Tailwind Nextjs Starter Blog v2.0

مقدمه

به انتشار قالب Tailwind Nextjs Starter Blog v2.0 خوش آمدید. این نسخه یک بازنویسی بزرگ از کدبیس برای پشتیبانی از Nextjs App directory و React Server Components است. ادامه دهید تا ویژگی‌های جدید و نحوه مهاجرت از V1 را کشف کنید.

V1 به V2

قالب برای اولین بار در ژانویه 2021 منتشر شد و از آن زمان توسط هزاران کاربر استفاده شده است. در Next.js Templates، Tailwind Awesome و سایر سایت‌های لیست‌بندی شده است. روزانه 200+ بازدیدکننده منحصر به فرد جذب می‌کند که 1500-2000 بازدید صفحه را ثبت می‌کند، با 1.3k fork و بسیاری کلون‌های دیگر.

با تشکر فراوان از جامعه کاربران و مشارکت‌کنندگان برای موفقیت این قالب! یک ویدیو مونتاژ کوچک از بلاگ‌ها (در حالی که لیست را در readme پاک می‌کردم) ایجاد کردم تا تنوع بلاگ‌های ایجاد شده با استفاده از قالب را نشان دهم و این نقطه عطف را جشن بگیرم:

نسخه 2 بر موفقیت نسخه قبلی بنا شده و ویژگی‌ها و بهبودهای جدید زیادی را معرفی می‌کند. کدبیس برای پشتیبانی از Next.js App directory و React Server Components بازنویسی شده است. Markdown / MDX اکنون با استفاده از Contentlayer پردازش می‌شود، یک SDK محتوای type-safe که محتوای شما را اعتبارسنجی و به داده‌های JSON type-safe تبدیل می‌کند. با Pliny یکپارچه می‌شود، یک کتابخانه جدید که کامپوننت‌های Next.js آماده برای استفاده را برای بهبود سایت استاتیک شما با analytics، نظرات و اشتراک خبرنامه ارائه می‌دهد. یک کامپوننت جستجوی command palette (⌘-k) جدید نیز به قالب اضافه شده است.

بیایید به ویژگی‌ها و بهبودهای جدید در V2 بپردازیم.

Next.js App Directory و React Server Components

اکنون که Next.js App router در نهایت پایدار است و عمدتاً با Page Router سازگار است، کدبیس به تنظیمات جدید مهاجرت کرده است. این اجازه می‌دهد رویکرد رندرینگ ترکیبی، با استفاده از React Server Components که در سمت سرور تولید می‌شوند برای بارگذاری سریع‌تر صفحات و اندازه bundle کوچکتر، در حالی که توانایی استفاده از کامپوننت‌های React سمت کلاینت برای تعامل را حفظ می‌کند.[^1]

با قدرت‌های اضافی، یک پارادایم جدید برای یادگیری می‌آید. کدبیس را برای استفاده حداکثری از ویژگی‌های جدید مهاجرت داده‌ام. این شامل تغییرات در ساختار پوشه، تقسیم کامپوننت‌ها به server vs client components، استفاده از server side data fetching و استفاده از Metadata API توصیه شده برای کشف SEO است.

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

Typescript First

کدبیس به Typescript مهاجرت کرده است. در حالی که نسخه قبلی قالب در هر دو Javascript و Typescript در دسترس بود، تصمیم گرفتم بار نگهداری را کاهش دهم و روی Typescript تمرکز کنم. این همچنین امکان بررسی نوع بهتر و تکمیل کد در IDEها را فراهم می‌کند.

Typescript همچنین یک تطابق کامل با پردازنده markdown type-safe جدید ما - Contentlayer است.

Contentlayer

Contentlayer یک SDK محتوا است که محتوای شما را اعتبارسنجی و به داده‌های JSON type-safe تبدیل می‌کند که می‌توانید به راحتی در برنامه خود import کنید. کار با فایل‌های markdown یا MDX محلی را بسیار آسان می‌کند. این جایگزین MDX-bundler و workflow پردازش markdown خودمان می‌شود.

ابتدا، یک منبع محتوا تعریف می‌شود، نام نوع سند، منبعی که در آن قرار دارد به همراه فیلدهای frontmatter و هر فیلد محاسبه شده اضافی که باید به عنوان بخشی از فرآیند تولید شود را مشخص می‌کند.

export const Blog = defineDocumentType(() => ({
  name: 'Blog',
  filePathPattern: 'blog/**/*.mdx',
  contentType: 'mdx',
  fields: {
    title: { type: 'string', required: true },
    date: { type: 'date', required: true },
    tags: { type: 'list', of: { type: 'string' }, default: [] },
    ...
  },
  computedFields: {
    readingTime: { type: 'json', resolve: (doc) => readingTime(doc.body.raw) },
    slug: {
      type: 'string',
      resolve: (doc) => doc._raw.flattenedPath.replace(/^.+?(\/)/, ''),
    }
    ...
  },
}))

Contentlayer سپس فایل‌های MDX را با پلاگین‌های markdown remark یا rehype مورد نظر ما پردازش می‌کند، schema را اعتبارسنجی می‌کند، تعاریف نوع را تولید می‌کند و فایل‌های json را که می‌توانند به راحتی در صفحات ما import شوند، خروجی می‌دهد. Hot reloading به صورت پیش‌فرض موجود است، بنابراین ویرایش‌های فایل‌های markdown بلافاصله در مرورگر منعکس می‌شوند!

Pliny

دلیل بزرگی برای محبوبیت قالب، قابلیت سفارشی‌سازی و یکپارچه‌سازی با سرویس‌های دیگر از ارائه‌دهندگان analytics تا راه‌حل‌های نظرات بود. با این حال، این به معنای این است که کدهای boilerplate زیادی باید در قالب co-located شوند حتی اگر کاربر از ویژگی استفاده نکند. به‌روزرسانی‌ها و رفع اشکال‌ها باید به صورت دستی به کدبیس کاربر کپی شوند.

برای حل این، منطق را به یک مخزن جداگانه - Pliny abstract کرده‌ام. Pliny کامپوننت‌های Next.js آماده برای استفاده را برای بهبود سایت‌های استاتیک ارائه می‌دهد:

• Analytics
  • Google Analytics
  • Plausible Analytics
  • Simple Analytics
  • Umami Analytics
  • Posthog
• Comments
  • Disqus
  • Giscus
  • Utterances
• Newsletter (از Next 13 API Routes استفاده می‌کند)
  • Buttondown
  • Convertkit
  • Email Octopus
  • Klaviyo
  • Mailchimp
  • Revue
• Command palette search با stylesheet tailwind
  • Algolia
  • Kbar (جستجوی محلی)
• کامپوننت‌های utility UI
  • Bleed
  • Newsletter / Blog Newsletter
  • Pre / Code block
  • Table of Contents

سرویس مورد نظر خود را با تغییر siteMetadata.js و تغییر فیلدهای مناسب انتخاب کنید. به عنوان مثال برای تغییر از Umami Analytics به Plausible، می‌توانیم فیلدهای زیر را تغییر دهیم:

analytics: {
-   umamiAnalytics: {
-     // We use an env variable for this site to avoid other users cloning our analytics ID
-     umamiWebsiteId: process.env.NEXT_UMAMI_ID, // e.g. 123e4567-e89b-12d3-a456-426614174000
-   },
+    plausibleAnalytics: {
+      plausibleDataDomain: '', // e.g. tailwind-nextjs-starter-blog.vercel.app
+    },
},

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

در زیر، Pliny کامپوننت‌های سطح بالا مانند <Analytics analyticsConfig={analyticsConfig}/> و <Comments commentsConfig={commentsConfig}/> را export می‌کند که یک شیء پیکربندی را می‌گیرد و کامپوننت مناسب را render می‌کند. از آنجایی که layoutها در سمت سرور تعریف شده‌اند، Next.js می‌تواند از شیء پیکربندی برای تعیین اینکه کدام کامپوننت را render کند استفاده کند و فقط bundle کامپوننت مورد نیاز را به کلاینت ارسال کند.

کامپوننت جستجوی جدید

یک بلاگ در سال 2023 بدون یک نوار جستجوی command palette چیست؟

یکی از ویژگی‌های بسیار درخواست شده اضافه شده است 🎉! کامپوننت جستجو از 2 ارائه‌دهنده جستجو پشتیبانی می‌کند - Algolia و Kbar جستجوی محلی.

Algolia

Algolia Docsearch یک سرویس رایگان محبوب است که در بسیاری از وب‌سایت‌های مستندات استفاده می‌شود. به طور خودکار وب‌سایتی که برای index کردن ارسال شده است را scrape می‌کند و نتیجه جستجو را از طریق یک modal dialog زیبا در دسترس قرار می‌دهد. کامپوننت pliny بسیار از پیاده‌سازی Docusaurus الهام گرفته شده و با یک stylesheet که با تم Tailwind CSS سازگار است، همراه است.

Kbar

Kbar یک رابط cmd+k سریع، قابل حمل و قابل گسترش است. پیاده‌سازی pliny از kbar برای ایجاد یک dialog box جستجوی محلی استفاده می‌کند. کامپوننت یک فایل JSON، به طور پیش‌فرض search.json، که در فرآیند build contentlayer ایجاد شده است را بارگذاری می‌کند. سعی کنید ⌘-k یا ctrl-k را فشار دهید تا نوار جستجو را در عمل ببینید!

به‌روزرسانی‌های استایل و Layout

تم

tailwind.config.js به‌روزرسانی شده است تا از پیش‌فرض‌های typography tailwind در صورت امکان استفاده کند و از پشتیبانی داخلی برای dark mode از طریق کلاس prose-invert استفاده کند. این جایگزین کلاس و پیکربندی قبلی prose-dark می‌شود.

رنگ تم اصلی از teal به pink و تم خاکستری اصلی از neutral به gray به‌روزرسانی شده است.

Inter اکنون با Space Grotesk به عنوان فونت پیش‌فرض جایگزین شده است.

Layoutهای جدید

کامپوننت‌های Layout موجود در پوشه layouts، راهی ساده برای سفارشی‌سازی ظاهر و احساس بلاگ ارائه می‌دهند.[^2]

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

در v2، یک layout پست جدید - PostBanner اضافه کردم. دارای یک تصویر بنر بزرگ و یک کانتینر محتوای مرکزی است. پست بلاگ "Pictures of Canada" را که برای استفاده از layout جدید به‌روزرسانی شده است، بررسی کنید.

layout لیست بلاگ پیش‌فرض نیز به‌روزرسانی شده است تا یک sidebar با تگ‌های بلاگ را شامل شود. نوار جستجو در layout قبلی با command palette search جدید جایگزین شده است. برای بازگشت به layout قدیمی، به سادگی صفحاتی که از کامپوننت ListLayoutWithTags استفاده می‌کنند را به ListLayout اصلی تغییر دهید.

توصیه‌های مهاجرت

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

تغییرات استایل باید نسبتاً جزئی باشند و می‌توانند از tailwind.config.js قدیمی به جدید کپی شوند. اگر کپی می‌کنید، ممکن است نیاز داشته باشید کلاس prose-dark را به کامپوننت‌هایی که به استایل typography tailwind opt-in می‌کنند، اضافه کنید. فونت import را در کامپوننت root layout برای استفاده از فونت مورد نظر تغییر دهید.

تغییرات در pipeline پردازش MDX و schema می‌توانند به راحتی به تنظیمات جدید Contentlayer port شوند. اگر تغییراتی در فیلدهای frontmatter وجود دارد، می‌توانید نوع سند را در contentlayer.config.ts برای شامل کردن فیلدهای جدید تغییر دهید. پلاگین‌های سفارشی می‌توانند به ویژگی‌های remarkPlugins و rehypePlugins در export makeSource از contentlayer.config.ts اضافه شوند.

Layoutهای Markdown دیگر به طور خودکار از پوشه layouts source نمی‌شوند. در عوض، باید در شیء layouts تعریف شده در blog/[...slug]/page.tsx مشخص شوند.[^3]

برای port کردن کامپوننت‌ها یا صفحات بزرگتر، توصیه می‌کنم ابتدا آن را به عنوان یک کامپوننت کلاینت با استفاده از دستور "use client" مشخص کنید. پس از اینکه به درستی render شد، می‌توانید کامپوننت‌های تعاملی (قسمت‌هایی که به hooks use متکی هستند) را به عنوان یک کامپوننت کلاینت تقسیم کنید و کد باقی‌مانده را به عنوان یک کامپوننت سرور نگه دارید. برای جزئیات بیشتر، راهنمای جامع مهاجرت Next.js را مشورت کنید.

نتیجه‌گیری

امیدوارم از ویژگی‌ها و بهبودهای جدید در V2 لذت ببرید. اگر بازخورد یا پیشنهادی دارید، می‌توانید یک issue باز کنید یا با من در Twitter تماس بگیرید.

پشتیبانی

از قالب استفاده می‌کنید؟ این تلاش را با دادن یک star در GitHub، به اشتراک گذاشتن بلاگ خود و shoutout در Twitter یا sponsor پروژه پشتیبانی کنید.

مجوز

MIT © Timothy Lin

[^1]: نسخه قبلی Preact را به build production تزریق می‌کند. با این حال، این دیگر ممکن نیست زیرا از React Server Components پشتیبانی نمی‌کند. در حالی که اندازه bundle کلی به حدود 85kB افزایش یافته است، بیشتر محتوا می‌تواند در سمت سرور pre-render شود، که منجر به first contentful paint و time to interactive پایین می‌شود. استفاده از React در سراسر همچنین منجر به رفتار سازگارتر با کتابخانه‌ها و کامپوننت‌های خارجی می‌شود. [^2]: این با Next.js App Directory layouts متفاوت است و بهتر است به عنوان کانتینرهای React قابل استفاده مجدد فکر شود. [^3]: این از مزایای Server Components با ساده کردن مشخص کردن layout انتخابی در فایل markdown و تطابق با شیء layouts که سپس برای render کامپوننت layout مناسب استفاده می‌شود، استفاده می‌کند.