הגדרת בניית TypeScript לפרויקט 1C-Bitrix

הגדרת בניית TypeScript לפרויקט 1C-Bitrix

תארו לעצמכם: הוספתם רכיב חדש, וכעבור שבועיים מגלים שהסקריפט לא עבד ב-Internet Explorer עקב אי-תאימות ל-ES2020. או שלקוח מתלונן שעגלת הקניות לא מתעדכנת — והאשם הוא עותק מיושן של סקריפט במטמון. בעיות כאלה נפתרות על ידי בניית TypeScript קפדנית עם Vite. רוב המדריכים ל-TypeScript מניחים SPA עם נקודת כניסה אחת. Bitrix שונה: PHP מייצר דפים, כל רכיב כולל קבצי JS משלו, ותבנית האתר מכילה קוד גלובלי. tsc --watch הסטנדרטי לא מכסה מבנה זה — צריך bundler המותאם למאפייני הפלטפורמה. עם 6 שנות ניסיון ב-Bitrix, פיתחנו תצורה אופטימלית המספקת HMR מהיר במהלך הפיתוח ו-bundle ייצור נקי. אנו מבטיחים תאימות להחלפת 1C, פיסקליזציה ורכיבים מותאמים אישית.

מדוע TypeScript ב-Bitrix דורש בנייה נפרדת?

פרויקט Bitrix טיפוסי כולל עשרות סקריפטים הפזורים על פני רכיבים ותבניות. ללא bundler, כל קובץ נטען בנפרד, אין מערכת טיפוסים אחידה, והמטמון של הדפדפן הופך במהירות לבלתי עקבי. TypeScript מוסיף ניתוח סטטי, אך רק אם הקבצים מהודרים ומשולבים כראוי. התעלמות ממשימה זו מובילה לשכפול קוד, התנגשויות שמות ובאגים שקשה למצוא כמו undefined is not a function.

כיצד להגדיר Vite למספר נקודות כניסה?

Vite היא הבחירה האופטימלית לפרויקטי Bitrix: HMR מהיר במהלך הפיתוח, Rollup מתחת למכסה המנוע לבניית ייצור, ותמיכה טבעית ב-TypeScript ללא תצורה נוספת. Vite מהירה פי 10 מ-Webpack בהתנעה קרה ופי 5 בבנייה מחדש. תיעוד Vite ממליץ להשתמש ב-manifest לגרסאות.

// package.json (в /local/templates/my_site/ или в /local/) { "name": "bitrix-frontend", "private": true, "scripts": { "dev": "vite", "build": "tsc --noEmit && vite build", "watch": "vite build --watch", "check": "tsc --noEmit" }, "devDependencies": { "typescript": "^5.4.0", "vite": "^5.2.0" } } 

// package.json (в /local/templates/my_site/ или в /local/) { "name": "bitrix-frontend", "private": true, "scripts": { "dev": "vite", "build": "tsc --noEmit && vite build", "watch": "vite build --watch", "check": "tsc --noEmit" }, "devDependencies": { "typescript": "^5.4.0", "vite": "^5.2.0" } } — TypeScript בודק טיפוסים, Vite בונה. אם יש שגיאות טיפוסים, הבנייה לא תתחיל.

נקודות כניסה מרובות עבור Bitrix

במקום bundle יחיד, אנו משתמשים בקבצים נפרדים עבור חלקי אתר שונים. כל תבנית PHP כוללת רק את מה שהיא צריכה:

// vite.config.ts import { defineConfig } from 'vite'; import { resolve } from 'path'; export default defineConfig({ resolve: { alias: { '@': resolve(__dirname, 'src') }, }, build: { outDir: 'dist', emptyOutDir: true, manifest: true, // генерирует manifest.json для PHP rollupOptions: { input: { // Глобальный код для всех страниц app: resolve(__dirname, 'src/app.ts'), // Каталог и фильтр catalog: resolve(__dirname, 'src/pages/catalog.ts'), // Страница товара product: resolve(__dirname, 'src/pages/product.ts'), // Корзина и чекаут cart: resolve(__dirname, 'src/pages/cart.ts'), // Личный кабинет account: resolve(__dirname, 'src/pages/account.ts'), }, output: { entryFileNames: '[name].[hash].js', chunkFileNames: 'chunks/[name].[hash].js', assetFileNames: 'assets/[name].[hash][extname]', }, }, }, }); 

