preact cli

preact-cli

تحذير

preact-cli للأسف لم يعد يرى التطور النشط! إنه مستقر حتى تتمكن من الاعتماد عليه لجميع تطبيقاتك الحالية ، ولكن لإنشاء تطبيقات جديدة ، نوصي Vite عبر create-preact . إنه يوفر العديد من الميزات نفسها ولكنه تجربة أسرع وأكثر حداثة. شكرا لجميع المساهمين والمستخدمين على مر السنين!

ابدأ في بناء تطبيق ويب تقدمي Preact بالثواني

محتويات

• سمات
• الاستخدام
• القوالب الرسمية
• خيارات CLI
  • PREACT خلق
  • بناء preact
  • ساعة Preact
  • قائمة preact
  • معلومات prect
• ما قبل الإعادة
• التكوين المخصص
  • الإضافات
  • قائمة المتصفح
  • بابل
  • WebPack
  • مسارات متعددة مسببة
  • نموذج
• باستخدام المعالجات المسبقة CSS
  • ساس
  • أقل
• باستخدام متغيرات البيئة
• تقسيم الكود القائم على المسار

سمات

• 100/100 منارة ، مباشرة خارج الصندوق (دليل)
• تقسيم التعليمات البرمجية التلقائي بالكامل للمسارات (انظر تقسيم الكود المستند إلى الطريق)
• رمز الشفافية تقسيم أي مكون مع async! بادئة
• عمال الخدمات التي تم إنشاؤها تلقائيًا للتخزين المؤقت للإنترنت مدعومًا بواسطة Workbox
• دعم نمط PRPL للتحميل الفعال
• تكوين الصفر ما قبل التقديم / الجهة المعرض من جانب الخادم
• دعم وحدات CSS ، أقل ، ساس ، القلم ؛ مع Autoprefixer
• راقب أحجام الحزمة/القطع الخاصة بك مع تتبع مدمج
• تصاعد التطبيق التلقائي ، مساعدي تصحيح الأخطاء واستبدال الوحدة الساخنة
• في 4.5 كيلو بايت فقط ، تحصل على بيئة مثمرة:
  • preact
  • preact-router
  • 1.5 كيلو بايت من البوليفيل المحملة بشرط لجلب ووعد

متطلبات

مهم : node.js> = v14.14 مطلوب.

الاستخدام

$ npm init preact-cli < template-name > < project-name >

$ yarn create preact-cli < template-name > < project-name >

مثال:

$ npm init preact-cli default my-project

يسحب الأمر أعلاه القالب من preactjs-templates/الافتراضي وينشئ المشروع على ./my-project/ .

القوالب الرسمية

الغرض من قوالب مشروع PREACT الرسمية هو توفير إعدادات أدوات التطوير المتقنة حتى يتمكن المستخدمون من البدء برمز التطبيق الفعلي بأسرع وقت ممكن. ومع ذلك ، فإن هذه القوالب غير متوفرة من حيث كيفية تنظيم رمز التطبيق الخاص بك والمكتبات التي تستخدمها بالإضافة إلى preact.js.

جميع قوالب المشروع الرسمية هي repos في منظمة preactjs-templates. عند إضافة قالب جديد إلى المؤسسة ، ستتمكن من تشغيل npm init preact-cli <template-name> <project-name> لاستخدام هذا القالب.

تشمل القوالب الحالية المتاحة:

• الافتراضي - قالب افتراضي مع جميع الميزات

• بسيط - أبسط إعداد preact ممكن في ملف واحد

• NetLify - قالب NetLify CMS باستخدام Preact

• TypeScript - القالب الافتراضي المنفذ في TypeScript

• عنصر واجهة مستخدم - قالب ليتم تضمين عنصر واجهة مستخدم في موقع ويب آخر

• نوع القطعة - قالب واجهة مستخدم يتم تنفيذه في TypeScript

؟ نصيحة: يمكن استخدام أي repo github مع مجلد 'template' كقالب مخصص:
npm init preact-cli <username>/<repository> <project-name>

خيارات CLI

قائمة preact

يسرد جميع مستودعات preactjs-cli الرسمية

$ [npm init / yarn create] preact-cli list

PREACT خلق

