Next.js/middleware

الأدوات الوسطية في Next.js

تُمكِّنك الأدوات الوسيطة MiddleWare من استخدام الشيفرة لتعديل الإعدادات، وهذا ما يمنحك مرونة كاملة في Next.js نظرًا للقدرة على تنفيذ الشيفرة قبل أن يكتمل الطلب.

النسخة	التغييرات
12.0.9	إلزامية استخدام عناوين المطلقة أثناء تشغيل التطبيق بالاستفادة من الحوسبة الحدية Edge
12.0.0	دعم الأدوات الوسطية (تجريبيًا)

وفقًا للطلب الذي يرسله المستخدم، ستتمكن من تعديل الاستجابة من خلال إعادة كتابة أو إعادة التوجيه أو إضافة الترويسات أو حتى بالتصيير الآني لمحتوى HTML.

استخدامات الأدوات الوسطية في Next.js

• ثبّت النسخة الحدث من Next.js:

npm install next@latest

• أنشئ الملف middleware.ts_ ضمن المجلد pages/.
• صدِّر أخيرًا دالة الأداة الوسطية من الملف middleware.ts_.

// pages/_middleware.ts

import type { NextFetchEvent, NextRequest } from 'next/server'

export function middleware(req: NextRequest, ev: NextFetchEvent) {
  return new Response('Hello, world!')
}

تنويه: استخدمنا في هذا المثال واجهة ويب البرمجية المعيارية للاستجابة Web API Response.

الواجهة البرمجية

تتشكل الأدوات الوسطية من خلال الدالة الموجودة في الملف، وتعتمد واجهتها البرمجية على الكائنات الأصلية التالية: FetchEvent و Response و Request. وقد وُسِّعت هذه الكائنات لتعطيك تحكمًا أفضل بطريقة التعامل مع الاستجابة وتهيئتها وفقًا للطلب الوارد من المستخدم.

ستكون بصمة الدالة كالتالي:

import type { NextFetchEvent } from 'next/server'
import type { NextRequest } from 'next/server'

export type Middleware = (
  request: NextRequest,
  event: NextFetchEvent
) => Promise<Response | undefined> | Response | undefined

بإمكانك تصدير الدالة افتراضيًا ولا حاجة لتسميتها middleware، مع أن ذلك أمر تقليدي. ولا حاجة أيضًا أن تكون الدالة غير متزامنة async إلا إن أردتها أن تنفِّذ شيفرة غير متزامنة.

لمعلومات أكثر، اطلع على توثيق الواجهة البرمجية للأداة الوسطية في Next.js.

أمثلة عن حالات استخدام Next.js

تُستخدم الأداة الوسطية غالبًا في الحالات التي تشترك فيها مجموعة من الصفحات في منطق برمجي معين مثل:

• الاستيثاق.
• الحماية من الشيفرات الآلية.
• إعادة التوجيه والكتابة.
• التعامل مع المتصفحات غير المدعومة.
• الرايات المستقبلية والاختبارات ثنائية الخيار A/B tests.
• متطلبات التوجه المتقد من خلال i18n.

بإمكانك الاطلاع على أمثلة عن حالات الاستخدام السابقة على GitHub

ترتيب التنفيذ

إن أنشأت الأداة الوسطية في المجلد pages/_middleware.ts/، ستُنفَّذ مع جميع الوجهات الموجودة في هذا المجلد. يفترض المثال التالي وجود وجهتين هما about.tsx و teams.tsx:

- package.json
- /pages
    _middleware.ts # pages ستُنفَّذ كل الوجهات في المجلد 
    index.tsx
    about.tsx
    teams.tsx

إن وجدت مجلدات فرعية متداخله مع الوجهات، فستُنفَّذ الأداة الوسطية من الأعلى للأسفل. لنفترض مثلًا وجود الأداتين /pages/about/_middleware.ts و /pages/about/team/_middleware.ts، فستُنفّذ الأدلة الموجودة في /about أولًا. يظهر المثال التالي تنفيذ الأداة الوسطية في الوجهات المتداخلة:

- package.json
- /pages
    index.tsx
    - /about
      _middleware.ts # تُنفّذ أولًا
      about.tsx
      - /teams
        _middleware.ts # تُنفَّذ ثانيًا
        teams.tsx

تُنفّذ الأداة الوسطية مباشرة بعد التوجيهات redirects والترويسات headers وقبل أول عملية بحث لنظام الملفات. يستثني ذلك ملفات المجلد next_/.

نشر التطبيقات التي تضم أدوات وسطية

تستخدم الأدوات الوسطية بيئة تشغيل مقيّدة تدعم واجهات ويب البرمجية المعيارية مثل fetch. يعمل ذلك جيدًا مع next start وعلى منصات الحوسبة الحدية مثل Vercel الذي يستخدم الدوال الحدية Edge Functions.

المصادر

• الصفحة middleware(beta) من توثيق Next.js الرسمي.

اقرأ أيضًا

• الواجهة البرمجية التي تُستخدمها الأداة الوسطية.
• واجهات ويب البرمجية التي تدعم بيئة التشغيل الحدية.
• قياس الأداء في تطبيقات Next.js.