definePlugin

Call Signature

definePlugin<TEnv, TName, TProvides, TRequires, TClient>(config): CfastPlugin<TName, Awaited<TProvides>, RequiresFromPlugins<TRequires>, TClient, TEnv>

Defined in: packages/core/src/define-plugin.ts:90

Defines a cfast plugin for use with createApp().use().

Two equivalent forms are supported:

1. Inferred form (preferred) — pass plugin references in requires and the setup(ctx) parameter is automatically typed with their provides:

   const dbPlugin = definePlugin({
     name: "db",
     requires: [authPlugin],
     setup(ctx) {
       ctx.auth.user; // typed from authPlugin
       return { client: createDb({}) };
     },
   });

   No need to import or declare a TRequires type token — the dependency type flows directly from the registered plugin objects. Leaf plugins simply omit requires and get ctx: { request, env }.

2. Curried form (legacy) — kept for backward compatibility with code that only has access to a PluginProvides<typeof authPlugin> type (e.g. when you cannot import the actual plugin value):

   definePlugin<AuthPluginProvides>()({
     name: "db",
     setup(ctx) { ctx.auth.user; return { ... }; },
   });

Plugins declared via the inferred form also benefit from runtime validation: app.use(plugin) throws a CfastConfigError if any plugin listed in requires has not yet been registered, with a message that names the missing dependency.

Type Parameters

TEnv

TEnv = Record<string, unknown>

TName

TName extends string = string

TProvides

TProvides = unknown

TRequires

TRequires extends readonly CfastPlugin<string, unknown, any, unknown, any>[] = []

TClient

TClient = unknown

Parameters

config

Plugin configuration with name, setup, and optional requires, Provider, client.

client?

TClient

name

TName

Provider?

ComponentType<{ children: ReactNode; }>

requires?

TRequires

setup

(ctx) => TProvides | Promise<TProvides>

Returns

CfastPlugin<TName, Awaited<TProvides>, RequiresFromPlugins<TRequires>, TClient, TEnv>

A CfastPlugin instance ready to pass to app.use().

Example

// Leaf plugin (no dependencies)
const analyticsPlugin = definePlugin({
  name: 'analytics',
  setup(ctx) {
    return { track: (event: string) => {} };
  },
});

// Dependent plugin — requires inferred from plugin references
const dbPlugin = definePlugin({
  name: 'db',
  requires: [authPlugin],
  setup(ctx) {
    ctx.auth.user; // typed from authPlugin
    return { client: createDb({}) };
  },
});

// Env-typed plugin — pass the env type as the single explicit generic
// to type ctx.env precisely (no casts needed):
const storagePlugin = definePlugin<Cloudflare.Env>({
  name: 'storage',
  setup(ctx) {
    ctx.env.BUCKET; // typed as R2Bucket, not unknown
    return { upload: (file: File) => ctx.env.BUCKET.put(file.name, file) };
  },
});

Call Signature

definePlugin<TRequires, TEnv>(): <TName, TProvides, TClient>(config) => CfastPlugin<TName, Awaited<TProvides>, TRequires, TClient, TEnv>

Defined in: packages/core/src/define-plugin.ts:115

Defines a cfast plugin for use with createApp().use().

Two equivalent forms are supported:

1. Inferred form (preferred) — pass plugin references in requires and the setup(ctx) parameter is automatically typed with their provides:

   const dbPlugin = definePlugin({
     name: "db",
     requires: [authPlugin],
     setup(ctx) {
       ctx.auth.user; // typed from authPlugin
       return { client: createDb({}) };
     },
   });

   No need to import or declare a TRequires type token — the dependency type flows directly from the registered plugin objects. Leaf plugins simply omit requires and get ctx: { request, env }.

2. Curried form (legacy) — kept for backward compatibility with code that only has access to a PluginProvides<typeof authPlugin> type (e.g. when you cannot import the actual plugin value):

   definePlugin<AuthPluginProvides>()({
     name: "db",
     setup(ctx) { ctx.auth.user; return { ... }; },
   });

Plugins declared via the inferred form also benefit from runtime validation: app.use(plugin) throws a CfastConfigError if any plugin listed in requires has not yet been registered, with a message that names the missing dependency.

Type Parameters

TRequires

TRequires

TEnv

TEnv = Record<string, unknown>

Returns

A CfastPlugin instance ready to pass to app.use().

<TName, TProvides, TClient>(config): CfastPlugin<TName, Awaited<TProvides>, TRequires, TClient, TEnv>

Type Parameters

TName

TName extends string

TProvides

TProvides

TClient

TClient = unknown

Parameters

config

client?

TClient

name

TName

Provider?

ComponentType<{ children: ReactNode; }>

setup

(ctx) => TProvides | Promise<TProvides>

Returns

CfastPlugin<TName, Awaited<TProvides>, TRequires, TClient, TEnv>

Example

// Leaf plugin (no dependencies)
const analyticsPlugin = definePlugin({
  name: 'analytics',
  setup(ctx) {
    return { track: (event: string) => {} };
  },
});

// Dependent plugin — requires inferred from plugin references
const dbPlugin = definePlugin({
  name: 'db',
  requires: [authPlugin],
  setup(ctx) {
    ctx.auth.user; // typed from authPlugin
    return { client: createDb({}) };
  },
});

// Env-typed plugin — pass the env type as the single explicit generic
// to type ctx.env precisely (no casts needed):
const storagePlugin = definePlugin<Cloudflare.Env>({
  name: 'storage',
  setup(ctx) {
    ctx.env.BUCKET; // typed as R2Bucket, not unknown
    return { upload: (file: File) => ctx.env.BUCKET.put(file.name, file) };
  },
});