חיבור אוטומטי ל-Workspace בכלי הפיתוח ל-Chrome

‫Workspace היא תכונה עוצמתית שמאפשרת לערוך ישירות את קובצי המקור של האתר מתוך כלי הפיתוח של Chrome, בלי הצורך לעבור כל הזמן בין עורך הקוד לדפדפן.

סקירה כללית

סביבת עבודה בכלי הפיתוח ל-Chrome ממפה קבצים שמוגשים על ידי שרת אינטרנט לקבצים בתיקייה מקומית במחשב. כשמפעילים סביבת עבודה לפרויקט מקומי, כל שינוי שמבצעים בקבצים בחלונית Sources ב-DevTools נשמר אוטומטית בקבצים של הפרויקט המקומי. כך תוכלו לערוך את הקוד בצורה חלקה, כאילו אתם עובדים ישירות על בסיס הקוד של הפרויקט, וליהנות מהתובנות בזמן אמת של כלי הפיתוח.

היתרונות של חיבור אוטומטי ל-Workspace

חיבור אוטומטי של סביבת עבודה משפר את הגדרת סביבת העבודה בכך שהוא מבטל את הצורך בהגדרה ידנית. במקום להוסיף ידנית תיקיות פרויקט ל-DevTools, שרת הפיתוח המקומי יכול לספק devtools.json קובץ מיוחד ש-Chrome DevTools מזהה באופן אוטומטי. היתרונות של הגישה הזו:

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

איך פועל החיבור האוטומטי של סביבת עבודה?

חיבור אוטומטי של סביבת עבודה מתבצע על ידי חשיפה של קובץ JSON ספציפי בנתיב מוגדר מראש בשרת הפיתוח המקומי. כשכלי הפיתוח ל-Chrome פתוחים ואתם עוברים באתר שמוצג מ-localhost, המערכת שולחת באופן אוטומטי בקשה אל:

/.well-known/appspecific/com.chrome.devtools.json

אם השרת מגיב עם קובץ devtools.json תקין, כלי הפיתוח משתמשים במידע שבקובץ כדי להתחבר אוטומטית לתיקיות המקור של הפרויקט. הקובץ devtools.json בדרך כלל מכיל:

{
  "workspace": {
    "root": "/Users/yourname/path/to/your/project",
    "uuid": "a-random-version-4-uuid"
  }
}

• ‫workspace.root: הנתיב המוחלט לתיקיית השורש של הפרויקט במערכת הקבצים המקומית.
• ‫workspace.uuid: מזהה ייחודי (UUID v4) של הפרויקט. כך כלי DevTools יכולים להבחין בין פרויקטים שונים.

אחרי ש-DevTools מקבל ומעבד את הקובץ הזה, מופיע לחצן Connect בחלונית Sources > Workspaces.

מיועד לפיתוח ולניפוי באגים מקומיים

מנגנון הגילוי האוטומטי של סביבת העבודה דרך devtools.json מיועד באופן בלעדי לסביבות פיתוח מקומיות, והוא פועל רק כשהאפליקציה מוגשת מ-localhost. כלי הפיתוח ל-Chrome שולחים את הבקשה /.well-known/appspecific/com.chrome.devtools.json רק במצב פיתוח כשמבצעים ניפוי באגים בפרויקט מקומי. התכונה הזו לא מיועדת לסביבות ייצור.

איך נותנים הרשאה לגשת לקבצים ששמורים במכשיר

מטעמי אבטחה, דפדפן Chrome דורש הרשאה מפורשת מהמשתמש כדי שאתר יוכל לגשת לקבצים ברשת המקומית או במחשב. כשכלי הפיתוח מנסים להתחבר לפרויקט המקומי באמצעות devtools.json, תתבקשו לתת ל-Chrome הרשאה לגשת לספרייה של הפרויקט. הבקשה הזו להרשאה עומדת בדרישות המדיניות של Chrome בנושא גישה לרשת המקומית, שמגבילה בקשות מרשתות ציבוריות ליעדים מקומיים, אלא אם ניתנה הרשאה. היכולת לבקש את ההרשאה הזו מוגבלת להקשרים מאובטחים (HTTPS). בפיתוח מקומי, המשמעות היא שבדרך כלל localhost נחשב להקשר מאובטח.

