Skip to main content

Setting up a Repo for Prismatic

When building integrations and custom connectors (also called custom components) with Prismatic, it's important to organize your repository in a way that promotes code reuse, maintainability, and efficient CI/CD workflows. This guide will walk you through setting up a repository structure that supports both code-native integrations and custom connectors.

Example repository​

For a complete working example, check out our example project structure repository on GitHub. This repository demonstrates best practices for organizing your Prismatic projects and includes CI/CD automation using GitHub Actions.

A well-organized Prismatic repository typically includes the following directories:

my-prismatic-project/
├── .github/
│   └── workflows/            # CI/CD pipelines for automation
│       ├── components.yml
│       └── integrations.yml
├── components                # Custom components for low-code integrations
│   ├── acme
│   └── todoist
├── integrations              # Code-native integrations
│   ├── slack
│   └── todoist
└── shared-libs               # Shared libraries for CNI + Components
│   ├── acme
│   └── todoist
└── package.json

Components directory​

The components/ directory contains your custom connectors - reusable building blocks that can be used across multiple integrations. Each component should be in its own subdirectory with its own package.json, source code, and tests.

components/
├── acme-crm/
│   ├── src/
│   │   ├── index.ts
│   │   ├── actions.ts
│   │   └── connections.ts
│   ├── package.json
│   └── tsconfig.json
└── todoist/
    ├── src/
    │   └── index.ts
    └── package.json

Components are published to your Prismatic tenant and can then be used in both low-code and code-native integrations.

Integrations directory​

The integrations/ directory contains your code-native integrations - complete integration solutions built entirely in TypeScript. Like components, each integration should have its own subdirectory with its dependencies and configuration. Each integration should be initialized using the Prismatic CLI tool by running prism integrations:init.

integrations/
└── slack/
    ├── src/
    │   ├── index.ts
    │   └── flows.ts
    │   └── configPages.ts
    ├── package.json
    └── tsconfig.json

Shared libraries directory​

The shared-libs/ directory contains reusable TypeScript packages that can be shared across both components and integrations. This promotes code reuse and keeps your codebase DRY (Don't Repeat Yourself).

Using shared libraries offers several advantages:

  1. Faster iterations: Updates to shared code immediately benefit all dependent projects
  2. Local code visibility: All code remains in your repository for easier navigation and debugging
  3. Code reusability: Common logic (API clients, utilities, types) centralizes in one location
shared-libs/
├── acme-client/
│   ├── src/
│   │   ├── index.ts
│   │   └── types.ts
│   ├── package.json
│   └── tsconfig.json
└── common-utils/
    ├── src/
    │   └── index.ts
    └── package.json

Shared libraries can be referenced in your components and integrations as local dependencies in their package.json files:

components/acme-crm/package.json
{
  "dependencies": {
    "@prismatic-io/spectral": "^9.0.0",
    "acme-client": "file:../../shared-libs/acme-client"
  }
}
Why use shared libraries?

When building both custom components and code-native integrations that interact with the same external APIs, you have two options for sharing code:

  1. Abstract common logic into shared libraries
  2. Publish custom component and install the component's manifest into your code-native project.

Using shared libraries is often the better choice because it allows for faster iterations and easier debugging. When you update a shared library, all components and integrations that depend on it immediately benefit from the changes without needing to republish components.

Publishing components and integrations​

Publishing from the command line​

You can manually publish components and integrations using the Prism CLI:

# Publish a component
cd components/my-component
npm run build
prism components:publish

# Publish a code-native integration
cd integrations/my-integration
npm run build
export INTEGRATION_ID=$(prism integrations:import)
prism integrations:publish ${INTEGRATION_ID}

Publishing in a CI/CD pipeline​

For automated publishing, you can integrate the Prism CLI into your CI/CD pipeline. The CLI supports authentication via refresh tokens, making it easy to automate deployments.

If you're using GitHub Actions, Prismatic provides pre-built actions that make publishing even easier. See our GitHub Actions guide for detailed instructions on:

  • Setting up authentication with GitHub secrets
  • Publishing components automatically when code changes
  • Publishing integrations automatically when code changes
  • Ensuring components are published before integrations that depend on them
  • Linking component and integration versions to pull requests

For other CI/CD systems (GitLab CI, Jenkins, CircleCI, Azure DevOps, etc.), you can use the Prism CLI directly. See Publishing components in a CI/CD pipeline for details.

Managing multiple environments​

If you have multiple Prismatic tenants (for example, a development environment and production environments in different regions), you can manage them in your CI/CD pipeline by:

  1. Creating separate refresh tokens for each environment
  2. Storing them as secrets in your CI/CD system (e.g., PRISM_REFRESH_TOKEN_DEV, PRISM_REFRESH_TOKEN_PROD)
  3. Storing the Prismatic URL for each environment as variables (e.g., PRISMATIC_URL_DEV, PRISMATIC_URL_PROD)
  4. Creating separate workflow jobs or branches for each environment

See the Example Project Structure repo for a complete example of publishing to multiple regions. The example repo leverages GitHub Actions' Environments feature to manage secrets for different Prismatic tenants.

Best practices​

Use version control​

Always commit your component and integration source code to version control (Git). This allows you to track changes, collaborate with team members, and roll back if needed.

Organize by domain​

If you have lots of custom components, group related components and integrations together. For example, if you have multiple components related to your CRM system, consider placing them in a components/crm/ subdirectory.

Document your code​

Add README files to your components and integrations explaining:

  • What the component or integration does
  • How to install dependencies
  • How to build and test locally
  • Any configuration required

Test in a dev environment before publishing​

When possible, test your components and integrations in a development Prismatic tenant before publishing to production. This helps catch issues early and ensures a smoother deployment process.

Leverage monorepo tools​

For larger projects with many components and integrations, consider using monorepo tools like:

These tools make it easier to manage dependencies, run scripts across multiple packages, and optimize build times.

Next steps​

Now that you have your repository set up, you're ready to start building: