API интеграции Astro

Интеграции Astro добавляют новую функциональность и поведение в ваш проект всего несколькими строками кода.

Эта справочная страница предназначена для тех, кто пишет свои собственные интеграции. Чтобы узнать, как использовать интеграцию в своем проекте, ознакомьтесь с нашим Руководством по использованию интеграций (EN).

Примеры

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

Рендереры: svelte (EN), react (EN), preact (EN), vue (EN), solid (EN)
Библиотеки: partytown (EN)
Функционал: sitemap (EN)

Краткий справочник по API

interface AstroIntegration {
  name: string;
  hooks: {
    'astro:config:setup'?: (options: {
      config: AstroConfig;
      command: 'dev' | 'build' | 'preview' | 'sync';
      isRestart: boolean;
      updateConfig: (newConfig: DeepPartial<AstroConfig>) => AstroConfig;
      addRenderer: (renderer: AstroRenderer) => void;
      addWatchFile: (path: URL | string) => void;
      addClientDirective: (directive: ClientDirectiveConfig) => void;
      addMiddleware: (middleware: AstroIntegrationMiddleware) => void;
      addDevToolbarApp: (entrypoint: DevToolbarAppEntry) => void;
      injectScript: (stage: InjectedScriptStage, content: string) => void;
      injectRoute: (injectedRoute: InjectedRoute) => void;
      createCodegenDir: () => URL;
      logger: AstroIntegrationLogger;
    }) => void | Promise<void>;
    'astro:route:setup'?: (options: {
      route: RouteOptions;
      logger: AstroIntegrationLogger;
    }) => void | Promise<void>;
    'astro:routes:resolved'?: (options: {
      routes: IntegrationResolvedRoute[];
      logger: AstroIntegrationLogger;
    }) => void | Promise<void>;
    'astro:config:done'?: (options: {
      config: AstroConfig;
      setAdapter: (adapter: AstroAdapter) => void;
      injectTypes: (injectedType: InjectedType) => URL;
      logger: AstroIntegrationLogger;
      buildOutput: 'static' | 'server';
    }) => void | Promise<void>;
    'astro:server:setup'?: (options: {
      server: vite.ViteDevServer;
      logger: AstroIntegrationLogger;
      toolbar: ReturnType<typeof getToolbarServerCommunicationHelpers>;
      refreshContent?: (options: RefreshContentOptions) => Promise<void>;
    }) => void | Promise<void>;
    'astro:server:start'?: (options: {
      address: AddressInfo;
      logger: AstroIntegrationLogger;
    }) => void | Promise<void>;
    'astro:server:done'?: (options: {
      logger: AstroIntegrationLogger;
    }) => void | Promise<void>;
    'astro:build:start'?: (options: {
      logger: AstroIntegrationLogger;
    }) => void | Promise<void>;
    'astro:build:setup'?: (options: {
      vite: vite.InlineConfig;
      pages: Map<string, PageBuildData>;
      target: 'client' | 'server';
      updateConfig: (newConfig: vite.InlineConfig) => void;
      logger: AstroIntegrationLogger;
    }) => void | Promise<void>;
    'astro:build:ssr'?: (options: {
      manifest: SerializedSSRManifest;
      entryPoints: Map<IntegrationRouteData, URL>;
      middlewareEntryPoint: URL | undefined;
      logger: AstroIntegrationLogger;
    }) => void | Promise<void>;
    'astro:build:generated'?: (options: {
      dir: URL;
      logger: AstroIntegrationLogger;
    }) => void | Promise<void>;
    'astro:build:done'?: (options: {
      pages: { pathname: string }[];
      dir: URL;
      assets: Map<string, URL[]>;
      logger: AstroIntegrationLogger;
    }) => void | Promise<void>;

    // ... любые кастомные хуки для интеграций
  };
}

Хуки

Astro предоставляет хуки, которые интеграции могут реализовать для выполнения на определённых этапах жизненного цикла Astro. Хуки Astro определены в интерфейсе IntegrationHooks, который является частью глобального пространства имён Astro. Каждый хук имеет опцию logger, позволяющую использовать логгер Astro для записи логов.

В Astro встроены следующие хуки:

`astro:config:setup`

Следующий хук: astro:route:setup

Когда: При инициализации, перед тем как Vite или конфигурация Astro (EN) будут разрешены.

Зачем: Для расширения конфигурации проекта. Это включает обновление конфигурации Astro (EN), применение плагинов Vite, добавление рендеров компонентов и внедрение скриптов на страницу.

'astro:config:setup'?: (options: {
  config: AstroConfig;
  command: 'dev' | 'build' | 'preview' | 'sync';
  isRestart: boolean;
  updateConfig: (newConfig: DeepPartial<AstroConfig>) => AstroConfig;
  addRenderer: (renderer: AstroRenderer) => void;
  addClientDirective: (directive: ClientDirectiveConfig) => void;
  addMiddleware: (middleware: AstroIntegrationMiddleware) => void;
  addDevToolbarApp: (entrypoint: DevToolbarAppEntry) => void;
  addWatchFile: (path: URL | string) => void;
  injectScript: (stage: InjectedScriptStage, content: string) => void;
  injectRoute: (injectedRoute: InjectedRoute) => void;
  createCodegenDir: () => URL;
  logger: AstroIntegrationLogger;
}) => void | Promise<void>;

Опция `config`

Тип: AstroConfig

Доступная только для чтения копия пользовательской конфигурации Astro (EN). Это разрешается до запуска любых других интеграций. Если вам нужна копия конфигурации после того, как все интеграции завершили обновление своих конфигураций, см. хук astro:config:done.

Опция `command`

Тип: 'dev' | 'build' | 'preview' | 'sync'

dev — Проект выполняется с помощью astro dev
build — Проект выполняется с помощью astro build
preview — Проект выполняется с помощью astro preview
sync — Проект выполняется с помощью astro sync