יצירה והצגה של קובץ devtools.json

בפרויקט טיפוסי של חזית האתר שפועל בשרת פיתוח מקומי, צריך להגדיר את השרת כך שיגיב לבקשת /.well-known/appspecific/com.chrome.devtools.json עם תוכן JSON נכון.

כך בדרך כלל עושים את זה:

1. יצירת מזהה ייחודי אוניברסלי (UUID): תצטרכו מזהה ייחודי אוניברסלי (UUID) בגרסה 4. אפשר ליצור קובץ כזה באמצעות כלים אונליין או סקריפט.
2. קביעת תיקיית הבסיס של הפרויקט: מקבלים את הנתיב המוחלט לתיקיית הבסיס של הפרויקט.
3. יוצרים נקודת קצה: מגדירים את שרת הפיתוח לטיפול בבקשות GET אל /.well-known/appspecific/com.chrome.devtools.json.
4. הצגת ה-JSON: כשמגיעים לנקודת הקצה הזו, מוצגת תגובת JSON עם הכותרת Content-Type: application/json והתוכן devtools.json.

הנתיב workspace.root שצוין בקובץ devtools.json חייב להיות נתיב מוחלט לספריית השורש של הפרויקט במערכת הקבצים המקומית. המשמעות היא שהנתיב ישתנה בהתאם למערכת ההפעלה (לדוגמה, /Users/yourname/projects/my-app ב-macOS או ב-Linux או C:\Users\yourname\projects\my-app ב-Windows) ולהגדרת הפרויקט הספציפית. כדאי להוסיף אותו לקבצים שמתעלמים מהם (למשל לרשימת ‎.gitignore) כדי להימנע מבדיקת הקובץ הזה בסביבת הייצור.

חשוב שהשרת ייצור או יציג את הנתיב הזה באופן דינמי, או שתגדירו אותו בצורה נכונה בסביבת הפיתוח. כדאי להוסיף אותו לרשימת הקבצים להתעלמות (למשל, לרשימה .gitignore) כדי להימנע מבדיקת הקובץ הזה בסביבת הייצור.

דוגמאות

יש הרבה דרכים לספק קובץ devtools.json, בהתאם לסט הטכנולוגיות של הפרויקט.

‫Node.js ו-Express

הסקריפט הזה מפעיל שרת Express מינימלי. הוא מציג קובץ JSON בנתיב /.well-known/appspecific/com.chrome.devtools.json שמכיל את הנתיב אל projectRoot.. הוא מצביע על התיקייה שממנה השרת מופעל. משנים את המשתנה projectRoot כך שיצביע בצורה נכונה על ספריית הבסיס בפועל של הפרויקט, ולא בהכרח על המקום שבו נמצא סקריפט השרת.

const express = require('express');
const path = require('path');
const { v4: uuidv4 } = require('uuid');

const app = express();
const port = 3000;

if (process.env.NODE_ENV !== 'production') {
  app.get('/.well-known/appspecific/com.chrome.devtools.json', (req, res) => {
    const projectRoot = path.resolve(__dirname);
    const workspaceUuid = uuidv4();

    res.json({
      workspace: {
        root: projectRoot,
        uuid: workspaceUuid,
      },
    });
  });
}

app.listen(port, () => {
  console.log(`Development server listening at http://localhost:${port}`);
});

שימוש בסקריפט devtools-json-generator

אתם יכולים להשתמש ב-generate-devtools-json כדי ליצור את devtools.json בשבילכם.

כדי ליצור את הקובץ devtools.json בספרייה הנוכחית, מריצים את הפקודה:

npx generate-devtools-json

לחלופין, כדי ליצור את הקובץ בספרייה ספציפית, מעבירים את הספרייה כארגומנט:

