Ctrlk
For the complete documentation index, see llms.txt. This page is also available as Markdown.

라이브러리 만들기

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

라이브러리는 일반적인 문제에 대한 해결책을 공유하는 훌륭한 방법입니다. 복잡한 과제는 한 번만 다루고, 해결책을 라이브러리로 캡슐화해 두면, 이후 같은 문제가 생길 때는 코드 한 줄만 작성하면 됩니다. 라이브러리를 커뮤니티와 공유함으로써 모든 제작자의 생산성을 기하급수적으로 높일 수 있습니다.

현재, 다음의 라이브러리들은 예제 페이지 에서 모두 사용할 수 있습니다. 여러분도 직접 만들어 공유해 보시기를 권장합니다.

여기에 자세히 설명된 단계를 따르면, Decentraland 씬과 호환되고 다른 사람과 쉽게 공유할 수 있는 라이브러리를 만드는 데 따르는 대부분의 복잡성을 피할 수 있습니다.

라이브러리 만들기

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

자신만의 라이브러리를 만들고 NPM을 통해 공유하려면 다음을 수행하세요:

  1. 새 빈 폴더를 만들고, 그곳에서 새 VS Code 창을 여세요.

  2. Visual Studio의 왼쪽 사이드바에서 Decentraland 탭을 선택하세요

  3. 클릭 프로젝트 만들기, 그런 다음 라이브러리

    이렇게 하면 Decentraland 라이브러리에 필요한 모든 기본 파일과 종속성이 생성됩니다.

  4. 고유한 name 에서 package.json. 이는 NPM에 게시할 때 사용될 이름입니다. npm에서 동일한 이름을 사용하는 다른 기존 프로젝트가 없는지 확인하세요. 또한 다른 사람들이 라이브러리를 찾을 수 있도록 설명과 태그도 입력하세요.

  5. 새 공개 GitHub 저장소를 프로젝트에 대해 만드세요.

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

    의 package.json 파일에서, 다음을 확인하세요 저장소 다음을 url 필드를 저장소의 URL로 지정하세요. 그러면 사용자가 탐색할 때 쉽게 찾을 수 있습니다 npmjs.com.

  6. NPM 토큰을 받으세요:

    1. https://www.npmjs.com/ 에서 계정을 만들거나 로그인하세요.

    2. 다음으로 이동하세요 계정 > 액세스 토큰 > 새 토큰 생성 새 토큰을 만들고 게시 권한을 부여하세요.

      성공 메시지에는 새로 생성된 토큰의 문자열이 포함됩니다. 이 문자열을 복사해 안전한 곳에 보관하세요.

  7. GitHub 저장소에서 다음으로 이동하세요 설정 > 비밀 > 작업, 그런 다음 새 저장소 비밀.

    비밀 이름을 지정하세요 NPM_TOKEN, 그리고 NPM 토큰의 문자열을 값으로 붙여넣으세요.

  8. 변경 사항(아무 변경이나)을 GitHub 저장소의 main 브랜치로 푸시하면 패키지가 게시됩니다.

    이제 끝입니다. 이제 누구나 다음을 사용해 패키지를 설치할 수 있습니다 npm i <package-name>! 이제 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. 씬 폴더에서 다음을 실행하세요 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 페이지를 여세요. 페이지 오른쪽 여백에 있는 릴리스 링크를 여세요.

  2. 클릭 새 릴리스 초안.

  3. 켜짐 태그 선택 새 버전의 이름을 적으세요. 예를 들어 "1.1.0". 또한 릴리스 제목에도 이름을 적으세요. 흔히 같은 이름인 "1.1.0"을 사용합니다.

    중요: 태그는 숫자여야 하며, 추가 문자나 기호가 있으면 안 됩니다. 숫자는 이전에 게시된 릴리스보다 커야 합니다.

  4. 사용자가 무엇이 새로워졌는지 알 수 있도록 릴리스를 설명하세요.

    팁: 버튼을 클릭하세요 릴리스 노트 자동 생성 를 눌러 마지막 릴리스 이후의 모든 커밋을 출력하세요.

  5. 누르세요 릴리스 게시. 이 작업은 다음을 사용하여 npm에 새 자동 게시를 트리거합니다 @latest 플래그를. 이제 라이브러리 사용자는 이 버전을 다운로드하게 됩니다.

