connect

connect(options?: IConnectOptions): Promise<IPlatformCoreAPI>;

export interface IConnectOptions {
    loadDefaultTheme?: boolean;
    loadUtilities?: boolean;
    loadPlatformCSS?: boolean;
    loadElements?: boolean;
    baseLanguagePath?: string;
    platform?: boolean;
    beta?: boolean;
    moduleId?: string;
    testOptions?: {
        actions?: IActionsStubs;
        sources?: ISourcesStubs;
        outletContext?: string;
        incomingContext?: IncomingContext;
        outletName?: string;
        initialParams?: Record<string, any>;
        loadElements?: boolean;
        loadPlatformCSS?: boolean;
    };
}

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

const tecton = await connect();

// Use sources to get data
const data = await tecton.sources.requestExtensionData?.({ route: 'get_user_info' });

// Use actions to trigger platform behaviors
tecton.actions.setTitle?.('My Feature');

// Subscribe to parameter changes
tecton.sources.paramsChanged?.((params) => {
    console.log('Params updated:', params);
});

// Clean up when done
tecton.teardown();

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

const tecton = await connect({
    loadPlatformCSS: false,   // Skip loading platform CSS
    beta: true,               // Enable beta features
});

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

const tecton = await connect();

// Access incoming context values
const contextId = tecton.incomingContext?.id;
const contextValue = tecton.incomingContext?.value;

Using Test Mode with testOptions

Tecton's primary function is to create an environment within an iframe that mirrors the application in which it is embedded. The connect method establishes this relationship with the containing app and returns functionality exposed by it. There are, however, times when you may want to run your application outside of the iframe — for example, when running tests or during development and continuous integration when working outside the scope of a platform.

Passing testOptions to the connect method puts Tecton into test mode. This bypasses any attempt to establish a platform connection and returns only stubbed functions. The return value of connect is a promise that resolves to all of the functions documented in this guide. Any functions your app relies on must be provided as stubs via testOptions, with the exception of setParams and paramsChanged, which are still provided automatically. If your app receives params from the containing app on bootup, these can also be passed to testOptions under the initialParams property.

connect({
    testOptions: {
        actions: {
            sendModal({ message, button1, button2 }) {
                let result = window.confirm(message);
                return Promise.resolve(result ? button1.actionName : button2.actionName);
            }
        },
        sources: {
            fetchPlatformData(endPoint) {
                return HypotheticalFixturesCatalog.get(endPoint);
            }
        },
        initialParams: {
            hasEnrolled: true,
            userId: 121
        },
        loadElements: false
    }
});

There are some creative ways to use this dynamically that can provide value depending on your situation.

The most basic approach is to use a static config for testMode, toggled based on whether the app is running inside an iframe. When it is not, window.parent === window.

connect({
    testOptions: window.parent === window ? {loadElements: false} : undefined
});

Using namespaced globals passed from your test gives you more control over stub methods for assertions and lets you choose values based on the situation.

connect({
    testOptions: App.TectonTestOptions
});

it('submitting feature form shows modal', async function () {
    let wasCalled;

    App.TectonTestOptions = {
        actions: {
            showModal({ message }) {
                expect(message).to.equal('Form Submitted!');
                wasCalled = true;
            }
        }
    };

    await BootApp();
    await NavigateToFeature();
    await fillOutFormAndSubmit();

    expect(wasCalled).to.be.ok;
});

Using the Platform Option

By default, Tecton connects at the feature level, meaning it assumes it is running within a specific feature or module of the platform. If you wish to connect at the platform level instead, you can set the platform option to true when calling connect. This returns a subset of capabilities available at the platform level and sets up Tecton design system elements accordingly. Connecting at the platform level also enables dynamic menu and navigation elements to be loaded, if they are configured for the platform.