component

Define a custom component for the Prismatic platform, grouping actions, triggers, data sources, and connections under a single key.

The component function creates a component object that can be imported into the Prismatic API. A component bundles related actions, triggers, data sources, and connections under a unique key.

Function signature

function component<TPublic extends boolean, TKey extends string>(
  definition: ComponentDefinition<TPublic, TKey>
): ReturnType<typeof convertComponent>

Parameters

definition · ComponentDefinition<TPublic, TKey> · required

An object describing the component. See fields below.

ComponentDefinition fields

definition.key · string · required

A unique programmatic identifier for this component. Used in URLs and API references.

definition.public · boolean

Whether this component is available to all organizations (true) or only your own (false). Only Prismatic-managed public components may set this to true. Defaults to false.

definition.display · ComponentDisplayDefinition · required

Controls how the component appears in the Prismatic UI.

Show ComponentDisplayDefinition fields

display.label · string · required

Human-readable name shown in the UI.

display.description · string · required

Brief description of what the component does.

display.iconPath · string · required

Path to the component icon, relative to the built component source. Required for both public and private components.

display.category · string

Category grouping in the UI. For public components, must be one of "Application Connectors", "Data Platforms", "Helpers", "Logic", or "Triggers". Private components may use any string.

definition.actions · Record<string, ActionDefinition>

A map of action keys to their definitions. See action.

definition.triggers · Record<string, TriggerDefinition | PollingTriggerDefinition>

A map of trigger keys to their definitions. See trigger and pollingTrigger.

definition.dataSources · Record<string, DataSourceDefinition>

A map of data source keys to their definitions. See dataSource.

definition.connections · ConnectionDefinition[]

An array of connection definitions. See connection, oauth2Connection, and onPremConnection.

definition.hooks · ComponentHooks

Optional lifecycle hooks for the component.

Show ComponentHooks fields

hooks.error · (error: unknown) => unknown | Promise<unknown>

A global error handler that wraps all action and trigger perform functions. When defined, any unhandled error thrown by a perform function is passed to this handler before propagating. See error handling.

definition.documentationUrl · string

URL for this component’s documentation page. Required when public is true — must be https://prismatic.io/docs/components/{key}/. Optional for private components.

Return type

Returns a converted component object shaped for the Prismatic API. This value should be the default export of your component’s entry point.

Example

import { component, action, connection, input } from "@prismatic-io/spectral";

const myConnection = connection({
  key: "apiKeyConnection",
  display: {
    label: "API Key",
    description: "Authenticate with an API key",
  },
  inputs: {
    apiKey: {
      label: "API Key",
      placeholder: "Your API key",
      type: "password",
      required: true,
      shown: true,
    },
  },
});

const myAction = action({
  display: {
    label: "Get Record",
    description: "Fetch a single record by ID",
  },
  inputs: {
    connection: input({
      label: "Connection",
      type: "connection",
      required: true,
    }),
    recordId: input({
      label: "Record ID",
      type: "string",
      required: true,
    }),
  },
  perform: async (context, params) => {
    return { data: { id: params.recordId } };
  },
});

export default component({
  key: "myComponent",
  display: {
    label: "My Component",
    description: "A sample custom component",
    iconPath: "icon.png",
  },
  actions: { myAction },
  connections: [myConnection],
  hooks: {
    error: (error) => {
      // Transform or log errors globally
      throw error;
    },
  },
  documentationUrl: "https://example.com/docs/my-component",
});

Related

• action — Define an action within a component
• trigger — Define a trigger within a component
• pollingTrigger — Define a polling trigger
• dataSource — Define a data source
• connection — Define a connection