커스텀 템플릿 만들기

Firebase Studio는 언어나 프레임워크를 빠르게 시작하는 데 필요한 모든 파일, 시스템 패키지(예: 컴파일러), 확장 프로그램이 포함된 기본 제공 템플릿을 다양하게 제공합니다.

GitHub에서 호스팅되는 커뮤니티 템플릿을 사용하여 Firebase Studio 작업공간을 실행할 수도 있습니다. 템플릿에서 새 작업공간을 실행하는 방법에 대한 자세한 내용은 Firebase Studio 작업공간 만들기를 참조하세요.

대부분의 사용자는 기본 제공 템플릿을 사용하거나 Git에서 프로젝트를 가져오지만 고급 사용 사례의 경우 자체 템플릿을 만들 수 있습니다.

자체 프레임워크, 라이브러리 또는 서비스를 빌드하는 경우 사용자가 클라우드 기반 가상 머신의 모든 기능을 활용하여 브라우저를 벗어나지 않고도 기술을 빠르게 시작할 수 있도록 할 수 있습니다.
프로젝트에 선호하는 기술 스택이 있으면 커스텀 템플릿을 사용하여 새 프로젝트를 시작하는 자체 프로세스를 간소화할 수 있습니다.
튜토리얼이나 Codelab을 통해 다른 사용자를 가르치는 경우 Codelab 시작점을 커스텀 템플릿으로 사전 구성하여 학생들을 위한 초기 단계 중 일부를 삭제할 수 있습니다.

커스텀 템플릿을 만들고 테스트한 후 웹사이트, Git 저장소 README 파일, 패키지 세부정보 페이지(예: NPM) 또는 사용자가 기술을 사용할 것으로 예상되는 다른 위치에 배치할 수 있도록 링크를 만들 수 있습니다.

기본 요건

시작하기 전에 확인할 것

idx/dev.nix 파일을 사용하여 환경을 맞춤설정하는 방법을 알아봅니다.
Nix 언어 기본사항을 숙지하고 참조를 가까이에 둡니다.

템플릿 파일 구조

Firebase Studio 템플릿은 다음과 같은 파일이 최소 2개 이상 포함된 공개 Git 저장소(또는 저장소의 폴더나 브랜치)입니다.

idx-template.json에는 사용자에게 표시되는 이름, 설명, 사용자가 템플릿을 구성하는 데 사용할 수 있는 파라미터를 포함한 템플릿의 메타데이터가 포함됩니다. 예를 들어 개발자는 사용자가 여러 프로그래밍 언어나 사용 사례 예시 중에서 선택하도록 허용할 수 있습니다. Firebase Studio는 이 정보를 사용하여 사용자가 템플릿에서 새 작업공간을 만들 때 사용자에게 표시되는 UI를 준비합니다.
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 파일 2개 제외)을 사용자 작업공간에 복사합니다. 환경을 정의하는 dev.nix 파일이 있는 .idx 하위 폴더가 이미 있어야 합니다.

다음 파일을 공개 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 템플릿용 저장소 2개를 유지관리합니다.

공식 템플릿: 새 앱을 만들 때 Firebase Studio 대시보드에서 직접 선택하는 템플릿입니다.
커뮤니티 템플릿: 이 템플릿을 사용하면 오픈소스 커뮤니티의 참여를 허용할 수 있습니다. 커뮤니티 템플릿을 사용하려면 커뮤니티 템플릿 Git 저장소를 클론합니다. 사용할 템플릿에 대한 전체 링크를 사용할 수 있습니다.

도움말: 새 템플릿을 추가하거나 기존 템플릿을 업데이트하여 커뮤니티에 다시 참여하려면 pull 요청을 제출하세요.

기존 템플릿을 기반으로 커스텀 템플릿을 만들려면 다음 안내를 따르세요.

커스텀 템플릿의 기반으로 사용할 템플릿을 결정한 후 프로젝트를 클론합니다.
템플릿 맞춤설정을 시작하여 필요에 따라 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 등 추가 바이너리를 설치해야 할 수 있습니다.

dev.nix 파일의 packages에 추가하여 추가 시스템 패키지로 작업공간을 맞춤설정하는 것처럼 idx-template.nix 파일에서 packages를 지정하여 부트스트랩 스크립트에 추가 시스템 패키지를 사용할 수 있습니다.