قم بإنشاء مشروع لبدء تطوير سريع.

 $ [npm init / yarn create] preact-cli <template-name> <project-name>

  --name        The application name.
  --cwd         A directory to use instead of $PWD.
  --force       Force option to create the directory for the new app  [boolean] [default: false]
  --git         Initialize version control using git.                 [boolean] [default: false]
  --install     Installs dependencies.                                [boolean] [default: true]

بناء preact

إنشاء بناء إنتاج

يمكنك تعطيل default: true عن طريق البادئة بها --no-<option> ؛ على سبيل المثال ، --no-sw و --no-prerender .

 $ [npm run / yarn] preact build

    --src              Specify source directory  (default src)
    --dest             Specify output directory  (default build)
    --cwd              A directory to use instead of $PWD  (default .)
    --sw               Generate and attach a Service Worker  (default true)
    --babelConfig      Path to custom Babel config (default .babelrc)
    --prerender        Renders route(s) into generated static HTML  (default true)
    --prerenderUrls    Path to pre-rendered routes config  (default prerender-urls.json)
    --template         Path to custom EJS or HTML template  (default 'src/template.ejs')
    --analyze          Launch interactive Analyzer to inspect production bundle(s) (default false)
    -c, --config       Path to custom CLI config  (default preact.config.js)
    -v, --verbose      Verbose output
    -h, --help         Displays this message

ساعة Preact

قم بتدوير خادم تطوير بميزات متعددة مثل hot-module-replacement ، module-watcher

 $ [npm run / yarn] preact watch

    --src              Specify source directory  (default src)
    --cwd              A directory to use instead of $PWD  (default .)
    --clear            Clear the console (default true)
    --sw               Generate and attach a Service Worker  (default false)
    --babelConfig      Path to custom Babel config (default .babelrc)
    --https            Run server with HTTPS protocol
    --key              Path to PEM key for custom SSL certificate
    --cert             Path to custom SSL certificate
    --cacert           Path to optional CA certificate override
    --prerender        Pre-render static content on first run
    --prerenderUrls    Path to pre-rendered routes config  (default prerender-urls.json)
    --template         Path to custom EJS or HTML template  (default 'src/template.ejs')
    --refresh          Enables experimental preact-refresh functionality
    -c, --config       Path to custom CLI config  (default preact.config.js)
    -H, --host         Set server hostname  (default 0.0.0.0)
    -p, --port         Set server port  (default 8080)
    -h, --help         Displays this message

ملحوظة:

1. يمكنك تشغيل خادم DEV باستخدام HTTPS ثم يمكنك استخدام HTTPS=true preact watch
2. يمكنك تشغيل خادم DEV على منفذ مختلف باستخدام PORT=8091 preact watch

معلومات prect

يطبع معلومات تصحيح الأخطاء المتعلقة بالبيئة المحلية.

$ [npm run / yarn] preact info

ما قبل الإعادة

PREACT CLI من أجل اتباع نمط PRPL يعرض المسار الأولي ( / ) في فهرس ثابت تم إنشاؤه index.html - وهذا يضمن أن المستخدمين يتمكنون من رؤية صفحتك قبل تشغيل أي JavaScript ، وبالتالي تزويد المستخدمين بأجهزة بطيئة أو اتصال ضعيف محتوى موقع الويب الخاص بك بشكل أسرع.

يقوم Preact CLI بذلك عن طريق تقديم تطبيقك داخل العقدة - وهذا يعني أنه ليس لدينا إمكانية الوصول إلى DOM أو المتغيرات العالمية الأخرى المتوفرة في المتصفحات ، مماثلة لكيفية وجودها في سيناريوهات تقديم من جانب الخادم. في حال احتجت إلى الاعتماد على واجهات برمجة التطبيقات للمتصفح ، يمكنك:

• تسرب من التمرير عن طريق المرور --no-prerender إلى preact build ،
• اكتب التعليمات البرمجية الخاصة بك بطريقة تدعم تقديم جانب الخادم عن طريق لف الرمز الذي يتطلب واجهات برمجة تطبيقات المتصفح في العبارات الشرطية if (typeof window !== "undefined") { ... } أنه لا يتم الوصول إلى خطوط الرمز على الخادم. بدلاً من ذلك ، يمكنك استخدام مكتبة المساعد مثل النافذة أو العلم.

التكوين المخصص

الإضافات

لجعل تخصيص التكوين الخاص بك أسهل ، يدعم Preact-Cli المكونات الإضافية. قم بزيارة المكونات الإضافية Wiki للحصول على برنامج تعليمي حول كيفية استخدامها.

