Plugin Registration

How the plugins array works

Each entry in the plugins array is a plain object with two properties: a namespace string that uniquely identifies the plugin, and a config payload with its options. You never create this object manually. Plugin packages export typed factory helpers such as defineHttp, defineI18n, defineSchedule, and defineSignal that produce correctly shaped entries with full TypeScript inference. The framework resolves each plugin's config at runtime by matching the namespace, so changing one plugin never affects another.

import { defineConfig } from '@spraxium/core';
import { defineHttp } from '@spraxium/http';
import { defineI18n } from '@spraxium/i18n';
import { defineSchedule } from '@spraxium/schedule';

export default defineConfig({
  plugins: [
    defineI18n({
      defaultLocale: 'en-US',
      references: [{ name: 'commands', path: './locales' }],
    }),
    defineHttp({
      enabled: true,
      port: 3001,
      host: 'localhost',
      apiKey: process.env.HTTP_API_KEY ?? 'dev-secret',
      sharding: false,
    }),
    defineSchedule({
      timezone: 'America/Sao_Paulo',
      defaultLockTtlMs: 60_000,
      disableAll: false,
    }),
  ],
});

First-party plugin factories

Extracting plugin config into separate files

For projects with several plugins, keeping all factory calls inline in spraxium.config.ts makes the file hard to review. The recommended pattern is to extract each plugin's factory call into a dedicated file under config/, export the result as a named constant, and import it in the root config. This keeps each plugin's options isolated and independently auditable.

import { defineSchedule } from '@spraxium/schedule';

export const schedulePlugin = defineSchedule({
  timezone: 'America/Sao_Paulo',
  defaultLockTtlMs: 60_000,
  disableAll: false,
});