> 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를 사용하여 다음으로의 모든 push마다 패키지의 새 버전을 게시하도록 구성되어 있습니다. `main`.

   다음에서 `package.json` 파일에서, 다음에서 `저장소` 에서 `url` 필드를 repo의 URL로 지정하세요. 그러면 사용자가 [npmjs.com](https://www.npmjs.com).
6. NPM 토큰 받기:
   1. <https://www.npmjs.com/에서> 계정을 만들거나 로그인하세요.
   2. 다음으로 이동하세요 **Account > Access Tokens > Generate new Token** 새 토큰을 만들고, **게시** 권한을 부여하세요.

      성공 메시지에는 새로 생성된 토큰의 문자열이 포함됩니다. 이 문자열을 복사해 안전한 곳에 보관하세요.
7. github 저장소에서 다음으로 이동하세요 **Settings > Secrets > Actions**, 그런 다음 **New Repository Secret**.

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

   이제 끝입니다. 이제 누구나 다음을 사용해 패키지를 설치할 수 있습니다 `npm i <package-name>`! 이제 [npmjs.com](https://www.npmjs.com).
9. 프로젝트의 `/src` 폴더를, 노출하고 싶은 모든 기능으로 채우고 GitHub에 변경 사항을 push하세요.

## 개발

라이브러리의 `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. 라이브러리의 package.json에 "start": "tsc -p tsconfig.json --watch" 스크립트를 추가하세요
2. 실행 `npm start` 를 라이브러리에서

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

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

## 버전 관리

라이브러리 버전은 자동으로 다음에 게시됩니다 `npm` 와 함께 `@latest` 그리고 `@next` 플래그.

그 `@next` 플래그는 항상 `main` 브랜치의 마지막 커밋을 가리킵니다. 이 버전은 마지막 변경 사항이 테스트되지 않았을 수 있으므로 불안정할 수 있습니다. 라이브러리 사용자는 다음과 같이(자체 책임 하에) 설치할 수 있습니다 `npm i <library name>@next`.

그 `@latest` 플래그는 라이브러리의 마지막 안정 릴리스를 가리킵니다. 이것이 라이브러리 사용자가 보통 설치해야 하는 것입니다. 사용자가 다음을 수행할 때 npm이 가져오는 버전입니다 `npm i <library name>`.

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

1. 프로젝트의 GitHub 페이지를 엽니다. 페이지 오른쪽 가장자리에 있는 **Releases** 링크를 엽니다.
2. 클릭 **Draft new release**.
3. 켜짐 **태그를 선택하세요** 새 버전의 이름을 작성하세요. 예를 들어 "1.1.0"입니다. 또한 **Release Title**에도 이름을 작성하세요. 보통은 같은 이름인 "1.1.0"입니다.

   > 중요: 태그는 숫자여야 하며, 추가 문자나 기호가 없어야 합니다. 숫자는 이전에 게시된 릴리스보다 더 커야 합니다.
4. 사용자에게 새로운 점이 무엇인지 알 수 있도록 릴리스를 설명하세요.

   > 팁: 버튼을 클릭하세요 **Auto generate release notes** 를 눌러 마지막 릴리스 이후의 모든 커밋을 출력하세요.
5. 누르세요 **Publish Release**. 이 작업은 `@latest` 플래그와 함께 npm에 대한 새 자동 게시를 트리거합니다. 이제 라이브러리 사용자는 이 버전을 다운로드하게 됩니다.

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

다른 창작자들이 사용하기 쉽도록 라이브러리를 만들기 위해 최선을 다하세요. 우리의 가정은 우리가 만드는 도구의 형태를 항상 좌우하는 데 도움이 됩니다. 종종 이러한 가정은 우리에게는 명백해 보이지만, 다른 맥락을 가진 사람들은 완전히 다른 가정을 할 수 있습니다.

* 함수, 컴포넌트, 매개변수를 포함해 라이브러리의 모든 것에 이름을 신중하게 지으세요. 완전히 미스터리인 짧은 이름보다, 스스로 설명이 되는 긴 이름이 더 좋습니다.
* 라이브러리의 다양한 잠재적 사용 사례를 폭넓게 생각하세요. 누군가는 스마트 웨어러블에서 여러분의 라이브러리를 사용할 수도 있고, 누군가는 시스템을 필요할 때 켜거나 끄고 싶을 수도 있으며, 누군가는 같은 씬에 시스템 인스턴스를 여러 개 추가해야 할 수도 있습니다. 모든 사람이 여러분과 같은 어려움을 겪는 것은 아닙니다.
* 그렇다고 해서 가능한 모든 사용 사례를 지원할 필요는 없습니다. 사실 유연성과 사용의 단순성 사이에는 항상 타협이 있으며, 좋은 도구를 만든다는 것은 결국 그 균형을 잘 잡는 일입니다. 무엇을 지원하지 않기로 했는지에 대한 경계는 전략적으로 정하세요. 다만, 선택한 한계는 명확히 문서화하는 것이 중요합니다.
* 이것은 문서화로 이어집니다. 예제, 각 매개변수가 하는 일에 대한 설명, 어떤 시나리오에서는 작동하지 않을지에 대한 설명, 그리고 사용되는 맥락에 대해 어떤 가정을 하는지에 대한 메모와 함께 라이브러리를 명확하게 문서화하세요. 라이브러리의 README.md는 종종 이 내용을 공개하기에 가장 좋은 장소입니다.
* 또 다른 훌륭한 도구는 메타데이터 주석을 코드 안에 직접 추가하는 것입니다. 이런 주석은 사용자가 라이브러리의 타입을 입력할 때 IDE(VS Studio Code 같은)에서 표시됩니다. 각 함수/컴포넌트의 용도, 각 매개변수가 무엇을 받는지, 그리고 함수가 무엇을 반환하는지 설명할 수 있습니다. 덕분에 라이브러리 사용자는 코드와 문서를 오갈 필요가 없습니다. 모든 것이 한곳에 있으니까요! 예를 들어, 다음의 함수를 보세요 `@dcl/ecs-scene-utils` 라이브러리:

  ```ts
  /**
   * 값이 최소값이나 최대값을 넘지 않도록 제한합니다.
   *
   * @param value - 입력 숫자
   * @param min - 최소 출력값.
   * @param max - 최대 출력값.
   * @returns min과 max 사이의 결과 매핑된 값
   * @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 dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

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

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.