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

דף זה תורגם על ידי Cloud Translation API.

יצירת תבנית בהתאמה אישית

ב-IDX יש מגוון רחב של תבניות מובנות שכוללות את כל הקבצים, חבילות המערכת (למשל מהדרים) ותוספים שהמשתמש צריך כדי להתחיל לעבוד במהירות עם שפה או framework.

תוכלו גם ליצור תבניות משלכם שניתנות להגדרה על ידי המשתמש. למשל:

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

ברגע שיש לכם תבנית מותאמת אישית מוכנה, תוכלו ליצור קישור בשבילה ולהציב אותה באתר שלכם, בקובץ README של מאגר Git, בדף פרטי החבילה (למשל ב-NPM) או במקומות אחרים שמהם המשתמשים ירצו להתחיל להשתמש בטכנולוגיה שלכם.

דרישות מוקדמות

לפני שמתחילים, חשוב לוודא שאתם יודעים איך להתאים אישית את הסביבה בעזרת קובצי .idx/dev.nix.

התבניות גם משתמשות בשפת Nix, אז כדאי לרענן את הידע שלכם על כמה מהעקרונות הבסיסיים או להשתמש בה כחומר עזר.

מבנה הקובץ של התבנית

תבנית היא מאגר ציבורי של GitHub (או תיקייה או הסתעפות במאגר) שמכיל לפחות שני קבצים:

יצירה של סביבת עבודה חדשה מתבנית בהתאמה אישית

idx-template.json כולל את המטא-נתונים של התבנית, כולל השם הגלוי למשתמש, התיאור והפרמטרים שזמינים למשתמשים להגדרת התבנית. לדוגמה, תוכלו לאפשר למשתמשים לבחור מתוך כמה שפות תכנות או תרחישים לדוגמה. ב-IDX משתמשים במידע הזה כדי להכין את ממשק המשתמש שיוצג למשתמשים כשהם בוחרים ליצור סביבת עבודה חדשה מהתבנית.
idx-template.nix הוא קובץ שנכתב בשפת Nix ומכיל סקריפט של מעטפת Bash (עטוף בפונקציה של Nix) האחראית על:
1. יצירת ספריית העבודה החדשה של סביבת העבודה ו
2. להגדיר את הסביבה על ידי יצירת קובץ .idx/dev.nix. שימו לב שאפשר גם להריץ כלי פיגומים של פרויקטים, כמו flutter create או npm init בסקריפט הזה, או להריץ סקריפט מותאם אישית שנכתב ב-Go, ב-Python, ב-Node.js או בשפה אחרת.
הקובץ הזה יופעל עם הפרמטרים שצוינו על ידי המשתמש כשהוא הגדיר את התבנית.

אפשר להוסיף קבצים אחרים לצד שני הקבצים האלה, לשימוש ב-idx-template.nix, כדי ליצור את התבנית. לדוגמה, אפשר לכלול את קובץ .idx/dev.nix הסופי, או אפילו לכלול את כל קובצי הפיגומים ישירות מהמאגר.

דוגמה בסיסית: הפיכת כל מאגר ציבורי של GitHub לתבנית

לפני שנכנסים לפרטים לגבי ההגדרה של idx-template.json ו-idx-template.nix, כדאי לראות תבנית בסיסית לדוגמה שמציגה את הנתונים הבאים:

לא מכיל פרמטרים שניתן להגדיר על ידי המשתמש
פשוט מעתיקים את כל הקבצים ממאגר התבניות (חוץ משני קובצי idx-template) לסביבת העבודה של המשתמש. כבר צריכה להיות תיקיית משנה .idx עם קובץ dev.nix שמגדיר את הסביבה.

כשמוסיפים את הקבצים הבאים לכל מאגר ציבורי של GitHub (או תיקיית משנה או הסתעפות), המאגר הזה הופך בפועל לתבנית IDX.

`idx-template.json`

{
  "name": "Hello world",
  "description": "A template for a CLI program that prints 'hello world'",
  "icon": "https://www.gstatic.com/images/branding/productlogos/idx/v1/192px.svg",
  "params": []
}

`idx-template.nix`

