Build with the Extension SDK
This guide shows how to build an extension app with the Extension SDK: set up the app, connect to GraFx Experience, call the platform API, and embed the app.
How it works
GraFx Experience loads your app in an iframe. The Extension SDK (@kadanza/extension-sdk) handles:
- The handshake with the portal
- The token that lets your app act for the signed-in user
- API calls to the Experience Extension API
You don't need to write your own postMessage code. Use createExtensionSDK() and the flows in the SDK.
Before you start
- A local extension with SDK authentication on, and Experience pages and/or Admin Console pages on
- Node.js and npm
- Hosting for the app, reachable over HTTPS. See Hosting your extension.
Turn on SDK authentication
Without it, your app doesn't receive a token and can't call the API.
Step 1: Set up the app
Use React, Vite, and TypeScript:
npm create vite@latest my-extension -- --template react-ts
cd my-extension
npm install @kadanza/extension-sdk react-router-dom
Use HashRouter, not BrowserRouter. GraFx Experience adds a tenantUrl parameter to the iframe URL, and hash routing keeps it in place while your app navigates.
Step 2: Connect to GraFx Experience
import { createExtensionSDK } from "@kadanza/extension-sdk";
const sdk = createExtensionSDK();
const { authToken, extensionDetails, designTokens } = await sdk.connect({
routingType: "client-hash",
authTokenAutoRefresh: true,
});
- Create the SDK once. Later calls to
createExtensionSDK()return the same instance. routingType: "client-hash"lets GraFx Experience change routes without reloading the iframe.connect()resolves when GraFx Experience answers the handshake.- Fields the page doesn't provide are
null. For example, Admin Console pages have nospaceIdorpageId.
React apps
Wrap your app in a provider that connects once, shows the UI only after the handshake, and calls destroy() on pagehide. See Building a React extension.
Step 3: Call the platform API
Use sdk.apiCall() with paths from the Experience Extension API. The SDK adds the Authorization and X-Tenant headers.
Calls are limited to the API permissions of your extension. To validate the token on your own back end, see Extension SDK JWT claims.
Step 4: Host and embed
You host the app yourself, or your customer or a third party hosts it. For now, CHILI GraFx does not host extension apps.
- Deploy the app over HTTPS.
- In the Admin Console, go to Extensions > Installed and open your extension.
- Set Base URL to your app's address, and add the page paths it serves.
- Turn on Active and save.
GraFx Experience loads your app from the Base URL and adds a tenantUrl parameter with the portal's address. The SDK only accepts messages from that address.
When your app changes route, call emitNavigationChange so the portal knows. See Navigation.
Further reading
| Resource | Covers |
|---|---|
| Building a React extension | Provider, handshake, API calls, navigation |
| Flows | Handshake, design tokens, apiCall, token refresh, page settings, navigation |
| Embedding | How GraFx Experience embeds your app |
| SDK API reference | Classes, interfaces, and payloads |
| npm package | Installation and versions |