The SitecoreClient API

The SitecoreClient class is a generic, framework-agnostic client that you can use to interact with SitecoreAI's headless APIs and services. It provides a unified interface for retrieving and managing content, layout, dictionary data, error pages, preview data, sitemaps, robots.txt, and other site-related information from a SitecoreAI backend, typically via GraphQL endpoints.

It enables the following:

  • Content retrieval - fetch page layout data, preview data, and component data for rendering pages and components.

  • Localization - retrieve dictionary phrases for specific sites and locales.

  • Personalization - provide personalized content by handling variant IDs and rewriting layout data accordingly.

  • SEO support - fetch sitemap XML and robots.txt content for SEO and crawler support.

  • Static paths - generate static paths for all site pages, enabling workflows such as static site generation.

  • Extensibility - implement custom services using dependency injection in the constructor.

Configuration

To initialize the SitecoreClient, you need to provide a configuration object of type SitecoreClientInit.

The configuration object is derived from the SitecoreConfig type, which includes all settings necessary for connecting to SitecoreAI's headless services. It includes a custom property that allows you to inject custom implementations for the services used by SitecoreClient.

Key methods

Here is a list of the methods exposed by the SitecoreClient class, including their purpose, input parameters, and expected outputs. You can learn more about the related services by referring to the linked API documentation.

Method name

Description

Type signature

getComponentData

(Next.js only) Uses ComponentPropsService to parse components from the Next.js component factory with layout data, then executes the getComponentServicerProps method and returns the resulting component props.

getComponentData(layoutData: LayoutServiceData, context: GetServerSidePropsContext | GetStaticPropsContext, moduleFactory: ModuleFactory): Promise<ComponentPropsCollection>

getDictionary

Uses DictionaryService to retrieve dictionary phrases for a given site and locale.

getDictionary(routeOptions?: Partial<RouteOptions>, fetchOptions?: FetchOptions): Promise<DictionaryPhrases>

getErrorPage

Uses ErrorPagesService to retrieve an error page for a given site and locale.

getErrorPage(code: ErrorPage, pageOptions?: RouteOptions, fetchOptions?: FetchOptions): Promise<Page | null>

getHeadLinks

Retrieves the head <link> elements for SitecoreAI styles and themes.

enableStyles - When true, includes content styles, CSS files associated with your Sitecore content, that are typically component-specific or content-managed stylesheets.

enableThemes - When true, includes the Design studio/theme stylesheet links (CSS files associated with the Design studio themes). Themes provide site-wide styling and design consistency.

getHeadLinks(layoutData: LayoutServiceData, options?: { enableStyles?: boolean; enableThemes?: boolean }): HTMLLink[]

Both enableStyles and enableThemes are true by default.

getPage

Uses LayoutService to retrieve page data for a given route.

getPage(path: string | string[], pageOptions?: PageOptions, fetchOptions?: FetchOptions): Promise<Page | null>

getPagePaths

Uses SitePathService to retrieve the static paths of pages based on the specified languages.

getPagePaths(languages?: string[], fetchOptions?: FetchOptions): Promise<StaticPath[]>

getPreview

Uses EditingService to retrieve preview page and layout details.

getPreview(previewData: EditingPreviewData | undefined, fetchOptions?: FetchOptions): Promise<Page | null>

getRobots

Uses RobotsService to retrieve the content of the robots.txt file for a given site.

getRobots(siteName: string, fetchOptions?: FetchOptions): Promise<string | null>

getSiteMap

Uses SitemapXmlService to retrieve either an individual sitemap or a sitemap index for a given site.

getSiteMap(options: SitemapXmlOptions, fetchOptions?: FetchOptions): Promise<string>

getDesignLibraryData

Uses ComponentLayoutService to retrieve a Design studio page.

getDesignLibraryData(designLibData: DesignLibraryRenderPreviewData, fetchOptions?: FetchOptions): Promise<Page>

getData

Exposes a simple, typed way to run raw GraphQL requests directly from SitecoreClient. It forwards your call to the SDK’s low-level GraphQLClient.request with the same retry, header, and fetch behavior you’ve configured.

Examples:

RequestResponse
type SearchResult = { search: { results: { id: string; name: string }[] } };

const res = await client.getData<SearchResult>(
  `
  query SearchByName($name: String!, $lang: String!) {
    search(where: { name: { equals: $name } }, language: $lang) {
      results { id name }
    }
  }`,
  { name: 'Home', lang: 'en' }
);
RequestResponse
import { gql } from 'graphql-tag';

const Query = gql`
  query ($lang: String!) { search(language: $lang) { results { id } } }
`;

const res = await client.getData<{ search: { results: { id: string }[] } }>(Query, { lang: 'en' });

getData<T = unknown>( query: string | import('graphql').DocumentNode, variables?: Record<string, unknown>, fetchOptions?: FetchOptions ): Promise<T>

Do you have some feedback for us?

If you have suggestions for improving this article,