Skip to main content
⚠️ AppKit is in an early development phase and is subject to change without notice. DO NOT use in production environments.

# Abstract Class: Plugin<TConfig>

Base abstract class for creating AppKit plugins.

All plugins must declare a static `manifest` property with their metadata and resource requirements. The manifest defines:

- `required` resources: Always needed for the plugin to function
- `optional` resources: May be needed depending on plugin configuration

## Static vs Runtime Resource Requirements​

The manifest is static and doesn't know the plugin's runtime configuration. For resources that become required based on config options, plugins can implement a static `getResourceRequirements(config)` method.

At runtime, this method is called with the actual config to determine which "optional" resources should be treated as "required".

## Examples​

    import { Plugin, toPlugin, PluginManifest, ResourceType } from '@databricks/appkit';

    const myManifest: PluginManifest = {
      name: 'myPlugin',
      displayName: 'My Plugin',
      description: 'Does something awesome',
      resources: {
        required: [
          { type: ResourceType.SQL_WAREHOUSE, alias: 'warehouse', ... }
        ],
        optional: []
      }
    };

    class MyPlugin extends Plugin<MyConfig> {
      static manifest = myManifest;
      name = 'myPlugin';
    }

    interface MyConfig extends BasePluginConfig {
      enableCaching?: boolean;
    }

    const myManifest: PluginManifest = {
      name: 'myPlugin',
      resources: {
        required: [
          { type: ResourceType.SQL_WAREHOUSE, alias: 'warehouse', ... }
        ],
        optional: [
          // Database is optional in the static manifest
          { type: ResourceType.DATABASE, alias: 'cache', description: 'Required if caching enabled', ... }
        ]
      }
    };

    class MyPlugin extends Plugin<MyConfig> {
      static manifest = myManifest;
      name = 'myPlugin';

      // Runtime method: converts optional resources to required based on config
      static getResourceRequirements(config: MyConfig) {
        const resources = [];
        if (config.enableCaching) {
          // When caching is enabled, Database becomes required
          resources.push({
            type: ResourceType.DATABASE,
            alias: 'cache',
            resourceKey: 'database',
            description: 'Cache storage for query results',
            permission: 'CAN_CONNECT_AND_CREATE',
            fields: {
              instance_name: { env: 'DATABRICKS_CACHE_INSTANCE' },
              database_name: { env: 'DATABRICKS_CACHE_DB' },
            },
            required: true  // Mark as required at runtime
          });
        }
        return resources;
      }
    }

## Type Parameters​

Type Parameter | Default type
--- | ---
`TConfig` extends `BasePluginConfig` | `BasePluginConfig`

## Implements​

- `BasePlugin`

## Constructors​

### Constructor​

    new Plugin<TConfig>(config: TConfig): Plugin<TConfig>;

#### Parameters​

Parameter | Type
--- | ---
`config` | `TConfig`

#### Returns​

`Plugin`<`TConfig`>

## Properties​

### app​

    protected app: AppManager;

### cache​

    protected cache: CacheManager;

### config​

    protected config: TConfig;

### devFileReader​

    protected devFileReader: DevFileReader;

### isReady​

    protected isReady: boolean = false;

### name​

    name: string;

Plugin name identifier.

#### Implementation of​

    BasePlugin.name

### streamManager​

    protected streamManager: StreamManager;

### telemetry​

    protected telemetry: ITelemetry;

### phase​

    static phase: PluginPhase = "normal";

Plugin initialization phase.

- 'core': Initialized first (e.g., config plugins)
- 'normal': Initialized second (most plugins)
- 'deferred': Initialized last (e.g., server plugin)

## Methods​

### abortActiveOperations()​

    abortActiveOperations(): void;

#### Returns​

`void`

#### Implementation of​

    BasePlugin.abortActiveOperations

### asUser()​

    asUser(req: Request): this;

Execute operations using the user's identity from the request. Returns a proxy of this plugin where all method calls execute with the user's Databricks credentials instead of the service principal.

#### Parameters​

Parameter | Type | Description
--- | --- | ---
`req` | `Request` | The Express request containing the user token in headers

#### Returns​

`this`

A proxied plugin instance that executes as the user

#### Throws​

Error if user token is not available in request headers

### execute()​

    protected execute<T>(
       fn: (signal?: AbortSignal) => Promise<T>,
       options: PluginExecutionSettings,
    userKey?: string): Promise<T | undefined>;

#### Type Parameters​

Type Parameter
`T`

#### Parameters​

Parameter | Type
--- | ---
`fn` | (`signal?`: `AbortSignal`) => `Promise`<`T`>
`options` | `PluginExecutionSettings`
`userKey?` | `string`

#### Returns​

`Promise`<`T` | `undefined`>

### executeStream()​

    protected executeStream<T>(
       res: IAppResponse,
       fn: StreamExecuteHandler<T>,
       options: StreamExecutionSettings,
    userKey?: string): Promise<void>;

#### Type Parameters​

Type Parameter
`T`

#### Parameters​

Parameter | Type
--- | ---
`res` | `IAppResponse`
`fn` | `StreamExecuteHandler`<`T`>
`options` | `StreamExecutionSettings`
`userKey?` | `string`

#### Returns​

`Promise`<`void`>

### exports()​

    exports(): unknown;

Returns the public exports for this plugin. Override this to define a custom public API. By default, returns an empty object.

#### Returns​

`unknown`

#### Implementation of​

    BasePlugin.exports

### getEndpoints()​

    getEndpoints(): PluginEndpointMap;

#### Returns​

`PluginEndpointMap`

#### Implementation of​

    BasePlugin.getEndpoints

### injectRoutes()​

    injectRoutes(_: Router): void;

#### Parameters​

Parameter | Type
--- | ---
`_` | `Router`

#### Returns​

`void`

#### Implementation of​

    BasePlugin.injectRoutes

### registerEndpoint()​

    protected registerEndpoint(name: string, path: string): void;

#### Parameters​

Parameter | Type
--- | ---
`name` | `string`
`path` | `string`

#### Returns​

`void`

### route()​

    protected route<_TResponse>(router: Router, config: RouteConfig): void;

#### Type Parameters​

Type Parameter
`_TResponse`

#### Parameters​

Parameter | Type
--- | ---
`router` | `Router`
`config` | `RouteConfig`

#### Returns​

`void`

### setup()​

    setup(): Promise<void>;

#### Returns​

`Promise`<`void`>

#### Implementation of​

    BasePlugin.setup