Publique no NPM
Está construindo um novo componente Astro? Publique-o ao npm!
Publicar um componente Astro é uma ótima forma de reutilizar o seu trabalho entre projetos e o compartilhar com a grande comunidade do Astro. Componentes Astro podem ser publicados diretamente e instalados pelo NPM, assim como qualquer outro pacote JavaScript.
Procurando por inspiração? Veja alguns dos nossos temas e componentes favoritos da comunidade do Astro. Você também pode pesquisar pelo npm para ver o catálogo público inteiro.
Veja o template de componentes da comunidade do Astro e comece com um template mantido pela comunidade!
Início Rápido
Seção intitulada Início RápidoPara começar a desenvolver seu componente rapidamente, você pode usar um template configurado para você.
Criando um pacote
Seção intitulada Criando um pacoteAntes de se aprofundar, será útil ter um entendimento básico de:
Para criar um pacote, configure seu ambiente de desenvolvimento para utilizar workspaces em um projeto. Isso irá permitir que você desenvolva o seu componente ao lado de uma cópia funcional do Astro.
Diretóriodiretorio-do-meu-novo-componente/
Diretóriodemo/
- … para testes e demonstração
- package.json
Diretóriopackages/
Diretóriomeu-componente/
- index.js
- package.json
- … arquivos adicionais utilizados pelo pacote
Esse exemplo, chamado de meu-projeto
, cria um projeto com um único pacote, chamado de meu-componente
e um diretório demo
para testes e demonstração do componente.
Isso é configurado no arquivo da raiz do projeto package.json
:
Nesse exemplo, múltiplos pacotes podem ser desenvolvidos juntos a partir do diretório packages
. Esses pacotes podem ser referenciados de demo
, aonde você pode instalar uma cópia funcional do Astro.
Há dois arquivos iniciais que irão fazer parte do seu pacote individual: package.json
e index.js
.
package.json
Seção intitulada package.jsonO package.json
no diretório do pacote inclui todas as informações relacionadas ao seu pacote, como sua descrição, dependências e outros metadados do pacote.
description
Seção intitulada descriptionUma pequena descrição do seu componente, utilizada para ajudar outros a entender o que seu pacote faz.
O formato de módulo utilizado pelo Node.js e pelo Astro para interpretar seus arquivos index.js
.
Use "type": "module"
para que assim seu index.js
possa ser usado como ponto de entrada com import
e export
.
homepage
Seção intitulada homepageA url da página inicial do seu projeto.
Essa é uma ótima forma de direcionar usuários a uma demonstração online, documentação ou a página inicial do seu projeto.
exports
Seção intitulada exportsOs pontos de entrada de um pacote quando importado pelo seu nome.
Neste exemplo, importar meu-componente
utilizaria index.js
, enquanto importar meu-componente/astro
ou meu-componente/react
utilizaria MeuComponenteAstro.astro
ou MeuComponenteReact.jsx
respectivamente.
Uma otimização opcional para excluir arquivos desnecessários do empacotamento enviado aos usuários via npm. Note de que apenas arquivos listados aqui serão incluídos no seu pacote, então se você adicionar ou modificar arquivos necessários para seu pacote funcionar, você precisar atualizar essa lista de acordo.
keywords
Seção intitulada keywordsUm array de palavras-chave relevantes para o seu componente, utilizado para ajudar outros a encontrar seu pacote no npm e em outros catálogos de pesquisa.
Adicione astro-component
ou withastro
como uma palavra-chave especial para maximizar a sua descoberta no ecossistema Astro.
Palavras-chave também são utilizadas por nossa biblioteca de integrações! Veja abaixo para uma lista completa das palavras-chave que procuramos no NPM.
index.js
Seção intitulada index.jsO ponto de entrada principal do pacote é utilizado sempre que seu pacote é importado.
Isso permite que você empacote múltiplos componentes juntos em uma única interface.
Exemplo: Utilizando Importações Nomeadas
Seção intitulada Exemplo: Utilizando Importações NomeadasExemplo: Utilizando Importações de Namespace
Seção intitulada Exemplo: Utilizando Importações de NamespaceExemplo: Utilizando Importações Individuais
Seção intitulada Exemplo: Utilizando Importações IndividuaisDesenvolvendo seu pacote
Seção intitulada Desenvolvendo seu pacoteAstro não possui um “modo pacote” dedicado para desenvolvimento. Nesse caso, você deve utilizar um projeto demonstrativo para desenvolver e testar seu pacote dentro do seu projeto. Pode ser um website privado apenas para desenvolvimento ou uma demonstração/documentação pública para o seu pacote.
Se você estiver extraindo componentes de um projeto existente, você pode até mesmo continuar a utilizar aquele projeto para desenvolver os seus componentes extraídos.
Testando seu componente
Seção intitulada Testando seu componenteAstro atualmente não vem com um executador de testes. (Se você estiver interessado em ajudar com isso, junte-se a nós no Discord!)
Enquanto isso, nossas recomendações atuais para testes é:
- Adicionar um diretório
fixtures
ao seu diretóriodemo/src/pages
. - Adicionar uma nova página para cada teste que você deseja executar.
- Cada página deve ter algum uso diferente do componente que você gostaria de testar.
- Execute
astro build
para construir suas fixtures, então compare o resultado final do diretóriodist/__fixtures__/
com o resultado esperado.
Diretóriomeu-projeto/demo/src/pages/__fixtures__/
- nome-teste-01.astro
- nome-teste-02.astro
- nome-teste-03.astro
Publicando seu componente
Seção intitulada Publicando seu componenteAssim que você tiver seu pacote pronto, você pode publicá-lo no npm usando o comando npm publish
. Se o comando falhar, certifique-se de que você está logado via npm login
e que seu package.json
está correto. Se o comando funcionou, você terminou!
Entenda que não há uma etapa de build
para pacotes Astro. Quaisquer tipos de arquivos que o Astro suporta, como .astro
, .ts
, .jsx
e .css
, podem ser publicados diretamente sem uma etapa de construção.
Se você precisar de outro tipo de arquivo que não é nativamente suportado pelo Astro, adicione uma etapa de construção ao seu pacote. Esta prática avançada fica por sua conta.
Biblioteca de Integrações
Seção intitulada Biblioteca de IntegraçõesCompartilhe o seu trabalho árduo adicionando sua integração a nossa biblioteca de integrações!
Dados do package.json
Seção intitulada Dados do package.jsonA biblioteca é automaticamente atualizada toda noite, puxando cada pacote publicado no NPM com a palavra-chave astro-component
ou withastro
.
A biblioteca de integrações lê os dados name
, description
, repository
e homepage
do seu package.json
.
Avatars são uma ótima forma de destacar a sua marca na biblioteca! Assim que seu pacote estiver publicado você pode adicionar um GitHub issue com o seu avatar anexado e nós iremos adicionar a sua listagem.
Precisa sobrescrever a informação que nossa biblioteca lê do NPM? Sem problema! Adicione uma issue com as informações atualizadas e nós nos certificaremos que o name
, description
ou homepage
customizado seja utilizado no lugar.
Coleções
Seção intitulada ColeçõesEm adição a palavra-chave obrigatória astro-component
ou withastro
, palavras-chave especiais são utilizadas para automaticamente organizar pacotes. Incluindo qualquer uma das palavras-chave abaixo irão adicionar sua integração a uma coleção em nossa biblioteca de integrações.
coleção | palavras-chave |
---|---|
Acessibilidade | a11y , accessibility |
Adaptadores | astro-adapter |
Analytics | analytics |
CSS + UI | css , ui , icon , icons , renderer |
Frameworks | renderer |
Performance + SEO | performance , perf , seo , optimization |
Compartilhe
Seção intitulada CompartilheNós incentivamos que você compartilhe o seu trabalho, assim como amamos ver o que nossos talentosos Astronautas criaram. Venha e compartilhe o que você criou conosco em nosso Discord ou mencione @astrodotbuild em um Tweet!
Reference