npx generate-devtools-json /path/to/your/project

מידע נוסף על devtools-json-generator זמין בדף הבית של הפרויקט.

שילובים

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

Vite

בפרויקטים שמבוססים על Vite (כולל SvelteKit), הפתרון הוא vite-plugin-devtools-json. הוא מאפשר ליצור את קובץ ה-devtools.json ולהציג אותו באופן אוטומטי תוך כדי תנועה.

כדי להשתמש בו, צריך להתקין את הפלאגין:

npm install -D vite-plugin-devtools-json

לאחר מכן מוסיפים אותו ל-vite.config.js (או ל-vite.config.ts):

// vite.config.js
import { defineConfig } from 'vite';
import devtoolsJson from 'vite-plugin-devtools-json';

export default defineConfig({
  plugins: [
    devtoolsJson({
      // Optional: specify a custom root path if different from Vite's root
      // root: '/path/to/your/project/root',
    }),
  ],
});

Angular

אם אתם משתמשים ב-ng serve כדי להריץ את פרויקט Angular באופן מקומי (והגרסה של ng serve היא לפחות 19.0.0), Angular CLI מספק תוכנת ביניים שמציגה את קובץ devtools.json הנכון באופן אוטומטי.@angular/cli

לדוגמה, כדי ליצור ולהריץ אפליקציה חדשה:

npm install -g @angular/cli
ng new my-first-angular-app
ng serve

כשעוברים אל https://localhost:4200/.well-known/appspecific/com.chrome.devtools.json, אפשר לראות את קובץ ה-JSON שנוצר.

פתרון בעיות

בקטע הזה מפורטים טיפים לפתרון בעיות נפוצות שקשורות לחיבור אוטומטי של סביבת עבודה.

הסרת תיקייה מסביבות עבודה

אם תיקיית פרויקט כבר חוברה אוטומטית, אפשר להסיר אותה ידנית מהגדרות סביבת העבודה בכלי הפיתוח:

• פותחים את כלי הפיתוח ל-Chrome.
• עוברים לכרטיסייה מקורות.
• בחלונית הימנית, בוחרים בכרטיסיית המשנה סביבות עבודה.
• לוחצים לחיצה ימנית על תיקיית הפרויקט הלא רצויה ובוחרים באפשרות הסרה מסביבת העבודה.

התעלמות משגיאות 404 בשרת

אם אתם לא רוצים להשתמש בתכונה הזו בפרויקט מסוים ומופיעות שגיאות 404 ביומני השרת לגבי בקשת /.well-known/appspecific/com.chrome.devtools.json, אתם יכולים להתעלם מהשגיאות האלה. הבקשה לא מזיקה אם הקובץ לא מוצג. אפשר גם להגדיר את השרת כך שיגיב עם סטטוס 404 לנתיב הספציפי הזה בלי לרשום שגיאה ביומן.

איך משביתים את התכונה הזו בכלי הפיתוח ל-Chrome

אם אתם רוצים להשבית את התכונה של גילוי אוטומטי של סביבת עבודה בכלי הפיתוח ל-Chrome, אתם צריכים להגדיר את התכונה הניסיונית המתאימה של Chrome:

• פותחים את Chrome ועוברים אל chrome://flags.
• מחפשים את ההגדרה DevTools Project Settings (הגדרות הפרויקט של כלי הפיתוח) ומשנים אותה לDisabled (מושבת).
• יכול להיות שתמצאו גם דגל קשור בשם DevTools Automatic Workspace Folders (תיקיות אוטומטיות של סביבת עבודה בכלי הפיתוח) ותוכלו להשבית אותו גם כן.
• מפעילים מחדש את Chrome כדי שהשינויים ייכנסו לתוקף.

סיכום

הבנה של מנגנון devtools.json ושימוש בו יכולים לשפר משמעותית את תהליך העבודה שלכם בפיתוח מקומי באמצעות כלי הפיתוח ל-Chrome.