Публикация в NPM

Создаете новый компонент Astro? Опубликуйте его в npm!.

Публикация компонента Astro - отличный способ повторного использования вашей существующей работы в ваших проектах и ее распространения среди широкого сообщества Astro. Компоненты Astro могут быть опубликованы напрямую в NPM и установлены оттуда, как и любой другой JavaScript-пакет.

Ищете вдохновение? Посмотрите некоторые из наших любимых тем и компонентов от сообщества Astro. Вы также можете воспользоваться поиском по npm, чтобы просмотреть весь публичный каталог.

Не хотите заниматься этим в одиночку?

Ознакомьтесь с шаблоном компонента Astro сообщества, чтобы получить поддерживаемый сообществом готовый шаблон!

Быстрый старт

Заголовок раздела Быстрый старт

Чтобы быстро приступить к разработке своего компонента, вы можете воспользоваться уже готовым шаблоном.

# Инициализируйте шаблон компонента Astro в новом каталоге
npm create astro@latest my-new-component-directory -- --template component
# yarn
yarn create astro my-new-component-directory --template component
# pnpm
pnpm create astro@latest my-new-component-directory -- --template component

Создание пакета

Заголовок раздела Создание пакета

Необходимые условия

Прежде чем погрузиться в эту тему, необходимо иметь базовое представление о:

• Модули Node
• Манифест пакета (package.json)
• Рабочие пространства

Для создания нового пакета настройте вашу среду разработки на использование рабочих пространств внутри вашего проекта. Это позволит вам разрабатывать ваш компонент наряду с рабочей копией Astro.

• Директорияmy-new-component-directory/

  • Директорияdemo/

    • … для тестирования и демонстрации
  • package.json
  • Директорияpackages/

    • Директорияmy-component/

      • index.js
      • package.json
      • … дополнительные файлы, используемые пакетом

В этом примере, названном my-project, создается проект с одним пакетом, названным my-component, и директорией demo/ для тестирования и демонстрации компонента.

Это настраивается в файле package.json корневой директории проекта:

{
  "name": "my-project",
  "workspaces": ["demo", "packages/*"]
}

В этом примере несколько пакетов могут разрабатываться вместе из директории packages. Эти пакеты также могут быть использованы из demo, где вы можете установить рабочую копию Astro.

npm create astro@latest demo -- --template minimal
# yarn
yarn create astro demo --template minimal
# pnpm
pnpm create astro@latest demo -- --template minimal

Для вашего индивидуального пакета существуют два начальных файла: package.json и index.js.

package.json

Заголовок раздела package.json

package.json в директории пакета содержит всю информацию, относящуюся к вашему пакету, включая его описание, зависимости и любые другие метаданные пакета

{
  "name": "my-component",
  "description": "Описание компонента",
  "version": "1.0.0",
  "homepage": "https://github.com/owner/project#readme",
  "type": "module",
  "exports": {
    ".": "./index.js",
    "./astro": "./MyAstroComponent.astro",
    "./react": "./MyReactComponent.jsx"
  },
  "files": ["index.js", "MyAstroComponent.astro", "MyReactComponent.jsx"],
  "keywords": ["astro", "withastro", "astro-component", "...", "..."]
}

description

Заголовок раздела description

Краткое описание вашего компонента, которое помогает другим понять, что он делает.

{
  "description": "An Astro Element Generator"
}

type

Заголовок раздела type

Формат модуля, используемый Node.js и Astro для интерпретации ваших файлов index.js.

{
  "type": "module"
}

Используйте "type": "module", чтобы ваш index.js можно было использовать в качестве точки входа с помощью import и export.

homepage

Заголовок раздела homepage

URL домашней страницы проекта.

{
  "homepage": "https://github.com/owner/project#readme"
}

Это отличный способ направить пользователей на онлайн-демо, документацию или домашнюю страницу вашего проекта.

exports

Заголовок раздела exports

Точки входа пакета при импорте по имени.

{
  "exports": {
    ".": "./index.js",
    "./astro": "./MyAstroComponent.astro",
    "./react": "./MyReactComponent.jsx"
  }
}

В этом примере импорт my-component будет использовать index.js, в то время как импорт my-component/astro или my-component/react будет использовать MyAstroComponent.astro или MyReactComponent.jsx соответственно.

files

Заголовок раздела files

Опциональная оптимизация для исключения ненужных файлов из пакета, отправляемого пользователям через npm. Обратите внимание, что только файлы, перечисленные здесь, будут включены в ваш пакет, поэтому если вы добавляете или изменяете файлы, необходимые для работы вашего пакета, вам необходимо обновить этот список соответственно.

{
  "files": ["index.js", "MyAstroComponent.astro", "MyReactComponent.jsx"]
}

keywords

Заголовок раздела keywords

Массив ключевых слов, относящихся к вашему компоненту, используемый для помощи другим находить ваш компонент в npm и в любых других каталогах поиска.

Добавьте astro-component или withastro в качестве специального ключевого слова, чтобы максимально повысить его обнаружимость в экосистеме Astro.

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

Совет

