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.

Não quer começar do zero?

Veja o template de componentes da comunidade do Astro e comece com um template mantido pela comunidade!

Início Rápido

Para começar a desenvolver seu componente rapidamente, você pode usar um template configurado para você.

# Inicialize o template de Componente Astro em um novo diretório
npm create astro@latest diretorio-do-meu-novo-componente -- --template component
# yarn
yarn create astro diretorio-do-meu-novo-componente --template component
# pnpm
npm create astro@latest diretorio-do-meu-novo-componente -- --template component

Criando um pacote

Pré-requisitos

Antes de se aprofundar, será útil ter um entendimento básico de:

• Módulos Node
• Manifesto do Pacote (package.json)
• Workspaces

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:

{
  "name": "meu-projeto",
  "workspaces": ["demo", "packages/*"]
}

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.

npm create astro@latest demo -- --template minimal
# yarn
yarn create astro my-new-component-directory --template minimal
# pnpm
pnpm create astro@latest my-new-component-directory -- --template minimal

Há dois arquivos iniciais que irão fazer parte do seu pacote individual: package.json e index.js.

package.json

O 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.

{
  "name": "meu-componente",
  "description": "Descrição do componente",
  "version": "1.0.0",
  "homepage": "https://github.com/dono/projeto#readme",
  "type": "module",
  "exports": {
    ".": "./index.js",
    "./astro": "./MeuComponenteAstro.astro",
    "./react": "./MeuComponenteReact.jsx"
  },
  "files": ["index.js", "MeuComponenteAstro.astro", "MeuComponenteReact.jsx"],
  "keywords": ["astro", "withastro", "astro-component", "...", "..."]
}

description

Uma pequena descrição do seu componente, utilizada para ajudar outros a entender o que seu pacote faz.

{
  "description": "Um gerador de elementos Astro"
}

type

O formato de módulo utilizado pelo Node.js e pelo Astro para interpretar seus arquivos index.js.

{
  "type": "module"
}

Use "type": "module" para que assim seu index.js possa ser usado como ponto de entrada com import e export.

homepage

A url da página inicial do seu projeto.

{
  "homepage": "https://github.com/dono/projeto#readme"
}

Essa é uma ótima forma de direcionar usuários a uma demonstração online, documentação ou a página inicial do seu projeto.

exports

Os pontos de entrada de um pacote quando importado pelo seu nome.

{
  "exports": {
    ".": "./index.js",
    "./astro": "./MeuComponenteAstro.astro",
    "./react": "./MeuComponenteReact.jsx"
  }
}

Neste exemplo, importar meu-componente utilizaria index.js, enquanto importar meu-componente/astro ou meu-componente/react utilizaria MeuComponenteAstro.astro ou MeuComponenteReact.jsx respectivamente.

files

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.

{
  "files": ["index.js", "MeuComponenteAstro.astro", "MeuComponenteReact.jsx"]
}

keywords

Um 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.

{
  "keywords": ["astro-component", "withastro", "... etc", "... etc"]
}

Dica

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

O ponto de entrada principal do pacote é utilizado sempre que seu pacote é importado.

export { default as MeuComponenteAstro } from './MeuComponenteAstro.astro';

export { default as MeuComponenteReact } from './MeuComponenteReact';

Isso permite que você empacote múltiplos componentes juntos em uma única interface.

Exemplo: Utilizando Importações Nomeadas

---
import { MeuComponenteAstro } from 'meu-componente';
import { MeuComponenteReact } from 'meu-componente';
---
<MeuComponenteAstro />
<MeuComponenteReact />

Exemplo: Utilizando Importações de Namespace

---
import * as Exemplo from 'componente-astro-exemplo';
---
<Exemplo.MeuComponenteAstro />
<Exemplo.MeuComponenteReact />

Exemplo: Utilizando Importações Individuais

---
import MeuComponenteAstro from 'componente-astro-exemplo/astro';
import MeuComponenteReact from 'componente-astro-exemplo/react';
---
<MeuComponenteAstro />
<MeuComponenteReact />

---

Desenvolvendo seu pacote

Astro 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

Astro 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 é:

1. Adicionar um diretório fixtures ao seu diretório demo/src/pages.
2. Adicionar uma nova página para cada teste que você deseja executar.
3. Cada página deve ter algum uso diferente do componente que você gostaria de testar.
4. Execute astro build para construir suas fixtures, então compare o resultado final do diretório dist/__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

Assim 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

Compartilhe o seu trabalho árduo adicionando sua integração a nossa biblioteca de integrações!

Dados do package.json

A 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.

Dica

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

Em 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

Nó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!