Опция `isRestart`

Тип: boolean

Добавлено в: astro@1.5.0

false при запуске сервера разработки, true при срабатывании перезагрузки. Полезно для определения, когда эта функция вызывается более одного раза.

Опция `updateConfig`

Тип: (newConfig: DeepPartial<AstroConfig>) => AstroConfig;

Функция обратного вызова для обновления предоставленной пользователем конфигурации Astro (EN). Любая предоставленная вами конфигурация будет объединена с пользовательской конфигурацией + обновлениями конфигурации других интеграций, поэтому вы можете не включать ключи!

Например, предположим, что вам нужно добавить в проект пользователя плагин Vite:

import bananaCSS from '@vitejs/official-banana-css-plugin';

export default {
  name: 'banana-css-integration',
  hooks: {
    'astro:config:setup': ({ updateConfig }) => {
      updateConfig({
        vite: {
          plugins: [bananaCSS()],
        }
      })
    }
  }
}

Опция `addRenderer`

Тип: (renderer: AstroRenderer ) => void;
Примеры: svelte, react, preact, vue, solid

Функция обратного вызова для добавления рендерера фреймворка компонентов (например, React, Vue, Svelte и т. д.). Вы можете просмотреть примеры и определение типа выше для более продвинутых опций, но вот два основных варианта, о которых стоит знать:

clientEntrypoint - путь к файлу, который выполняется на клиенте при каждом использовании вашего компонента. Это в основном для рендеринга или гидратации вашего компонента с помощью JS.
serverEntrypoint - путь к файлу, который выполняется во время запросов с сервера или статической сборки всякий раз, когда используется ваш компонент. Они должны рендерить компоненты в статическую разметку, с хуками для гидратации, если это применимо. Классическим примером является обратный вызов renderToString от React.

Функции clientEntrypoint и serverEntrypoint принимают URL.

Опция `addWatchFile`

Тип: (path: URL | string) => void

Добавлено в: astro@1.5.0

Если ваша интеграция зависит от какого-то конфигурационного файла, за которым Vite не следит и/или для вступления в силу которого требуется полный перезапуск сервера разработки, добавьте его с помощью addWatchFile. Каждый раз, при изменении этого файла, сервер разработки Astro будет перезагружен (вы можете проверить, когда произойдет перезагрузка с помощью isRestart).

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

// Путь должен быть абсолютным!
addWatchFile('/home/user/.../my-config.json');
addWatchFile(new URL('./tailwind.config.js', config.root));

Опция `addClientDirective`

Тип: (directive: ClientDirectiveConfig ) => void;

Добавлено в: astro@2.6.0

Добавляет пользовательскую клиентскую директиву (EN) для использования в файлах .astro.

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

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

import { defineConfig } from 'astro/config';
import clickDirective from './astro-click-directive/register.js'

// https://astro.build/config
export default defineConfig({
  integrations: [
    clickDirective()
  ],
});

/**
 * @type {() => import('astro').AstroIntegration}
 */
export default () => ({
  name: "client:click",
  hooks: {
    "astro:config:setup": ({ addClientDirective }) => {
      addClientDirective({
        name: "click",
        entrypoint: "./astro-click-directive/click.js",
      });
    },
  },
});

/**
 * Гидратация при первом нажатии на окно
 * @type {import('astro').ClientDirective}
 */
export default (load, opts, el) => {
  window.addEventListener('click', async () => {
    const hydrate = await load()
    await hydrate()
  }, { once: true })
}

Вы также можете добавить типы для директив в файл определения типов вашей библиотеки:

import 'astro'
declare module 'astro' {
  interface AstroClientDirectives {
    'client:click'?: boolean
  }
}

Опция `addDevToolbarApp`

Тип: (entrypoint: DevToolbarAppEntry) => void;

Добавлено в: astro@3.4.0

Добавляет пользовательское приложение для панели разработчика (EN).

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

import { defineConfig } from 'astro/config';
import devToolbarIntegration from './astro-dev-toolbar-app/integration.js'

// https://astro.build/config
export default defineConfig({
  integrations: [
    devToolbarIntegration()
  ],
});

/**
 * @type {() => import('astro').AstroIntegration}
 */
export default () => ({
  name: "dev-toolbar-app",
  hooks: {
    "astro:config:setup": ({ addDevToolbarApp }) => {
      addDevToolbarApp({
        entrypoint: "./astro-dev-toolbar-app/plugin.js",
        id: "my-plugin",
        name: "My Plugin"
      });
    },
  },
});


/**
 * @type {import('astro').DevToolbarApp}
 */
export default {
  id: "my-plugin",
  name: "My Plugin",
  icon: "<svg>...</svg>",
  init() {
    console.log("I'm a dev toolbar app!")
  },
};

Опция `addMiddleware`

Тип: (middleware: AstroIntegrationMiddleware ) => void;

Добавлено в: astro@3.5.0

Добавляет мидлвар (EN), который будет выполняться при каждом запросе. Принимает модуль entrypoint, содержащий мидлвар, и параметр order, чтобы указать, должен ли он выполняться до (pre) или после (post) других мидлваров.

/**
 * @type {() => import('astro').AstroIntegration}
 */
export default () => ({
  name: "my-middleware-package",
  hooks: {
    "astro:config:setup": ({ addMiddleware }) => {
        addMiddleware({
          entrypoint: '@my-package/middleware',
          order: 'pre'
        });
    },
  },
});

Мидлвар определяется в пакете с функцией onRequest, как и в случае с пользовательским мидлваром.

import { defineMiddleware } from 'astro:middleware';

export const onRequest = defineMiddleware(async (context, next) => {
  if(context.url.pathname === '/some-test-path') {
    return Response.json({
      ok: true
    });
  }

  return next();
});

Функция также принимает URL для entrypoint:

