Quickstart

Integrate your tools, workflows, or custom UI directly into the PIM with a TypeScript app.

Struct PIM allows you to extend your PIM environment with custom apps that can create a more interactive user experience. These custom apps can run as iframe-based widgets inside the PIM UI, enabling you to create custom widgets to enhance your workflow and experience.

In this quickstart guide, we will show how to set up a minimal custom widget app using TypeScript, Struct UI for styling, and the Struct Extension SDK to communicate with the PIM.

1. Initialize a TypeScript project with Vite

mkdir my-pim-integration
cd my-pim-integration
npm create vite@latest .

• When prompted, choose:

  • Framework: vanilla

  • Variant: TypeScript

This sets up a clean TypeScript project with Vite, ready for framework-agnostic development.

2. Install PIM SDK and UI Packages

Install the required packages:

npm install @structdk/extension-sdk @structdk/ui @structdk/struct-icon

You can now import these packages in your src/main.ts.

3. Setting up a minimal extension

In src/main.ts, set up the SDK and import the @structdk/ui and @structdk/struct-icon packages:

import '@structdk/ui/dist/struct-ui.css';
import '@structdk/struct-icon/font/struct-icon-24.css'
import { createStructSDK } from '@structdk/extension-sdk';
import type { TabContextPayload } from '@structdk/extension-sdk';

async function init() {
  // SDK instance
  const struct = createStructSDK({ hostOrigin: 'https://your-struct-instance.struct.com' });
  
}

// Initialize app on window load
window.addEventListener('load', () => {
  init();
});

For more details refer to the documentation for the following packages: https://www.npmjs.com/package/@structdk/extension-sdk

https://www.npmjs.com/package/@structdk/struct-icon

https://www.npmjs.com/package/@structdk/ui

4. Create UI component

Create reusable UI component using Struct UI and Struct Icon. For example, src/components/hello.ts:

export function HelloWorld(container: HTMLElement, onClick: () => void) {
  container.innerHTML = `
    <div class="card p-4 space-y-4">
      <h1 class="text-xl font-semibold">Hello World</h1>
      <button class="btn btn-primary">
        <span class="si-24 si-button-play" aria-hidden="true"></span>
        Click me
      </button>
    </div>`;

  const button = container.querySelector<HTMLButtonElement>('.btn');
  button?.addEventListener('click', onClick);
}

5. Render the component in your app

Import the component and render it in src/main.ts:

import '@structdk/ui/dist/struct-ui.css';
import '@structdk/struct-icon/font/struct-icon-24.css'
import { createStructSDK } from '@structdk/extension-sdk';
import { HelloWorld } from './components/hello';

async function init() {
  // SDK instance
  const struct = createStructSDK({ hostOrigin: 'https://your-struct-instance.struct.com' });

  // Render Hello World
  const app = document.getElementById('app');
  if (app) {
    
      const helloContainer = document.createElement('div');
      app.appendChild(helloContainer);

    HelloWorld(helloContainer, () => {
      struct.actions.showSnackbarMessage({
        message: 'Hello World clicked!',
        placement: 'top',
        isError: false
      });
    });
  }
}

// Initialize app on window load
window.addEventListener('load', () => {
  init();
});

6. Integrate app

1. Click "Create App"-button to begin setting up the custom app.

1. Configure the General settings for the app.

1. Setup extension points.

1. Embed the new external widget in the dashboard.

The URLs used in this setup must point to a running application. In this quickstart, the app is run locally for development purposes. In a production setup, the app should be deployed and accessible by Struct PIM.

This wraps up the flow for setting up and integrating an app to the PIM.