Ключевые слова также используются нашей библиотекой интеграций! См. ниже полный список ключевых слов, которые мы ищем в NPM.

---

index.js

Заголовок раздела index.js

Основная точка входа в пакет, используемая при импорте вашего пакета.

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

export { default as MyReactComponent } from './MyReactComponent.jsx';

Это позволяет упаковывать несколько компонентов вместе в единый интерфейс.

Пример: Использование Именованных Импортов

Заголовок раздела Пример: Использование Именованных Импортов

---
import { MyAstroComponent } from 'my-component';
import { MyReactComponent } from 'my-component';
---
<MyAstroComponent />
<MyReactComponent />

Пример: Использование Импорта Пространства Имен

Заголовок раздела Пример: Использование Импорта Пространства Имен

---
import * as Example from 'example-astro-component';
---
<Example.MyAstroComponent />
<Example.MyReactComponent />

Пример: Использование Индивидуальных Импортов

Заголовок раздела Пример: Использование Индивидуальных Импортов

---
import MyAstroComponent from 'example-astro-component/astro';
import MyReactComponent from 'example-astro-component/react';
---
<MyAstroComponent />
<MyReactComponent />

---

Разработка вашего пакета

Заголовок раздела Разработка вашего пакета

В Astro нет отдельного “режима пакета” для разработки. Вместо этого вы должны использовать демонстрационный проект для разработки и тестирования вашего пакета внутри вашего проекта. Это может быть частный веб-сайт, используемый только для разработки, или публичный демонстрационный/документационный веб-сайт для вашего пакета.

Если вы извлекаете компоненты из существующего проекта, вы можете даже продолжить использовать этот проект для разработки ваших извлеченных компонентов.

Тестирование вашего компонента

Заголовок раздела Тестирование вашего компонента

На данный момент в Astro нет встроенного средства для тестирования. (Если вас интересует помощь в этом, присоединяйтесь к нам в Discord!)

Тем не менее, наш текущий рекомендуемый подход для тестирования:

1. Добавьте тестовый каталог fixtures в каталог demo/src/pages.
2. Добавьте новую страницу для каждого теста, который вы хотите запустить.
3. Каждая страница должна включать в себя несколько различных компонентов, которые вы хотите протестировать.
4. Запустите astro build для сборки ваших фикстур, затем сравните вывод директории dist/__fixtures__/ с тем, что вы ожидали.

• Директорияmy-project/demo/src/pages/__fixtures__/

  • test-name-01.astro
  • test-name-02.astro
  • test-name-03.astro

Публикация вашего компонента

Заголовок раздела Публикация вашего компонента

Как только вы подготовили пакет, вы можете опубликовать его в npm с помощью команды npm publish. Если это не удастся, убедитесь, что вы вошли в систему через npm login и что ваш package.json корректен. Если все получилось, то все готово!

Обратите внимание, что для пакетов Astro нет шага build. Любой тип файла, который Astro поддерживает нативно, такой как .astro, .ts, .jsx и .css, может быть опубликован напрямую без этапа сборки.

Если вам нужен другой тип файлов, который не поддерживается Astro нативно, добавьте этап сборки в ваш пакет. Это дополнительное упражнение остается на ваше усмотрение.

Библиотека Интеграций

Заголовок раздела Библиотека Интеграций

Поделитесь своими наработками, добавив свою интеграцию в нашу библиотеку интеграций!

Совет

Вам нужна помощь в создании вашей интеграции или вы просто хотите познакомиться с другими создателями интеграций? У нас есть специальный канал #integrations на нашем Discord-сервере. Заходите, поздоровайтесь!

package.json data

Заголовок раздела package.json data

Библиотека автоматически обновляется еженедельно и включает в себя все пакеты, опубликованные в NPM с ключевым словом astro-component или withastro.

Библиотека интеграций считывает данные name, description, repository и homepage из вашего package.json.

Аватары - отличный способ выделить свой бренд в библиотеке! Как только ваш пакет будет опубликован, вы можете создать проблему на GitHub прикрепив ваш аватар, и мы добавим его в ваш список.

Совет

Нужно переопределить информацию, которую наша библиотека считывает с NPM? Нет проблем! Создайте проблему с обновленной информацией, и мы убедимся, что вместо этого будет использоваться настраиваемое значение name, description или homepage.

Коллекции

Заголовок раздела Коллекции

Помимо обязательного ключевого слова astro-component или withastro, специальные ключевые слова также используются для автоматической организации пакетов. Включение любого из ключевых слов ниже добавит вашу интеграцию в коллекцию нашей библиотеки интеграций.

коллекция	ключевые слова
Доступность	a11y, accessibility
Адаптеры	astro-adapter
Аналитика	analytics
CSS + UI	css, ui, icon, icons, renderer
Фреймворки	renderer
Производительность + SEO	performance, perf, seo, optimization

Поделитесь

Заголовок раздела Поделитесь

Мы призываем вас делиться своими работами, и нам действительно нравится смотреть на то, что создают наши талантливые астронавты. Поделитесь с нами своими работами в Discord или упомяните @astrodotbuild в твите!