# No user-configurable parameters
{ pkgs, ... }: {
  # Shell script that produces the final environment
  bootstrap = ''
    # Copy the folder containing the `idx-template` files to the final
    # project folder for the new workspace. ${./.} inserts the directory
    # of the checked-out Git folder containing this template.
    cp -rf ${./.} "$out"

    # Set some permissions
    chmod -R +w "$out"

    # Remove the template files themselves and any connection to the template's
    # Git repository
    rm -rf "$out/.git" "$out/idx-template".{nix,json}
  '';
}

שימוש בחבילות מערכת נוספות בסקריפט `bootstrap`

הדוגמה הקודמת משתמשת רק בפקודות POSIX בסיסיות כדי להעתיק קבצים למקום הנכון. יכול להיות שבסקריפט bootstrap של התבנית תצטרכו להתקין קבצים בינאריים נוספים, כמו git, node, python3 או אחרים.

אפשר להפוך חבילות מערכת נוספות לזמינות לסקריפט האתחול על ידי ציון packages בקובץ idx-template.nix, בדיוק כמו שמבצעים התאמה אישית של סביבת עבודה באמצעות חבילות מערכת נוספות על ידי הוספה ל-packages בקובץ dev.nix שלו.

כך מוסיפים את הקובץ pkgs.nodejs, שכולל קבצים בינאריים כמו node, npx ו-npm:

# idx-template.nix
{pkgs}: {
  packages = [
    # Enable "node", "npm" and "npx" in the bootstrap script below.
    # Note, this is NOT the list of packages available to the workspace once
    # it's created. Those go in .idx/dev.nix
    pkgs.nodejs
  ];

  bootstrap = ''
    mkdir "$out"
    # We can now use "npm"
    npm init --yes my-boot-strap@latest "$out"
  ''
}

הוספת פרמטרים שניתנים להגדרה על ידי המשתמש

כדי לאפשר למשתמשים להתאים אישית את נקודת ההתחלה לפרויקט החדש, אפשר ליצור כמה תבניות או ליצור תבנית אחת עם פרמטרים. זו אפשרות נהדרת אם נקודות ההתחלה השונות הן רק ערכים שונים שמועברים לכלי CLI (לדוגמה --language=js לעומת --language=ts).

כדי להוסיף פרמטרים, צריך:

מתארים את הפרמטר באובייקט params של קובץ המטא-נתונים idx-template.json. IDX משתמש במידע שבקובץ הזה כדי להכין את ממשק המשתמש (כמו תיבות סימון, תפריטים נפתחים ושדות טקסט) שמוצגים למשתמשים בתבנית.
מעדכנים את האתחול של idx-template.nix כך שישתמש בערכים שהמשתמש בחר בזמן יצירת התבנית.

צריך לתאר את הפרמטר ב-`idx-template.json`

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

{
  "name": "Hello world",
  "description": "A hello world app",
  "params": [
    {
      "id": "language",
      "name": "Programming Language",
      "type": "enum",
      "default": "ts",
      "options": {
        "js": "JavaScript",
        "ts": "TypeScript"
      },
      "required": true
    }
  ]
}

מכיוון שיש שני ערכים (JavaScript ו-TypeScript), ממשק המשתמש יציג קבוצת לחצני בחירה לשתי האפשרויות ויעביר את הערך ts או js לסקריפט idx-template.nix.

לכל אובייקט של פרמטר יש את המאפיינים הבאים:

נכס	TYPE	תיאור
id	`string`	המזהה הייחודי של הפרמטר, שדומה לשם המשתנה.
שם	`string`	השם המוצג של הפרמטר הזה.
סוג	`string`	מציינת את רכיב ממשק המשתמש שיש להשתמש בו לפרמטר הזה, ואת סוג הנתונים שיועבר לסקריפט bootrap. הערכים החוקיים כוללים: `"enum"` – מציג קבוצה של לחצני בחירה או תפריט נפתח, ומעביר `string` ל-Bootstrap `"boolean"` – מציג תיבת סימון ועובר את `true` או `false` `"text"` - מציג שדה טקסט ומעביר `string`
אפשרויות	`object`	עבור פרמטרים של `enum`, הערך הזה מייצג את האפשרויות להצגת המשתמשים. לדוגמה, אם האפשרויות הן `{"js": "JavaScript", ...}`, האפשרות 'JavaScript' תוצג כאפשרות, וכשייבחר הערך של הפרמטר יהיה `js`.
ברירת מחדל	‫`string` או `boolean`	מגדיר את הערך הראשוני בממשק המשתמש. לפרמטרים `enum`, הערך הזה חייב להיות אחד מהמפתחות ב-`options`. בפרמטרים של `boolean`, הערך צריך להיות `true` או `false`.
חובה	`boolean`	מציין שהפרמטר הזה הוא חובה.

