تنزيل next pwa - تنزيل كود مصدر next pwa

البرنامج المساعد Zero Config PWA لـ Next.js

يتم تشغيل هذا البرنامج المساعد بواسطة Workbox والأشياء الجيدة الأخرى.

شارك مشروع PWA الرائع الخاص بك هنا

سمات

0️⃣ صفر تكوين لتسجيل وإنشاء عامل الخدمة
تحسين ذاكرة التخزين المؤقت المسبقة وذاكرة التخزين المؤقت لوقت التشغيل
؟ تعظيم درجة المنارة
؟ من السهل أن نفهم الأمثلة
؟ دعم دون اتصال بالإنترنت تمامًا مع مثال احتياطي؟
؟ استخدم Workbox وworkbox-window v6
؟ العمل مع ملفات تعريف الارتباط خارج الصندوق
طلبات النطاق الافتراضي للصوت والفيديو
☕ لا حاجة لخادم مخصص لمثال Next.js 9+
؟ التعامل مع مثال الاشتراك في أحداث دورة حياة PWA
؟ عامل مخصص لتشغيل تعليمات برمجية إضافية مع تقسيم التعليمات البرمجية ومثال لدعم الآلة الكاتبة
متغيرات البيئة العامة متوفرة في العامل المخصص كالمعتاد
؟ عامل خدمة تصحيح الأخطاء بثقة في وضع التطوير دون التخزين المؤقت
؟ التدويل (المعروف أيضًا باسم I18N) مع المثال next-i18next
؟ يمكن تكوينه بنفس خيارات تكوين مربع العمل لـ GenerateSW وInjectManifest
قم بتدوير GitPod وجرب أمثلة في السرعة الصاروخية
⚡ دعم blitz.js (ما عليك سوى إضافته إلى blitz.config.js )
؟ (تجريبي) التخزين المؤقت المسبق .module.js عندما يكون next.config.js مضبوطًا على experimental.modern على true

الملاحظة 1 - يجب أن يعمل إصدار next-pwa 2.0.0+ فقط مع next.js 9.1+، ويجب أن يتم تقديم الملفات الثابتة فقط من خلال الدليل public . وهذا سيجعل الأمور أسهل.
الملاحظة 2 - إذا واجهت خطأ TypeError: Cannot read property **'javascript' of undefined** أثناء الإنشاء، فيرجى التفكير في الترقية إلى webpack5 في next.config.js .

ثَبَّتَ

إذا كنت جديدًا على next.js أو react.js على الإطلاق، فقد ترغب في الخروج أولاً للتعرف على مستند next.js أو next.js. ثم ابدأ بمثال بسيط أو مثال لتطبيق ويب تقدمي في مستودع next.js.

yarn add next-pwa

الاستخدام الأساسي

الخطوة 1: معPWA

قم بتحديث أو إنشاء next.config.js باستخدام

 const withPWA = require ( 'next-pwa' ) ( {
  dest : 'public'
} )

module . exports = withPWA ( {
  // next.js config
} )

بعد تشغيل next build ، سيؤدي هذا إلى إنشاء ملفين في ملفك public : workbox-*.js و sw.js ، والذي سيتم تقديمه تلقائيًا بشكل ثابت.

إذا كنت تستخدم الإصدار 9 من Next.js أو أحدث، فتخطى الخيارات أدناه وانتقل إلى الخطوة 2.

إذا كنت تستخدم Next.js أقدم من الإصدار 9، فستحتاج إلى تحديد أحد الخيارات أدناه قبل المتابعة إلى الخطوة 2.

الخيار 1: استضافة الملفات الثابتة

انسخ الملفات إلى خادم استضافة الملفات الثابتة الخاص بك، بحيث يمكن الوصول إليها من المسارات التالية: https://yourdomain.com/sw.js و https://yourdomain.com/workbox-*.js .

أحد الأمثلة هو استخدام خدمة استضافة Firebase لاستضافة تلك الملفات بشكل ثابت. يمكنك أتمتة خطوة النسخ باستخدام البرامج النصية في سير عمل النشر الخاص بك.

لأسباب أمنية، يجب عليك استضافة هذه الملفات مباشرة من المجال الخاص بك. إذا تم تسليم المحتوى باستخدام إعادة التوجيه، فسيرفض المتصفح تشغيل عامل الخدمة.

الخيار 2: استخدام الخادم المخصص

عند تلقي طلب HTTP، اختبر ما إذا كانت هذه الملفات مطلوبة، ثم قم بإرجاع تلك الملفات الثابتة.

