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.

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

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.

Directorydiretorio-do-meu-novo-componente/
- Directorydemo/
  - … para testes e demonstração
- package.json
- Directorypackages/
  - Directorymeu-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"]
}

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

Adicionar um diretório fixtures ao seu diretório demo/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ório dist/__fixtures__/ com o resultado esperado.
- Directorymeu-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.

Categorias

Em adição a palavra-chave obrigatória astro-component ou withastro, palavras-chave especiais são utilizadas para organizar pacotes automaticamente. A inclusão de qualquer uma das palavras-chave abaixo irá adicionar sua integração à categoria correspondente em nossa biblioteca de integrações.

categoria	palavras-chave
Acessibilidade	`a11y`, `accessibility`
Adaptadores	`astro-adapter`
Analytics	`analytics`
CSS + UI	`css`, `ui`, `icon`, `icons`, `renderer`
Frameworks	`renderer`
Content Loaders	`astro-loader`
Performance + SEO	`performance`, `perf`, `seo`, `optimization`
Dev Toolbar	`devtools`, `dev-overlay`, `dev-toolbar`
Utilidades	`tooling`, `utils`, `utility`

Pacotes que não incluem qualquer palavra-chave correspondente a uma categoria serão mostrados como Sem Categoria.

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!

Contribua

Comunidade

Publique no NPM

Início Rápido

Criando um pacote

`package.json`

`description`

`type`

`homepage`

`exports`

`files`

`keywords`

`index.js`

Exemplo: Utilizando Importações Nomeadas

Exemplo: Utilizando Importações de Namespace

Exemplo: Utilizando Importações Individuais

Desenvolvendo seu pacote

Testando seu componente

Publicando seu componente

Biblioteca de Integrações

Dados do `package.json`

Categorias

Compartilhe

O que passa em sua cabeça?

Criar uma Issue no GitHub

Enviar feedback

Enviar feedback

Publique no NPM

Início Rápido

Criando um pacote

package.json

description

type

homepage

exports

files

keywords

index.js

Exemplo: Utilizando Importações Nomeadas

Exemplo: Utilizando Importações de Namespace

Exemplo: Utilizando Importações Individuais

Desenvolvendo seu pacote

Testando seu componente

Publicando seu componente

Biblioteca de Integrações

Dados do package.json

Categorias

Compartilhe

`package.json`

`description`

`type`

`homepage`

`exports`

`files`

`keywords`

`index.js`

Dados do `package.json`