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.

Para começar a desenvolver seu componente rapidamente, nós temos 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

Para criar um pacote nós fortemente recomendados configurar 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.

diretorio-do-meu-novo-componente/
├─ demo/
| └─ ... para testes e demonstração
├─ package.json
└─ packages/
  └─ meu-componente/
      ├─ index.js
      ├─ package.json
      └─ ... arquivos adicionais usados pelo pacote

Nesse exemplo, chamado de meu-projeto, nós criamos 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.

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","astro-component", "...", "..."]
}

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

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

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

{
  "type": "module"
}

Nós recomendados utilizar "type": "module" para que assim seu index.js possa ser usado como ponto de entrada com import e export.

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.

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.

Esta é 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"]
}

Um array de palavras-chave relevantes para o seu componente que será utilizado para ajudar outros a encontrar seu pacote no npm e em outros catálogos de pesquisa.

Nós recomendados adicionar astro-component como uma palavra-chave especial para maximizar a sua descoberta no ecossistema Astro.

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

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.

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

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

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

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.

Astro atualmente não vem com um executador de testes. Isso é algo que gostaríamos de resolver. (Se você estiver interessado em ajudar, 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.

meu-projeto/demo/src/pages/__fixtures__/
  ├─ nome-teste-01.astro
  ├─ nome-teste-02.astro
  └─ nome-teste-03.astro

Assim que você tiver seu pacote pronto, você pode publicá-lo no npm!

Para publicar um pacote no npm, utilize 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 podem ser publicados diretamente sem uma etapa de construção, pois sabemos que o Astro já os suporta nativamente. Isso inclui arquivos com extensões como .astro, .ts, .jsx e .css.

Se você precisar de outro tipo de arquivo que não é nativamente suportado pelo Astro, sinta-se livre para adicionar uma etapa de construção ao seu pacote. Esta prática avançada fica por sua conta.

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

A biblioteca é automaticamente atualizada toda noite, puxando cada pacote publicado no NPM com a palavra-chave astro-component.

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.

Em adição a palavra-chave obrigatória astro-component, outras palavras-chave são utilizadas para automaticamente organizar os pacotes. Incluindo qualquer uma das palavras-chave abaixo, que irão adicionar sua integração a uma coleção em nossa biblioteca de integrações.

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!