다음은 node, npx, npm과 같은 바이너리가 포함된 pkgs.nodejs를 추가하는 예시입니다.

# 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 비교).

파라미터를 추가하려면 다음 안내를 따르세요.

idx-template.json 메타데이터 파일의 params 객체에서 파라미터를 설명합니다. Firebase Studio는 이 파일의 정보를 사용하여 템플릿 사용자에게 표시되는 UI(예: 체크박스, 드롭다운, 텍스트 입력란)를 준비합니다.
사용자가 템플릿을 인스턴스화하는 동안 선택한 값을 사용하도록 idx-template.nix 부트스트랩을 업데이트합니다.

`idx-template.json`에서 파라미터 설명

다음은 옵션 수에 따라 Firebase Studio에 드롭다운 메뉴나 라디오 버튼 그룹으로 표시되는 enum 파라미터를 추가하는 예시입니다.

{
  "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
    }
  ]
}

값이 2개(JavaScript 및 TypeScript)이므로 UI는 두 옵션의 라디오 버튼 그룹을 렌더링하고 ts 또는 js 값을 idx-template.nix 스크립트에 전달합니다.

각 파라미터 객체에는 다음과 같은 속성이 있습니다.

속성	TYPE	설명
id	`string`	변수 이름과 유사한 파라미터의 고유 ID입니다.
이름	`string`	이 파라미터의 표시 이름입니다.
유형	`string`	이 파라미터에 사용할 UI 구성요소와 부트스트랩 스크립트에 전달할 데이터 유형을 지정합니다. 유효한 값은 다음과 같습니다. `"enum"` - 드롭다운이나 라디오 버튼 그룹을 표시하고 `string`을 부트스트랩에 전달합니다. `"boolean"` - 체크박스를 표시하고 `true` 또는 `false`를 전달합니다. `"text"` - 텍스트 입력란을 표시하고 `string`을 전달합니다.
옵션	`object`	`enum` 파라미터의 경우 사용자에게 표시할 옵션을 나타냅니다. 예를 들어 옵션이 `{"js": "JavaScript", ...}`이면 'JavaScript'가 옵션으로 표시되고 이를 선택하면 이 파라미터 값은 `js`이 됩니다.
기본값	`string` 또는 `boolean`	UI에서 초기값을 설정합니다. `enum` 파라미터의 경우 `options`의 키 중 하나여야 합니다. `boolean` 파라미터의 경우 `true` 또는 `false`여야 합니다.
필수	`boolean`	이 파라미터가 필수임을 나타냅니다.

`idx-template.nix`에서 파라미터 값 사용

idx-template.json 파일에서 params 객체를 정의한 후에는 사용자가 선택한 파라미터 값을 기반으로 부트스트랩 스크립트를 맞춤설정할 수 있습니다.

이전 섹션의 예시를 따라 ID가 language이고 가능한 값으로 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-template.nix 파일이 아닌 .idx/dev.nix 파일을 업데이트하여 다음과 같이 openFiles 속성이 있는 onCreate 작업공간 후크를 포함합니다.

# .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 = { ... };
  };
}

기본 작업공간 아이콘 선택

.idx 디렉터리 내 dev.nix 파일 옆에 icon.png PNG 파일을 배치하면 템플릿으로 만든 작업공간의 기본 아이콘을 선택할 수 있습니다.

새 작업공간에서 템플릿 테스트

템플릿을 엔드 투 엔드로 테스트하는 가장 간단한 방법은 템플릿으로 새 작업공간을 만드는 것입니다. 다음 링크에 방문하여 예시를 템플릿의 GitHub 저장소 URL로 바꿉니다.

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에서 열기' 버튼에서 연결하는 URL이기도 합니다.

템플릿이 예상대로 작동하는지 확인한 후 템플릿을 GitHub 저장소에 게시하고 테스트용 작업공간을 만들 때 사용한 것과 동일한 링크를 공유합니다.

사용자가 템플릿을 더 쉽게 찾을 수 있도록 'Firebase Studio에서 열기' 버튼을 웹사이트나 저장소 README에 추가합니다.