Capabilities

Updated:

Capabilities enable Tecton modules to communicate with the platform they're embedded in. Use Actions to trigger platform behaviors, and Sources to access platform data.

Capabilities require q2-tecton-sdk for features rendered inside of a platform configured with q2-tecton-platform. They are not available for design-system-only usecases.

Quick Reference

import tecton from 'q2-tecton-sdk';
await tecton.connect();

// Actions
tecton.actions.setTitle('My Page');
tecton.actions.navigateTo('/accounts');

// Sources
const locale = await tecton.sources.loc();
const canTransfer = await tecton.sources.canUser('transfer');

Why Capabilities?

Tecton modules render inside iframes, providing the security isolation needed when code from different teams and companies runs on the same page. This isolation introduces challenges:

  • How does the iframe make API requests without direct access to session tokens?
  • How does a module tell the platform to navigate or show a modal?
  • How does a module check if the user has permission to view certain content?

Capabilities solve these challenges by providing a safe, reliable communication channel between modules and platforms.

Getting Started

All extensions must establish a connection to the platform:

import { connect } from 'q2-tecton-sdk';

const tecton = await connect();

Once connected, Actions and Sources are available on the tecton object for use in your module. See below for examples of how to use them and a list of common capabilities provided by Tecton.

Actions

Actions trigger the platform to perform operations. Common categories:

  • showModal({ title, message }) - Display a modal dialog
  • setTitle(title) - Set the page title
  • printWindow() - Print the current view

Example: Show a Modal

tecton.actions.showModal({
  title: 'Greeting',
  message: 'Hello! Welcome to the app.'
});

Sources

Sources provide data from the platform to your module. Two patterns:

One-time Data (Promise-based)

const isAllowed = await tecton.sources.canUser('viewAccounts');

Reactive Data (Callback-based)

tecton.sources.languageChanged((newLanguage) => {
  // Update UI for new language
});

Common Sources

  • canUser(permission) - Check user permissions
  • languageChanged(callback) - React to language changes
  • promptForMFA({ message }) - Launch multi-factor authentication workflow