Existing Components in Code-Native

You can use Prismatic's components in a code-native integration by installing them as npm packages. Each package includes the component's code and TypeScript types, so you can call its actions, configure connections, and use its triggers and data sources directly in TypeScript. You manage component versions alongside your other dependencies and can test calls to components locally.

Install a component package

The examples below use Amazon S3. Start with a code-native integration project and the latest Prism CLI. Install the component as a direct dependency from your project directory:

Install the Amazon S3 component

npm install @prismatic-io/components-aws-s3 @prismatic-io/spectral

Keep the component in dependencies, rather than devDependencies, so the Prism CLI can discover it when importing your integration.

This installs the component and the latest Spectral SDK.

Import the component from the package root:

Import the Amazon S3 component

import awsS3 from "@prismatic-io/components-aws-s3";

Using existing connections in code-native

For a reusable connection, reference its Stable Key from the Prismatic web app with the appropriate Spectral helper. For example, this config page uses an existing customer-activated S3 connection:

src/configPages.ts: reuse a customer connection

import {
  configPage,
  customerActivatedConnection,
} from "@prismatic-io/spectral";

export const configPages = {
  Connections: configPage({
    elements: {
      "Amazon S3 Connection": customerActivatedConnection({
        stableKey: "REPLACE_WITH_YOUR_CONNECTION_STABLE_KEY",
      }),
    },
  }),
};

Use the helper for your connection type; user connections, for example, belong on a user level config page.

To create an integration-scoped connection, use the connection factory from the component package instead:

src/configPages.ts: define an integration-scoped connection

import { configPage } from "@prismatic-io/spectral";
import awsS3 from "@prismatic-io/components-aws-s3";

export const configPages = {
  Connections: configPage({
    elements: {
      "Amazon S3 Connection": awsS3.connections.apiKeySecret({
        stableKey: "amazon-s3-connection",
        values: {},
      }),
    },
  }),
};

The connection factory supplies the component's input definitions. With values: {}, the config wizard prompts the customer for the access key ID and secret access key defined by this connection.

Using existing actions in code-native

Call an action through the imported component's actions property from inside your flow's onExecution function. Pass the action's inputs directly; the SDK supplies the execution context. For S3, the connection input is named accessKey. Input names vary by action, so use the package's TypeScript hints and the component reference when supplying them.

src/flows.ts

import { flow } from "@prismatic-io/spectral";
import awsS3 from "@prismatic-io/components-aws-s3";

export const listBuckets = flow({
  name: "List S3 Buckets",
  stableKey: "list-s3-buckets",
  onExecution: async (context) => {
    const result = await awsS3.actions.listBuckets({
      accessKey: context.configVars["Amazon S3 Connection"],
      awsRegion: "us-east-1",
    });

    context.logger.info(`Found ${result.data.length} buckets`);
    return result;
  },
});

export default [listBuckets];

The package includes the action's implementation, which runs as part of your integration. Use the config page from the previous section and export both your config pages and flows from the integration entry point:

src/index.ts

import { integration } from "@prismatic-io/spectral";
import { configPages } from "./configPages";
import flows from "./flows";

export { configPages } from "./configPages";

export default integration({
  name: "Amazon S3 Integration",
  configPages,
  flows,
});

Keep the scaffold's .spectral directory and TypeScript configuration. They use the named configPages export to infer the types of context.configVars.

Using existing data sources in code-native

A component's data source factory creates a config variable for your configuration wizard. For example, add this element to a config page to let customers select a bucket using their S3 connection:

Config page element: select an S3 bucket

"S3 Bucket": awsS3.dataSources.selectBucket({
  stableKey: "s3-bucket",
  values: {
    accessKey: { configVar: "Amazon S3 Connection" },
  },
}),

Import awsS3 in the config pages file, as in the integration-scoped connection example. The configVar reference supplies the customer's configured connection when the data source runs. For fixed input values, use { value: ... } inside values.

Using existing triggers in code-native

Assign a component trigger to your flow's onTrigger property. Trigger inputs can use literal values or references to config variables. This flow polls for new S3 buckets every hour:

src/flows.ts: poll for new S3 buckets

import { flow } from "@prismatic-io/spectral";
import awsS3 from "@prismatic-io/components-aws-s3";

export const newBuckets = flow({
  name: "New S3 Buckets",
  stableKey: "new-s3-buckets",
  schedule: { value: "0 * * * *" },
  onTrigger: awsS3.triggers.pollNewBucketsTrigger({
    accessKey: { configVar: "Amazon S3 Connection" },
    awsRegion: "us-east-1",
  }),
  onExecution: async (_context, params) => {
    return { data: params.onTrigger.results.body.data };
  },
});

export default [newBuckets];

Use the trigger's component documentation for polling behavior and additional inputs.

Update and test component packages

To adopt a component update, update the npm dependency and review the component's changelog and SDK requirements. Commit your package.json and lockfile so the version you test is also used by your build pipeline. Then rebuild, test, import, publish, and deploy your integration through your usual release process. Installing a new package version in your project does not update deployed instances by itself.

Because npm packages include component code, you can test component calls locally. Use mocks for unit tests that should not call an external API, and test customer configuration and deployment behavior in Prismatic.

For integrations that use component manifests, see the legacy manifest reference and migration guidance.