قائمة المتصفح

يمكنك تخصيص قائمة إصدارات المتصفح المدعومة من خلال الإعلان عن مفتاح "browserslist" داخل package.json الخاصة بك. سيؤدي تغيير هذه القيم إلى تعديل إرث JavaScript (عبر @babel/preset-env ) وإخراج CSS (عبر autoprefixer ).

بشكل افتراضي ، يحاكي preact-cli التكوين التالي:

package.json

{
	"browserslist" : [ " > 0.5% " , " last 2 versions " , " Firefox ESR " , " not dead " ]
}

بابل

لتخصيص بابل ، لديك خياران:

1. يمكنك إنشاء ملف .babelrc في دليل الجذر لمشروعك ، أو استخدام مسار --babelConfig إلى أي ملف تكوين بابل صالح. سيتم دمج أي إعدادات تحددها هنا في Preact CLI Preset. على سبيل المثال ، إذا قمت بتمرير كائن "plugins" يحتوي على مكونات إضافية مختلفة من تلك المستخدمة بالفعل ، فسيتم إضافتها ببساطة فوق التكوين الموجود. إذا كانت هناك تعارضات ، فستحتاج إلى النظر في الخيار 2 ، حيث أن الافتراضي سوف يكون له الأسبقية.

2. إذا كنت ترغب في تعديل تكوين بابل الحالي ، فيجب عليك استخدام ملف preact.config.js . قم بزيارة قسم WebPack لمزيد من المعلومات ، أو تحقق من مثال Babel التخصيص!

WebPack

لتخصيص تكوين WebPack الخاص بـ Preact-Cli ، قم بإنشاء ملف preact.config.js أو ملف preact.config.json :

preact.config.js

 // ... imports or other code up here ...

/**
 * Function that mutates the original webpack config.
 * Supports asynchronous changes when a promise is returned (or it's an async function).
 *
 * @param {import('preact-cli').Config} config - original webpack config
 * @param {import('preact-cli').Env} env - current environment and options pass to the CLI
 * @param {import('preact-cli').Helpers} helpers - object with useful helpers for working with the webpack config
 * @param {Record<string, unknown>} options - this is mainly relevant for plugins (will always be empty in the config), default to an empty object
 */
export default ( config , env , helpers , options ) => {
	/** you can change the config here **/
} ;

راجع WebPack Config Pownspers Wiki لمزيد من المعلومات حول وسيطة helpers التي تحتوي على طرق للعثور على أجزاء مختلفة من التكوين. بالإضافة إلى ذلك ، راجع وصفاتنا التي تحتوي على أمثلة حول كيفية تغيير تكوين حزمة الويب.

مسارات متعددة مسببة

سوف --prerender -العلم قبل أن يكون افتراضيًا فقط جذر التطبيق الخاص بك. إذا كنت ترغب في تأجيل الطرق الأخرى ، فيمكنك إنشاء ملف prerender-urls.json ، والذي يحتوي على مجموعة من الطرق التي تريد تقديمها. التنسيق المطلوب لتحديد مساراتك هو مجموعة من الكائنات مع مفتاح url ومفتاح title اختياري.

prerender-urls.json

[
	{
		"url" : " / " ,
		"title" : " Homepage "
	},
	{
		"url" : " /route/random "
	}
]

يمكنك تخصيص مسار و/أو اسم prerender-urls.json باستخدام العلم- --prerenderUrls .

preact build --prerenderUrls src/prerender-urls.json

إذا كان ملف JSON ثابتًا مقيدًا جدًا ، فقد ترغب في توفير ملف JavaScript يقوم بتصدير طرقك بدلاً من ذلك. يمكن تصدير الطرق كسلسلة JSON أو كائن ويمكن إرجاعها اختياريًا من وظيفة.

prerender-urls.js

 module . exports = [
	{
		url : '/' ,
		title : 'Homepage' ,
	} ,
	{
		url : '/route/random' ,
	} ,
] ;

prerender-urls.js

 export default ( ) => {
	return [
		{
			url : '/' ,
			title : 'Homepage' ,
		} ,
		{
			url : '/route/random' ,
		} ,
	] ;
} ; 

نموذج

لتخصيص مستند HTML الذي يستخدمه التطبيق الخاص بك ، قم بتحرير ملف template.ejs في دليل مصدر التطبيق الخاص بك.

