htmx 4.0.0 با جایگزینی XHR با Fetch API معماری وب را مدرن کرد

اگر وب‌سایت شما بر پایه htmx است، باید بدانید که معماری زیرساختی این ابزار برای اولین بار پس از سال‌ها تغییر بنیادین داده است. این تغییر یعنی پایان دوران وابستگی به استانداردهای قدیمی مرورگر و ورود به عصر برنامه‌نویسی ناهمگام (Async) مدرن.

طبق اعلام تیم توسعه، htmx در نسخه ۴.۰.۰ موتور داخلی خود را از سیستم قدیمی XMLHttpRequest به Fetch API منتقل کرده است. این جابه‌جایی نه تنها کدها را ساده‌تر می‌کند، بلکه استریم کردن HTML را به شکلی بهینه می‌سازد که پیش از این ممکن نبود.

برای سال‌ها، htmx برای حفظ سازگاری با مرورگرهای بسیار قدیمی به XMLHttpRequest متکی بود. اما نیاز به قابلیت‌های پیشرفته‌تر در استریم داده‌ها و همسویی با استانداردهای جدید جاوااسکریپت، تیم را به ۸ ماه تلاش برای بازنویسی کتابخانه واداشت. آن‌ها برای تضمین پایداری، از ابزاری به نام fixi و مجموعه‌ای جامع از تست‌های پیشین استفاده کردند تا مطمئن شوند هیچ‌یک از عملکردهای حیاتی در این انتقال آسیب ندیده‌اند.

زمینه و روند توسعه

ایده‌ی نسخه ۴ زمانی شکل گرفت که توسعه‌دهنده اصلی با ساخت fixi، تسلط بیشتری روی Fetch API و برنامه‌نویسی ناهمگام جاوااسکریپت پیدا کرد. این انتقال پس از پیشنهادهای کریستین تانول درباره استریم HTML تسریع شد؛ او استدلال کرد که انتقال هسته داخلی به Fetch، کتابخانه را برای همه ساده‌تر می‌کند.

در این مسیر، مایکل وست و الکس پتروس نقش کلیدی داشتند. تیم توسعه ابتدا با پورت کردن fixi و مجموعه‌ی تست‌های htmx کار را آغاز کرد. در طول این فرآیند، آن‌ها دوباره دلایل اصلی بسیاری از رفتارهای نسخه ۲ را کشف کردند و در نهایت پیاده‌سازی جدید را به نسخه‌ی قدیمی نزدیک‌تر کردند تا پایداری سیستم تضمین شود. هدف نهایی این است که اپلیکیشن‌های مبتنی بر htmx به عنوان «سرویس‌های وب ۱۰۰ ساله» شناخته شوند.

تصور کنید اپلیکیشن وب شما مجموعه‌ای از قطعات لگو است؛ در نسخه‌های قبلی، برخی قطعات به‌طور خودکار ویژگی‌های پایه را از صفحه پایه به ارث می‌بردند، حتی اگر شما نخواسته بودید. htmx 4 این سیستم را به حالت «دستی» تغییر داده تا از سردرگمی‌های رایج در سلسله‌مراتب پیچیده CSS جلوگیری کند.

تغییر به ارث‌بری صریح

مهم‌ترین تغییر شکست‌دهنده (Breaking Change) در نسخه ۴، جایگزینی ارث‌بری ضمنی با ارث‌بری صریح است. در نسخه ۲، ویژگی‌های تعریف شده در المان‌های والد به‌طور خودکار روی فرزندان اعمال می‌شد. این رفتار که از دوران intercooler.js به ارث رسیده بود و از CSS الهام گرفته شده بود، در سناریوهای پیچیده باعث ایجاد رفتارهای پیش‌بینی‌ناپذیر و دشوار برای درک می‌شد.

اکنون برای فعال کردن این قابلیت، باید پسوند :inherited را به نام ویژگی اضافه کنید. برای مثال، یک اعلان تایید که پیش‌تر با <div hx-confirm="Are you sure?"> کار می‌کرد، اکنون باید به صورت <div hx-confirm:inherited="Are you sure?"> نوشته شود تا روی دکمه‌های فرزند اثر بگذارد.

برای تسهیل این انتقال، تیم htmx یک ابزار ارتقای خط فرمان (CLI) منتشر کرده که قالب‌ها را برای یافتن پسوندهای گم‌شده اسکن می‌کند. همچنین ویژگی‌هایی مانند hx-disinherit دیگر نیازی نیستند و باید از کدها حذف شوند زیرا سیستم ارث‌بری اکنون به‌طور پیش‌فرض غیرفعال است.

