API интеграции Astro
Интеграции Astro добавляют новую функциональность и поведение в ваш проект всего несколькими строками кода.
Эта справочная страница предназначена для тех, кто пишет свои собственные интеграции. Чтобы узнать, как использовать интеграцию в своем проекте, ознакомьтесь с нашим Руководством по использованию интеграций.
Примеры
Заголовок раздела ПримерыОфициальные интеграции Astro могут служить вам в качестве примера при создании собственных интеграций.
- Рендереры:
lit
,svelte
,react
,preact
,vue
,solid
- Библиотеки:
tailwind
,partytown
- Функционал:
sitemap
Быстрая справка по API
Заголовок раздела Быстрая справка по APIastro:config:setup
Заголовок раздела astro:config:setupСледующий хук: astro:config:done
Когда: При инициализации, перед тем как Vite или конфигурация Astro будут разрешены.
Зачем: Для расширения конфигурации проекта. Это включает обновление конфигурации Astro, применение плагинов Vite, добавление рендеров компонентов и внедрение скриптов на страницу.
Опция config
Заголовок раздела Опция configТип: AstroConfig
Доступная только для чтения копия пользовательской конфигурации Astro. Это разрешается до запуска любых других интеграций. Если вам нужна копия конфигурации после того, как все интеграции завершили обновление своих конфигураций, см. хук astro:config:done
.
Опция command
Заголовок раздела Опция commandТип: 'dev' | 'build' | 'preview'
dev
— Проект выполняется с помощью astro devbuild
— Проект выполняется с помощьюastro build
preview
— Проект выполняется с помощьюastro preview
Опция isRestart
Заголовок раздела Опция isRestartТип: boolean
false
когда сервер разработки запускается, true
когда происходит перезагрузка. Полезно для определения, когда эта функция вызывается более одного раза.
Опция updateConfig
Заголовок раздела Опция updateConfigТип: (newConfig: DeepPartial<AstroConfig>) => AstroConfig;
Функция обратного вызова для обновления предоставленной пользователем конфигурации Astro. Любая предоставленная вами конфигурация будет объединена с пользовательской конфигурацией + обновлениями конфигурации других интеграций, поэтому вы можете не включать ключи!
Например, предположим, что вам нужно добавить в проект пользователя плагин Vite:
Опция addRenderer
Заголовок раздела Опция addRendererТип: (renderer:
AstroRenderer
) => void;
Примеры: lit
, svelte
, react
, preact
, vue
, solid
Функция обратного вызова для добавления рендерера фреймворка компонентов (например, React, Vue, Svelte и т. д.). Вы можете просмотреть примеры и определение типа выше для более продвинутых опций, но вот два основных варианта, о которых стоит знать:
clientEntrypoint
- путь к файлу, который выполняется на клиенте при каждом использовании вашего компонента. Это в основном для рендеринга или гидратации вашего компонента с помощью JS.serverEntrypoint
- путь к файлу, который выполняется во время запросов с сервера или статической сборки всякий раз, когда используется ваш компонент. Они должны рендерить компоненты в статическую разметку, с хуками для гидратации, если это применимо. Классическим примером является обратный вызовrenderToString
от React.
Опция addWatchFile
Заголовок раздела Опция addWatchFileТип: URL | string
Если ваша интеграция зависит от какого-то конфигурационного файла, за которым Vite не следит и/или для вступления в силу которого требуется полный перезапуск сервера разработки, добавьте его с помощью addWatchFile
. Каждый раз, при изменении этого файла, сервер разработки Astro будет перезагружен (вы можете проверить, когда произойдет перезагрузка с помощью isRestart
).
Пример использования:
Опция addClientDirective
Заголовок раздела Опция addClientDirective
Добавлено в:
astro@2.6.0
Тип: (directive:
ClientDirectiveConfig
) => void;
Добавляет пользовательскую директиву клиента, которая будет использоваться в файлах .astro
.
Обратите внимание, что точки входа директив поставляются только через esbuild и должны быть небольшими, чтобы не замедлять гидратацию компонентов.
Пример использования:
Вы также можете добавить типы для директив в файл определения типов вашей библиотеки:
Опция addDevToolbarApp
Заголовок раздела Опция addDevToolbarApp
Добавлено в:
astro@3.4.0
Тип: (pluginEntrypoint: string) => void;
Добавляет пользовательское приложение панели инструментов разработчика.
Пример использования:
Опция addMiddleware
Заголовок раздела Опция addMiddleware
Добавлено в:
astro@3.5.0
Тип: (middleware:
AstroIntegrationMiddleware
) => void;
Добавляет промежуточное ПО,, которое будет запускаться при каждом запросе. Принимает модуль entrypoint
, содержащий промежуточное ПО, и order
, указывающий, должно ли оно запускаться до (pre
) других промежуточных программ или после (post
).
Промежуточное ПО определяется в пакете с функцией onRequest
, также как и с пользовательским промежуточным ПО.
Опция injectRoute
Заголовок раздела Опция injectRouteТип: ({ pattern: string, entrypoint: string }) => void;
Функция обратного вызова для инъекции маршрутов в проект Astro. Инжектируемые маршруты могут быть страницами .astro
или обработчиками маршрутов .js
и .ts
.
injectRoute
принимает объект с pattern
и entrypoint
.
pattern
- куда маршрут должен быть выведен в браузере, например/foo/bar
. Шаблон может использовать синтаксис пути к файлу Astro для обозначения динамических маршрутов, например/foo/[bar]
или/foo/[...bar]
. Обратите внимание, что расширение файла не требуется вpattern
.entrypoint
- обычный модульный указатель, указывающий на страницу.astro
или обработчик маршрута.js
/.ts
, который обрабатывает маршрут, обозначенный вpattern
.
Пример использования:
Для интеграции, предназначенной для установки в другие проекты, используйте имя пакета для ссылки на точку входа в маршрут.
В следующем примере показан пакет, опубликованный в npm под именем @fancy/dashboard
, инжектирующий маршрут панели инструментов:
При публикации вашего пакета (в данном случае @fancy/dashboard
) на npm, вы должны экспортировать dashboard.astro
в ваш package.json
:
Опция injectScript
Заголовок раздела Опция injectScriptТип: (stage: InjectedScriptStage, content: string) => void;
Функция обратного вызова для вставки строки содержимого JavaScript на каждую страницу.
Параметр stage
указывает на то, как должен быть вставлен этот скрипт (content
). Некоторые этапы позволяют вставлять скрипты без модификации, другие - оптимизировать во время шага сборки Vite:
-
"head-inline"
: Вставляется в тег<script>
в<head>
каждой страницы. Не оптимизирован или разрешен Vite. -
"before-hydration"
: Импортируется на стороне клиента, перед запуском скрипта гидратации. Оптимизируется и разрешается Vite. -
"page"
: Аналогичноhead-inline
, за исключением того, что импортируемый фрагмент обрабатывается Vite и объединяется с любыми другими тегами<script>
, определенными внутри компонентов Astro на странице. Скрипт будет загружен с помощью<script type="module">
в конечный вывод страницы, оптимизирован и разрешен Vite. -
page-ssr
: Импортируется как отдельный модуль в frontmatter каждого компонента страницы Astro. Поскольку на этом этапе импортируется ваш скрипт, глобальныйAstro
недоступен, и ваш скрипт будет запущен только один раз при первой оценкеimport
.Основное применение этапа
page-ssr
- это вставка CSSимпорта
на каждую страницу для оптимизации и разрешения Vite:
astro:config:done
Заголовок раздела astro:config:doneПредыдущий хук: astro:config:setup
Следующий хук: astro:server:setup
при работе в режиме “dev”, или astro:build:start
при “production” сборке.
Когда: После того, как конфигурация Astro была разрешена, и другие интеграции выполнили свои хуки astro:config:setup
.
Зачем: Для получения окончательной конфигурации для использования в других хуках.
Опция config
Заголовок раздела Опция configТип: AstroConfig
Доступная только для чтения копия предоставленной пользователем конфигурации Astro. Это разрешается после выполнения других интеграций.
astro:server:setup
Заголовок раздела astro:server:setupПредыдущий хук: astro:config:done
Следующий хук: astro:server:start
Когда: Сразу после создания сервера Vite в режиме “dev”, но перед событием listen()
. См. API createServer Vite для получения дополнительной информации.
Зачем: Для обновления параметров сервера Vite и промежуточного ПО.
Опция server
Заголовок раздела Опция serverТип: ViteDevServer
Изменяемый экземпляр сервера Vite, используемый в режиме “dev”. Например, это используется нашей интеграцией Partytown для вставки сервера Partytown в качестве промежуточного ПО:
astro:server:start
Заголовок раздела astro:server:startПредыдущий хук: astro:server:setup
Следующий хук: astro:server:done
Когда: Сразу после срабатывания события listen()
сервера.
Зачем: Для перехвата сетевых запросов по указанному адресу. Если вы намерены использовать этот адрес для промежуточного ПО, рассмотрите возможность использования astro:server:setup
вместо этого.
Опция address
Заголовок раздела Опция addressТип: AddressInfo
Адрес, семейство и номер порта, предоставленные модулем Net NodeJS.
astro:server:done
Заголовок раздела astro:server:doneСледующий хук: astro:server:start
Когда: Сразу после закрытия сервера разработки.
Зачем: Для выполнения любых событий очистки, которые могут быть запущены во время хуков astro:server:setup
или astro:server:start
.
astro:build:start
Заголовок раздела astro:build:startПредыдущий хук: astro:config:done
Следующий хук: astro:build:setup
Когда: После события astro:config:done
, но перед началом производственной сборки.
Зачем: Для настройки любых глобальных объектов или клиентов, необходимых во время производственной сборки. Это также может расширить параметры конфигурации сборки в API адаптера.
astro:build:setup
Заголовок раздела astro:build:setupПредыдущий хук: astro:build:start
Следующий хук: astro:build:ssr
Когда: После хука astro:build:start
, запускается непосредственно перед сборкой.
Зачем: На этом этапе конфигурация Vite для сборки полностью сконструирована, это ваш последний шанс ее изменить. Это может быть полезно, например, для перезаписи некоторых значений по умолчанию. Если вы не уверены, следует ли использовать этот хук или astro:build:start
, используйте вместо этого astro:build:start
.
astro:build:generated
Заголовок раздела astro:build:generatedПредыдущий хук: astro:build:setup
Когда: После завершения статической производственной сборки, генерирующей маршруты и ассеты.
Зачем: Для доступа к сгенерированным маршрутам и ресурсам до очистки артефактов сборки. Это очень редкий случай использования. Мы рекомендуем использовать astro:build:done
, если вам действительно нужен доступ к сгенерированным файлам перед очисткой.
astro:build:ssr
Заголовок раздела astro:build:ssrПредыдущий хук: astro:build:setup
Когда: После завершения производственной сборки с SSR.
Зачем: Для доступа к манифесту SSR и карте излученных точек входа. Это полезно при создании пользовательских сборок SSR в плагинах или интеграциях.
entryPoints
сопоставляет маршрут страницы с физическим файлом, созданным после сборки;middlewareEntryPoint
- путь файловой системы к файлу промежуточного ПО;
astro:build:done
Заголовок раздела astro:build:doneПредыдущий хук: astro:build:ssr
Когда: После завершения сборки (SSG или SSR).
Зачем: Чтобы получить доступ к сгенерированным маршрутам и ассетам для расширения (например, скопировать содержимое в сгенерированную директорию /assets
). Если вы планируете преобразовывать сгенерированные ассеты, мы рекомендуем использовать API плагинов Vite и настройку через astro:config:setup
вместо этого.
Опция dir
Заголовок раздела Опция dirТип: URL
URL-путь к выходному каталогу сборки. Обратите внимание, что если вам нужна корректная строка абсолютного пути, вам следует использовать встроенную в Node утилиту fileURLToPath
.
Опция routes
Заголовок раздела Опция routesТип: RouteData[]
Список всех сгенерированных маршрутов вместе с их метаданными.
Вы можете ссылаться на полный тип RouteData
ниже, но наиболее часто используемые свойства:
component
— путь к входному файлу относительно корня проектаpathname
— URL выходного файла (не определен для маршрутов с параметрами[dynamic]
и[...spread]
)
Справка о типе RouteData
Заголовок раздела Справка о типе RouteDataОпция pages
Заголовок раздела Опция pagesТип: { pathname: string }[]
Список всех сгенерированных страниц. Это объект с одним свойством.
pathname
— окончательный путь страницы.
Разрешите установку с помощью astro add
Заголовок раздела Разрешите установку с помощью astro addКоманда astro add
позволяет пользователям легко добавлять интеграции и адаптеры в свой проект. Если вы хотите, чтобы ваша интеграция могла быть установлена с помощью этого инструмента, добавьте astro-integration
в поле keywords
в вашем package.json
:
Как только вы опубликуете свою интеграцию на npm, запуск astro add example
установит ваш пакет с любыми зависимостями, указанными в вашем package.json
. Это также применит вашу интеграцию к пользовательскому astro.config
, как показано ниже:
Это предполагает, что ваше определение интеграции является 1) экспортом default
и 2) функцией. Убедитесь, что это так, прежде чем добавлять ключевое слово astro-integration
!
AstroIntegrationLogger
Заголовок раздела AstroIntegrationLoggerЭкземпляр логгера Astro, полезный для записи логов. Этот логгер использует тот же уровень логирования, настроенный через CLI.
Доступные методы для записи в терминал:
logger.info("Сообщение")
;logger.warn("Сообщение")
;logger.error("Сообщение")
;logger.debug("Сообщение")
;
Все сообщения дополняются меткой, которая имеет то же значение, что и интеграция.
Приведенный выше пример будет регистрировать сообщение, которое включает предоставленное сообщение info
:
Чтобы записать в журнал несколько сообщений с другой меткой, используйте метод .fork
, чтобы указать альтернативу стандартному name
:
Приведенный выше пример по умолчанию будет создавать логи с [astro-format]
, и [astro-format/build]
при указании:
Порядок выполнения интеграций
Заголовок раздела Порядок выполнения интеграцийВсе интеграции запускаются в том порядке, в котором они настроены. Например, для массива [react(), svelte()]
в пользовательском файле astro.config.*
, react
будет запущен раньше svelte
.
В идеале ваша интеграция должна выполняться в любом порядке. Если это невозможно, мы рекомендуем документировать, что ваша интеграция должна быть первой или последней в массиве конфигурации integrations
пользователя.
Объединение интеграций в пресеты
Заголовок раздела Объединение интеграций в пресетыИнтеграция также может быть написана как набор нескольких более мелких интеграций. Мы называем эти наборы пресетами. Вместо создания функции-фабрики, возвращающей единственный объект интеграции, пресет возвращает массив объектов интеграции. Это полезно для создания сложных функций из нескольких интеграций.
Ресурсы сообщества
Заголовок раздела Ресурсы сообщества- Создание ваших собственных интеграций Astro - Эммануэль Оханс на FreeCodeCamp
- Шаблон интеграции Astro - Флориан Лефебр на GitHub