مثال server.js

 const { createServer } = require ( 'http' )
const { join } = require ( 'path' )
const { parse } = require ( 'url' )
const next = require ( 'next' )

const app = next ( { dev : process . env . NODE_ENV !== 'production' } )
const handle = app . getRequestHandler ( )

app . prepare ( ) . then ( ( ) => {
  createServer ( ( req , res ) => {
    const parsedUrl = parse ( req . url , true )
    const { pathname } = parsedUrl

    if ( pathname === '/sw.js' || / ^/(workbox|worker|fallback)-w+.js$ / . test ( pathname ) ) {
      const filePath = join ( __dirname , '.next' , pathname )
      app . serveStatic ( req , res , filePath )
    } else {
      handle ( req , res , parsedUrl )
    }
  } ) . listen ( 3000 , ( ) => {
    console . log ( `> Ready on http://localhost: ${ 3000 } ` )
  } )
} )

الإعداد التالي ليس له علاقة بالمكون الإضافي next-pwa ، ومن المحتمل أنك قمت بإعداده بالفعل. إذا لم يكن الأمر كذلك، فاستمر في إعدادها.

الخطوة 2: إضافة ملف البيان (مثال)

قم بإنشاء ملف manifest.json في مجلدك public :

{
  "name" : " PWA App " ,
  "short_name" : " App " ,
  "icons" : [
    {
      "src" : " /icons/android-chrome-192x192.png " ,
      "sizes" : " 192x192 " ,
      "type" : " image/png " ,
      "purpose" : " any maskable "
    },
    {
      "src" : " /icons/android-chrome-384x384.png " ,
      "sizes" : " 384x384 " ,
      "type" : " image/png "
    },
    {
      "src" : " /icons/icon-512x512.png " ,
      "sizes" : " 512x512 " ,
      "type" : " image/png "
    }
  ],
  "theme_color" : " #FFFFFF " ,
  "background_color" : " #FFFFFF " ,
  "start_url" : " / " ,
  "display" : " standalone " ,
  "orientation" : " portrait "
}

الخطوة 3: إضافة التعريف الرئيسي (مثال)

أضف ما يلي إلى _document.jsx أو _app.tsx ، في :

 < meta name =" application-name " content =" PWA App " />
< meta name =" apple-mobile-web-app-capable " content =" yes " />
< meta name =" apple-mobile-web-app-status-bar-style " content =" default " />
< meta name =" apple-mobile-web-app-title " content =" PWA App " />
< meta name =" description " content =" Best PWA App in the world " />
< meta name =" format-detection " content =" telephone=no " />
< meta name =" mobile-web-app-capable " content =" yes " />
< meta name =" msapplication-config " content =" /icons/browserconfig.xml " />
< meta name =" msapplication-TileColor " content =" #2B5797 " />
< meta name =" msapplication-tap-highlight " content =" no " />
< meta name =" theme-color " content =" #000000 " />

< link rel =" apple-touch-icon " href =" /icons/touch-icon-iphone.png " />
< link rel =" apple-touch-icon " sizes =" 152x152 " href =" /icons/touch-icon-ipad.png " />
< link rel =" apple-touch-icon " sizes =" 180x180 " href =" /icons/touch-icon-iphone-retina.png " />
< link rel =" apple-touch-icon " sizes =" 167x167 " href =" /icons/touch-icon-ipad-retina.png " />

< link rel =" icon " type =" image/png " sizes =" 32x32 " href =" /icons/favicon-32x32.png " />
< link rel =" icon " type =" image/png " sizes =" 16x16 " href =" /icons/favicon-16x16.png " />
< link rel =" manifest " href =" /manifest.json " />
< link rel =" mask-icon " href =" /icons/safari-pinned-tab.svg " color =" #5bbad5 " />
< link rel =" shortcut icon " href =" /favicon.ico " />
< link rel =" stylesheet " href =" https://fonts.googleapis.com/css?family=Roboto:300,400,500 " />

< meta name =" twitter:card " content =" summary " />
< meta name =" twitter:url " content =" https://yourdomain.com " />
< meta name =" twitter:title " content =" PWA App " />
< meta name =" twitter:description " content =" Best PWA App in the world " />
< meta name =" twitter:image " content =" https://yourdomain.com/icons/android-chrome-192x192.png " />
< meta name =" twitter:creator " content =" @DavidWShadow " />
< meta property =" og:type " content =" website " />
< meta property =" og:title " content =" PWA App " />
< meta property =" og:description " content =" Best PWA App in the world " />
< meta property =" og:site_name " content =" PWA App " />
< meta property =" og:url " content =" https://yourdomain.com " />
< meta property =" og:image " content =" https://yourdomain.com/icons/apple-touch-icon.png " />

