BuildPlugin

A module owns processing, optional input detection and source-directory declarations.

Import

import type { BuildPlugin } from '@bedrock-core/builder-plugin';

Properties

Property	Type	Description
requirements	PluginRequirements	Optional owner module types and named direct pack dependencies
run	BuildStep	Required operation receiving context and settings
detect	(context, settings) => BuildDetection | Promise<BuildDetection>	Optional input probe used in automatic mode
inputDirectories	(context, settings) => readonly string[] | Promise<readonly string[]>	Optional non-template source directories reserved before generation

BuildStep returns void, { cached?, reason? } or a promise of either. Throwing or rejecting prevents export. BuildDetection contains needed: boolean and reason: string; detection must inspect inputs without evaluating resource modules.

Usage

import type { BuildPlugin } from '@bedrock-core/builder-plugin';

export const requirements = { modules: ['script'] };

export const detect: BuildPlugin['detect'] = (context) => ({
  needed: Object.keys(context.packs).length > 0,
  reason: 'configured packs',
});

export const run: BuildPlugin['run'] = async (context) => {
  context.signal?.throwIfAborted();
  context.registerDependency('config.json');
};

Pack requirements

requirements.modules is a nonempty array of manifest module types. Each pack matching any type receives one invocation. requirements.dependencies maps role names to { modules, optional?, multiple? }; the host resolves each role through direct local manifest dependencies. A role requires exactly one match unless its flags say otherwise.

The SDK exports PluginRequirements, PackRequirement, PackLinkOverrides and LinkedPacks for typed plugins. Pack matching and dependency resolution are managed by Builder. Plugins covers pack restrictions, link overrides and project scope. Omitting requirements declares a project-wide tool.

Notes

Export these functions as named module exports. Plugin definitions identify the module and profile boundary. External steps run unconditionally unless they select mode: "auto"; a module without a detector runs in either mode.

Built-in packages expose this contract through their ./plugin entry points. The host supplies BuildContext services and manages ordering, staging, validation and publication.