یک قالب سفارشی ایجاد کنید

با مجموعه‌ها، منظم بمانید ذخیره و طبقه‌بندی محتوا براساس اولویت‌های شما.

Firebase Studio طیف وسیعی از قالب‌های داخلی را ارائه می‌کند که شامل تمام فایل‌ها، بسته‌های سیستمی (مثلاً کامپایلرها) و افزونه‌هایی است که برای شروع سریع با یک زبان یا فریمورک به آن‌ها نیاز دارید.

همچنین می‌توانید با استفاده از قالب‌های انجمن میزبانی شده در GitHub، یک فضای کاری Firebase Studio راه‌اندازی کنید. برای اطلاعات بیشتر درباره راه‌اندازی یک فضای کاری جدید از یک الگو، به ایجاد فضای کاری Firebase Studio مراجعه کنید.

اکثر کاربران از قالب‌های داخلی استفاده می‌کنند یا پروژه‌هایی را از Git وارد می‌کنند، اما برای موارد استفاده پیشرفته‌تر، می‌توانید الگوهای خود را ایجاد کنید:

• اگر چارچوب، کتابخانه یا سرویس خود را می‌سازید، می‌توانید با قدرت کامل یک ماشین مجازی مبتنی بر ابر، به کاربران خود اجازه دهید به سرعت با فناوری شما بدون ترک مرورگر شروع کنند.

• اگر پشته فناوری ترجیحی برای پروژه های خود دارید، می توانید فرآیند خود را برای شروع پروژه های جدید با یک الگوی سفارشی ساده کنید.

• اگر به دیگران آموزش می‌دهید، مثلاً از طریق یک برنامه آموزشی یا نرم‌افزار کد ، می‌توانید برخی از مراحل اولیه را برای دانش‌آموزان خود با از قبل پیکربندی نقطه شروع برای 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 تنظیم می کند. توجه داشته باشید که شما همچنین می توانید یک ابزار scaffolding پروژه مانند 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 یا موارد دیگر داشته باشد.

می‌توانید با تعیین 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. بوت استرپ 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
    }
  ]
}

از آنجایی که دو مقدار وجود دارد (جاوا اسکریپت و تایپ اسکریپت)، رابط کاربری یک گروه دکمه رادیویی را برای دو گزینه ارائه می دهد و مقدار ts یا js را به اسکریپت idx-template.nix ارسال می کند.

هر شی پارامتر دارای ویژگی های زیر است:

از مقادیر پارامتر در idx-template.nix استفاده کنید

پس از تعریف شیء params در فایل idx-template.json خود، می توانید سفارشی سازی اسکریپت بوت استرپ را بر اساس مقادیر پارامتری که کاربر انتخاب می کند شروع کنید.

به دنبال مثال در بخش قبل، اگر یک پارامتر با language ID دارید که یک 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، جاوا اسکریپت و 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

همچنین این نشانی اینترنتی است که با دیگران به اشتراک می گذارید تا بتوانند از الگوی جدید شما استفاده کنند، یا نشانی اینترنتی که از دکمه «باز کردن در Firebase Studio » به آن پیوند می دهید.

قالب خود را به اشتراک بگذارید

پس از اینکه تأیید کردید که الگوی شما مطابق انتظار عمل می کند، آن را در یک مخزن GitHub منتشر کنید و همان پیوندی را که هنگام ایجاد یک فضای کاری برای آزمایش استفاده کرده اید، به اشتراک بگذارید.

و برای اینکه کاربران بتوانند الگوی شما را حتی آسان‌تر پیدا کنند، دکمه «Open in Firebase Studio » را به وب‌سایت یا مخزن README خود اضافه کنید.