استانداردسازی سیستم رویدادها

نام رویدادها اکنون از الگوی سخت‌گیرانه htmx:phase:action[:sub-action] پیروی می‌کنند تا جایگزین نام‌گذاری‌های ارگانیک و اغلب گیج‌کننده نسخه ۲ شوند. تغییرات کلیدی عبارت‌اند از:

• htmx:beforeRequest تبدیل شد به htmx:before:request
• htmx:afterRequest تبدیل شد به htmx:after:request
• htmx:beforeSwap تبدیل شد به htmx:before:swap
• htmx:afterSwap تبدیل شد به htmx:after:swap
• htmx:configRequest تبدیل شد به htmx:config:request

جزئیات رویدادها و حذف‌ها

علاوه بر تغییر نام، معماری رویدادها نیز ساده‌تر و بهینه‌تر شده است:

• مدیریت خطا: اکثر رویدادهای خطا در یک رویداد واحد htmx:error ادغام شدند. پاسخ‌های خطای HTTP به‌طور خاص رویداد htmx:response:error را فعال می‌کنند.
• حذف XHR: تمام رویدادهای htmx:xhr:* به دلیل جایگزینی کامل با Fetch API حذف شدند.
• اعتبارسنجی: رویدادهای htmx:validation:* حذف شده و جای خود را به اعتبارسنجی بومی (Native) فرم‌های مرورگر دادند.

ابزار بررسی ارتقای خط فرمان می‌تواند این نام‌های قدیمی رویدادها را در ویژگی‌های hx-on و فایل‌های جاوااسکریپت شناسایی و علامت‌گذاری کند.

بازنگری در تاریخچه و حافظه پنهان

پشتیبانی از تاریخچه (History) دیگر به‌طور پیش‌فرض از localStorage استفاده نمی‌کند. در نسخه ۲، ذخیره اسنپ‌شات‌های صفحه در حافظه محلی باعث می‌شد وقتی کتابخانه‌های جاوااسکریپت خارجی DOM را تغییر می‌دهند، بازگشت به صفحه قبلی با خطاهای منطقی همراه باشد، زیرا اسنپ‌شات بازیابی شده فاقد منطق زیربنایی آن کتابخانه‌ها بود.

در htmx 4، هنگام بازگشت به عقب، صفحه دوباره فراخوانی (Re-fetch) شده و در بدنه یا المان تعیین شده [hx-history-elt] جایگزین می‌شود. برای کسانی که همچنان به کش محلی نیاز دارند، افزونه hx-history-cache ارائه شده که از sessionStorage استفاده می‌کند و با Alpine.js سازگار است.

قابلیت‌های هسته جدید

دو ویژگی بزرگ در این نسخه معرفی شده‌اند: Morph Swaps و تگ <hx-partial>.

Morph Swaps: جایگزینی‌های مورفینگ اکنون به‌طور پیش‌فرض و بدون نیاز به افزونه پشتیبانی می‌شوند. در حالی که خالق htmx پیش‌تر idiomorph را توسعه داده بود، مایکل وست الگوریتم آن را بهبود بخشید و آن را به‌طور یکپارچه در هسته htmx 4 ادغام کرد تا به‌روزرسانی‌ها بدون از دست دادن فوکوس یا وضعیت (State) المان‌ها رخ دهند.

تگ <hx-partial>: این تگ جایگزینی شفاف و قدرتمند برای Out-of-band swaps در به‌روزرسانی‌های پیچیده است. برای مثال، می‌توانید با استفاده از <hx-partial hx-target="#messages" hx-swap="beforeend"> یک پیام جدید را اضافه کنید و هم‌زمان با یک تگ دیگر مانند <hx-partial hx-target="#count"> شمارنده پیام‌ها را در یک پاسخ واحد به‌روز کنید.

اکوسیستم افزونه‌ها

انتقال به Fetch API موجی از افزونه‌های جدید و بازنویسی شده را به همراه داشت:

• hx-preload: سرعت درخواست‌ها را با پیش‌بارگذاری محتوا (مثلاً هنگام نگه داشتن موس روی لینک) افزایش می‌دهد.
• hx-download: دانلود فایل‌ها را به‌صورت بومی و بر پایه Fetch پیاده می‌کند.
• hx-alpine-compat: اصطکاک و تداخل‌های سازگاری بین htmx و Alpine.js را حل می‌کند.
• hx-history-cache: تاریخچه را در sessionStorage ذخیره کرده و سازگاری با Alpine.js را فراهم می‌کند.
• hx-live: راهکاری جدید برای اسکریپت‌نویسی فرانت‌اند که از Alpine.js، jQuery و hyperscript الهام گرفته است و از «واکنش‌گرایی مبتنی بر DOM و سازگار با HATEOAS» پشتیبانی می‌کند.

