Host-модули (external packages)

Frontend target extension собирается как ES library. Зависимости хоста не попадают в bundle — вместо этого используются host shims: виртуальные модули, которые в runtime читают singleton из registerExtensionHostModules.

Whitelist (register-host-modules.ts)

Хост регистрирует модули в apps/frontend/src/shared/extensions/register-host-modules.ts:

Specifier	Назначение
vue	Vue 3 runtime
vue-router	Router
vue-i18n	i18n
primevue	PrimeVue barrel
@primevue/core	Core API
@primevue/core/api	PrimeVue API helpers
@primevue/forms	Forms
@primevue/forms/resolvers/zod	Zod resolver
@primeuix/themes	Themes
primeicons	Icons (stub)
axios	HTTP client
lodash-es	Utilities
@artiroute/extension-sdk	SDK barrel
@artiroute/extension-sdk/extension	Extension API
@artiroute/extension-sdk/host	Host API
@artiroute/host/api	REST/GraphQL/uploads с BASE_URL
@artiroute/host/auth	Auth providers
@artiroute/host/settings	Extension settings
@artiroute/host/ai-providers	AI provider registry

@artiroute/host/api

Используйте для любых browser-side вызовов backend (кроме auth routes — см. @artiroute/host/auth):

Метод	Назначение
withAppBase(path)	Путь приложения с учётом BASE_URL
getGraphqlUrl()	URL GraphQL endpoint
getExtensionApiUrl(extensionId, path)	REST prefix /api/ext/{id}/...
resolvePublicFileUrl(pathOrUrl)	URL файла/аватара с /uploads/ и base
fetchGraphql(query, variables?)	POST GraphQL с cookie и Bearer token

Subpath imports (catch-all)

Импорты вида primevue/tag, @primevue/core/api резолвятся через catch-all plugin @artiroute/extension-build:

// HOST_SUBPATH_PREFIXES
'primevue';
'@primevue/core';
'@primevue/forms';
'@artiroute/extension-sdk';

При сборке extension Vite генерирует shim, который в runtime вызывает resolveHostSubpathModule и достаёт export из namespace хоста.

Не нужно регистрировать каждый subpath вручную, если prefix уже в списке.

Что бандлится

Любой npm-пакет вне whitelist попадает в bundle extension:

import { format } from 'date-fns'; // OK — будет в bundle
import { z } from 'zod'; // OK — будет в bundle (если используется в extension code)

Следите за размером bundle. Утилиты — да; UI-фреймворки — нет.

Как добавить новый host shim

Если extension нужен пакет, который уже есть в frontend host (например @vue-flow/core):

1. Добавить import и запись в registerAnalystHelperExtensionHostModules() в register-host-modules.ts
2. Если нужны subpath imports — добавить prefix в HOST_SUBPATH_PREFIXES (packages/extension-build/src/host-subpath-shim-plugin.ts)
3. Пересобрать: pnpm extension-build:build
4. Добавить peerDependencies в extension

Это изменение хоста — через PR, не только в extension.

Симптомы неправильных imports

Симптом	Причина
Bundle > 100 KB для простого UI	Vue/PrimeVue попали в bundle
Failed to resolve import "primevue/..."	Prefix не в HOST_SUBPATH_PREFIXES
Компоненты без стилей	CSS PrimeVue не из хоста — см. Стили
Duplicate Vue instance	Vue забандлен вместо shim
Cannot POST /api/... на демо	Хардкод /api/ без @artiroute/host/api — см. Troubleshooting

extension-build internals

• ahExtensionHostSubpathShimPlugin — catch-all subpaths
• ahRollupMergeExternalPlugin — external для host specifiers
• hostShimAliases() — alias на packages/extension-build/shims/

Подробнее в packages/extension-build/README.md.