/**
 * @type {() => import('astro').AstroIntegration}
 */
export default () => ({
  name: "my-middleware-package",
  hooks: {
    "astro:config:setup": ({ addMiddleware }) => {
      addMiddleware({
        entrypoint: new URL('./middleware.js', import.meta.url),
        order: 'pre'
      });
    },
  },
});

Опция `injectRoute`

Тип: ({ pattern: string; entrypoint: string | URL; prerender?: boolean }) => void;

Функция обратного вызова для инъекции маршрутов в проект Astro. Инжектируемые маршруты могут быть страницами .astro или обработчиками маршрутов .js и .ts.

injectRoute принимает объект с pattern и entrypoint.

pattern — куда маршрут должен быть выведен в браузере, например /foo/bar. Шаблон может использовать синтаксис пути к файлу Astro для обозначения динамических маршрутов, например /foo/[bar] или /foo/[...bar]. Обратите внимание, что расширение файла не требуется в pattern.
entrypoint — обычный модульный указатель, указывающий на страницу .astro или обработчик маршрута .js/.ts, который обрабатывает маршрут, обозначенный в pattern.
prerender — булево значение, которое нужно установить, если Astro не может определить ваш экспорт prerender.

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

injectRoute({
  // Используйте синтаксис шаблонов Astro для динамических маршрутов.
  pattern: '/subfolder/[dynamic]',
  // Используйте синтаксис относительного пути для локального маршрута.
  entrypoint: './src/dynamic-page.astro',
  // Используйте только в том случае, если Astro не может определить ваш экспорт `prerender`
  prerender: false
});

Для интеграции, предназначенной для установки в других проектах, используйте имя её пакета для указания точки входа маршрута.Следующий пример показывает пакет, опубликованный в npm как @fancy/dashboard, который добавляет маршрут для панели управления:

injectRoute({
  pattern: '/fancy-dashboard',
  entrypoint: '@fancy/dashboard/dashboard.astro'
});

При публикации вашего пакета (в данном случае @fancy/dashboard) на npm, вы должны экспортировать dashboard.astro в ваш package.json:

{
  "name": "@fancy/dashboard",
  // ...
  "exports": { "./dashboard.astro": "./dashboard.astro" }`
}

Функция также принимает URL для entrypoint:

injectRoute({
  pattern: '/fancy-dashboard',
  entrypoint: new URL('./dashboard.astro', import.meta.url)
});

Опция `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: Импортируется как отдельный модуль в метаданных каждого компонента страницы Astro. Поскольку на этом этапе импортируется ваш скрипт, глобальный Astro недоступен, и ваш скрипт будет запущен только один раз при первом анализе import.

Основное применение этапа page-ssr - это вставка CSS import на каждую страницу для оптимизации и разрешения Vite:
```
injectScript('page-ssr', 'import "global-styles.css";');
```

`createCodegenDir`

Тип: () => URL;

Добавлено в: astro@5.0.0

Функция, которая создаёт папку <root>/.astro/integrations/<normalized_integration_name> и возвращает её путь.

Она позволяет вам иметь выделенную папку, избегая конфликтов с другими интеграциями или самим Astro. Эта директория создаётся при вызове данной функции, поэтому можно безопасно записывать файлы напрямую:

import { writeFileSync } from 'node:fs'

const integration = {
  name: 'my-integration',
  hooks: {
    'astro:config:setup': ({ createCodegenDir }) => {
      const codegenDir = createCodegenDir()
      writeFileSync(new URL('cache.json', codegenDir), '{}', 'utf-8')
    }
  }
}

`astro:route:setup`

Предыдущий хук: astro:config:setup

Следующий хук: astro:routes:resolved

Когда: В astro build — перед началом сборки. В astro dev — во время построения графа модулей и при каждом изменении файлового маршрута (добавление/удаление/обновление).

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

'astro:route:setup'?: (options: {
  route: RouteOptions;
  logger: AstroIntegrationLogger;
}) => void | Promise<void>;

Опция `route`

Тип: RouteOptions

Объект со свойством component для идентификации маршрута и следующими дополнительными значениями, позволяющими настроить сгенерированный маршрут: prerender.

`route.component`

Тип: string

Добавлено в: astro@4.14.0

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

`route.prerender`

Тип: boolean
По умолчанию: undefined

Добавлено в: astro@4.14.0

Свойство prerender используется для настройки рендеринга на стороне сервера по запросу для маршрута. Если файл маршрута содержит явное значение export const prerender, оно будет использоваться по умолчанию вместо undefined.

import { defineConfig } from 'astro/config';

export default defineConfig({
  integrations: [setPrerender()],
});

function setPrerender() {
  return {
    name: 'set-prerender',
    hooks: {
      'astro:route:setup': ({ route }) => {
        if (route.component.endsWith('/blog/[slug].astro')) {
          route.prerender = true;
        }
      },
    },
  };
}

Если окончательное значение после выполнения всех хуков равно undefined, маршрут будет использовать значение по умолчанию для предварительного рендеринга на основе опции output (EN): предварительный рендеринг для режима static и рендеринг по запросу для режима server.

`astro:routes:resolved`

Добавлено в: astro@5.0.0

Предыдущий хук: astro:route:setup

Следующий хук: astro:config:done (только во время настройки)

Когда: В astro dev, также выполняется при каждом изменении файлового маршрута (добавление/удаление/обновление).

Зачем: Для доступа к маршрутам и их метаданным

'astro:routes:resolved'?: (options: {
  routes: IntegrationResolvedRoute[];
  logger: AstroIntegrationLogger;
}) => void | Promise<void>;

Опция `routes`

Тип: IntegrationResolvedRoute[]

Список всех маршрутов с их связанными метаданными.

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

const integration = () => {
  return {
    name: 'my-integration',
    hooks: {
      'astro:routes:resolved': ({ routes }) => {
        const projectRoutes = routes.filter(r => r.origin === 'project').map(r => r.pattern)
        
        console.log(projectRoutes)
      },
    }
  }
}

`astro:config:done`

Предыдущий хук: astro:routes:resolved

Следующий хук: astro:server:setup при работе в режиме «dev», или astro:build:start при «production» сборке.

Когда: После того, как конфигурация Astro была разрешена, и другие интеграции выполнили свои хуки astro:config:setup.

Зачем: Для получения окончательной конфигурации для использования в других хуках.

'astro:config:done'?: (options: {
  config: AstroConfig;
  setAdapter: (adapter: AstroAdapter) => void;
  injectTypes: (injectedType: InjectedType) => URL;
  logger: AstroIntegrationLogger;
  buildOutput: 'static' | 'server';
}) => void | Promise<void>;

Опция `config`

Тип: AstroConfig

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

Опция `setAdapter()`

Тип: (adapter: AstroAdapter) => void;

Делает интеграцию адаптером. Подробнее в справочнике по API адаптеров (EN).

Опция `injectTypes()`

Тип: (injectedType: { filename: string; content: string }) => URL

Добавлено в: astro@4.14.0

Позволяет внедрять типы в проект пользователя, добавляя новый файл *.d.ts.

Свойство filename будет использоваться для создания файла по пути /.astro/integrations/<normalized_integration_name>/<normalized_filename>.d.ts и должно заканчиваться на ".d.ts".

Свойство content создаёт содержимое файла и должно быть валидным TypeScript.

Кроме того, injectTypes() возвращает URL к нормализованному пути, чтобы вы могли позже перезаписать его содержимое или манипулировать им любым удобным способом.

const path = injectTypes({
  filename: "types.d.ts",
  content: "declare module 'virtual:integration' {}"
})
console.log(path) // URL

Опция `buildOutput`

Тип: 'static' | 'server'

Добавлено в: astro@5.0.0

Позволяет адаптировать логику вашей интеграции в зависимости от вывода проекта пользователя.

`astro:server:setup`

Предыдущий хук: astro:config:done

Следующий хук: astro:server:start

Когда: Сразу после создания сервера Vite в режиме «dev», но перед событием listen(). См. API createServer Vite для получения дополнительной информации.

Зачем: Для обновления параметров сервера Vite и мидлвара, или включения поддержки обновления слоя контента.

'astro:server:setup'?: (options: {
  server: vite.ViteDevServer;
  logger: AstroIntegrationLogger;
  toolbar: ReturnType<typeof getToolbarServerCommunicationHelpers>;
  refreshContent: (options: {
    loaders?: Array<string>;
    context?: Record<string, any>;
  }) => Promise<void>;
}) => void | Promise<void>;

Опция `server`

Тип: ViteDevServer

Изменяемый экземпляр сервера Vite, используемый в режиме «dev». Например, это используется нашей интеграцией Partytown (EN) для вставки сервера Partytown в качестве мидлвара:

export default {
  name: 'partytown',
  hooks: {
    'astro:server:setup': ({ server }) => {
      server.middlewares.use(
        function middleware(req, res, next) {
          // обработка запросов
        }
      );
    }
  }
}

Опция `toolbar`

Тип: ReturnType<typeof getToolbarServerCommunicationHelpers>

Добавлено в: astro@4.7.0

Объект, предоставляющий функции обратного вызова для взаимодействия с панелью разработчика (EN):

`on()`

Тип: <T>(event: string, callback: (data: T) => void) => void

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

`onAppInitialized()`

Тип: (appId: string, callback: (data: Record<string, never>) => void) => void

Функция, вызываемая при инициализации приложения панели разработчика. Первый аргумент — это идентификатор инициализированного приложения. Второй аргумент — функция обратного вызова, которая выполняется при инициализации приложения.

`onAppToggled()`

Тип: (appId: string, callback: (data: { state: boolean; }) => void) => void

Функция, вызываемая при включении или выключении приложения панели разработчика. Первый аргумент — это идентификатор приложения, которое было переключено. Второй аргумент — функция обратного вызова, предоставляющая состояние для выполнения при переключении приложения.

`send()`

Тип: <T>(event: string, payload: T) => void

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

`refreshContent()` option

Тип: (options: { loaders?: Array<string>; context?: Record<string, any>; }) => Promise<void>

Добавлено в: astro@5.0.0

Функция, позволяющая интеграциям инициировать обновление слоя контента во время работы astro dev. Например, её можно использовать для регистрации конечной точки вебхука в режиме разработки или для открытия сокета к CMS, чтобы отслеживать изменения.

По умолчанию refreshContent обновляет все коллекции. Вы можете дополнительно передать свойство loaders — массив имён загрузчиков. Если оно указано, обновятся только коллекции, использующие эти загрузчики. Например, интеграция с CMS может использовать это свойство для обновления только своих коллекций.

Также можно передать объект context в загрузчики. Это позволяет передавать произвольные данные, такие как тело вебхука или событие из вебсокета.

{
  name: 'my-integration',
  hooks: {
    'astro:server:setup': async ({ server, refreshContent }) => {
      // Регистрируем конечную точку вебхука для сервера разработки
      server.middlewares.use('/_refresh', async (req, res) => {
        if(req.method !== 'POST') {
          res.statusCode = 405
          res.end('Метод не разрешён');
          return
        }
        let body = '';
        req.on('data', chunk => {
          body += chunk.toString();
        });
        req.on('end', async () => {
          try {
            const webhookBody = JSON.parse(body);
            await refreshContent({
              context: { webhookBody },
              loaders: ['my-loader']
            });
            res.writeHead(200, { 'Content-Type': 'application/json' });
            res.end(JSON.stringify({ message: 'Контент успешно обновлён' }));
          } catch (error) {
            res.writeHead(500, { 'Content-Type': 'application/json' });
            res.end(JSON.stringify({ error: 'Не удалось обновить контент: ' + error.message }));
          }
        });
      });
    }
  }
}

Загрузчик может затем получить доступ к свойству refreshContextData, чтобы получить тело вебхука. Подробнее см. в описании свойства refreshContextData (EN).

`astro:server:start`

Предыдущий хук: astro:server:setup

Следующий хук: astro:server:done

Когда: Сразу после срабатывания события listen() сервера.

Зачем: Для перехвата сетевых запросов по указанному адресу. Если вы намерены использовать этот адрес для мидлвара, рассмотрите возможность использования astro:server:setup вместо этого.

'astro:server:start'?: (options: {
  address: AddressInfo;
  logger: AstroIntegrationLogger;
}) => void | Promise<void>;

Опция `address`

Тип: AddressInfo

Адрес, семейство и номер порта, предоставленные модулем Net Node.js.

`astro:server:done`

Предыдущий хук: astro:server:start

Когда: Сразу после закрытия сервера разработки.

Зачем: Для выполнения любых событий очистки, которые могут быть запущены во время хуков astro:server:setup или astro:server:start.

'astro:server:done'?: (options: {
  logger: AstroIntegrationLogger;
}) => void | Promise<void>;

`astro:build:start`

Предыдущий хук: astro:config:done

Следующий хук: astro:build:setup

Когда: После события astro:config:done, но перед запуском сборки для продакшена.

Зачем: Для настройки любых глобальных объектов или клиентов, необходимых во время продакшен-сборки. Это также может расширить параметры конфигурации сборки в API адаптера (EN).

'astro:build:start'?: (options: {
  logger: AstroIntegrationLogger;
}) => void | Promise<void>;

`astro:build:setup`

Предыдущий хук: astro:build:start

Следующий хук: astro:build:ssr

Когда: После хука astro:build:start, запускается непосредственно перед сборкой.

Зачем: На этом этапе конфигурация Vite для сборки полностью сконструирована, это ваш последний шанс её изменить. Это может быть полезно, например, для перезаписи некоторых значений по умолчанию. Если вы не уверены, следует ли использовать этот хук или astro:build:start, используйте вместо этого astro:build:start.

'astro:build:setup'?: (options: {
  vite: vite.InlineConfig;
  pages: Map<string, PageBuildData>;
  target: 'client' | 'server';
  updateConfig: (newConfig: vite.InlineConfig) => void;
  logger: AstroIntegrationLogger;
}) => void | Promise<void>;

Опция `vite`

Тип: InlineConfig

Объект, позволяющий получить доступ к конфигурации Vite, используемой при сборке.

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

export default {
  name: 'my-integration',
  hooks: {
    'astro:build:setup': ({ vite }) => {
      const { publicDir, root } = vite;
    },
  }
}

Опция `pages`

Тип: Map<string, PageBuildData>

Map, содержащий список страниц в качестве ключей и их данные сборки в качестве значений.

Это можно использовать для выполнения действия, если маршрут соответствует определённому критерию:

export default {
  name: 'my-integration',
  hooks: {
    'astro:build:setup': ({ pages }) => {
      pages.forEach((data) => {
        if (data.route.pattern.test("/blog")) {
          console.log(data.route.type);
        }
      });
    },
  }
}

Опция `target`

Тип: 'client' | 'server'

Сборка разделена на две фазы: client и server. Эта опция позволяет определить текущую фазу сборки.

Её можно использовать для выполнения действия только в определённой фазе:

export default {
  name: 'my-integration',
  hooks: {
    'astro:build:setup': ({ target }) => {
      if (target === "server") {
        // делаем что-нибудь в фазе сервера
      }
    },
  }
}

Опция `updateConfig()`

Тип: (newConfig: InlineConfig) => void

Функция обратного вызова для обновления параметров Vite, используемых при сборке. Любая предоставленная вами конфигурация будет объединена с конфигурацией пользователя и обновлениями других интеграций, поэтому вы можете свободно опускать ключи!

Например, это можно использовать для добавления плагина в проект пользователя:

import awesomeCssPlugin from 'awesome-css-vite-plugin';

export default {
  name: 'my-integration',
  hooks: {
    'astro:build:setup': ({ updateConfig }) => {
      updateConfig({
        plugins: [awesomeCssPlugin()],
      })
    }
  }
}

`astro:build:ssr`

Предыдущий хук: astro:build:setup

Следующий хук: astro:build:generated

Когда: После завершения продакшен-сборки с SSR.

Зачем: Для доступа к SSR-манифесту и карте созданных точек входа. Это полезно при создании пользовательских SSR-сборок в плагинах или интеграциях.

entryPoints сопоставляет маршрут страницы с физическим файлом, созданным после сборки;
middlewareEntryPoint - путь файловой системы к файлу мидлвара;

'astro:build:ssr'?: (options: {
  manifest: SerializedSSRManifest;
  entryPoints: Map<IntegrationRouteData, URL>;
  middlewareEntryPoint: URL | undefined;
  logger: AstroIntegrationLogger;
}) => void | Promise<void>;

Опция `manifest`

Тип: SerializedSSRManifest

Позволяет создать пользовательскую сборку, получая доступ к SSR-манифесту.

export default {
  name: 'my-integration',
  hooks: {
    'astro:build:ssr': ({ manifest }) => {
      const { i18n } = manifest;
      if (i18n?.strategy === "domains-prefix-always") {
        // что-то делаем
      }
    },
  },
}

Опция `entryPoints`

Тип: Map<IntegrationRouteData, URL>

Добавлено в: astro@2.7.0

Map созданных точек входа, где ключом являются данные IntegrationRouteData, а значением — URL физического файла.

export default {
  name: 'my-integration',
  hooks: {
    'astro:build:ssr': ({ entryPoints }) => {
      entryPoints.forEach((url) => {
        console.log(url.href);
      });
    },
  },
}

Опция `middlewareEntryPoint`

Тип: URL | undefined

Добавлено в: astro@2.8.0

Предоставляет путь к файлу мидлвара (EN).

export default {
  name: 'my-integration',
  hooks: {
    'astro:build:ssr': ({ middlewareEntryPoint }) => {
      if (middlewareEntryPoint) {
        // выполняем какие-нибудь операции, если существует мидлвар
      }
    },
  },
}

`astro:build:generated`

Добавлено в: astro@1.3.0

Предыдущий хук: astro:build:ssr

Следующий хук: astro:build:done

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

Зачем: Для доступа к сгенерированным маршрутам и ресурсам до очистки артефактов сборки. Это очень редкий случай использования. Мы рекомендуем использовать astro:build:done, если вам действительно нужен доступ к сгенерированным файлам перед очисткой.

'astro:build:generated'?: (options: {
  dir: URL;
  logger: AstroIntegrationLogger;
}) => void | Promise<void>;

Опция `dir`

Тип: URL

URL-путь к директории вывода сборки. Обратите внимание, что если вам нужна валидная абсолютная строка пути, следует использовать встроенную в Node утилиту fileURLToPath.

import { fileURLToPath } from 'node:url';

export default {
  name: 'my-integration',
  hooks: {
    'astro:build:generated': ({ dir }) => {
      const outFile = fileURLToPath(new URL('./my-integration.json', dir));
    }
  }
}

`astro:build:done`

Предыдущий хук: astro:build:generated

Когда: После завершения продакшен-сборки (SSG или SSR).

Зачем: Чтобы получить доступ к сгенерированным маршрутам и ресурсам для расширения (например, скопировать содержимое в сгенерированную директорию /assets). Если вы планируете преобразовывать сгенерированные ресурсы, мы рекомендуем использовать API плагинов Vite и настройку через astro:config:setup вместо этого.

'astro:build:done'?: (options: {
  pages: { pathname: string }[];
  dir: URL;
  /** @deprecated Используйте карту `assets`` и новый хук `astro:routes:resolved` */
  routes: IntegrationRouteData[];
  assets: Map<string, URL[]>;
  logger: AstroIntegrationLogger;
}) => void | Promise<void>;

Опция `dir`

Тип: URL

URL-путь к выходному каталогу сборки. Обратите внимание, что если вам нужна валидная строка абсолютного пути, вам следует использовать встроенную в Node утилиту fileURLToPath.

import { writeFile } from 'node:fs/promises';
import { fileURLToPath } from 'node:url';

export default function myIntegration() {
  return {
    hooks: {
      'astro:build:done': async ({ dir }) => {
        const metadata = await getIntegrationMetadata();
        // Используем `fileURLToPath`, чтобы получить валидную абсолютную строку пути, совместимую с разными платформами
        const outFile = fileURLToPath(new URL('./my-integration.json', dir));
        await writeFile(outFile, JSON.stringify(metadata));
      }
    }
  }
}

Опция `routes`

:::cautionЭто свойство устарело начиная с v5.0. Ознакомьтесь с руководством по миграции.:::

Тип: IntegrationRouteData[]

Список всех сгенерированных маршрутов вместе с их метаданными.

Вы можете ссылаться на полный тип IntegrationRouteData ниже, но наиболее часто используемые свойства:

component — путь к входному файлу относительно корня проекта
pathname — URL выходного файла (не определен для маршрутов с параметрами [dynamic] и [...spread])

Опция `assets`

Тип: Map<string, URL[]>

Добавлено в: astro@5.0.0

Содержит URL-адреса путей к выходным файлам, сгруппированные по свойству pattern типа IntegrationResolvedRoute.

Опция `pages`

Тип: { pathname: string }[]

Список всех сгенерированных страниц. Это объект с одним свойством.

pathname — окончательный путь страницы.

Пользовательские хуки

Пользовательские хуки можно добавлять в интеграции, расширяя интерфейс IntegrationHooks с помощью глобального расширения.

declare global {
  namespace Astro {
    export interface IntegrationHook {
      'your:hook': (params: YourHookParameters) => Promise<void>
    }
  }
}

Astro резервирует префикс astro: для будущих встроенных хуков. Пожалуйста, выберите другой префикс при именовании вашего пользовательского хука.

Справочник по типам интеграций

`AstroIntegrationLogger`

Экземпляр логгера Astro, полезный для записи логов. Этот логгер использует тот же уровень логирования (EN), что и настроенный через CLI.

Доступные методы для записи в терминал:

logger.info("Сообщение");
logger.warn("Сообщение");
logger.error("Сообщение");
logger.debug("Сообщение");

Все сообщения предваряются меткой, значение которой совпадает с именем интеграции.

import type { AstroIntegration } from "astro";
export function formatIntegration(): AstroIntegration {
  return {
    name: "astro-format",
    hooks: {
      "astro:build:done": ({ logger }) => {
        // делаем что-нибудь
        logger.info("Интеграция готова.");
      }
    }
  }
}

Пример выше запишет сообщение, включающее предоставленное info-сообщение:

[astro-format] Integration ready.

Чтобы записать сообщения с другой меткой, используйте метод .fork, чтобы указать альтернативу значению по умолчанию name:

import type { AstroIntegration } from "astro";
export function formatIntegration(): AstroIntegration {
  return {
    name: "astro-format",
    hooks: {
      "astro:config:done": ({ logger }) => {
        // делаем что-нибудь
        logger.info("Интеграция готова.");
      },
      "astro:build:done": ({ logger }) => {
        const buildLogger = logger.fork("astro-format/build");
        // делаем что-нибудь
        buildLogger.info("Сборка завершена.")
      }
    }
  }
}

Пример выше будет создавать логи с [astro-format] по умолчанию и [astro-format/build], когда это указано:

[astro-format] Интеграция готова.
[astro-format/build] Сборка завершена.

`HookParameters`

Вы можете получить тип аргументов хука, передав имя хука в утилиту типа HookParameters. В следующем примере аргумент options функции типизирован в соответствии с параметрами хука astro:config:setup:

import type { HookParameters } from 'astro';

function mySetup(options: HookParameters<'astro:config:setup'>) {
  options.updateConfig({ /* ... */ });
}

Справка о типе `IntegrationResolvedRoute`

interface IntegrationResolvedRoute {
  pattern: RouteData['route'];
  patternRegex: RouteData['pattern'];
  entrypoint: RouteData['component'];
  isPrerendered: RouteData['prerender'];
  redirectRoute?: IntegrationResolvedRoute;
  generate: (data?: any) => string;
  params: string[];
  pathname?: string;
  segments: RoutePart[][];
  type: RouteType;
  redirect?: RedirectConfig;
  origin: 'internal' | 'external' | 'project';
}

`pattern`

Тип: string

Позволяет определить тип маршрута на основе его пути. Вот несколько примеров путей, связанных с их шаблоном:

src/pages/index.astro будет /
src/pages/blog/[...slug].astro будет /blog/[...slug]
src/pages/site/[blog]/[...slug].astro будет /site/[blog]/[...slug]

`patternRegex`

Тип: RegExp

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

Например, для пути [fruit]/about.astro регулярное выражение будет /^\/([^/]+?)\/about\/?$/. Использование pattern.test("banana/about") вернёт true.

`entrypoint`

Тип: string

Путь URL исходного компонента.

`isPrerendered`

Тип: boolean

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

output: 'static', когда маршрут не экспортирует const prerender = true
output: 'server', когда маршрут экспортирует const prerender = false

`redirectRoute`

Тип: IntegrationResolvedRoute | undefined

Когда значение IntegrationResolvedRoute.type равно redirect, значение будет IntegrationResolvedRoute, на который нужно перенаправить. В противном случае значение будет неопределённым.

`generate()`

Тип: (data?: any) => string

Функция, которая предоставляет необязательные параметры маршрута, интерполирует их с шаблоном маршрута и возвращает имя пути маршрута.

Например, для маршрута, такого как /blog/[...id].astro, функция generate может вернуть:

console.log(generate({ id: 'presentation' })) // выведет `/blog/presentation`

`params`

Тип: string[]

Позволяет получить доступ к params маршрута. Например, когда проект использует следующие динамические маршруты (EN) /pages/[lang]/[...slug].astro, значение будет ['lang', '...slug'].

`pathname`

Тип: string | undefined

Для обычных маршрутов значение будет представлять собой путь URL, по которому будет обслуживаться этот маршрут. Когда проект использует динамические маршруты (EN) (т. е. [dynamic] или [...spread]), путь будет неопределённым.

`segments`

Тип: RoutePart[][]

Позволяет получить доступ к params маршрута с дополнительной метаинформацией. Каждый объект содержит следующие свойства:

content: имя param,
dynamic: является ли маршрут динамическим или нет,
spread: использует ли динамический маршрут синтаксис распространения или нет.

Например, следующий маршрут /pages/[blog]/[...slug].astro выведет сегменты:

[
  [ { content: 'pages', dynamic: false, spread: false } ],
  [ { content: 'blog', dynamic: true, spread: false } ],
  [ { content: '...slug', dynamic: true, spread: true } ]
]

`type`

Тип: RouteType

Позволяет определить тип маршрута. Возможные значения:

page: маршрут, который находится в файловой системе, обычно это компонент Astro
endpoint: маршрут, который находится в файловой системе, обычно это JS-файл, который предоставляет методы эндпойнтов
redirect: маршрут, который указывает на другой маршрут, находящийся в файловой системе
fallback: маршрут, который не существует в файловой системе и который необходимо обрабатывать другими средствами, обычно с помощью мидлваров

`redirect`

Тип: RedirectConfig | undefined

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

`origin`

Тип: 'internal' | 'external' | 'project'

Определяет, поступает ли маршрут из ядра Astro (internal), интеграции (external) или проекта пользователя (project).

Справка о типе `IntegrationRouteData`

:::cautionЭтот тип устарел с версии v5.0. Используйте вместо него IntegrationResolvedRoute.:::

Упрощенная версия RouteData, которая используется в интеграциях.

interface IntegrationRouteData {
  type: RouteType;
  component: string;
  pathname?: string;
  pattern: RegExp;
  params: string[];
  segments: { content: string; dynamic: boolean; spread: boolean; }[][];
  generate: (data?: any) => string;
  prerender: boolean;
  distURL?: URL[];
  redirect?: RedirectConfig;
  redirectRoute?: IntegrationRouteData;
}

`type`

Тип: RouteType

Позволяет определить тип маршрута. Значение может быть:

page: маршрут, который находится в файловой системе, обычно это компонент Astro
endpoint: маршрут, который находится в файловой системе, обычно это JS-файл, который предоставляет методы эндпойнтов
redirect: маршрут, который указывает на другой маршрут, находящийся в файловой системе
fallback: маршрут, который не существует в файловой системе и который необходимо обрабатывать другими средствами, обычно с помощью мидлваров

`component`

Тип: string

Позволяет получить доступ к пути URL исходного компонента.

`pathname`

Тип: string | undefined

`pattern`

Тип: RegExp

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

Например, для пути [fruit]/about.astro регулярное выражение будет /^\/([^/]+?)\/about\/?$/. Использование pattern.test("banana/about") вернет true.

`params`

Тип: string[]

`segments`

Тип: { content: string; dynamic: boolean; spread: boolean; }[][]

content: param,
dynamic: является ли маршрут динамическим или нет,
spread: использует ли динамический маршрут синтаксис распространения или нет.

Например, следующий маршрут /pages/[lang]/index.astro выведет сегменты [[ { content: 'lang', dynamic: true, spread: false } ]].

`generate()`

Тип: (data?: any) => string

Например, для маршрута, такого как /blog/[...id].astro, функция generate может вернуть:

console.log(generate({ id: 'presentation' })) // выведет `/blog/presentation`

`prerender`

Тип: boolean

Определяет, является ли маршрут предварительно отрендеренным или нет.

`distURL`

Тип: URL[] | undefined

Пути физических файлов, создаваемых этим маршрутом. Когда маршрут не является предварительно отрендеренным, значение будет либо undefined, либо пустым массивом.

`redirect`

Тип: RedirectConfig | undefined

`redirectRoute`

Тип: IntegrationRouteData | undefined

Когда значение RouteData.type равно redirect, значение будет содержать IntegrationRouteData маршрута, на который нужно перенаправить. В противном случае значение будет неопределенным.

Разрешаем установку с помощью `astro add`

Команда astro add (EN) позволяет пользователям легко добавлять интеграции и адаптеры в свой проект. Если вы хотите, чтобы ваша интеграция могла быть установлена с помощью этого инструмента, добавьте astro-integration в поле keywords в вашем package.json:

{
  "name": "example",
  "keywords": ["astro-integration"],
}

После того как вы опубликуете свою интеграцию в npm, выполнение команды astro add example установит ваш пакет с любыми зависимостями, указанными в вашем package.json. Это также применит вашу интеграцию к astro.config.* пользователя следующим образом:

// astro.config.mjs
import { defineConfig } from 'astro/config';
import example from 'example';

export default defineConfig({
  integrations: [example()],
})

:::cautionЭто предполагает, что определение вашей интеграции 1) является default экспортом и 2) является функцией. Убедитесь, что это так, прежде чем добавлять ключевое слово astro-integration!:::

