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

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

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

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

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

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

אחרי שיוצרים תבנית בהתאמה אישית ובודקים אותה, אפשר ליצור קישור לתבנית ולהוסיף אותו לאתר, לקובץ 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 הסופי, או אפילו לכלול את כל קובצי ה-scaffolding ישירות במאגר.

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

כדי ליצור תבנית במהירות, מומלץ להתחיל באחת מהשיטות הבאות ליצירת תבנית 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 של התבניות המשותפות. אפשר להשתמש בקישור המלא לתבנית שבה רוצים להשתמש.

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

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

מחליטים באיזו תבנית רוצים להשתמש כבסיס לתבנית המותאמת אישית, ואז משכפלים את הפרויקט.
מתאימים אישית את idx-template.json, idx-template.nix ו-.idx/dev.nix לפי הצורך, החל מהתאמה אישית של התבנית.
בודקים את השינויים במאגר.
כדי לפרסם ולבדוק את התבנית, פועלים לפי השלבים במאמר יצירת סביבת עבודה חדשה לתבנית. אם אתם משתמשים במאגר מקונן, אתם צריכים לקשר אליו ישירות בכתובת ה-URL. לדוגמה, אם השתמשתם בתבנית הקהילה Vanilla Vite, תצטרכו להקצות ולבדוק סביבת עבודה חדשה באמצעות כתובת ה-URL הבאה:
```
https://studio.firebase.google.com/new?template=https://github.com/firebase-studio/community-templates/tree/main/vite-vanilla
```

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

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

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

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

שימוש בחבילות מערכת נוספות בסקריפט `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. ‫Firebase Studio משתמש במידע שבקובץ הזה כדי להכין את ממשק המשתמש (למשל תיבות סימון, תפריטים נפתחים ושדות טקסט) שמוצג למשתמשים בתבנית.
מעדכנים את 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.

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

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

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

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

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

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

אתם יכולים לבחור את סמל ברירת המחדל לסביבות עבודה שנוצרו באמצעות התבנית שלכם, על ידי הצבת קובץ 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 של המאגר.