نصيحة: ضع العلامة الوصفية لرأس viewport في _app.js بدلاً من _document.js إذا كنت في حاجة إليها.

 < meta
  name = 'viewport'
  content = 'minimum-scale=1, initial-scale=1, width=device-width, shrink-to-fit=no, user-scalable=no, viewport-fit=cover'
/ >

التراجعات دون اتصال

تكون العمليات الاحتياطية دون اتصال مفيدة عندما تفشل عملية الجلب من ذاكرة التخزين المؤقت والشبكة، ويتم تقديم مورد تم تخزينه مؤقتًا مسبقًا بدلاً من تقديم خطأ من المتصفح.

للبدء، ما عليك سوى إضافة صفحة /_offline مثل pages/_offline.js أو pages/_offline.jsx أو pages/_offline.ts أو pages/_offline.tsx . إذن أنت جاهز تمامًا! عندما يكون المستخدم غير متصل بالإنترنت، ستعود كافة الصفحات التي لم يتم تخزينها مؤقتًا إلى "/_offline".

استخدم هذا المثال لرؤيته في العمل

يساعدك next-pwa على تخزين تلك الموارد مؤقتًا عند التحميل الأول، ثم إدخال معالج احتياطي إلى المكون الإضافي handlerDidError في جميع تكوينات runtimeCaching ، بحيث يتم تقديم الموارد المخزنة مؤقتًا عند فشل الجلب.

يمكنك أيضًا إعداد precacheFallback.fallbackURL في إدخال تكوين runtimeCaching الخاص بك لتنفيذ وظائف مماثلة. الفرق هو أن الطريقة المذكورة أعلاه تعتمد على نوع المورد، وتعتمد هذه الطريقة على نمط عنوان URL المطابق. إذا تم تعيين هذا التكوين في إدخال تكوين runtimeCaching، فسيتم تعطيل الإجراء الاحتياطي المستند إلى نوع المورد تلقائيًا لنمط عنوان URL هذا لتجنب التعارض.

إعدادات

هناك خيارات يمكنك استخدامها لتخصيص سلوك هذه الإضافة عن طريق إضافة كائن pwa في التكوين التالي في next.config.js :

 const withPWA = require ( 'next-pwa' ) ( {
  dest : 'public'
  // disable: process.env.NODE_ENV === 'development',
  // register: true,
  // scope: '/app',
  // sw: 'service-worker.js',
  //...
} )

module . exports = withPWA ( {
  // next.js config
} )

الخيارات المتاحة

