Wiring connectors into your app

Wire the generated connector files into the frontend after rayfin connector add has created the connector entry and you have installed the exact pinned packages it printed. Category A connectors can run with configuration only; Category B connectors also need runtime hooks.

Import the connector client

Changed in 1.36

ConnectorsRayfinClient is exported from the stable client entry:

import { ConnectorsRayfinClient } from '@microsoft/rayfin-client';

The older @microsoft/rayfin-client/experimental subpath still exports it for compatibility. New code should use the stable package root.

The type parameters are <DataSchema, FunctionsSchema, ConnectorsSchema>. Use Record<string, never> for any slot your app does not use.

Pass connector config in the first argument

The constructor is:

new ConnectorsRayfinClient(config, connectorsRuntime?)

config extends the standard Rayfin client config, so it accepts baseUrl and publishableKey. It also requires connectors, a map keyed by connector name whose values are the generated connectorConfig objects.

host is optional. When omitted, the connectors layer detects { type: 'cli' } under Node and { type: 'standalone' } in browsers. Pass { type: 'embedded' } only when the app is running inside the Fabric portal host and the host integration has asserted that environment.

Pass Category B runtimes in the second argument

The second constructor argument is the per-connector runtime map, keyed by connector name. Category A connectors need no runtime entry.

Category B connectors require one:

• kusto() merges the generated queryServiceUri and databaseName into the outbound payload. Without it, KQL queries cannot route to the cluster.
• fabricSemanticModel() decodes the Arrow response. Without it, semantic-model query results cannot be read.

Keep connector keys identical

The connector key must be identical in four places:

1. The name in rayfin.yml.
2. The property in AppConnectorsSchema.
3. The property in the connectors option.
4. The property in the runtime map for Category B connectors.

If they differ, TypeScript reports Property '<name>' does not exist on connectors.

Use src/lib/connectors.ts when the CLI generates it

New in 1.36

rayfin connector add can maintain src/lib/connectors.ts for templates that include that file. The generated file centralizes connector schema types, config values, and Category B runtimes so the client setup stays small.

A complete generated file for one Category A connector and two Category B connectors looks like this:

// @generated by `rayfin connector add` — do not edit below this line.

import { fabricSemanticModel } from '@microsoft/rayfin-connector-fabric-semanticmodel';
import { kusto } from '@microsoft/rayfin-connector-kusto';
import type { ConnectorConfig, ConnectorsRuntime } from '@microsoft/rayfin-connectors';
import {
  connectorConfig as inventoryConfig,
  type InventorySchema,
} from '../../rayfin/connectors/inventory/schema';
import {
  connectorConfig as salesmodelConfig,
  type SalesmodelSchema,
} from '../../rayfin/connectors/salesmodel/schema';
import {
  connectorConfig as telemetryConfig,
  type TelemetrySchema,
} from '../../rayfin/connectors/telemetry/schema';

export type AppConnectorsSchema = {
  inventory: InventorySchema;
  salesmodel: SalesmodelSchema;
  telemetry: TelemetrySchema;
};

export const connectorConfigs: Record<string, ConnectorConfig> = {
  inventory: inventoryConfig,
  salesmodel: salesmodelConfig,
  telemetry: telemetryConfig,
};

export const connectorRuntimes: ConnectorsRuntime = {
  salesmodel: fabricSemanticModel(),
  telemetry: kusto(),
};

If your app has this file, import it from the frontend client instead of duplicating the maps.

Wire one client

This example wires the connector maps from src/lib/connectors.ts. It assumes inventory, salesmodel, and telemetry are the exact connector names in rayfin.yml.

import { ConnectorsRayfinClient } from '@microsoft/rayfin-client';
import type { AppConnectorsSchema } from '../lib/connectors';
import { connectorConfigs, connectorRuntimes } from '../lib/connectors';

export const rayfinClient = new ConnectorsRayfinClient<
  Record<string, never>,
  Record<string, never>,
  AppConnectorsSchema
>(
  {
    baseUrl: import.meta.env.VITE_RAYFIN_API_URL,
    publishableKey: import.meta.env.VITE_RAYFIN_PUBLISHABLE_KEY,
    authStorage: true,
    connectors: connectorConfigs,
  },
  connectorRuntimes,
);

Choose an entities registration form

Category A aggregate schema.ts files must give connectorConfig.entities enough metadata for default selections. Each entity entry can be either a string array of scalar field names or the decorated entity class.

Prefer string arrays in code the browser loads. A decorated entity class can break a browser bundle; see Decorated entity classes can break a browser bundle.

import type { GraphQLBackedConnector } from '@microsoft/rayfin-connector-fabric-graphql';
import type { ConnectorConfig } from '@microsoft/rayfin-connectors';

import type { Order } from './Order.js';
import type { Customer } from './Customer.js';

export type { Order } from './Order.js';
export type { Customer } from './Customer.js';

export const connectorConfig = {
  connector: 'fabric-warehouse',
  operations: ['read', 'update'],
  entities: {
    Order: ['orderId', 'customerId', 'total', 'placedUtc'],
    Customer: ['customerId', 'email'],
  },
} as const satisfies ConnectorConfig;

export type InventorySchema = GraphQLBackedConnector<
  { Order: typeof Order; Customer: typeof Customer },
  typeof connectorConfig
>;

Use the class form only when app code must select relationship dotted paths such as orderItems.quantity. Relationship selections require @one and @many cardinality metadata. A relationship select against the array form throws ENTITIES_REQUIRED_FOR_RELATIONSHIP_SELECT.

import { Order } from './Order.js';
import { Customer } from './Customer.js';

export { Order } from './Order.js';
export { Customer } from './Customer.js';

export const connectorConfig = {
  connector: 'fabric-warehouse',
  operations: ['read', 'update'],
  entities: {
    Order,
    Customer,
  },
} as const satisfies ConnectorConfig;

If you use the class form, run the production build and verify the deployed page loads before relying on it.

Troubleshoot client wiring

Continue by connector type

• Fabric SQL sources
• Semantic models
• KQL databases