@salesforce/sdk-data (Beta)

Runtime SDK for accessing Salesforce record data via GraphQL and REST from React web apps.

Beta: This is a pilot or beta service subject to the Beta Services Terms or a written Unified Pilot Agreement, and applicable terms in the Product Terms Directory.

Installation

npm install @salesforce/sdk-data

Quick Start

import { createDataSDK, gql } from "@salesforce/sdk-data";

const MY_QUERY = gql`
  query GetAccounts {
    uiapi {
      query {
        Account(first: 10) {
          edges {
            node {
              Id
              Name {
                value
              }
              Industry {
                value
              }
            }
          }
        }
      }
    }
  }
`;

const dataSdk = await createDataSDK();
const response = await dataSdk.graphql?.<GetAccountsQuery>(MY_QUERY);

API Reference

createDataSDK(options?)

Factory that creates a DataSDK instance. Detects the runtime surface automatically and returns the appropriate implementation.

async function createDataSDK(options?: DataSDKOptions): Promise<DataSDK>;

DataSDKOptions

| Property | Type | Description | | :--------- | :----------------------- | :----------------------------------- | | surface | string | Override automatic surface detection | | uiBundle | UIBundleDataSDKOptions | Options for the UI Bundle surface |

UIBundleDataSDKOptions

| Property | Type | Description | | :--------- | :---------------------------------------- | :-------------------------------------------- | | basePath | string | Base URL prefix for Salesforce API calls | | onStatus | Partial<Record<number, StatusCallback>> | HTTP status code callback map (e.g. 401, 403) |

DataSDK Interface

interface DataSDK {
  graphql?: <T, V = Record<string, unknown>>(
    query: string,
    variables?: V,
  ) => Promise<GraphQLResponse<T>>;
  fetch?: typeof fetch;
}

Both methods are optional — availability depends on the runtime environment. Always use optional chaining when calling them.

graphql<T, V>(query, variables?)

Sends a GraphQL request to the Salesforce UI API endpoint.

| Parameter | Type | Description | | :---------- | :------- | :----------------------------------------- | | query | string | GraphQL query or mutation operation | | variables | V | Optional variables referenced by the query |

Returns Promise<GraphQLResponse<T>>:

interface GraphQLResponse<T> {
  data: T;
  errors?: Array<{
    message: string;
    locations?: Array<{ line: number; column: number }>;
    path?: string[];
  }>;
}

fetch(input, init?)

Fetch wrapper for Salesforce REST endpoints not covered by GraphQL. Handles CSRF token management and base path resolution.

Supported endpoints include /services/apexrest/*, /services/data/v{version}/ui-api/*, /services/data/v{version}/chatter/*, and others.

gql Template Tag

Identity template literal tag for inline GraphQL queries. Enables editor syntax highlighting and codegen detection without any runtime transformation.

import { gql } from "@salesforce/sdk-data";

const MY_QUERY = gql`
  query MyQuery {
    uiapi { ... }
  }
`;

NodeOfConnection<T>

Utility type that extracts the node type from a UI API GraphQL connection response (the edges/node pattern).

import { type NodeOfConnection } from "@salesforce/sdk-data";
import type { GetAccountsQuery } from "../graphql-operations-types";

type AccountNode = NodeOfConnection<GetAccountsQuery["uiapi"]["query"]["Account"]>;

Use this when your query returns the connection shape and you need a clean type for individual records. If your query uses simple flat types, you don't need NodeOfConnection.

Usage Patterns

Inline Queries with gql

Best for simple queries without variables that are colocated with the usage code.

import { createDataSDK, gql } from "@salesforce/sdk-data";
import type { CurrentUserQuery } from "../graphql-operations-types";

const CURRENT_USER = gql`
  query CurrentUser {
    uiapi {
      currentUser {
        Id
        Name {
          value
        }
      }
    }
  }
`;

export async function getCurrentUser() {
  const dataSdk = await createDataSDK();
  const response = await dataSdk.graphql?.<CurrentUserQuery>(CURRENT_USER);

  if (response?.errors?.length) {
    throw new Error(response.errors.map((e) => e.message).join("; "));
  }

  return response?.data?.uiapi.currentUser ?? null;
}

External .graphql Files

Best for complex queries with variables, fragments, or queries shared across files. Import with the ?raw suffix.

src/api/utils/query/getProperties.graphql

query GetProperties($first: Int) {
  uiapi {
    query {
      Property__c(first: $first) {
        edges {
          node {
            Id
            Name {
              value
            }
            Address__c {
              value
            }
            Status__c {
              value
            }
          }
        }
      }
    }
  }
}

src/api/getProperties.ts

import { createDataSDK, type NodeOfConnection } from "@salesforce/sdk-data";
import GET_PROPERTIES from "./query/getProperties.graphql?raw";
import type { GetPropertiesQuery, GetPropertiesQueryVariables } from "../graphql-operations-types";

type PropertyNode = NodeOfConnection<GetPropertiesQuery["uiapi"]["query"]["Property__c"]>;

export async function getProperties(first = 50): Promise<PropertyNode[]> {
  const dataSdk = await createDataSDK();
  const response = await dataSdk.graphql?.<GetPropertiesQuery, GetPropertiesQueryVariables>(
    GET_PROPERTIES,
    { first },
  );

  if (response?.errors?.length) {
    throw new Error(response.errors.map((e) => e.message).join("; "));
  }

  return response?.data?.uiapi?.query?.Property__c?.edges?.map((e) => e?.node) || [];
}

REST via fetch

Use dataSdk.fetch?.() for Salesforce REST endpoints not covered by GraphQL, such as Apex REST or Connect API.

import { createDataSDK } from "@salesforce/sdk-data";

const dataSdk = await createDataSDK();
const response = await dataSdk.fetch?.("/services/apexrest/property/listings");
const listings = await response?.json();

Data Access Guidelines

1. Prefer GraphQL via dataSdk.graphql?.() for record data access.
2. Use dataSdk.fetch?.() for REST endpoints not covered by GraphQL (Apex REST, UI API, Connect API).
3. Always use optional chaining (graphql?.(), fetch?.()) — both methods may be unavailable depending on the runtime surface.
4. Never call fetch() or axios directly for Salesforce endpoints. The SDK handles authentication and CSRF tokens.
5. Use the gql tag or .graphql files — never plain string literals for queries.
6. Provide type generics to graphql?.() for type-safe responses.

// Prefer this
await dataSdk.graphql?.<GetAccountsQuery>(query);

// Not this
await dataSdk.graphql?.(query);

See Also

• GraphQL API Developer Guide
• UI API Schema Conventions
• React App Recipes