تعطيل: منطقي - ما إذا كان سيتم تعطيل ميزة pwa ككل
- الافتراضي: false
- قم بتعيين disable: false ، بحيث يتم إنشاء عامل الخدمة في كل من dev و prod
- ضبط disable: true لتعطيل PWA تمامًا
- إذا لم تكن بحاجة إلى تصحيح أخطاء عامل الخدمة في dev ، فيمكنك تعيين disable: process.env.NODE_ENV === 'development'
التسجيل: منطقي - ما إذا كنت تريد السماح لهذا البرنامج المساعد بتسجيل عامل الخدمة نيابةً عنك
- الافتراضي إلى true
- اضبط على false عندما تريد التعامل مع عامل خدمة التسجيل بنفسك، ويمكن القيام بذلك في componentDidMount لتطبيقك الجذر. يمكنك اعتبار السجل.js كمثال.
النطاق: سلسلة - نطاق عنوان url لـ pwa
- الافتراضي: basePath في next.config.js أو /
- اضبط على /app بحيث يكون المسار الموجود ضمن /app هو PWA بينما لا يكون الآخرون كذلك
sw: سلسلة - اسم ملف البرنامج النصي لعامل الخدمة
- الافتراضي: /sw.js
- اضبط على اسم ملف آخر إذا كنت تريد تخصيص اسم ملف الإخراج
runtimeCaching - استراتيجيات التخزين المؤقت (صفيف أو وظيفة رد الاتصال)
- الافتراضي: راجع قسم التخزين المؤقت لوقت التشغيل للتعرف على التكوين الافتراضي
- يقبل مجموعة من كائنات إدخال ذاكرة التخزين المؤقت، يرجى اتباع البنية هنا
- ملاحظة: ترتيب المصفوفة مهم. القاعدة الأولى التي تطابق فعالة. لذلك، يرجى دائمًا وضع القواعد ذات النطاق الأكبر خلف القواعد ذات النطاق الأصغر والمحدد.
publicExcludes - مصفوفة من سلاسل الأنماط الشاملة لاستبعاد الملفات الموجودة في المجلد public من التخزين المؤقت مسبقًا.
- الافتراضي: ['!noprecache/**/*'] - هذا يعني أن السلوك الافتراضي سيقوم بتخزين جميع الملفات الموجودة داخل المجلد public مؤقتًا مسبقًا باستثناء الملفات الموجودة داخل المجلد /public/noprecache . يمكنك ببساطة وضع الملفات داخل هذا المجلد حتى لا يتم تخزينها مؤقتًا دون تكوين هذا.
- مثال: ['!img/super-large-image.jpg', '!fonts/not-used-fonts.otf']
buildExcludes - مصفوفة من الأنماط أو الوظائف الإضافية لاستبعاد الملفات من التخزين المؤقت مسبقًا في مجلد .next/static (أو الإصدار المخصص الخاص بك)
- تقصير: []
- مثال: [/chunks/images/.*$/] - لا تقم بتخزين الملفات مؤقتًا مسبقًا ضمن .next/static/chunks/images (نوصي بشدة بهذا للعمل مع البرنامج الإضافي next-optimized-images )
- مستند: صفيف (سلسلة أو RegExp أو وظيفة ()). يتم استخدام محدد واحد أو أكثر لاستبعاد الأصول من بيان التخزين المؤقت المسبق. يتم تفسير ذلك باتباع نفس القواعد المتبعة في خيار الاستبعاد القياسي لـ Webpack.
CacheStartUrl - ما إذا كان سيتم تخزين عنوان URL للبدء مؤقتًا أم لا
- الافتراضي: true
- مناقشة حالة الاستخدام لعدم تخزين عنوان URL للبدء مؤقتًا على الإطلاق
DynamicStartUrl - إذا كان عنوان url الخاص بك يعرض مستند HTML مختلفًا في حالة مختلفة (مثل تسجيل الدخول مقابل عدم تسجيل الدخول)، فيجب ضبط هذا على true.
- الافتراضي: true
- يصبح فعالاً عند ضبط cacheStartUrl على true
- نوصي: اضبط على "خطأ" إذا كان عنوان url الخاص بك يعرض دائمًا نفس مستند HTML، فسيتم تخزين عنوان url للبدء مسبقًا، مما سيساعد على تسريع التحميل الأول.
DynamicStartUrlRedirect - إذا كان عنوان URL للبدء الخاص بك يعيد التوجيه إلى مسار آخر مثل /login ، فمن المستحسن إعداد عنوان URL المعاد توجيهه هذا للحصول على أفضل تجربة للمستخدم.
- الافتراضي: undefined
- يصبح فعالاً عند ضبط dynamicStartUrlRedirect على true
الاحتياطيات - تكوين المسارات المخزنة مؤقتًا للرجوع عندما لا يكون كل من ذاكرة التخزين المؤقت والشبكة متاحين لخدمة الموارد.
- إذا كنت تحتاج فقط إلى صفحة احتياطية دون اتصال بالإنترنت، فما عليك سوى إنشاء صفحة /_offline مثل pages/_offline.js وستكون جاهزًا تمامًا، دون الحاجة إلى أي تكوين
- الافتراضي: object
  - fallbacks.document - المسار الاحتياطي للمستند (الصفحة)، الافتراضي هو /_offline إذا قمت بإنشاء تلك الصفحة
  - fallbacks.image - المسار الاحتياطي للصورة، الافتراضي هو لا شيء
  - fallbacks.audio - المسار الاحتياطي للصوت، الافتراضي هو لا شيء
  - fallbacks.video - المسار الاحتياطي للفيديو، الافتراضي هو لا شيء
  - fallbacks.font - المسار الاحتياطي للخط، الافتراضي هو لا شيء