שימוש בערכי פרמטרים ב-`idx-template.nix`

אחרי שמגדירים את האובייקט params בקובץ idx-template.json, אפשר להתחיל להתאים אישית את סקריפט ה-Boottrap על סמך ערכי הפרמטרים שהמשתמש בוחר.

בהמשך לדוגמה בסעיף הקודם, אם יש לכם פרמטר יחיד עם המזהה language, שהוא enum עם הערכים האפשריים ts או js, תוכלו להשתמש בו באופן הבא:

# idx-template.nix
# Accept additional arguments to this template corresponding to template
# parameter IDs, including default values (language=ts by default in this example).
{ pkgs, language ? "ts", ... }: {
  packages = [
    pkgs.nodejs
  ];

  bootstrap = ''
    # We use Nix string interpolation to pass the user's chosen programming
    # language to our script.
    npm init --yes my-boot-strap@latest "$out" -- --lang=${language}
  ''
}

דפוס נפוץ נוסף הוא לכלול תוכן באופן מותנה בהתאם לערך של מחרוזת. דרך נוספת לכתוב את הדוגמה הקודמת היא:

npm init --yes my-boot-strap@latest "$out" -- \
    ${if language == "ts" then "--lang=ts" else "--lang=js" }

בחירת הקבצים שייפתחו כברירת מחדל

כדאי להתאים אישית את הקבצים שייפתחו לעריכה כשיוצרים סביבות עבודה חדשות באמצעות התבנית. לדוגמה, אם התבנית היא לאתר בסיסי, תוכלו לפתוח את הקבצים הראשיים של HTML, JavaScript ו-CSS.

כדי להתאים אישית את הקבצים שייפתחו כברירת מחדל, צריך לעדכן את הקובץ .idx/dev.nix (לא את הקובץ idx-template.nix!) כך שיכלול הוק (hook) סביבת עבודה onCreate עם מאפיין openFiles, באופן הבא:

# .idx/dev.nix
{pkgs}: {
  ...
  idx = {
    # Workspace lifecycle hooks
    workspace = {
      # Runs when a workspace is first created with this `dev.nix` file
      onCreate = {
        # Open editors for the following files by default, if they exist.
        # The last file in the list will be focused.
        default.openFiles = [
          "src/index.css"
          "src/index.js"
          "src/index.html"
        ];
        # Include other scripts here, as needed, for example:
        # installDependencies = "npm install";
      };
      # To run something each time the workspace is (re)started, use the `onStart` hook
    };
    # Enable previews and customize configuration
    previews = { ... };
  };
}

יצירה של סביבת עבודה חדשה מהתבנית

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

https://idx.google.com/new?template=https://github.com/my-org/my-repo

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

https://github.com/my-org/my-repo/
https://github.com/my-org/my-repo/tree/main/path/to/myidxtemplate
https://github.com/my-org/my-repo/tree/branch
https://github.com/my-org/my-repo/tree/branch/path/to/myidxtemplate

זאת גם כתובת ה-URL שתשתפו עם אחרים כדי שהם יוכלו להשתמש בתבנית החדשה, או כתובת ה-URL שאליה תקשרו מהלחצן Open in IDX.

אחרי שמוודאים שהתבנית פועלת כצפוי, צריך לפרסם אותה במאגר ב-GitHub ולשתף את אותו הקישור שבו השתמשתם כשיצרתם סביבת עבודה לבדיקה.

כדי שיהיה למשתמשים עוד יותר קל למצוא את התבנית, כדאי להוסיף לחצן Open in IDX לאתר או למאגר README.