Writing Custom Components
Overview
Prismatic is extensible and allows for developer users to develop their own custom components. Components that Prismatic users develop are proprietary to their organization, and are private.
Sample component code is referenced throughout this page.
Custom Component Library
Prismatic provides a NodeJS package, @prismatic-io/spectral, which provides TypeScript typing and some utility functions.
For information on Spectral's utility functions and types, see our custom component library docs.
Initializing a New Component
To initialize a new project, run prism components:init {{ COMPONENT NAME }}
.
Your component name must be comprised of alphanumeric characters, hyphens, and underscores, and start and end with alphanumeric characters. This will create a directory structure that looks like this:
assets/icon.png
is the icon that will be displayed next to your component Square transparent PNGs at least 128 x 128 pixels in size look best, and will be scaled by the web app appropriately.jest.config.js
contains configuration for the Jest testing frameworkpackage.json
is a standard node package definition filesrc/index.ts
contains the code for your component. This file can be broken into multiple files as neededsrc/index.test.ts
contains tests for component actions defined inindex.ts
. See Unit Testing Custom Componentstsconfig.json
contains configuration for TypeScriptwebpack.config.js
contains configuration for Webpack
After these files are created run cd {{ COMPONENT_NAME }}
to enter the directory of your component, and then npm install
or yarn install
to install dependencies.
Writing Actions
A component is comprised of one or many actions. For example, the HTTP component contains actions to GET (httpGet
), POST (httpPost
), etc.
An action
takes four arguments:
- A unique
key
name of the action, preferably in camelCase. - Information on how the web app
display
the action - A function to
perform
- A series of
input
fields
Adding Inputs
Components can take inputs
. Each input
is comprised of a required key
, label
, and type
and optional placeholder
, default
, comments
, required
and model
.
Consider this example input:
This contributes to an input prompt that looks like this:

Note where the label
and placeholder
text appeared in the web app, and note that First Name and Last Name are required - indicated with a *
, but Middle Name is not.
Input key names
The key
specified above (in this case, "middleName"
) is accessible as an input for the perform
function.
perform
functions
Writing Each action contains one perform
function, which is an async function with two parameters that may or may not have a return value.
In this example firstName
, middleName
, and lastName
, are input parameters for this perform
function
perform
Function Parameters
The perform
function takes two parameters, context
and params
, that can be destructured into their respective properties:
context
Parameter
The The context
parameter is an object that contains three attributes: configVars
, logger
and credential
.
context.configVars
context.configVars
is utilized only by the Custom Code Component, and is an object that contains key/value pairs of configuration variables that are accessible to the action.
For example, if your integration has config variables named myEndpoint
and username
, you could access them like so:
note
context.configVars
is only accessible to the custom code component, as that component takes no inputs.
To pass config variables into other components, reference the config variables as inputs
of your component.
context.logger
context.logger
is a logging object and can be helpful to debug components.
context.credential
context.credential
is an object that stores information about any credentials tied to this action in the form
The fields
presented are dependent on what type of credential is passed in -- see Authorization Methods.
If, for example, you use the basic
authorization type, the credential
payload might read
The credential parameter can be used in your custom component like this:
params
Parameter
The The params
parameter is an object that has attributes for each input field the action supports.
For example, for the perform action defined above, params
has params.firstName
, params.middleName
, and params.lastName
.
firstName
, middleName
, and lastName
are based off of the key
of each input
The function is written with a destructured params
parameter.
It could be rewritten without being destructured.
Component Outputs
In the example above, the function returns a string of the form Last, First M.
.
This return value of a custom component is accessible to subsequent steps by referencing this step's results
:

Component outputs can take many forms. To return a simple string, number, boolean, list, or object your return block can read:
Those values can be used as inputs in subsequent steps by referencing this step's results
.
Outputting Binary Data
Some custom components will not output a number, string, boolean, list, or object, but will instead output an entire file (like an image, PDF, video, etc).
For those custom components, the return value will contain a file Buffer
as the data
return, and a contentType
key to indicate kind of file is being returned.
See Mozilla's documentation for a list of common file MIME types.
For example, if your custom component returns a rendered PDF file, and the PDF contents are saved in a Buffer
variable named pdfContents
, the return block might look like this:
Setting Synchronous HTTP Status Codes
If you invoke your instances synchronously and would like to return an HTTP status code other than 200 - OK
, you can configure the final step of your integration to be a custom component that returns any HTTP status code you want.
To return a status code other than 200, add the status code to the object you return from your custom component. For example,
If this custom component is the last step of an integration, then the integration will return an HTTP status code of 415 if invoked synchronously.
Exporting a Component
Component code contains a default export of component
type. A component
contains a key
name, whether or not it's public
, a version
, some information about how the web app should display
it, and a list of actions
that the component contains. For the "proper and improper" names example component, the export can look like this
Publishing a Component
Package a component with webpack
by running npm run build
or yarn build
:
This will create a dist/
directory containing your compiled JavaScript and icon image.
Navigate to that directory, and use prism
to publish your component.