> For the complete documentation index, see [llms.txt](https://docs.decentraland.org/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.decentraland.org/creator/content-creator-ko/sdk7/libraries/create-libraries.md).

# 라이브러리 만들기

다른 사람들과 공유할 수 있도록 자신만의 Decentraland 라이브러리를 만드세요

라이브러리는 일반적인 문제에 대한 해결책을 공유하는 좋은 방법입니다. 복잡한 문제를 한 번 해결하고, 그 해결책을 라이브러리로 묶어 두면, 나중에 같은 문제가 생겼을 때 코드 한 줄만 작성하면 됩니다. 커뮤니티와 라이브러리를 공유하면 모든 제작자의 생산성을 기하급수적으로 높일 수 있습니다.

현재 [예제 페이지](https://studios.decentraland.org/resources?sdk_version=SDK7\&resource_type=Library) 의 라이브러리는 누구나 사용할 수 있습니다. 여러분도 직접 라이브러리를 만들어 공유해 보세요.

여기에 설명된 단계를 따르면 Decentraland 씬과 호환되고 다른 사람과 쉽게 공유할 수 있는 라이브러리를 만들 때 따르는 복잡한 과정을 대부분 피할 수 있습니다.

## 라이브러리 만들기

> **📔 참고**: 라이브러리를 빌드하기 전에 Node 버전 20 이상을 사용하고 있는지 확인하세요.

자신만의 라이브러리를 만들어 NPM을 통해 공유하려면 다음 단계를 따르세요.

1. 새 빈 폴더를 만들고 해당 폴더에서 VS Studio Code 새 창을 여세요.
2. Visual Studio 왼쪽 사이드바에서 Decentraland 탭을 선택합니다
3. 클릭 **프로젝트 만들기**, 그런 다음 선택합니다 **라이브러리**

   Decentraland 라이브러리에 필요한 모든 기본 파일과 종속 항목이 생성됩니다.
4. 고유한 `name` 을(를) `package.json`. 이 이름은 NPM에 게시할 때 사용됩니다. npm에 같은 이름을 사용하는 기존 프로젝트가 없는지 확인하세요. 다른 사람들이 라이브러리를 찾는 데 도움이 되도록 설명과 태그도 입력하세요.
5. 새로 만들기 *공개* 프로젝트의 GitHub 저장소.

   프로젝트는 다음에 푸시할 때마다 패키지의 새 버전을 게시하도록 GitHub Actions를 사용하도록 구성되어 있습니다. `main`.

   다음 `package.json` 파일에서, 다음 항목에 `repository` 다음을 가리키도록 `url` 필드를 저장소 URL로 설정합니다. 그러면 npmjs.com을 둘러보는 사용자가 저장소를 쉽게 찾을 수 있습니다. [npmjs.com](https://www.npmjs.com).
6. NPM 토큰 가져오기:
   1. <https://www.npmjs.com/에서> 계정을 만들거나 로그인합니다.
   2. 다음으로 이동합니다. **계정 > 액세스 토큰 > 새 토큰 생성** 새 토큰을 만들고 다음 권한을 부여합니다. **게시** 권한.

      성공 메시지에는 새로 생성된 토큰 문자열이 포함됩니다. 이 문자열을 복사해 안전한 곳에 저장하세요.
7. GitHub 리포지토리에서 다음으로 이동합니다. **설정 > 보안 비밀 > 작업**, 그런 다음 **새 리포지토리 보안 비밀**.

   보안 비밀 이름을 **NPM\_TOKEN**으로 지정하고, NPM 토큰 문자열을 값으로 붙여 넣으세요.
8. GitHub 리포지토리의 main 브랜치에 변경 사항(무엇이든)을 푸시하면 패키지가 게시됩니다.

   이제 누구나 다음 명령을 사용해 패키지를 설치할 수 있습니다. `npm i <package-name>`! 이제 [npmjs.com](https://www.npmjs.com).
9. 프로젝트의 `/src` 폴더에 공개하려는 모든 기능을 추가하고 변경 사항을 GitHub에 푸시하세요.

## 개발

라이브러리에서 공개하려는 함수, 컴포넌트 등을 `index.ts` 파일에 추가하면 쉽게 가져올 수 있습니다.

예를 들어 `RotatorComponent` 컴포넌트를 `index.ts`에 추가하면, 다음과 같이 작성해 씬으로 가져올 수 있습니다.

`import { RotatorComponent } from 'my-library'`

개발하는 동안 새 Decentraland 씬에서 라이브러리를 사용해 테스트하세요. 다음 명령을 실행해 npm 패키지를 씬에 설치합니다. `npm i <package-name>`. 그런 다음 라이브러리 기능을 시험해 볼 씬을 만들어 보세요. 모든 경우에 라이브러리가 예상대로 작동하는지 확인할 수 있도록 다양한 테스트 사례를 씬에서 다뤄 보세요.

### 빠른 반복 작업

라이브러리를 계속 조금씩 수정하고 테스트해야 한다면, 변경 사항을 커밋한 뒤 npm 게시가 완료될 때까지 기다려야 씬에서 새 버전을 시험할 수 있어 번거로울 수 있습니다. 다행히 라이브러리 테스트를 훨씬 빠르게 실행하는 방법이 있습니다.

다음의 **테스트 씬 프로젝트**:

1. 다음 스크립트를 `scripts` package.json의 목록에 추가하세요. `"link-sdk": "cd node_modules/@dcl/sdk && npm link && cd ../js-runtime && npm link"`
2. 실행합니다. `npm install`
3. 실행합니다. `npm install YOUR_LIBRARY_PATH`예를 들면 다음과 같습니다. `npm install /User/projects/dcl-sdk7-library-test`
4. 실행합니다. `npm run link-sdk`

다음 **라이브러리 프로젝트**:

1. 실행합니다. `npm install`
2. 에서 `npm run build`
3. 실행합니다. `npm link @dcl/sdk @dcl/js-runtime`

> **❗경고**: 이 단계의 순서가 중요합니다. 순서를 바꾸면 제대로 작동하지 않을 수 있습니다.

이렇게 하면 씬이 로컬 드라이브에 있는 라이브러리 버전과 동기화됩니다. 테스트하려는 라이브러리 변경 사항이 있으면 라이브러리 폴더에서 `npm run build` 를 실행하기만 하면 됩니다. 변경 사항을 GitHub나 NPM에 게시할 필요가 없습니다.

> **💡 팁**: 링크가 제대로 설정되었는지 확인하려면 `npm ls --link`를 실행하세요. 로컬 파일의 폴더를 가리키는 라이브러리 이름이 표시되어야 합니다.

라이브러리를 변경한 경우 업데이트하려면 `npm run build` 를 실행해야 합니다. 매번 실행하지 않으려면 다음을 수행하세요.

1. 라이브러리에 스크립트 "start": "tsc -p tsconfig.json --watch"를 추가합니다.
2. 다음을 실행합니다. `npm start` 를 라이브러리에서 실행합니다.

테스트를 마쳤으면 라이브러리 연결을 해제하는 것을 잊지 마세요.

1. scene 폴더에서 다음을 실행합니다. `npm install <library name>`
2. 그런 다음 라이브러리에서 다음을 실행합니다. `rm -rf node_modules && npm install`

## 버전 관리

라이브러리 버전은 다음 위치에 자동으로 게시됩니다. `npm` 다음 플래그와 함께 `@latest` 및 `@next` 를 사용합니다.

@next `@next` 플래그는 항상 `main` 브랜치의 최신 커밋을 가리킵니다. 마지막 변경 사항이 테스트되지 않았을 수 있으므로 이 버전은 불안정할 수 있습니다. 라이브러리 사용자는 다음 명령을 실행해 설치할 수 있습니다(위험은 감수해야 합니다). `npm i <library name>@next`.

@latest `@latest` 플래그는 라이브러리의 최신 안정 버전을 가리킵니다. 일반적으로 라이브러리 사용자는 이 버전을 설치해야 합니다. 사용자가 다음 명령을 실행할 때 npm이 가져오는 버전입니다. `npm i <library name>`.

@latest `@latest` 플래그가 최신 커밋을 가리키게 하려면 GitHub에서 라이브러리의 **릴리스** 를 만들어야 합니다.

1. 프로젝트의 GitHub 페이지를 엽니다. 페이지 오른쪽 여백에 있는 **릴리스** 링크를 엽니다.
2. 다음을 클릭합니다. **새 릴리스 초안 작성**.
3. 에서 **태그 선택** 새 버전의 이름을 입력합니다(예: "1.1.0"). 또한 **릴리스 제목**에 이름을 입력합니다. 보통 버전 이름인 "1.1.0"과 동일합니다.

   > 중요: 태그는 숫자만으로 이루어져야 하며 문자나 기호를 추가해서는 안 됩니다. 숫자는 이전에 게시된 릴리스의 숫자보다 커야 합니다.
4. 릴리스 내용을 설명해 사용자가 새로 추가된 사항을 알 수 있도록 합니다.

   > 팁: 다음 버튼을 클릭하면 **릴리스 노트 자동 생성** 마지막 릴리스 이후의 모든 커밋을 출력할 수 있습니다.
5. 누르기 **릴리스 게시**. 이 작업은 다음을 사용하여 npm에 새 자동 게시를 실행합니다. `@latest` 플래그. 이제 라이브러리 사용자는 이 버전을 다운로드하게 됩니다.

## 사용성에 관한 참고 사항

다른 제작자가 라이브러리를 쉽게 사용할 수 있도록 최선을 다하세요. 우리가 가진 가정은 우리가 만드는 도구에 늘 영향을 미칩니다. 흔히 이런 가정은 우리에게 당연해 보이지만, 다른 맥락에 있는 사람들은 전혀 다른 가정을 할 수 있습니다.

* 함수, 컴포넌트, 매개변수를 비롯해 라이브러리의 모든 요소에 이름을 신중하게 붙이세요. 짧지만 전혀 의미를 알 수 없는 이름보다는 길더라도 설명이 잘 되는 이름이 낫습니다.
* 라이브러리를 사용할 수 있는 다양한 사례를 폭넓게 고려하세요. 누군가는 스마트 웨어러블 기기에서 라이브러리를 사용할 수도 있고, 시스템을 특정 시점에 켜거나 꺼야 할 수도 있으며, 같은 장면에 시스템을 여러 개 추가해야 할 수도 있습니다. 모든 사람이 여러분과 같은 문제를 겪는 것은 아닙니다.
* 그렇다고 해서 가능한 모든 사용 사례를 지원해야 하는 것은 아닙니다. 실제로 유연성과 사용 편의성 사이에는 늘 절충이 필요합니다. 좋은 도구를 만드는 일은 적절한 균형을 찾는 것입니다. 지원하지 않을 기능의 범위를 전략적으로 정하세요. 다만 어떤 제한을 두기로 했는지 명확하게 문서화하는 것이 중요합니다.
* 이제 문서화에 대해 살펴보겠습니다. 예시와 각 매개변수의 역할에 대한 설명, 작동하지 않는 상황에 대한 참고 사항, 그리고 사용 환경에 관해 여러분이 전제한 내용을 포함해 라이브러리를 명확하게 문서화하세요. 보통 라이브러리의 README.md에 이러한 내용을 정리하는 것이 가장 좋습니다.
* 또 다른 유용한 방법은 코드에 메타데이터 주석을 직접 추가하는 것입니다. 이런 주석은 사용자가 라이브러리 코드를 입력할 때 IDE(예: VS Studio Code)에 표시됩니다. 각 함수나 컴포넌트의 용도, 각 매개변수에 전달해야 하는 값, 함수가 반환하는 값을 설명할 수 있습니다. 덕분에 라이브러리 사용자는 코드와 문서를 오갈 필요 없이 필요한 내용을 한곳에서 모두 확인할 수 있습니다! 예를 들어 다음에서 이 함수를 살펴보세요. `@dcl/ecs-scene-utils` 라이브러리:

  ```ts
  /**
   * 값이 최솟값보다 작거나 최댓값보다 크지 않도록 제한합니다.
   *
   * @param value - 입력 숫자
   * @param min - 최솟값
   * @param max - 최댓값
   * @returns 최솟값과 최댓값 사이에 매핑된 결과 값
   * @public
   */
  export function clamp(value: number, min: number, max: number) {
  	let result = value

  	if (value > max) {
  		result = max
  	} else if (value < min) {
  		result = min
  	}
  	return result
  }
  ```

  라이브러리 사용자는 다음을 입력할 때 이러한 힌트를 볼 수 있습니다. `clamp()` 함수:
* 항상 타입을 선언하세요. 사용자가 어떤 객체 구조를 다뤄야 할지 추측하게 두지 마세요.
* 라이브러리는 가볍게 유지하고 한 가지 기능에 집중하세요. Decentraland 장면을 컴파일하면 라이브러리의 모든 코드가 장면과 함께 패키징됩니다. 장면에서 호출하지 않는 코드도 마찬가지입니다. 따라서 용량이 크고 무거운 라이브러리는 만들지 않는 것이 좋습니다. 제작자가 필요한 기능만 골라 사용할 수 있도록 간결한 라이브러리를 만드는 편이 낫습니다.
* 라이브러리의 저장소를 계속 확인하세요. 사람들이 풀 리퀘스트를 보내거나 문제를 신고할 수 있습니다.
* 저장소에 라이선스 정보를 포함해 다른 사람들이 라이브러리를 자유롭게 사용할 수 있는지 알 수 있게 하세요. 기본 라이브러리에는 Apache 2 오픈 라이선스가 포함되어 있으며, 원한다면 변경해도 됩니다.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.decentraland.org/creator/content-creator-ko/sdk7/libraries/create-libraries.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
