Backend target

Entry: src/backend/index.ts → dist/backend/index.js.

Backend расширения выполняются внутри Keystone/Feathers host при bootstrap и поддерживают миграции Kysely и Feathers CRUD-сервисы в schema ext.*.

defineExtension (backend)

import type { ExtensionMigrationDb } from '@artiroute/extension-sdk/backend';
import { defineExtension } from '@artiroute/extension-sdk/extension';

export default defineExtension((ctx) => {
  ctx.registerMigration('001_init', {
    async up(db: ExtensionMigrationDb) {
      await db.schema
        .createTable('ext.project_notes')
        .ifNotExists()
        .addColumn('id', 'text', (col) => col.primaryKey())
        .addColumn('project_id', 'text', (col) =>
          col.notNull().references('Project.id').onDelete('cascade')
        )
        .addColumn('text', 'text', (col) => col.notNull())
        .execute();
    },
    async down(db) {
      await db.schema.dropTable('ext.project_notes').ifExists().execute();
    },
  });

  ctx.registerService('notes', {
    table: 'ext.project_notes',
    projectScoped: true,
  });
});

Schema ext.*

Все таблицы расширений — в PostgreSQL schema ext, префикс в имени таблицы: ext.<name>.

Можно: создавать таблицы, индексы, FK на core tables (Project.id, User.id).

Нельзя: изменять core Keystone lists без ADR и миграций хоста.

registerMigration

• Локальное имя миграции ('001_init') уникально в пределах extension id
• Выполняется при bootstrap / hotplug install
• down опционален — для uninstall/rollback

Миграции extension отдельны от core backend:migrate:*.

registerService

Автоматический Feathers REST/GraphQL bridge для таблицы:

Option	Описание
table	Полное имя ext.table_name
projectScoped	Фильтрация по project_id из контекста

Routes монтируются под prefix extension. Frontend extension обращается через свой API layer (см. project-notes/src/frontend/api/).

Discovery и data dir

Runtime path: apps/backend/data/extensions/<slug>/

После pnpm install:extensions backend читает manifest.json, импортирует backend/index.js, выполняет setup.

Hotplug

Backend host поддерживает reload/unload расширений без полного рестарта (API + events). После install нового zip может потребоваться hotplug или restart — зависит от окружения.

hostApis

В setup доступны host APIs (Keystone context, logging):

ctx.hostApis?.log?.('Extension loaded');

Типы: ExtensionBackendHostApis в backend module.

Manifest

targets: {
  backend: {},
}

Backend entry обязателен, если используются migrations/services.

Пример

Полный walkthrough: project-notes.

Artifact import / export

Регистрация handlers для импорта/экспорта артефактов: artifact-io.