CacheOnFrontEndNav - تمكين ذاكرة التخزين المؤقت الإضافية للمسار عند التنقل بين الصفحات التي تحتوي على next/link في الواجهة الأمامية. تحقق من هذا المثال للحصول على بعض السياق حول سبب تنفيذ ذلك.
- الافتراضي: false
- ملاحظة: يعمل هذا على تحسين تجربة المستخدم في حالات الاستخدام الخاصة ولكنه يضيف أيضًا بعض الحمل بسبب مكالمات الشبكة الإضافية، أقترح عليك اعتبار ذلك بمثابة مقايضة.
~~subdomainPrefix: سلسلة - بادئة عنوان url للسماح باستضافة ملفات ثابتة على نطاق فرعي~~
- ~~الافتراضي: "" - أي افتراضي بدون بادئة~~
- ~~مثال: /subdomain إذا كان التطبيق مستضافًا على example.com/subdomain~~
- مهمل، استخدم basePath بدلاً من ذلك
reloadOnOnline - يغير سلوك التطبيق عندما يكتشف الجهاز أنه قد عاد إلى "الاتصال بالإنترنت" ولديه اتصال بالشبكة. حدد ما إذا كان يجب على التطبيق استدعاء location.reload() لتحديث التطبيق.
- الافتراضي: true
customWorkerDir - قم بتخصيص الدليل حيث يبحث next-pwa عن تطبيق عامل مخصص لإضافته إلى عامل الخدمة الذي تم إنشاؤه بواسطة Workbox. لمزيد من المعلومات، راجع مثال العامل المخصص.
- الافتراضي: worker

خيارات أخرى

يستخدم next-pwa workbox-webpack-plugin ، ويمكن العثور على خيارات أخرى يمكن وضعها أيضًا في كائن pwa في المستندات الخاصة بـ GenerateSW وInjectManifest. إذا قمت بتحديد swSrc ، فسيتم استخدام البرنامج المساعد InjectManifest ، وإلا فسيتم استخدام GenerateSW لإنشاء عامل الخدمة.

التخزين المؤقت لوقت التشغيل

يستخدم next-pwa ملف ذاكرة التخزين المؤقت الافتراضي لوقت التشغيل.js

هناك احتمال كبير أنك قد ترغب في تخصيص قواعد التخزين المؤقت الخاصة بوقت التشغيل. لا تتردد في نسخ ملف cache.js الافتراضي وتخصيص القواعد كما تريد. لا تنس إدخال التكوينات في تكوين pwa الخاص بك في next.config.js .

فيما يلي المستند الخاص بكيفية كتابة تكوينات التخزين المؤقت لوقت التشغيل، بما في ذلك مزامنة الخلفية وميزات تحديث البث والمزيد!

نصائح

نمط UX شائع لمطالبة المستخدم بإعادة التحميل عند تثبيت عامل الخدمة الجديد
استخدم اصطلاحًا مثل {command: 'doSomething', message: ''} كائن عند postMessage إلى عامل الخدمة. بحيث يمكن للمستمع القيام بمهام مختلفة متعددة باستخدام if...else... .
عندما تقوم بتصحيح أخطاء عامل الخدمة، clean application cache باستمرار لتقليل بعض الأخطاء غير المستقرة.
إذا كنت تقوم بإعادة توجيه المستخدم إلى مسار آخر، فيرجى ملاحظة أن صندوق العمل بشكل افتراضي فقط يستجيب لذاكرة التخزين المؤقت بحالة HTTP 200، إذا كنت تريد حقًا تخزين الصفحة المعاد توجيهها مؤقتًا للمسار، فيمكنك تحديدها في runtimeCaching مثل options.cacheableResponse.statuses=[200,302] .
عند تصحيح الأخطاء، قد ترغب في تنسيق ملف sw.js الذي تم إنشاؤه لمعرفة ما يحدث بالفعل.
قم بإجبار next-pwa على إنشاء بناء إنتاج صندوق العامل عن طريق تحديد mode: 'production' في قسم pwa الخاص بك في next.config.js . على الرغم من أن next-pwa يقوم تلقائيًا بإنشاء بناء تطوير صندوق العامل أثناء التطوير (عن طريق تشغيل next ) وبناء إنتاج صندوق العامل أثناء الإنتاج (عن طريق تشغيل next build و next start ). قد لا تزال ترغب في إجباره على إنشاء الإنتاج حتى أثناء تطوير تطبيق الويب الخاص بك للسبب التالي:
1. تقليل ضوضاء التسجيل بسبب بناء الإنتاج لا يشمل التسجيل.
2. تحسين الأداء قليلاً بسبب تحسين بناء الإنتاج وتصغيره.
إذا كنت تريد فقط تعطيل تسجيل مربع العامل مع الحفاظ على بناء التطوير أثناء التطوير، فما عليك سوى وضع self.__WB_DISABLE_DEV_LOGS = true في worker/index.js الخاص بك (قم بإنشاء واحد إذا لم يكن لديك واحد).
من الشائع أن يستخدم المطورون سلسلة userAgent لتحديد ما إذا كان المستخدمون يستخدمون Safari/iOS/MacOS أو أي نظام أساسي آخر، وتعد مكتبة ua-parser-js صديقًا جيدًا لهذا الغرض.