Custom components

You learned how the component controller manages the lifecycle of components in the previous section. Now you’ll learn how to create your own reusable components by combining existing components into custom components.

Custom components allow you to package a pipeline of built-in and other custom components into a single, reusable unit. This makes it easier to share common patterns across your configurations and across teams.

A custom component includes:

Arguments: Settings that configure the custom component’s behavior.
Exports: Values the custom component exposes to consumers.
Components: Built-in and custom components that run as part of the custom component.

Create custom components

Use the declare configuration block to create a custom component. The block’s label becomes the custom component’s name, which you can then use like any built-in component.

Inside a declare block, you can use these configuration blocks:

[argument][]: Defines a named input parameter that users must provide when using your custom component. Access the value with argument.NAME.value.
[export][]: Defines a named output value that your custom component exposes to other components.
Built-in and custom components: The actual pipeline logic that processes data.

The component controller treats custom components the same as built-in components:

Evaluation: Arguments are evaluated and passed to the internal pipeline.
Execution: The internal components run and process data.
Export updates: When internal components update their exports, the custom component can update its own exports.
Health reporting: The custom component’s health reflects the health of its internal components.

Custom components are particularly useful for packaging common pipeline patterns that you want to reuse across multiple configurations.

Example

This example creates a custom component called add that demonstrates the key concepts:

declare "add" {
    argument "a" {
        comment = "First number to add"
        optional = false
    }

    argument "b" {
        comment = "Second number to add"
        optional = false
    }

    export "sum" {
        value = argument.a.value + argument.b.value
    }
}

add "example" {
    a = 15
    b = 17
}

// Reference the export: add.example.sum == 32

This custom component:

Declares two required arguments: a and b with descriptive comments.
Exports one value: sum that computes the addition of the two arguments.
Can be instantiated: Create an instance labeled example by providing values for a and b.
Exposes computed results: Other components can reference add.example.sum to use the result.

For more complex examples that combine multiple built-in components, refer to the declare block reference.

Next steps

Now that you understand custom components, explore related topics and advanced usage:

Configuration blocks reference - Learn about declare, argument, and export blocks in detail
Configure components - Use custom components in your pipelines

For sharing and organizing: