# Plugin

`class` in `core/plugin` · v0.12.0

<https://seedcord.org/docs/packages/core/0.12.0/classes/plugin>

Base class for a seedcord plugin. Extend it and implement `init()`. `this.core` is the running
bot.

Take the host as your constructor's first parameter and pass it to `super()`. Add your own parameters after
it. `attach()` types them at the call site.

A plugin that narrows `transport` or `runtime` in `Opts` passes the same values to `super()`.
`attach()` throws when either one differs from the bot's.

```ts
abstract class Plugin<
    Opts extends PluginOptions = {},
    TCore extends CoreBase = CoreBase,
    Fixed extends ScopeAxis = never
>
    implements Initializeable, HmrAware
```

## Examples

```ts
class Analytics extends Plugin<{ transport: 'gateway' }> {
    constructor(
        host: CoreBase,
        private readonly apiKey: string
    ) {
        super(host, { transport: 'gateway', init: { phase: StartupPhase.Login } });
    }

    public async init(): Promise<void> {
        await this.connect(this.apiKey);
    }
}

seedcord.attach('analytics', Analytics, apiKey);
```

## Constructors

### constructor

```ts
Plugin(
    host: CoreBase,
    [spec],
    input: PluginSpecArgs<Opts, Fixed>
)
```

Constructs a new instance of the `Plugin` class

## Properties

### core

```ts
protected core: TCore
```

The host, typed to the transport whose `Plugin` base this class extends.

### kv

```ts
protected kv: Kv
```

This plugin's records in the bot's `config.kv`, stored under its attach key. Two attachments of
one plugin class each get their own records. Renaming the attach key leaves the records under
the old key behind.

### logger

```ts
protected readonly logger: Logger
```

Logs under the plugin's class name, on the channel its attach key sets.

## Methods

### codegen

```ts
public async codegen?(): Promise<unknown>
```

Returns data that `seedcord codegen` writes into the bot's `seedcord-gen.ts` as a type.
Read it back with `Generated<typeof YourPlugin>`. Return plain data, or classes and objects
that a project file or your plugin's package exports. The class needs a `static readonly id`.

`seedcord codegen` calls this without running `init()`. Read only what the constructor stored
and the bot's files.

### dispose

```ts
public dispose?(): Promisable<void>
```

Runs during teardown, in `ShutdownPhase.Disconnect` by default. seedcord skips it when `init()`
has thrown.

When `init()` outlasts its timeout, seedcord calls this once that `init()` resolves, outside any
shutdown phase. The process must still be alive for that call to happen.

### init

```ts
public abstract init(): Promisable<void>
```

Runs in `StartupPhase.Configuration` by default.
Move it to a different phase with the [`PluginLifecycleSpec`](/docs/packages/core/0.12.0/interfaces/plugin-lifecycle-spec).

### onHmr

```ts
public onHmr(_event: HmrUpdateEvent): Promisable<void>
```

Override to reload plugin state on an HMR update.

### ready

```ts
public ready?(): Promisable<void>
```

Runs in the Ready phase, after every attached plugin's `init()` has resolved. The other Ready
tasks run alongside it, including the http server binding its port.

Override it when your work needs a logged-in client or a resolved application id.

### registerCriticalFiles

```ts
protected registerCriticalFiles(
    patterns: string[]
): void
```

Registers critical file patterns that should trigger a full restart when changed in Dev HMR.

### rejectOptions

```ts
protected rejectOptions(reason: string): never
```

Rejects the options this plugin got.