Порядок интеграций

Все интеграции выполняются в порядке, в котором они настроены. Например, для массива [react(), svelte()] в astro.config.* пользователя, react будет выполняться перед svelte.

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

Объединение интеграций в пресеты

Интеграция также может быть написана как коллекция нескольких, более мелких интеграций. Мы называем эти коллекции пресетами. Вместо создания фабричной функции, которая возвращает один объект интеграции, пресет возвращает массив объектов интеграции. Это полезно для создания сложных функций из нескольких интеграций.

integrations: [
  // Пример, где examplePreset() возвращает: [integrationOne, integrationTwo, ...etc]
  examplePreset()
]

Ресурсы сообщества

Создание ваших собственных интеграций Astro - Эммануэль Оханс на FreeCodeCamp
Шаблон интеграции Astro - Флориан Лефебр на GitHub

Внести свой вклад Сообщество Поддержать

API интеграции Astro

Примеры

Краткий справочник по API

Хуки

astro:config:setup

Опция config

Опция command

Опция isRestart

Опция updateConfig

Опция addRenderer

Опция addWatchFile

Опция addClientDirective

Опция addDevToolbarApp

Опция addMiddleware

Опция injectRoute

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

Опция injectScript

createCodegenDir

astro:route:setup

Опция route

route.component

