Firebase Studio cung cấp nhiều mẫu tích hợp sẵn bao gồm tất cả các tệp, gói hệ thống (ví dụ: trình biên dịch) và tiện ích mà bạn cần để nhanh chóng bắt đầu sử dụng một ngôn ngữ hoặc khung.
Bạn cũng có thể khởi chạy không gian làm việc Firebase Studio bằng các mẫu cho cộng đồng được lưu trữ trên GitHub. Để biết thêm thông tin về cách khởi chạy một không gian làm việc mới từ một mẫu, hãy xem bài viết Tạo không gian làm việc.Firebase Studio
Hầu hết người dùng sẽ sử dụng các mẫu tích hợp sẵn hoặc nhập dự án từ Git, nhưng đối với các trường hợp sử dụng nâng cao hơn, bạn có thể tạo mẫu của riêng mình:
Nếu bạn đang xây dựng khung, thư viện hoặc dịch vụ của riêng mình, bạn có thể cho phép người dùng nhanh chóng bắt đầu sử dụng công nghệ của bạn mà không cần rời khỏi trình duyệt, với toàn bộ sức mạnh của một máy ảo dựa trên đám mây.
Nếu có ngăn xếp công nghệ ưu tiên cho các dự án, bạn có thể đơn giản hoá quy trình của riêng mình để bắt đầu các dự án mới bằng một mẫu tuỳ chỉnh.
Nếu bạn đang dạy người khác, chẳng hạn như thông qua một hướng dẫn hoặc lớp học lập trình, bạn có thể loại bỏ một số bước ban đầu cho học viên bằng cách định cấu hình trước điểm xuất phát cho lớp học lập trình dưới dạng một mẫu tuỳ chỉnh.
Sau khi tạo và kiểm thử mẫu tùy chỉnh, bạn có thể tạo một đường liên kết cho
mẫu đó để đặt trên trang web, tệp README kho lưu trữ Git, trang chi tiết gói (ví dụ: trong NPM) hoặc
bất kỳ vị trí nào khác mà bạn muốn người dùng bắt đầu sử dụng công nghệ của bạn.
Điều kiện tiên quyết
Trước khi bạn bắt đầu:
Tìm hiểu cách sử dụng tệp
idx/dev.nixđể tuỳ chỉnh môi trường.Làm quen với các khái niệm cơ bản về ngôn ngữ Nix và luôn có tài liệu tham khảo.
Cấu trúc tệp mẫu
Mẫu Firebase Studio là một kho lưu trữ Git công khai (hoặc thư mục hoặc nhánh trong một kho lưu trữ) chứa ít nhất hai tệp:
idx-template.jsonbao gồm siêu dữ liệu cho mẫu, bao gồm tên, nội dung mô tả và các tham số mà người dùng có thể thấy để định cấu hình mẫu. Ví dụ: bạn có thể cho phép người dùng chọn trong số một số ngôn ngữ lập trình hoặc các trường hợp sử dụng mẫu. Firebase Studio sử dụng thông tin này để chuẩn bị giao diện người dùng hiển thị cho người dùng khi họ chọn tạo một không gian làm việc mới từ mẫu của bạn.idx-template.nixlà một tệp được viết bằng ngôn ngữ Nix chứa một tập lệnh shell Bash (được gói trong một hàm Nix) có chức năng:Tạo thư mục làm việc cho không gian làm việc mới.
Thiết lập môi trường bằng cách tạo tệp
.idx/dev.nix. Xin lưu ý rằng bạn cũng có thể chỉ chạy một công cụ tạo khung dự án nhưflutter createhoặcnpm inittrong tập lệnh này, hoặc chạy một tập lệnh tuỳ chỉnh được viết bằng Go, Python, Node.js hoặc một ngôn ngữ khác.Tệp này sẽ được thực thi với các tham số do người dùng chỉ định khi Firebase Studio tải mẫu.
Các tệp khác có thể được đưa vào cùng với hai tệp này để sử dụng trong idx-template.nix nhằm tạo thực thể cho mẫu. Ví dụ: bạn có thể đưa tệp .idx/dev.nix cuối cùng hoặc thậm chí đưa tất cả các tệp tạo khung ngay trong kho lưu trữ.
Tạo mẫu khởi động
Để đẩy nhanh quá trình tạo mẫu, bạn nên bắt đầu bằng một trong các phương thức sau để tạo mẫu Firebase Studio mà bạn có thể tuỳ chỉnh thêm:
- Biến mọi kho lưu trữ GitHub công khai thành một mẫu
- Sử dụng mẫu chính thức hoặc mẫu cho cộng đồng làm cơ sở cho mẫu của bạn
Ví dụ cơ bản: Biến mọi kho lưu trữ GitHub công khai thành một mẫu
Trước khi đi vào chi tiết về cách xác định idx-template.json và idx-template.nix, bạn nên xem một mẫu ví dụ cơ bản:
- Không chứa tham số mà người dùng có thể định cấu hình.
- Sao chép tất cả các tệp trong kho lưu trữ mẫu (ngoại trừ hai tệp
idx-template) vào không gian làm việc của người dùng. Phải có một thư mục con.idxvới tệpdev.nixxác định môi trường.
Nếu bạn thêm các tệp sau vào bất kỳ kho lưu trữ GitHub công khai nào (hoặc thư mục con hoặc nhánh), thì điều này sẽ biến kho lưu trữ đó thành một Firebase Studio mẫu.
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}
'';
}
Chuyển đến phần Tuỳ chỉnh mẫu để tìm hiểu về các thay đổi bổ sung mà bạn có thể thực hiện để tuỳ chỉnh mẫu.
Tạo mẫu tùy chỉnh bằng mẫu chính thức hoặc mẫu cho cộng đồng
Nhóm Firebase Studio duy trì hai kho lưu trữ cho Firebase Studio mẫu:
Mẫu chính thức: Đây là các mẫu mà bạn chọn trực tiếp từ Firebase Studio trang tổng quan khi tạo một ứng dụng mới.
Mẫu cho cộng đồng: Các mẫu này cho phép đóng góp từ cộng đồng nguồn mở. Để sử dụng mẫu cho cộng đồng, hãy sao chép kho lưu trữ Git mẫu cho cộng đồng. Bạn có thể sử dụng đường liên kết đầy đủ đến mẫu mà bạn muốn sử dụng.
Cách tạo mẫu tùy chỉnh dựa trên mẫu hiện có:
Quyết định mẫu nào sẽ dùng làm cơ sở cho mẫu tùy chỉnh của bạn, sau đó sao chép dự án.
Tuỳ chỉnh
idx-template.json,idx-template.nix, và.idx/dev.nixkhi cần, bắt đầu bằng phần Tuỳ chỉnh mẫu.Kiểm tra các thay đổi vào kho lưu trữ của bạn.
Làm theo hướng dẫn trong phần Tạo không gian làm việc mới cho mẫu để xuất bản và kiểm thử mẫu. Nếu bạn sử dụng kho lưu trữ lồng nhau, hãy liên kết trực tiếp đến kho lưu trữ đó trong URL. Ví dụ: nếu bạn đang sử dụng mẫu "Vanilla Vite" cho cộng đồng, bạn sẽ cung cấp và kiểm thử một không gian làm việc mới bằng URL sau:
https://studio.firebase.google.com/new?template=https://github.com/firebase-studio/community-templates/tree/main/vite-vanilla
Chuyển đến phần Tuỳ chỉnh mẫu để tìm hiểu về các thay đổi bổ sung mà bạn có thể thực hiện để tuỳ chỉnh mẫu.
Tuỳ chỉnh mẫu của bạn
Giờ đây, khi đã tạo một mẫu cơ bản để xây dựng, bạn có thể chỉnh sửa các tệp idx-template.json, idx-template.nix và .idx/dev.nix để phù hợp với yêu cầu của mình. Bạn có thể muốn tuỳ chỉnh các cấu hình bổ sung:
- Thêm gói hệ thống vào tập lệnh
bootstrap. - Thêm tham số mà người dùng có thể định cấu hình
- Chọn tệp sẽ mở theo mặc định
- Chọn biểu tượng không gian làm việc mặc định
Sử dụng các gói hệ thống bổ sung trong tập lệnh bootstrap
Ví dụ cơ bản chỉ sử dụng các lệnh POSIX cơ bản để sao chép
tệp vào đúng vị trí. Tập lệnh bootstrap của mẫu có thể yêu cầu cài đặt các tệp nhị phân bổ sung, chẳng hạn như git, node, python3 hoặc các tệp khác.
Bạn có thể cung cấp các gói hệ thống bổ sung cho tập lệnh khởi động
bằng cách chỉ định packages trong tệp idx-template.nix, giống như cách bạn
tuỳ chỉnh không gian làm việc bằng các gói hệ thống
bổ sung bằng cách thêm vào
packages trong tệp dev.nix.
Dưới đây là ví dụ về cách thêm pkgs.nodejs, bao gồm các tệp nhị phân như node,
npx và 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"
''
}
Thêm tham số mà người dùng có thể định cấu hình
Để cho phép người dùng tuỳ chỉnh điểm xuất phát cho dự án mới, bạn có thể tạo nhiều mẫu hoặc tạo một mẫu có tham số.
Đây là một lựa chọn tuyệt vời nếu các điểm bắt đầu khác nhau của bạn chỉ là các giá trị khác nhau được truyền đến một công cụ CLI (ví dụ: --language=js so với --language=ts).
Để thêm tham số, bạn sẽ:
- Mô tả tham số trong đối tượng
paramscủa tệp siêu dữ liệuidx-template.json. Firebase Studio sử dụng thông tin trong tệp này để chuẩn bị giao diện người dùng (chẳng hạn như hộp đánh dấu, trình đơn thả xuống và trường văn bản) hiển thị cho người dùng mẫu của bạn. - Cập nhật quá trình khởi động
idx-template.nixđể sử dụng các giá trị mà người dùng đã chọn trong khi tạo thực thể cho mẫu.
Mô tả tham số trong idx-template.json
Dưới đây là ví dụ về cách thêm tham số enum, mà Firebase Studio
hiển thị dưới dạng trình đơn thả xuống hoặc nhóm nút chọn, tuỳ thuộc vào số lượng lựa chọn:
{
"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
}
]
}
Vì có hai giá trị (JavaScript và TypeScript), nên giao diện người dùng sẽ hiển thị một nhóm nút chọn cho hai lựa chọn và truyền giá trị ts hoặc js đến tập lệnh idx-template.nix.
Mỗi đối tượng tham số có các thuộc tính sau:
| TÀI SẢN | LOẠI | NỘI DUNG MÔ TẢ |
|---|---|---|
| id | string |
Mã nhận dạng riêng biệt của tham số, tương tự như tên biến. |
| name | string |
Tên hiển thị cho tham số này. |
| type | string |
Chỉ định thành phần giao diện người dùng để sử dụng cho tham số này và kiểu dữ liệu để truyền đến tập lệnh khởi động. Các giá trị hợp lệ là:
|
| tuỳ chọn | object |
Đối với các tham số enum, tham số này biểu thị các lựa chọn để hiển thị cho người dùng. Ví dụ: nếu các lựa chọn là {"js": "JavaScript", ...}, "JavaScript" sẽ được hiển thị dưới dạng lựa chọn và khi được chọn, giá trị của tham số này sẽ là js. |
| mặc định | string hoặc boolean |
Đặt giá trị ban đầu trong giao diện người dùng. Đối với các tham số enum, đây phải là một trong các khoá trong options. Đối với các tham số boolean, đây phải là true hoặc false. |
| bắt buộc | boolean |
Cho biết tham số này là bắt buộc. |
Sử dụng giá trị tham số trong idx-template.nix
Sau khi xác định đối tượng params trong tệp idx-template.json, bạn có thể bắt đầu tuỳ chỉnh tập lệnh khởi động dựa trên các giá trị tham số mà người dùng chọn.
Theo ví dụ trong phần trước, nếu bạn có một tham số có mã nhận dạng language là một enum có các giá trị có thể là ts hoặc js, bạn có thể sử dụng như sau:
# 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}
''
}
Một mẫu phổ biến khác là bao gồm nội dung một cách có điều kiện tuỳ thuộc vào giá trị của một chuỗi. Một cách khác để viết ví dụ trước là:
npm init --yes my-boot-strap@latest "$out" -- \
${if language == "ts" then "--lang=ts" else "--lang=js" }
Chọn tệp sẽ mở theo mặc định
Bạn nên tuỳ chỉnh tệp sẽ mở để chỉnh sửa khi không gian làm việc mới được tạo bằng mẫu của bạn. Ví dụ: nếu mẫu của bạn dành cho một trang web cơ bản, bạn có thể muốn mở các tệp HTML, JavaScript và CSS chính.
Để tuỳ chỉnh tệp sẽ mở theo mặc định, hãy cập nhật tệp .idx/dev.nix (không phải tệp idx-template.nix!) để bao gồm móc nối không gian làm việc onCreate có thuộc tính openFiles, như sau:
# .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 = { ... };
};
}
Chọn biểu tượng không gian làm việc mặc định
Bạn có thể chọn biểu tượng mặc định cho các không gian làm việc được tạo bằng mẫu của mình bằng cách đặt tệp PNG có tên icon.png bên cạnh tệp dev.nix, bên trong thư mục .idx.
Kiểm thử mẫu trong không gian làm việc mới
Cách đơn giản nhất để kiểm thử mẫu từ đầu đến cuối là tạo một không gian làm việc mới bằng mẫu đó. Truy cập vào đường liên kết sau, thay thế ví dụ bằng URL kho lưu trữ GitHub của mẫu:
https://idx.google.com/new?template=https://github.com/my-org/my-repo
Bạn có thể thêm nhánh và thư mục con nếu muốn. Tất cả các mục sau đều hợp lệ, miễn là có thể truy cập công khai:
https://github.com/my-org/my-repo/https://github.com/my-org/my-repo/tree/main/path/to/myidxtemplatehttps://github.com/my-org/my-repo/tree/branchhttps://github.com/my-org/my-repo/tree/branch/path/to/myidxtemplate
Đây cũng là URL mà bạn sẽ chia sẻ với người khác để họ có thể sử dụng mẫu mới của bạn hoặc URL mà bạn sẽ liên kết đến từ nút "Mở trong Firebase Studio".
Chia sẻ mẫu của bạn
Sau khi xác nhận rằng mẫu của bạn hoạt động như mong đợi, hãy xuất bản mẫu đó vào kho lưu trữ GitHub và chia sẻ cùng một đường liên kết mà bạn đã sử dụng khi tạo không gian làm việc để kiểm thử.
Và để giúp người dùng dễ dàng tìm thấy mẫu của bạn hơn, hãy thêm nút "Mở trong Firebase Studio" vào trang web hoặc README kho lưu trữ.