Зависимости: можно и нельзя

Правила подключения npm-пакетов и интеграции с хостом artiroute.

Сводная таблица

Можно	Нельзя
npm-пакеты, попадающие в bundle extension (утилиты, парсеры, zod, date-fns)	vue, vue-router, vue-i18n в bundle
peerDependencies на host-библиотеки	primevue, @primevue/*, @primeuix/* в bundle
Таблицы ext.* через registerMigration	Свой Tailwind / PostCSS pipeline в extension
Новые artifact types через manifest + Template	Hardcode enum типов только в core Keystone
Запросить host shim через PR в register-host-modules.ts	Произвольный import UI-lib без shim
declareExpose / getExtensionExpose между extensions	Патч core schema без ADR
Subpath imports из HOST_SUBPATH_PREFIXES	Duplicate Vue/PrimeVue instances

Host-provided (external)

Эти модули всегда резолвятся через host, не бандлятся:

vue, vue-router, vue-i18n
primevue, @primevue/core, @primevue/forms, @primeuix/themes
axios, lodash-es
@artiroute/extension-sdk (+ /extension, /host)

• catch-all subpaths: primevue/*, @primevue/core/*, …

Список: Host-модули.

Bundled (в extension)

Любой пакет вне whitelist → Rollup включит в dist/frontend/index.js.

Хорошие кандидаты:

• zod — validation в extension logic
• date-fns, lodash-es (если не через host shim — lodash уже external)
• Domain-specific parsers, small utilities

Плохие кандидаты:

• UI frameworks (Element, Vuetify, …)
• Heavy editors (Monaco, Univer) — только через host shim + ADR
• Duplicate copies of already-host packages

peerDependencies vs devDependencies

{
  "peerDependencies": {
    "@artiroute/extension-sdk": "workspace:*",
    "vue": "^3.5.22",
    "primevue": "^4.4.1"
  },
  "devDependencies": {
    "@artiroute/extension-build": "workspace:*",
    "typescript": "^5.8.3",
    "vite": "^7.1.7"
  }
}

• peer — runtime от хоста, типы и import в source
• dev — только для сборки extension

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

Когда extension нужна библиотека, уже установленная в frontend host:

1. register-host-modules.ts

import * as MyLib from 'my-lib';

registerExtensionHostModules({
  // …existing
  'my-lib': MyLib,
});

2. Subpath support (если нужен my-lib/foo)

В packages/extension-build/src/host-subpath-shim-plugin.ts:

export const HOST_SUBPATH_PREFIXES = [
  // …existing
  { prefix: 'my-lib', namespaceKey: 'my-lib' },
];

3. Rebuild builder

pnpm extension-build:build

4. Extension peerDependency

"peerDependencies": {
  "my-lib": "^1.0.0"
}

Без shim import либо сломает сборку (если external), либо раздует bundle.

Backend dependencies

Backend target bundle отдельный (dist/backend/index.js). Зависимости backend extension:

• Должны быть совместимы с Node runtime хоста
• Не дублировать Keystone internals без необходимости
• DB access — только через ExtensionMigrationDb / Feathers services API

Нельзя: raw SQL к core tables в обход Keystone ACL без явного design review.

AI dependencies

AI target может использовать ai, zod — они бандлятся в dist/ai/index.js.

Согласуйте версии ai SDK с apps/ai-agent-service при добавлении новых major versions.

Лицензии и размер

По стандартам monorepo (zebrains architecture.core):

• Новые зависимости — осознанно: совместимость, размер, лицензии
• Крупные библиотеки в extension bundle — через ADR

Проверка bundle size

pnpm build:extensions
ls -la packages/extensions/my-ext/dist/frontend/index.js

После host shims типичный размер — 10–20 KB. Сотни KB — сигнал bundling host libs.