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

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

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

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

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

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

# Инициализируйте шаблон компонента 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

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

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

Directorymy-new-component-directory/
- Directorydemo/
  - … для тестирования и демонстрации
- package.json
- Directorypackages/
  - Directorymy-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 в директории пакета содержит всю информацию, относящуюся к вашему пакету, включая его описание, зависимости и любые другие метаданные пакета

{
  "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": "An Astro Element Generator"
}

`type`

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

{
  "type": "module"
}

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

`homepage`

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

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

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

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

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

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

`keywords`

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

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

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

`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!)

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

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

Directorymy-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 нативно, добавьте этап сборки в ваш пакет. Это дополнительное упражнение остается на ваше усмотрение.

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

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

`package.json` data

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

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

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

Коллекции

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

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

Поделитесь

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

Создать проблему в GitHub

Отправить нам отзыв

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

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

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

`package.json`

`description`

`type`

`homepage`

`exports`

`files`

`keywords`

`index.js`

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

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

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

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

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

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

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

`package.json` data

Коллекции

Поделитесь

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

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

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

package.json

description

type

homepage

exports

files

keywords

index.js

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

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

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

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

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

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

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

package.json data

Коллекции

Поделитесь

`package.json`

`description`

`type`

`homepage`

`exports`

`files`

`keywords`

`index.js`

`package.json` data