Component extensions: add features to a component without touching it
Extensions add namespaced fields, functions, workflows, templates and config to an existing component, can be switched off without losing data, and are how marketplace apps add features to components you already have.
A component holds your data model and the logic that belongs to it. Sometimes you want to add to a component you didn't write, or one that is shared: a tracking number on every order, an SEO block on every product, a status lookup against a carrier. Editing the core settings for each of those makes the component harder to reason about, and it makes the additions hard to remove.
An extension is the answer. It is a self-contained package that attaches to a component and adds capabilities without modifying the component's core settings. This post covers what an extension contributes, how its names stay separate from the component's own, how to switch it on and off, how to type it, and how marketplace apps use extensions. For the component itself, see our post on components.
You build and manage extensions in the dashboard under Developer › Extension Builder, and through the API and SDK.
What an extension contributes
An extension can add any of these:
| Part | What it is |
|---|---|
| Fields | Extra data fields stored alongside the component's native fields |
| Functions | Custom functions scoped to the extension |
| Workflows | Workflow nodes that react to the component's create, update and delete events |
| Templates | UI templates for rendering extension-specific views |
| Config | Extension-specific key-value configuration |
Extensions are versioned and can be activated or deactivated independently. While an extension is active, its fields, functions and workflows take part in all component operations automatically.
Here is a shipping_tracker extension that adds two fields, a function and some config to an orders component:
{
"name": "shipping_tracker",
"is_active": true,
"version": "1.0.0",
"fields": [
{
"key": "tracking_number",
"name": "Tracking Number",
"type": "string",
"module": "input",
"visible": true,
"constraints": { "required": true }
},
{
"key": "carrier",
"name": "Carrier",
"type": "string",
"module": "select",
"visible": true,
"constraints": { "selectables": { "items": ["DHL", "FedEx", "UPS", "USPS"] } }
}
],
"functions": [
{
"name": "get_tracking_status",
"expr": "return await Http.get(`https://api.carrier.com/track/${input.tracking_number}`)"
}
],
"workflows": [],
"config": { "default_carrier": "DHL" }
}
Keep API keys and URLs in the extension's config rather than hard-coding them in functions.
Namespacing
Everything an extension adds lives under its own name, so it can't collide with the component or with other extensions.
Fields are stored at extensions.{extension_name}.{field_key}. Use that full path to update, filter, sort and project:
const component = new Component("orders")
await component.create({
order_id: "ORD-001",
extensions: {
shipping_tracker: { tracking_number: "1234567890", carrier: "DHL" }
}
})
await component.update(uuid, { "extensions.shipping_tracker.carrier": "FedEx" })
const results = await component.find({
$adv: { "extensions.shipping_tracker.carrier": "DHL" }
})
Extension fields are ordinary fields under a prefix. They carry the same module and type as any other field and follow the same rules. For example, you can sort on one that stores a scalar, but not on one that stores an array or object. Because of the prefix, extensions is a reserved field key on a component, and field keys can't contain a dot.
Functions use dot notation: shipping_tracker.get_tracking_status.
Calling extension functions
Extension functions have the same structure and execution context as component functions. Call them as extensionName.functionName, over the API or from the SDK:
POST /v4/system/component/orders/function/shipping_tracker.get_status
import { Component } from "@ptkl/sdk"
const orders = new Component("orders")
await orders.function("shipping_tracker.get_status", {
tracking_number: "1234567890"
})
If you don't care which extension provides a function, prefix the name with $.. The platform then looks at the component's own functions first, then at active extensions in install order. If several extensions define the same name, the last one installed wins:
await orders.function("$.calculate", { amount: 100 })
Extension functions exist only while the extension is active. When it is deactivated, calling one returns a not-found error. Who may run them is a permission: functions for all of a component's functions, or function::{name} for one.
Workflows
When a record event happens, the platform runs the component's own workflows and then each active extension's workflows, in order. Extension workflows get the same event context as the component's, plus the extension's name and config:
{
"context": {
"event": "Before::Create",
"component": "orders",
"extension": { "name": "shipping_tracker", "config": { } },
"schema": "default"
}
}
A component's code, including its extension functions and extension workflows, runs as the component's run identity.
Activation and deactivation
Set is_active to false to switch an extension off:
- its fields stay in the data but are no longer validated or enforced;
- its functions become unavailable;
- its workflows stop running on record events;
- the data it stored is preserved.
Deleting an extension removes its definition from the component. The data in its fields is preserved, but nothing manages it any more. Write your workflows so they cope with the extension being off.
The SDK mirrors the API: getExtension, installExtension, updateExtension and deleteExtension. Each takes the component version, such as "0.1.0":
await component.updateExtension("shipping_tracker", "0.1.0", {
is_active: false
})
Typed extensions with IDL
An extension can declare its own IDL next to its fields and functions. The structure mirrors the component's IDL: global functions and a schemas map with per-schema types and fields.
{
"name": "premium",
"is_active": true,
"idl": {
"version": "1.0",
"functions": [
{
"name": "flag_item",
"input": { "sku": { "type": "string", "required": true } },
"output": { "type": "boolean" }
}
],
"schemas": {
"default": {
"types": {},
"fields": {
"flagged_items": { "type": "array", "items": { "type": "OrderItem" } }
}
}
}
}
}
Type names in an extension IDL resolve like this:
| Reference | Resolves to |
|---|---|
"OrderItem" |
The extension's own types first, then the component's |
"$.OrderItem" |
The component's types only |
"otherExtension.OrderItem" |
Rejected: no references between extensions |
The one-way rule
Extensions can reference the component's types. The component's IDL cannot reference extension types, because the component is written without knowing which extensions will be installed.
Install-time guards
When you install an extension, the platform checks its IDL against the component's for every schema it declares. Installation is blocked if an extension type name, field key or function name already exists in the component. So each name belongs to exactly one source.
To validate a value against an extension's IDL from the command line, use ptkl validate-idl.
How marketplace apps use extensions
An app (see our post on Forge) that adds a feature to a component the customer already has can do it with an extension. The app's install script adds the extension to the target component, and its uninstall script removes it. The install script first checks whether the extension exists, so running it twice is safe:
const { settings } = await platform.component("products").settings();
const existing = settings.extensions?.find(ext => ext.name === "my_app_tracking");
if (!existing) {
await platform.component("products").installExtension({
name: "my_app_tracking",
is_active: true,
fields: [ /* ... */ ]
}, settings.version);
}
Because the extension is namespaced, the app's fields and functions can't overwrite the customer's own. Because it can be deactivated, the customer's data survives. Uninstall scripts should remove or deactivate what install created, and deactivate rather than delete user data where possible.
When to use an extension
- A feature you want to add to a component you don't own.
- Optional behaviour that should be switchable without losing data.
- A package of fields, functions and workflows that you ship together and version.
If the change belongs to the component's core model, edit the component instead.
Worked example
Your orders component needs shipment tracking.
- Install
shipping_trackerwith atracking_numberfield, acarrierfield and aget_tracking_statusfunction. - Create orders with
extensions.shipping_tracker.tracking_numberset. - Call
orders.function("shipping_tracker.get_tracking_status", { tracking_number })to look up status. - Filter orders with
$adv: { "extensions.shipping_tracker.carrier": "DHL" }. - Switch it off with
is_active: false. The tracking numbers stay in the records.
Learn more
- Extensions: https://docs.protokol.io/components/extensions/
- Extension IDL: https://docs.protokol.io/components/idl/
- Extension functions: https://docs.protokol.io/components/functions/
- Lifecycle scripts for apps: https://docs.protokol.io/forge/scripts/