route.prerender

astro:routes:resolved

Опция routes

astro:config:done

Опция config

Опция setAdapter()

Опция injectTypes()

Опция buildOutput

astro:server:setup

Опция server

Опция toolbar

on()

onAppInitialized()

onAppToggled()

send()

refreshContent() option

astro:server:start

Опция address

astro:server:done

astro:build:start

astro:build:setup

Опция vite

Опция pages

Опция target

Опция updateConfig()

astro:build:ssr

Опция manifest

Опция entryPoints

Опция middlewareEntryPoint

astro:build:generated

Опция dir

astro:build:done

Опция dir

Опция routes

Опция assets

Опция pages

Пользовательские хуки

Справочник по типам интеграций

AstroIntegrationLogger

HookParameters

Справка о типе IntegrationResolvedRoute

pattern

patternRegex

entrypoint

isPrerendered

redirectRoute

generate()

params

pathname

segments

type

redirect

origin

Справка о типе IntegrationRouteData

type

component

pathname

pattern

params

`astro:config:setup`

Опция `config`

Опция `command`

Опция `isRestart`

Опция `updateConfig`

Опция `addRenderer`

Опция `addWatchFile`

Опция `addClientDirective`

Опция `addDevToolbarApp`

Опция `addMiddleware`

Опция `injectRoute`

Опция `injectScript`

`createCodegenDir`

`astro:route:setup`

Опция `route`

`route.component`

`route.prerender`

`astro:routes:resolved`

Опция `routes`

`astro:config:done`

Опция `config`

Опция `setAdapter()`

Опция `injectTypes()`

Опция `buildOutput`

`astro:server:setup`

Опция `server`

Опция `toolbar`

`on()`

`onAppInitialized()`

`onAppToggled()`

`send()`

`refreshContent()` option

`astro:server:start`

Опция `address`

`astro:server:done`

`astro:build:start`

`astro:build:setup`

Опция `vite`

Опция `pages`

Опция `target`

Опция `updateConfig()`

`astro:build:ssr`

Опция `manifest`

Опция `entryPoints`

Опция `middlewareEntryPoint`

`astro:build:generated`

Опция `dir`

`astro:build:done`

Опция `dir`

Опция `routes`

Опция `assets`

Опция `pages`

`AstroIntegrationLogger`

`HookParameters`

Справка о типе `IntegrationResolvedRoute`

`pattern`

`patternRegex`

`entrypoint`

`isPrerendered`

`redirectRoute`

`generate()`

`params`

`pathname`

`segments`

`type`

`redirect`

`origin`

Справка о типе `IntegrationRouteData`

`type`

`component`

`pathname`

`pattern`

`params`

`segments`

`generate()`

`prerender`

`distURL`

`redirect`

`redirectRoute`

Разрешаем установку с помощью `astro add`