Capabilities

Updated:

An overview of Tecton Capabilities, which allow modules to communicate with the platform they are embedded in.

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