사용성에 대한 참고 사항

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

  • 함수, 컴포넌트, 매개변수 등 라이브러리의 모든 것에 대해 이름을 신중하게 선택하세요. 완전한 수수께끼 같은 짧은 이름보다, 설명이 필요 없는 긴 이름이 더 좋습니다.

  • 라이브러리의 다양한 가능한 사용 사례를 폭넓게 생각하세요. 누군가는 스마트 웨어러블에서 라이브러리를 사용할 수도 있고, 누군가는 시스템을 때때로 켜거나 꺼야 할 수도 있으며, 또 다른 누군가는 같은 씬에 시스템 인스턴스를 여러 개 추가해야 할 수도 있습니다. 모든 사람이 당신과 같은 문제를 겪는 것은 아닙니다.

  • 그렇다고 해서 가능한 모든 사용 사례를 지원해야 하는 것은 아닙니다. 사실 유연성과 사용의 단순성 사이에는 언제나 절충이 필요하며, 좋은 도구를 만드는 일은 올바른 균형을 찾는 데 있습니다. 어떤 항목을 지원하지 않기로 할지 선을 어디에 그을지 전략적으로 결정하세요. 다만, 선택한 제한 사항은 명확하게 문서화하는 것이 중요합니다.

  • 이제 문서화에 대해 이야기해 봅시다. 예제, 각 매개변수가 하는 일에 대한 설명, 어떤 시나리오에서 작동하지 않는지에 대한 설명, 사용되는 맥락에 대해 어떤 가정을 하는지에 대한 설명을 포함해 라이브러리를 명확하게 문서화하세요. 라이브러리의 README.md는 종종 이런 내용을 공개하기에 가장 좋은 장소입니다.

  • 또 다른 훌륭한 도구는 메타데이터 주석을 코드 안에 직접 추가하는 것입니다. 이러한 주석은 사용자가 라이브러리를 입력할 때 IDE(예: VS Studio Code)에 표시됩니다. 각 함수/컴포넌트의 용도, 각 매개변수가 무엇을 받아야 하는지, 함수가 무엇을 반환하는지 설명할 수 있습니다. 덕분에 라이브러리 사용자는 코드와 문서 사이를 오갈 필요가 없습니다. 모든 것이 한곳에 있습니다! 예를 들어, 다음 함수는 @dcl/ecs-scene-utils 라이브러리의

    이 라이브러리의 사용자는 다음을 입력하는 동안 이러한 힌트가 표시되는 것을 봅니다 clamp() 함수:

  • 항상 타입을 선언하세요. 소비해야 할 객체 구조가 무엇인지 사람들에게 추측하게 두지 마세요.

  • 라이브러리는 가볍게 유지하고 하나의 기능에 집중하세요. Decentraland 씬이 컴파일되면, 씬에서 호출되지 않는 코드까지 포함해 해당 씬의 모든 라이브러리의 모든 코드가 함께 패키징됩니다. 이런 이유로 크고 무거운 라이브러리를 만드는 것은 피하는 것이 좋습니다. 제작자가 정말 필요한 것만 사용할 수 있게 해 주는 가벼운 라이브러리가 더 좋습니다.

  • 라이브러리의 저장소를 계속 주시하세요. 사람들이 풀 리퀘스트를 보내거나 이슈를 제기할 수 있습니다.

  • 저장소에 라이선스 정보를 포함하세요. 그러면 다른 사람들이 라이브러리를 자유롭게 사용할 수 있는지 알 수 있습니다. 기본 라이브러리에는 오픈 Apache 2 라이선스가 포함되어 있습니다. 원하시면 자유롭게 변경할 수 있습니다.

이전라이브러리 카탈로그
다음프로그래밍 패턴

마지막 업데이트