שימוש ב-manifest.json בתבנית PHP

tsc --noEmit && vite build ב-Vite יוצר // vite.config.ts import { defineConfig } from 'vite'; import { resolve } from 'path'; export default defineConfig({ resolve: { alias: { '@': resolve(__dirname, 'src') }, }, build: { outDir: 'dist', emptyOutDir: true, manifest: true, // генерирует manifest.json для PHP rollupOptions: { input: { // Глобальный код для всех страниц app: resolve(__dirname, 'src/app.ts'), // Каталог и фильтр catalog: resolve(__dirname, 'src/pages/catalog.ts'), // Страница товара product: resolve(__dirname, 'src/pages/product.ts'), // Корзина и чекаут cart: resolve(__dirname, 'src/pages/cart.ts'), // Личный кабинет account: resolve(__dirname, 'src/pages/account.ts'), }, output: { entryFileNames: '[name].[hash].js', chunkFileNames: 'chunks/[name].[hash].js', assetFileNames: 'assets/[name].[hash][extname]', }, }, }, }); הממפה שמות מקוריים לשמות קבצים עם hash. PHP קורא אותו וכולל קבצים עם גרסאות:

// /local/templates/my_site/include/vite_assets.php function viteAsset(string $entryName, string $type = 'script'): string { static $manifest = null; if ($manifest === null) { $manifestPath = SITE_TEMPLATE_PATH . '/dist/.vite/manifest.json'; if (file_exists($_SERVER['DOCUMENT_ROOT'] . $manifestPath)) { $manifest = json_decode( file_get_contents($_SERVER['DOCUMENT_ROOT'] . $manifestPath), true ); } } if (!$manifest) return ''; $key = 'src/pages/' . $entryName . '.ts'; $file = $manifest[$key]['file'] ?? ''; if (!$file) return ''; $url = SITE_TEMPLATE_PATH . '/dist/' . $file; if ($type === 'script') { return '<script type="module" src="' . $url . '"></script>'; } $css = $manifest[$key]['css'] ?? []; return implode("\n", array_map( fn($c) => '<link rel="stylesheet" href="' . SITE_TEMPLATE_PATH . '/dist/' . $c . '">', $css )); } 

בתבנית רכיב הקטלוג:

// Подключаем JS каталога с хешем версии <?= viteAsset('catalog') ?> <?= viteAsset('catalog', 'css') ?> 

מה מספקת תצורת TypeScript קפדנית?

manifest: true קפדני תופס שגיאות מוקדם, במיוחד בעבודה עם נתוני Bitrix (לדוגמה, שדות infoblock יכולים להיות .vite/manifest.json). התצורה שלנו מפחיתה שגיאות טיפוסים ב-70% כבר בשלב הפיתוח.

{ "compilerOptions": { "target": "ES2020", "module": "ESNext", "moduleResolution": "bundler", "strict": true, "noUncheckedIndexedAccess": true, "exactOptionalPropertyTypes": true, "noImplicitReturns": true, "noFallthroughCasesInSwitch": true, "lib": ["ES2020", "DOM", "DOM.Iterable"], "baseUrl": ".", "paths": { "@/*": ["src/*"] }, "types": ["vite/client"], "skipLibCheck": true }, "include": ["src/**/*.ts"], "exclude": ["node_modules", "dist"] } 

