> ## Content Index
> Fetch the complete content index at: https://blog.protokol.io/llms.txt
> Use this file to discover other available public pages before exploring further.

# Component extensions: add features to a component without touching it
- URL: https://blog.protokol.io/extensions/
- Published: 2026-11-17T17:33:05.000Z
- Updated: 2026-11-17T17:33:05.000Z
- Description: 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.
- Author: Strahinja Djuric
- Tags: Engineering

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](https://blog.protokol.io/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:

```json
{
  "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:

```js
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

```

```js
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:

```js
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:

```json
{
  "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"`:

```js
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`.

```json
{
  "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](https://blog.protokol.io/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:

```js
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.

1. Install `shipping_tracker` with a `tracking_number` field, a `carrier` field and a `get_tracking_status` function.
2. Create orders with `extensions.shipping_tracker.tracking_number` set.
3. Call `orders.function("shipping_tracker.get_tracking_status", { tracking_number })` to look up status.
4. Filter orders with `$adv: { "extensions.shipping_tracker.carrier": "DHL" }`.
5. Switch it off with `is_active: false`. The tracking numbers stay in the records.

## Learn more

- Extensions: [https://docs.protokol.io/components/extensions/](https://docs.protokol.io/components/extensions/?ref=blog.protokol.io)
- Extension IDL: [https://docs.protokol.io/components/idl/](https://docs.protokol.io/components/idl/?ref=blog.protokol.io)
- Extension functions: [https://docs.protokol.io/components/functions/](https://docs.protokol.io/components/functions/?ref=blog.protokol.io)
- Lifecycle scripts for apps: [https://docs.protokol.io/forge/scripts/](https://docs.protokol.io/forge/scripts/?ref=blog.protokol.io)