Skip to main content

Writing Your First Custom Component

What you will accomplish#

In this tutorial you will create the Slack component from scratch to illustrate how readily you can write custom code for an integration.

Initialize your project#

Suppose Prismatic's Slack component did not exist. How would one go about creating a component that sends notifications to Slack?

To start your integration, use the prism components:init subcommand to create a new TypeScript project.

# Initialize the projectprism components:init slackcd slack
# Pull down the Slack icon for use by the componentcurl 'https://prismatic.io/docs/img/slack.png' > assets/icon.png

This will create a NodeJS project with TypeScript support, complete with required dependencies, like Webpack and Prismatic's custom component library, spectral.

Add Dependencies#

Most of the dependencies you require have been added for you, but because you're building a Slack component, you will want to take advantage of the Slack webhook npm package.

npm install @slack/webhook

Add the following to the top of src/index.ts:

src/index.ts
import { action, component, input } from "@prismatic-io/spectral";import { IncomingWebhook } from "@slack/webhook";

Create some input fields#

What information will you need to send a Slack message? At minimum, we'll need two things:

  1. A Slack webhook URL to send messages to
  2. A message to send.

To create those input fields for your component, you will create two new inputs in src/index.ts. The label and placeholder will appear within the Prismatic web app when a user utilizes this action. type and required are self-explanatory.

src/index.ts
const webhookUrl = input({  label: "Webhook URL",  placeholder: "Slack Webhook URL",  type: "string",  required: true,});const message = input({  label: "Message",  placeholder: "Message to send",  type: "string",  required: true,});

Create a component action#

Now it's time to create an action that our component can take. You need to provide the action with a label and description to display in the web app, a set of inputs that you created above, and some code to perform when the action is invoked. You can take advantage of the Slack API in our perform function.

src/index.ts
const postSlackMessage = action({  display: {    label: "Slack Message",    description: "Post a message to a Slack channel",  },  perform: async (context, { message, webhookUrl }) => {    const webhook = new IncomingWebhook(webhookUrl);    await webhook.send({ text: message });  },  inputs: { webhookUrl, message },});

Export your component#

Lastly, we need to export a component object that has a unique key to identify it in Prismatic, contains a label and description to display in the web app, and an object containing the actions that are associated with the component.

src/index.ts
export default component({  key: "newSlack",  public: true,  display: {    label: "New Slack",    description: "Post messages to Slack",    iconPath: "icon.png",  },  actions: {    postSlackMessage,  },});

Build and deploy your component#

At this point you're ready to build your component, and then deploy it. Use webpack to package your component

yarn webpack

Your build exists in dist/. Now, you can use prism to deploy your component.

prism components:publish

Test your new component#

Congratulations! You've published your first custom component! Try modifying your first integration to use your new component, and verify that it posts to Slack like the official Prismatic Slack component does!