# Configure Git Repository

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](https://prismatic.io/docs/integrations/code-native.md) and [custom connectors](https://prismatic.io/docs/custom-connectors.md).

Click [here](https://vimeo.com/1129318603) to watch a webinar on this topic.

## Example repository[​](#example-repository "Direct link to Example repository")

For a complete working example, check out our [example project structure repository](https://github.com/prismatic-io/example-project-structure) on GitHub. This repository demonstrates best practices for organizing your Prismatic projects and includes CI/CD automation using GitHub Actions.

## Recommended project structure[​](#recommended-project-structure "Direct link to Recommended project structure")

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

```text
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[​](#components-directory "Direct link to 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.

```text
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[​](#integrations-directory "Direct link to Integrations directory")

The `integrations/` directory contains your [code-native integrations](https://prismatic.io/docs/integrations/code-native.md) - 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`.

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

```

### Shared libraries directory[​](#shared-libraries-directory "Direct link to 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

```text
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

```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](https://prismatic.io/docs/integrations/code-native/existing-components.md#adding-component-manifests-to-your-code-native-project) 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-components-and-integrations "Direct link to Publishing components and integrations")

### Publishing from the command line[​](#publishing-from-the-command-line "Direct link to Publishing from the command line")

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

```bash
# 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[​](#publishing-in-a-cicd-pipeline "Direct link to 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](https://prismatic.io/docs/api/github-actions.md) 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](https://prismatic.io/docs/custom-connectors/publishing.md#publishing-components-in-a-cicd-pipeline) for details.

## Managing multiple environments[​](#managing-multiple-environments "Direct link to 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. If your user is associated with multiple tenants in a single region, also storing the corresponding `PRISMATIC_TENANT_ID` for each environment
4. Storing the Prismatic URL for each environment as variables (e.g., `PRISMATIC_URL_DEV`, `PRISMATIC_URL_PROD`)
5. Creating separate workflow jobs or branches for each environment

See the [Example Project Structure](https://github.com/prismatic-io/example-project-structure) repo for a complete example of publishing to multiple regions. The example repo leverages GitHub Actions' [Environments](https://docs.github.com/en/actions/deployment/targeting-different-environments/using-environments-for-deployment) feature to manage secrets for different Prismatic tenants.

## Best practices[​](#best-practices "Direct link to Best practices")

### Use version control[​](#use-version-control "Direct link to 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[​](#organize-by-domain "Direct link to 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[​](#document-your-code "Direct link to 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[​](#test-in-a-dev-environment-before-publishing "Direct link to 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[​](#leverage-monorepo-tools "Direct link to Leverage monorepo tools")

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

* [npm workspaces](https://docs.npmjs.com/cli/v7/using-npm/workspaces)
* [yarn workspaces](https://yarnpkg.com/features/workspaces)
* [pnpm workspaces](https://pnpm.io/workspaces)
* [bun workspaces](https://bun.com/docs/install/workspaces)

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

## Next steps[​](#next-steps "Direct link to Next steps")

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

* [Build your first code-native integration](https://prismatic.io/docs/get-started/build-integrations/first-integration-code-native.md)
* [Write a custom component](https://prismatic.io/docs/custom-connectors.md)
* [Set up GitHub Actions for automated publishing](https://prismatic.io/docs/api/github-actions.md)
* [Explore the Prism CLI](https://prismatic.io/docs/cli.md)