> 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/contributor/contributor-pt/guias-do-contribuidor/componentes-bem-conhecidos/components.md).

# Componentes

Os componentes são pedaços de software autocontidos projetados como caixas-pretas que recebem outros componentes (ou nenhum) para executar suas tarefas. O objetivo principal é desacoplar seções de código e maximizar a testabilidade.

## Estrutura de Diretórios

Todos os componentes DEVEM ser definidos dentro de um diretório dedicado contendo pelo menos estes quatro arquivos:

* `component.ts` - Contém o código de implementação do componente
* `types.ts` - Contém a interface do componente e os tipos expostos
* `errors.ts` - Contém todas as classes de erro exportadas
* `index.ts` - Exporta a API pública do componente

### Exemplo de Estrutura

```
src/
└── components/
    └── my-component/
        ├── component.ts
        ├── types.ts
        ├── errors.ts
        └── index.ts
```

## Arquivo de Tipos

Os componentes obedecem a uma interface que define sua API pública. Essa interface pode ser compartilhada entre componentes intercambiáveis ou usada para entender os métodos expostos pelo componente.

Todos os componentes que possuem sua própria interface DEVEM defini-la em um `types.ts` arquivo dentro do diretório do componente.

Outros tipos expostos pelo componente TAMBÉM DEVEM ser colocados neste arquivo.

### Exemplo: `types.ts`

```tsx
export type Something = {
  aValue: boolean
  anotherValue: string
}

export interface IMyComponent {
  myFunction: () => boolean
  getSomething: () => Something
}
```

### Tipos Compartilhados

Tipos compartilhados entre múltiplos componentes, como interfaces comuns, DEVEM ser colocados em um `types.ts` arquivo no diretório raiz do código-fonte do projeto (`/src/types.ts`).

## Arquivo do Componente

O arquivo do componente contém a função criadora do componente. Essa função segue uma convenção específica de nomeação e estrutura.

### Convenção de Nomeação

As funções criadoras de componentes DEVEM ser nomeadas como: `create` + `ComponentName` + `Component`

**Exemplo:** `createMyNewComponent`

### Assinatura da Função

A função criadora DEVE:

1. Receber um objeto components como primeiro parâmetro contendo todas as dependências
2. Opcionalmente receber parâmetros adicionais de configuração
3. Retornar um objeto contendo os métodos expostos (públicos)

### Estrutura do Componente

No início da função criadora do componente:

1. Extrair dependências do objeto components
2. Inicializar variáveis comuns (por exemplo, loggers, configuração)
3. Definir funções auxiliares internas
4. Definir métodos públicos
5. Retornar a API pública

### Exemplo: `component.ts`

```tsx
import { IMyComponent, Something } from './types'
import { WrongStringError } from './errors'

export function createMyNewComponent(
  components: Pick<AppComponents, 'logs'>
): IMyComponent {
  const { logs } = components
  const logger = logs.getLogger('my-component')

  // Método interno - não exposto
  function computeString(fstString: string, sndString: string): string {
    if (fstString.length === 0) {
      throw new WrongStringError()
    }
    
    return fstString + ' ' + sndString
  }

  // Método público - exposto no objeto retornado
  function myFunction(): boolean {
    return true
  }

  // Método público - exposto no objeto retornado
  function getSomething(): Something {
    logger.info('Getting something')
    
    return {
      aValue: true,
      anotherValue: computeString('aString', 'anotherString')
    }
  }

  // Retornar a API pública
  return {
    myFunction,
    getSomething
  }
}
```

## Arquivo de Erros

O arquivo de erros contém classes de erro customizadas que um componente pode lançar. Esses erros podem ser usados em outros componentes ou controladores para identificar e tratar corretamente condições de erro específicas.

### Exemplo: `errors.ts`

```tsx
export class WrongStringError extends Error {
  constructor(message?: string) {
    super(message || 'Incorrect String')
    this.name = 'WrongStringError'
  }
}

export class ComponentNotInitializedError extends Error {
  constructor() {
    super('Component has not been initialized')
    this.name = 'ComponentNotInitializedError'
  }
}
```

### Boas Práticas de Tratamento de Erros

* Criar classes de erro específicas para diferentes condições de erro
* Incluir mensagens de erro significativas
* Defina o `name` property to match the class name for easier debugging
* Documentar quais erros podem ser lançados por cada método público

## Arquivo Index

O arquivo index serve como ponto de entrada público para o componente, exportando apenas o que deve ser acessível para outras partes da aplicação.

### Exemplo: `index.ts`

```tsx
export { createMyNewComponent } from './component'
export type { IMyComponent, Something } from './types'
export { WrongStringError } from './errors'
```

## Boas Práticas

1. **Responsabilidade Única** - Cada componente deve ter um propósito claro
2. **Dependências Explícitas** - Todas as dependências devem ser injetadas através do parâmetro components
3. **Imutabilidade** - Preferir estruturas de dados imutáveis sempre que possível
4. **Tratamento de Erros** - Usar classes de erro customizadas para diferentes condições de erro
5. **Registro (Logging)** - Usar o logger para depuração e monitoramento
6. **Segurança de Tipos** - Aproveitar o sistema de tipos do TypeScript ao máximo
7. **Documentação** - Documentar métodos complexos e lógica de negócio

## Ciclo de Vida do Componente

Alguns componentes podem precisar executar operações de configuração ou limpeza. WKC fornece métodos de ciclo de vida:

* `[START_COMPONENT]` - Chamado quando o componente inicia
* `[STOP_COMPONENT]` - Chamado quando o componente para

Veja a [Adaptadores](/contributor/contributor-pt/guias-do-contribuidor/componentes-bem-conhecidos/adapters.md) seção para exemplos de componentes usando métodos de ciclo de vida.


---

# 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/contributor/contributor-pt/guias-do-contribuidor/componentes-bem-conhecidos/components.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.