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

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

אפשר גם להפעיל סביבת עבודה ב-Firebase Studio באמצעות תבניות של הקהילה שמתארחות ב-GitHub. מידע נוסף על הפעלת סביבת עבודה חדשה מתבנית זמין במאמר יצירת סביבת עבודה ב-Firebase Studio.

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

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

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

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

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

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

לפני שתתחיל:

• איך משתמשים בקובץ idx/dev.nix כדי להתאים אישית את הסביבה

• כדאי להכיר את העקרונות הבסיסיים של שפת Nix ולשמור את המסמך הזה לשימוש עתידי.

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

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

• idx-template.json כולל את המטא-נתונים של התבנית, כולל השם, התיאור והפרמטרים שגלויים למשתמשים כדי להגדיר את התבנית. לדוגמה, תוכלו לאפשר למשתמשים לבחור מתוך מספר שפות תכנות או תרחישים לדוגמה. Firebase Studio משתמש במידע הזה כדי להכין את ממשק המשתמש שיוצג למשתמשים כשהם יבחרו ליצור סביבת עבודה חדשה מהתבנית שלכם.

• idx-template.nix הוא קובץ שנכתב בשפת Nix ומכיל סקריפט של מעטפת Bash (עטוף בפונקציית Nix) שמבצע את הפעולות הבאות:

  1. יצירת ספריית העבודה של סביבת העבודה החדשה.

  2. מגדיר את הסביבה שלו על ידי יצירת קובץ .idx/dev.nix. הערה: אפשר גם להריץ בכלי ליצירת תשתית לפרויקט כמו flutter create או npm init בתסריט הזה, או להריץ סקריפט בהתאמה אישית שנכתב ב-Go, ב-Python, ב-Node.js או בשפה אחרת.

     הקובץ הזה יופעל עם הפרמטרים שצוינו על ידי המשתמש כשהתבנית תיטען ב-Firebase Studio.

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

יצירת תבנית להתחלה

כדי לזרז את יצירת התבנית, מומלץ להתחיל באחת מהשיטות הבאות ליצירת תבנית Firebase Studio שאפשר להתאים אישית בהמשך:

• איך הופכים כל מאגר ציבורי ב-GitHub לתבנית
• שימוש בתבנית רשמית או בתבנית משותפת כבסיס לתבנית שלכם

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

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

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

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

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/studio/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}
  '';
}

במאמר התאמה אישית של התבנית מוסבר על שינויים נוספים שאפשר לבצע בהתאמה אישית של התבנית.

יצירת תבנית בהתאמה אישית באמצעות תבנית רשמית או תבנית של קהילה

הצוות של Firebase Studio מנהל שני מאגרים של תבניות Firebase Studio:

• תבניות רשמיות: אלה התבניות שבוחרים ישירות בלוח הבקרה Firebase Studio כשיוצרים אפליקציה חדשה.

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

כדי ליצור תבנית בהתאמה אישית על סמך תבנית קיימת:

1. בוחרים תבנית שתשמש כבסיס לתבנית בהתאמה אישית, ולאחר מכן מעתיקים את הפרויקט.

2. מתאימים אישית את idx-template.json,‏ idx-template.nix ו-.idx/dev.nix לפי הצורך, החל מהתאמה אישית של התבנית.

3. מוסיפים את השינויים למאגר.

4. כדי לפרסם ולבדוק את התבנית, פועלים לפי ההוראות במאמר יצירת סביבת עבודה חדשה לתבנית. אם אתם משתמשים במאגר בתצוגת עץ, צריך לקשר אליו ישירות בכתובת ה-URL. לדוגמה, אם משתמשים בתבנית 'Vanilla Vite' של הקהילה, צריך להקצות ולבדוק סביבת עבודה חדשה באמצעות כתובת ה-URL הבאה:

   https://studio.firebase.google.com/new?template=https://github.com/project-idx/community-templates/tree/main/vite-vanilla
   

במאמר התאמה אישית של התבנית מוסבר על שינויים נוספים שאפשר לבצע בהתאמה אישית של התבנית.

התאמה אישית של התבנית

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

• מוסיפים חבילות מערכת לתסריט bootstrap.
• הוספת פרמטרים שניתן להגדיר על ידי משתמשים
• בחירת הקבצים שייפתחו כברירת מחדל
• בחירת סמל ברירת מחדל לסביבת העבודה

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

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

כדי להפוך חבילות מערכת נוספות לזמינות לסקריפט ה-bootstrap, מציינים את 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).

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

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

מתארים את הפרמטר ב-idx-template.json

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

{
  "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.

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

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

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

בהמשך לדוגמה בקטע הקודם, אם יש לכם פרמטר יחיד עם המזהה 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!) כך שיכלול הוק של סביבת העבודה 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 = { ... };
  };
}

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

כדי לבחור את סמל ברירת המחדל למרחבי עבודה שנוצרים באמצעות התבנית, צריך להוסיף קובץ PNG בשם icon.png לצד הקובץ dev.nix בתיקייה .idx.

בדיקת התבנית בסביבת עבודה חדשה

הדרך הפשוטה ביותר לבדוק את התבנית מקצה לקצה היא ליצור סביבת עבודה חדשה באמצעותה. נכנסים לקישור הבא ומחליפים את הדוגמה בכתובת ה-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 שאליה תקשרו דרך הלחצן 'פתיחה ב-Firebase Studio'.

שיתוף התבנית

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

כדי להקל עוד יותר על המשתמשים למצוא את התבנית, מוסיפים לחצן 'פתיחה ב-Firebase Studio' לקובץ README באתר או במאגר.