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 project
prism components:init slack
cd slack
# Pull down the Slack icon for use by the component
curl '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 { version } from "../package.json";
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 key is referenced later in the action's perform function. 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 webhookField = input({
key: "webhookUrl",
label: "Webhook URL",
placeholder: "Slack Webhook URL",
type: "string",
required: true,
});
const messageField = input({
key: "message",
label: "Message",
placeholder: "Message to send",
type: "string",
required: true,
});

Create a component action

info

action keys are unique, and the existing Slack plugin utilizes the key postSlackMessage already. Hence, the "new" appended to the below action and component keys. Appending "new" to actual components is highly discouraged.

Now it's time to create an action that our component can take. You need to provide the action with a unique key, 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 postSlackMessageAction = action({
key: "newPostSlackMessage",
display: {
label: "Slack Message",
description: "Post a message to a Slack channel",
},
inputs: [webhookField, messageField],
perform: async (context, { message, webhookUrl }) => {
const webhook = new IncomingWebhook(webhookUrl);
await webhook.send({ text: message });
},
});

Export your component

Lastly, we need to export a component object that is versioned, has a key like the action key, contains a label and description to display in the web app, and lists the actions that are associated with the component.

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

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.

cd dist/
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!