برای استریم HTML، سه افزونه تخصصی ارائه شده است:

• hx-sse برای جریان‌های داده روی text/event-stream.
• hx-ws برای ارسال و دریافت استریم روی WebSockets.
• hx-multipart برای استریم‌ها روی multipart/mixed.

برای کسانی که ترجیح می‌دهند از یک فایل واحد استفاده کنند، باندل جدید htmax.js ارائه شده که htmx را به همراه محبوب‌ترین افزونه‌ها بسته‌بندی می‌کند.

مهاجرت و پشتیبانی از LLM

برای جلوگیری از شکستن سایت‌هایی که از URLهای CDN بدون نسخه استفاده می‌کنند، تیم توسعه نسخه ۴.۰ را به عنوان «latest» در NPM علامت‌گذاری نکرده است. نسخه ۲.x تا اوایل سال ۲۰۲۷ پیش‌فرض باقی می‌ماند، در حالی که نسخه ۴.۰ با برچسب «next» عرضه شده است. با این حال، وب‌سایت رسمی htmx اکنون به نسخه ۴ اشاره می‌کند.

تیم توسعه با درک نقش هوش مصنوعی در کدنویسی مدرن، «فایل‌های مهارت» (Skill files) مخصوص هوش مصنوعی زاینده (Generative AI) را منتشر کرده است:

• htmx-guidance: مهارت‌های اصلی برای توسعه با htmx 4.
• htmx-debugging: تشخیص و عیب‌یابی مشکلات در حین توسعه.
• htmx-extension-authoring: نوشتن و دیباگ کردن افزونه‌های htmx 4.
• htmx-upgrade-from-htmx2: مهاجرت کدها از نسخه ۲.x به ۴.x.

توسعه‌دهندگان می‌توانند ابزار ارتقا را با دستور npx [email protected] upgrade-check -- ./templates اجرا کنند. این ابزار از پسوندهای متنوعی از جمله .html ،.php ،.js ،.ts ،.jinja ،.jinja2 ،.j2 ،.erb و .hbs پشتیبانی می‌کند و از طریق فلگ --ext امکان افزودن پسوندهای بیشتر وجود دارد.

نمونه‌های ابزار ارتقا

این ابزار تغییرات بحرانی زیر را شناسایی و گزارش می‌کند:

• تغییر نام ویژگی‌ها: hx-disable به hx-ignore تغییر یافت (زیرا hx-disable اکنون به معنای «غیرفعال کردن در حین درخواست» است).
• حذف ویژگی‌ها: hx-vars حذف و جای خود را به hx-vals با پیشوند :js داد. hx-prompt نیز حذف شده و اکنون نیازمند افزونه hx-prompt است.
• تغییرات API: متد htmx.addClass() حذف شده و توسعه‌دهندگان باید از متد بومی مرورگر یعنی element.classList.add() استفاده کنند.

این چرخش معماری، سیگنالی برای حرکت به سمت «وب‌سرویس‌های ۱۰۰ ساله» است. با حذف رفتارهای ضمنی و تکیه بر APIهای استاندارد مرورگر مانند Fetch، htmx بدهی فنی ناشی از رفتارهای خاص و عجیب کتابخانه را کاهش می‌دهد.

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

برای مشاهده جدول کامل نگاشت رویدادها و جزئیات پیاده‌سازی الگوریتم جدید مورفینگ، مستندات رسمی htmx 4.0.0 را بررسی کنید.

گام بعدی شما

• اگر از htmx 2 استفاده می‌کنید، ابزار upgrade-check را روی قالب‌های خود اجرا کنید تا لیست تغییرات شکست‌دهنده را استخراج کنید.
• برای پیاده‌سازی به‌روزرسانی‌های پیچیده در صفحه، تگ <hx-partial> را جایگزین متدهای قدیمی Swap کنید.
• فایل‌های مهارت htmx 4 را به Context مدل‌های زبانی خود اضافه کنید تا در بازنویسی کدها دچار خطای نسخه‌های قدیمی نشوید.

اما داستان بهینه‌سازی‌های فرانت‌اند به اینجا ختم نمی‌شود؛ برای درک نحوه ترکیب این ابزار با معماری‌های مدرن‌تر، تحلیل ما درباره Alpine.js را بخوانید.