# Criar uma library

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

Atualmente, essas libraries no [página de Examples](https://studios.decentraland.org/resources?sdk_version=SDK7\&resource_type=Library) estão disponíveis para uso de todos. Encorajamos você a criar e compartilhar as suas também.

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

## Criar uma library

> **📔 Nota**: Certifique-se de que está usando a versão 16.x do Node ou uma mais recente antes de build sua library.

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

1. Crie uma nova pasta vazia e abra uma nova janela do VS Studio Code nela.
2. Selecione a aba Decentraland na barra lateral esquerda do Visual Studio
3. Clique em **Create Project**, depois selecione **Library**

   Isso criará todos os arquivos e dependências padrão para uma library de Decentraland.
4. Defina um `name` em `package.json`único. 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 library.
5. Crie um novo *public* repositório do GitHub para o seu projeto.

   O projeto está configurado para usar github actions para publicar uma nova versão do package a cada push para `main`.

   No campo `package.json` arquivo, certifique-se de que em `repositório` você aponte o `url` campo para a URL do seu repo. Dessa forma, fica fácil de encontrar para os users que estiverem navegando [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, dê a ele **Publish** permissões.

      A mensagem de sucesso inclui uma string para o token recém-gerado. Copie essa string e armazene-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 secret **NPM\_TOKEN**, e cole a string do token do NPM como seu valor.
8. Faça um push de uma mudança (qualquer mudança) para a branch principal do seu repo do GitHub e o package será publicado.

   É isso, agora o package pode ser instalado por qualquer pessoa usando `npm i <package-name>`! Agora você pode encontrar sua library se pesquisar por nome em [npmjs.com](https://www.npmjs.com).
9. Preencha a `/src` pasta do seu projeto com toda a funcionalidade que você deseja expor e faça push das mudanças para o GitHub.

## Desenvolver

Adicione quaisquer funções, components, etc. que você queira expor na `index.ts` file da library, assim elas ficam fáceis de importar.

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

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

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

### Iterações rápidas

Se você precisar fazer continuamente pequenos ajustes na sua library e testá-los, pode ser exaustivo ter que commitar as mudanças e depois esperar a publicação no npm ser concluída antes de poder experimentar a nova versão em uma scene. Felizmente, existe uma alternativa muito mais rápida para executar testes com sua library.

Em um **projeto de test scene**:

1. Adicione este script à lista de `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 campo **projeto da library**:

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

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

Isso manterá sua scene sincronizada com a versão da library que está diretamente no seu disco local. Para quaisquer mudanças na library que você queira testar, basta executar `npm run build` na pasta da library, sem necessidade de publicar as mudanças no GitHub ou no NPM.

> **💡 Dica**: Para verificar se o vínculo foi bem-sucedido, execute `npm ls --link`. Você deve ver o nome da library apontando para a pasta nos seus arquivos locais.

Se você fizer mudanças na library, deve executar `npm build` para atualizá-las. Para evitar ter que fazer isso toda vez:

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

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

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

## Versionamento

As versões da sua library são publicadas automaticamente em `npm` com um `@latest` e um `@next` flag.

O `@next` flag 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. Users da sua library podem instalá-la (por conta e risco próprios) executando `npm i <library name>@next`.

O `@latest` flag aponta para o último release estável da library. Esta é a versão que os users da sua library devem instalar normalmente. É a versão que o npm obtém quando eles executam `npm i <library name>`.

Para fazer a `@latest` flag apontar para seus commits mais recentes, você precisará fazer um **release** da sua library no GitHub.

1. Abra a página do GitHub do seu projeto. Abra o link **Releases** , na margem direita da página.
2. Clique em **Draft new release**.
3. On **Chose tag** escreva um nome para sua nova versão, por exemplo "1.1.0". Escreva também um nome em **Release Title**. Normalmente é 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 users saibam o que há de novo.

   > Dica: Clique no botão **Auto generate release notes** para listar todos os commits desde o último release.
5. Clique em **Publish Release**. Esta ação aciona uma nova publicação automática para o npm com a `@latest` flag. Os users da sua library agora farão download desta versão.

## Notas sobre usabilidade

Faça o possível para tornar sua library fácil de usar para outros creators. Nossas suposições sempre ajudam a moldar as tools que criamos. Muitas vezes essas suposições parecem óbvias para nós, mas outras pessoas, com outro contexto, podem ter suposições completamente diferentes.

* Escolha os nomes com cuidado para tudo na sua library, incluindo functions, components e parâmetros. É melhor ter um nome longo e autoexplicativo do que um curto que seja um completo mistério.
* Pense amplamente sobre os diferentes possíveis casos de uso da sua library. Talvez alguém use sua library em um smart wearable, talvez alguém precise ligar ou desligar seu system em certos momentos, talvez alguém precise adicionar múltiplas instâncias do seu system na mesma scene. Nem todos estarão enfrentando os mesmos desafios que você.
* Dito isso, você não precisa dar suporte a todos os possíveis casos de uso. Na verdade, sempre há concessões a fazer entre flexibilidade e simplicidade de uso; criar boas tools é justamente encontrar o equilíbrio certo. Seja estratégico sobre onde traçar a linha para o que você escolheu não suportar. No entanto, é importante documentar claramente as limitações que você decidiu adotar.
* Isso nos leva à Documentation. Documente sua library com clareza, 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 library costuma ser o melhor lugar para expor esse conteúdo.
* Outra ótima tool é adicionar comentários de metadata diretamente no seu code. Esses comentários são exibidos pelo IDE (como o VS Studio Code) à medida que os users da sua library digitam. Você pode descrever para que serve cada function/component, descrever o que cada parâmetro espera receber e o que uma function retorna. Graças a isso, os users da sua library não precisam alternar entre o code e a documentation; está tudo lá em um só lugar! Por exemplo, veja esta function da `@dcl/ecs-scene-utils` library:

  ```ts
  /**
   * Limita um valor para que ele não exceda 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 users desta library veem essas dicas exibidas enquanto digitam a `clamp()` função:
* Declare sempre os types. Não deixe as pessoas adivinharem qual estrutura de object elas terão de consumir.
* Mantenha sua library leve e focada em uma única funcionalidade. Quando uma scene de Decentraland é compilada, todo o code de todas as suas libraries é empacotado junto com ela, inclusive code que nunca é chamado pela scene. Por esse motivo, é melhor evitar criar libraries grandes e pesadas. É melhor ter libraries enxutas que permitam aos creators usar apenas o que realmente precisam.
* Fique de olho no repositório da sua library; as pessoas podem fazer pull requests ou reportar issues.
* Inclua informações de licensing no seu repo, assim os outros sabem se são livres para usar sua library. A library padrão inclui uma licença Apache 2 open, fique à vontade para alterar isso se quiser.


---

# Agent Instructions: 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:

```
GET https://docs.decentraland.org/creator/content-creator-pt/scenes-sdk7/libraries/create-libraries.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.