EJS هي لغة templating بسيطة تتيح لك إنشاء علامة HTML مع JavaScript العادي. إلى جانب html-webpack-plugin ، يمكنك إضافة HTML بشكل مشروط ، والوصول إلى الحزم والأصول الخاصة بك ، والربط بالمحتوى الخارجي إذا كنت ترغب في ذلك. الافتراضي الذي نقدمه في تهيئة المشروع يجب أن يتناسب مع غالبية حالات الاستخدام بشكل جيد للغاية ، ولكن لا تتردد في التخصيص!

يمكنك تخصيص موقع القالب الخاص بك مع العلم --template على أوامر build watch :

preact build --template renamed-src/template.ejs
preact watch --template template.ejs

باستخدام المعالجات المسبقة CSS

تأتي القوالب الافتراضية مع ملف .css لكل مكون. يمكنك البدء في استخدام المعالجات المسبقة CSS في أي وقت معين أثناء دورة حياة المشروع عن طريق تثبيت حزم إضافية ثم ببساطة استبدال ملفات .css .

ساس

• npm install --save-dev sass sass-loader@10 (داخل مجلد تطبيق Preact الخاص بك)
• ابدأ في استبدال ملفات .css بملفات .scss

أقل

• npm install --save-dev less less-loader@7 (داخل مجلد تطبيق Preact الخاص بك)
• ابدأ في استبدال ملفات .css بملفات .less

باستخدام متغيرات البيئة

يمكنك الرجوع واستخدام أي متغير بيئة في التطبيق الخاص بك والذي تم تجميعه مع PREACT_APP_ تلقائيًا:

src/index.js

 console . log ( process . env . PREACT_APP_MY_VARIABLE ) ;

إذا لم يكن متغيرك مسبوقًا ، فلا يزال بإمكانك إضافته يدويًا باستخدام preact.config.js (انظر تكوين definePlugin في الوصفات wiki).

من المهم أن نلاحظ أن DefinePlugin يقوم باستبدال النص المباشر ؛ لا يجعل process قابلة للاستخدام. يمكن أن تكون process.env كائنًا فارغًا ، ولكن سيتم استبدال process.env.PREACT_APP_MY_VARIABLE تلقائيًا (في حالة وجود قيمة).

يمكنك ضبط وتخزين المتغيرات باستخدام ملف .env في جذر مشروعك:

.env

 PREACT_APP_MY_VARIABLE="my-value"

يمكنك أيضًا الرجوع إلى متغيرات البيئة في preact.config.js :

 export default ( config , env , helpers , options ) => {
	if ( process . env . MY_VARIABLE ) {
		/** You can add a config here that will only used when your variable is truthy **/
	}
} ;

تقسيم الكود القائم على المسار

يتم توجيه مكونات "المسار" تلقائيًا في وقت البناء في وقت الإنشاء لإنشاء حزم أصغر وتجنب تحميل رمز أكثر مما هو مطلوب من قبل كل صفحة. يعمل هذا من خلال اعتراض الواردات لمكونات المسار باستخدام محمل غير متزامن ، والذي يرجع مكونًا خفيف الوزن يتولى تقسيم الكود بسلاسة.

يتم تطبيق تقسيم التعليمات البرمجية التلقائية على جميع ملفات JavaScript و TypeScript في المواقع التالية:

نمط	أمثلة
SRC / ROUTES / NAME	src/routes/home.js src/routes/about/index.tsx
SRC/ المكونات/ المسارات / الاسم	src/components/routes/profile.ts src/components/routes/profile/index.js
SRC/ مكونات/ async / الاسم	src/components/async/profile.ts src/components/async/profile/index.js

ملاحظة : يدعم تقسيم التعليمات البرمجية التلقائي الصادرات الافتراضية فقط ، وليس مسماة الصادرات:

 - import { Profile } from './routes/profile';
+ import Profile from './routes/profile';

هذا هو القيد المقصود يضمن تقسيم الكود الفعال. بالنسبة للمكونات التي تحتاج إلى تصدير مسماة ، ضعها في دليل لا يؤدي إلى تقسيم الكود التلقائي. يمكنك بعد ذلك تقسيم رمز التصدير الافتراضي يدويًا عن طريق إعادة تصديره من routes/ أو استيراده باستخدام "async!" بادئة.