> 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-pt/scenes-sdk7/bibliotecas/create-libraries.md).

# Criar uma Biblioteca

Crie suas próprias bibliotecas do Decentraland para compartilhar com outras pessoas

As bibliotecas são uma ótima maneira de compartilhar soluções para problemas comuns. Desafios complexos podem ser enfrentados uma vez, as soluções encapsuladas em uma biblioteca, e, sempre que surgirem, você só precisa escrever uma linha de código. Ao compartilhar bibliotecas com a comunidade, podemos fazer a produtividade de todos os criadores crescer exponencialmente.

Atualmente, essas bibliotecas na [página de Exemplos](https://studios.decentraland.org/resources?sdk_version=SDK7\&resource_type=Library) estão disponíveis para uso de todos. Nós o incentivamos a criar e compartilhar as suas também.

Seguindo as etapas detalhadas aqui, você pode evitar a maior parte da complexidade que vem com a criação de uma biblioteca compatível com cenas do Decentraland e fácil de compartilhar com outras pessoas.

## Criar uma biblioteca

> **📔 Nota**: Certifique-se de estar usando a versão 20 ou mais recente do Node antes de construir sua biblioteca.

Para criar sua própria biblioteca e compartilhá-la via NPM, faça o seguinte:

1. Crie uma nova pasta vazia e abra uma nova janela do Visual Studio Code ali.
2. Selecione a aba Decentraland na barra lateral esquerda do Visual Studio Code
3. Clica em **Criar projeto**, depois selecione **Biblioteca**

   Isso criará todos os arquivos e dependências padrão para uma biblioteca do Decentraland.
4. Defina um `nome` único `em`package.json. Este é o nome que será usado ao publicar no NPM; certifique-se de que não exista outro projeto usando esse nome no npm. Preencha também a descrição e quaisquer tags para ajudar outras pessoas a encontrar sua biblioteca.
5. Crie um novo repositório *público* no GitHub para o seu projeto.

   O projeto está configurado para usar GitHub Actions para publicar uma nova versão do pacote a cada push para `main`.

   No `em` arquivo, certifique-se de que em `repository` você aponte o campo `url` para a URL do seu repositório. Dessa forma, fica fácil para os usuários encontrá-la ao navegar em [npmjs.com](https://www.npmjs.com).
6. Obtenha um token do NPM:
   1. Crie uma conta ou faça login em <https://www.npmjs.com/>.
   2. Vá para **Account > Access Tokens > Generate new Token** Crie um novo token e dê a ele **Publish** permissões.

      A mensagem de sucesso inclui uma string do token recém-gerado. Copie essa string e guarde-a em um lugar seguro.
7. No seu repositório do GitHub, vá para **Settings > Secrets > Actions**, depois clique em **New Repository Secret**.

   Nomeie seu segredo **NPM\_TOKEN**, e cole a string do token do NPM como valor.
8. Envie uma alteração (qualquer alteração) para a branch main do seu repositório no GitHub e o pacote será publicado.

   É isso, agora o pacote pode ser instalado por qualquer pessoa usando `npm i <package-name>`! Agora você pode encontrar sua biblioteca se procurá-la pelo nome em [npmjs.com](https://www.npmjs.com).
9. Preencha a `/src` pasta do seu projeto com toda a funcionalidade que você quer expor e envie as alterações para o GitHub.

## Desenvolva

Adicione quaisquer funções, componentes etc. que você queira expor à `index.ts` da biblioteca, assim eles ficam fáceis de importar.

Por exemplo, se você adicionar um `RotatorComponent` componente a `index.ts`uma cena, você pode então importar esse componente para uma cena escrevendo o seguinte:

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

Teste sua biblioteca usando-a em uma nova cena do Decentraland enquanto a desenvolve. Instale seu pacote npm em uma cena executando `npm i <package-name>`. Depois, construa uma cena que sirva para testar a funcionalidade da biblioteca. Tente cobrir diferentes casos de teste com sua cena, para garantir que sua biblioteca funcione como esperado em todos os casos.

### Iterações rápidas

Se você precisar fazer pequenos ajustes na sua biblioteca continuamente e testá-los, pode ser exaustivo ter de confirmar as alterações e depois esperar a publicação no npm ser concluída antes de conseguir testar a nova versão em uma cena. Felizmente, existe uma alternativa muito mais rápida para executar testes com a sua biblioteca.

Em um **projeto de cena de teste**:

1. Adicione este script à lista `scripts` em package.json: `"link-sdk": "cd node_modules/@dcl/sdk && npm link && cd ../js-runtime && npm link"`
2. Execute `npm install`
3. Execute `npm install YOUR_LIBRARY_PATH`, por exemplo, `npm install /User/projects/dcl-sdk7-library-test`
4. Execute `npm run link-sdk`

No **projeto de biblioteca**:

1. Execute `npm install`
2. Execute `npm run build`
3. Execute: `npm link @dcl/sdk @dcl/js-runtime`

> **❗Aviso**: A ordem dessas etapas é importante. Pode não funcionar em outra ordem.

Isso manterá sua cena sincronizada com a versão da biblioteca que está diretamente no seu disco local. Para quaisquer alterações na biblioteca que você queira testar, basta executar `npm run build` na pasta da biblioteca; não há necessidade de publicar as alterações no GitHub ou no NPM.

> **💡 Dica**: Para verificar se a vinculação foi bem-sucedida, execute `npm ls --link`. Você deve ver o nome da biblioteca apontando para a pasta nos seus arquivos locais.

Se você fizer alterações na biblioteca, você deve executar `npm run build` para atualizá-las. Para evitar ter de fazer isso toda vez:

1. Adicione o script "start": "tsc -p tsconfig.json --watch" à biblioteca
2. Execute `npm start` na biblioteca

Quando terminar de testar, lembre-se de desvincular a biblioteca.

1. Na pasta da cena, execute `npm install <library name>`
2. Depois, na biblioteca, execute `rm -rf node_modules && npm install`

## Versionamento

As versões da sua biblioteca são publicadas automaticamente no `npm` com um `@latest` e um `@next` sinalizador.

A `@next` O sinalizador sempre aponta para o último commit na `main` branch. Esta versão pode ser instável, pois as últimas alterações podem não ter sido testadas. Os usuários da sua biblioteca podem instalá-la (por sua própria conta e risco) fazendo `npm i <library name>@next`.

A `@latest` O sinalizador aponta para a última versão estável da biblioteca. Esta é a versão que os usuários da sua biblioteca devem instalar normalmente. É a versão que o npm obtém quando fazem `npm i <library name>`.

Para fazer com que o `@latest` sinalizador aponte para seus commits mais recentes, você precisará fazer um **release** da sua biblioteca no GitHub.

1. Abra a página do GitHub do seu projeto. Abra o link **Releases** na margem direita da página.
2. Clica em **Criar novo release**.
3. Em **Escolha a tag** escreva um nome para sua nova versão, por exemplo "1.1.0". Escreva também um nome em **Título do release**. Esse costuma ser o mesmo nome, "1.1.0".

   > Importante: a tag deve ser um número, sem letras ou símbolos adicionais. O número deve ser maior do que os releases publicados anteriormente.
4. Descreva seu release, para que os usuários saibam o que há de novo.

   > Dica: clique no botão **Gerar notas de release automaticamente** para listar todos os commits desde o último release.
5. Clique em **Publicar release**. Esta ação aciona uma nova publicação automática no npm com o `@latest` sinalizador. Os usuários da sua biblioteca agora estarão baixando esta versão.

## Notas sobre usabilidade

Faça o possível para tornar sua biblioteca fácil de usar para outros criadores. Nossas suposições sempre ajudam a moldar as ferramentas que criamos. Muitas vezes essas suposições nos parecem óbvias, mas outros, com outro contexto, podem ter suposições completamente diferentes.

* Escolha nomes com cuidado para tudo na sua biblioteca, incluindo funções, componentes e parâmetros. É melhor ter um nome longo e autoexplicativo do que um curto que seja um completo mistério.
* Pense amplamente sobre diferentes casos de uso possíveis para sua biblioteca. Talvez alguém use sua biblioteca em um wearable inteligente, talvez alguém precise ligar ou desligar seu sistema em determinados momentos, talvez alguém precise adicionar várias instâncias do seu sistema na mesma cena. Nem todo mundo estará enfrentando os mesmos desafios que você.
* Dito isso, você não precisa dar suporte a todos os casos de uso possíveis. Na verdade, sempre há concessões a fazer entre flexibilidade e simplicidade de uso; criar boas ferramentas é, acima de tudo, encontrar o equilíbrio certo. Seja estratégico sobre onde traçar a linha do que você escolheu não suportar. É importante, porém, documentar claramente as limitações com as quais você decidiu ficar.
* Isso nos leva à Documentação. Documente sua biblioteca claramente, com exemplos, descrições do que cada parâmetro faz, comentários sobre quais cenários não funcionariam e quais suposições você está fazendo sobre o contexto em que ela está sendo usada. O README.md da biblioteca costuma ser o melhor lugar para expor esse conteúdo.
* Outra ótima ferramenta é adicionar comentários de metadados diretamente ao seu código. Esses comentários são exibidos pelo IDE (como o VS Studio Code) conforme os usuários da sua biblioteca digitam. Você pode descrever para que serve cada função/componente, descrever o que cada parâmetro espera receber e o que uma função retorna. Graças a isso, os usuários da sua biblioteca não precisam alternar entre o código e a documentação; está tudo em um só lugar! Por exemplo, veja esta função da `@dcl/ecs-scene-utils` biblioteca:

  ```ts
  /**
   * Limita um valor para que ele não ultrapasse um valor mínimo ou máximo.
   *
   * @param value - número de entrada
   * @param min - Valor mínimo de saída.
   * @param max - Valor máximo de saída.
   * @returns O valor mapeado resultante entre o min e o 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
  }
  ```

  Os usuários desta biblioteca veem essas dicas exibidas enquanto digitam a `clamp()` função:
* Sempre declare tipos. Não deixe as pessoas adivinharem qual estrutura de objeto elas terão de consumir.
* Mantenha sua biblioteca leve e focada em uma única funcionalidade. Quando uma cena do Decentraland é compilada, todo o código de todas as suas bibliotecas é empacotado junto, até mesmo o código que nunca é chamado pela cena. Por esse motivo, é melhor evitar criar bibliotecas grandes e pesadas. É melhor ter bibliotecas enxutas que permitam aos criadores usar apenas o que realmente precisam.
* Fique de olho no repositório da sua biblioteca; as pessoas podem fazer pull requests ou relatar problemas.
* Inclua informações de licenciamento no seu repositório, assim as outras pessoas saberão se podem usar sua biblioteca livremente. A biblioteca padrão inclui uma licença Apache 2 aberta; sinta-se à vontade para alterá-la, se desejar.


---

# 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-pt/scenes-sdk7/bibliotecas/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.