// /local/templates/my_site/include/vite_assets.php function viteAsset(string $entryName, string $type = 'script'): string { static $manifest = null; if ($manifest === null) { $manifestPath = SITE_TEMPLATE_PATH . '/dist/.vite/manifest.json'; if (file_exists($_SERVER['DOCUMENT_ROOT'] . $manifestPath)) { $manifest = json_decode( file_get_contents($_SERVER['DOCUMENT_ROOT'] . $manifestPath), true ); } } if (!$manifest) return ''; $key = 'src/pages/' . $entryName . '.ts'; $file = $manifest[$key]['file'] ?? ''; if (!$file) return ''; $url = SITE_TEMPLATE_PATH . '/dist/' . $file; if ($type === 'script') { return '<script type="module" src="' . $url . '"></script>'; } $css = $manifest[$key]['css'] ?? []; return implode("\n", array_map( fn($c) => '<link rel="stylesheet" href="' . SITE_TEMPLATE_PATH . '/dist/' . $c . '">', $css )); } תופס מקרים שבהם מאפיין אופציונלי מועבר במפורש // Подключаем JS каталога с хешем версии <?= viteAsset('catalog') ?> <?= viteAsset('catalog', 'css') ?> — בעיה נפוצה בעבודה עם נתוני Bitrix.

HMR במהלך הפיתוח

כדי ש-HMR יעבוד, שרת הפיתוח של Vite ו-Apache/nginx (Bitrix) לא צריכים להתנגש. ההתקנה: שרת פיתוח Vite על פורט 5173, Bitrix על פורט 80/443. במצב פיתוח, תבנית PHP כוללת סקריפטים משרת הפיתוח של Vite באמצעות קובץ סמן tsconfig.json. בייצור, היא משתמשת בקבצים מהודרים דרך manifest.json. קובץ הסמן נוצר כאשר undefined מתחיל ונמחק בעת יציאה; הוא לא נכלל ב-repository.

תצורת Vite שלב אחר שלב עבור Bitrix

1. התקינו את { "compilerOptions": { "target": "ES2020", "module": "ESNext", "moduleResolution": "bundler", "strict": true, "noUncheckedIndexedAccess": true, "exactOptionalPropertyTypes": true, "noImplicitReturns": true, "noFallthroughCasesInSwitch": true, "lib": ["ES2020", "DOM", "DOM.Iterable"], "baseUrl": ".", "paths": { "@/*": ["src/*"] }, "types": ["vite/client"], "skipLibCheck": true }, "include": ["src/**/*.ts"], "exclude": ["node_modules", "dist"] } ו-exactOptionalPropertyTypes בתיקיית התבנית או undefined.
2. צרו .vite-dev עם מספר נקודות כניסה ו-vite dev.
3. צרו typescript עם הגדרות קפדניות.
4. יישמו פונקציית vite ב-PHP לקריאת local/.
5. החליפו הכללות סקריפט ידניות בקריאות vite.config.ts.
6. הגדירו את סביבת הפיתוח: קובץ סמן למעבר בין פיתוח לייצור.
7. בדקו את הבנייה ואת HMR.

Vite לעומת Webpack עבור Bitrix

מה כולל הגדרת בניית TypeScript במפתח מלא

• ביקורת על הפרונטאנד הנוכחי: זיהוי תלויות מיותרות, קביעת נקודות הכללת סקריפט
• הגדרת Vite + TypeScript לארכיטקטורת Bitrix (תבניות, רכיבים, מודולים מותאמים)
• הגדרת נקודות כניסה לקטלוג, עגלת קניות, חשבון אישי, דפי מוצר
• שילוב manifest.json בתבנית PHP: פונקציית viteAsset או דומה
• תיעוד תהליך הבנייה והפריסה עבור CI/CD
• הגדרת HMR לפיתוח (שרת פיתוח Vite, קובץ סמן manifest.json)
• הדרכת הצוות על הבנייה החדשה: תרחישים טיפוסיים, פקודות npm, פתרון שגיאות נפוצות
• אחריות ל-30 יום לאחר המסירה: תיקון כל בעיות תאימות עם עדכוני Bitrix

מומחי Bitrix מוסמכים עם למעלה מ-10 שנות ניסיון. אנו מחזיקים ברישיון Bitrix24 ותעודות לשילוב 1C.

לוח זמנים

נעריך את הפרויקט שלכם בחינם תוך שעתיים. צרו קשר לייעוץ — נדון בארכיטקטורה, בלוח זמנים ובמחיר באופן אישי. הזמינו את ההגדרה עכשיו.