Client SDK - Frontic Docs

The Client SDK is generated specifically for your project using the Frontic CLI. Every block, listing, page, and context endpoint your project exposes becomes a typed method on the generated client.

Generate Client SDK

Run frontic generate to produce the typed client for your project — see the CLI reference for the full command.

Looking for the raw HTTP surface — for a non-JS backend, a custom proxy, or curl debugging? See the Fetch API reference. The SDK is a typed wrapper over those endpoints.

Initialization

The generated client supports two initialization patterns.

Direct import

For the simplest case — no proxy, no global config:

import client from "./.frontic/generated-client";

const data = await client.block("ProductCard", "<product-id>");

Factory with configuration

For projects that need a global proxy URL (e.g. browser-side requests routed through your own server to avoid CORS):

import { createClient } from "./.frontic/generated-client";

const client = createClient({
  proxyUrl: "https://www.demo-shop.com/api/frontic",
  // or with relative path (does NOT work on server side):
  proxyUrl: "/api/frontic",
});

const data = await client.block("ProductCard", "<product-id>");

Configuration

`createClient(config?)`

Create a configured client instance.

Parameters

object

Global configuration options.

Show Properties

string

Proxy URL used for all requests (e.g. /api/frontic). The client concatenates this with the original API path. The proxy should forward requests to the URL in the fs-target-url header. Useful for preventing browser CORS issues.

Returns

Client

A configured client instance with all client methods.

Methods

Every method below shares the same config object as a final argument, used to override per-request behaviour. The shared options are listed once here and referenced from each method.

Shared `config` object

Every method takes an optional config object as its final argument. Not every field applies to every method — the table below in each method’s section calls out which ones are honoured.

object

Per-request overrides. Optional.

Show Properties

string

Full URL of the page making the request. Drives domain-based Request Context resolution and is also used for tracking. Sent as fs-request-url.

string

A token that identifies the visitor’s persistent context state (region, locale). 36–50 characters. Takes precedence over contextDomain. Sent as fs-context.

string

The domain whose configured region and locale should resolve the request. A contextKey (if set) takes precedence. Sent as fs-domain.

string

Proxy URL used for this request, overriding any global configuration.

`client.block`

Fetch a Detail Block by its key.

Parameters

string

required

The block name. Example: 'ProductCard'.

string

required

The record key. Example: 'sku-12345'.

object

See shared config object.

Returns

Block<ApiName>

The block payload, fully typed against the project’s API surface.

Example

Client SDK

const data = await client.block("ProductCard", "<product-id>", {
  requestUrl: "https://demo-shop.com/snowboards",
  contextKey: "<context-key>",
});

`client.listing`

Fetch a Search Listing with optional parameters and query options.

Parameters

string

required

The listing name. Example: 'CategoryListing'.

object

Listing parameters. Shape depends on the listing’s parameter definition. Example: { categoryId: '<category-id>' }.

object

Per-request overrides plus listing-specific query options.

Show Properties

object

Query options applied to the listing.

Show query properties

array | object

One or more filter expressions, e.g. { type: 'equals', field: 'color', value: 'Red' }.

array | object

Sort expression(s), e.g. { field: 'publishedAt', order: 'asc' }.

string

Free-text search query.

number

Maximum number of results.

number

Page index for pagination.

string

See shared config object.

string

See shared config object.

string

See shared config object.

Returns

Listing<ApiName>

The listing payload — items, pagination metadata, applied filters, available facets.

Example

Client SDK

const data = await client.listing(
  "CategoryListing",
  { categoryId: "<category-id>" },
  {
    query: {
      filter: { type: "equals", field: "color", value: "Red" },
      sort: { field: "publishedAt", order: "asc" },
    },
    requestUrl: "https://demo-shop.com/sunglasses",
    contextKey: "<context-key>",
  },
);

`client.tree`

Fetch a Menu Tree — a hierarchical collection of records assembled from a Data Storage and rendered through a Detail Block.

Parameters

string

required

The tree’s API name. Example: 'CategoryNavigation'.

object

Tree-specific query options plus the shared config object.

Show Properties

object

Show query properties

string

Optional starting node. When provided, the response returns the node with this key plus its descendants. Example: { key: 'shop' }.

number

Optional level limit. Controls how many levels of $items are included. Example: { depth: 2 }.

Returns

Tree<ApiName>

An items array of root-level nodes, each carrying its subtree on $items. Every node’s shape (beyond $items) is defined by the tree’s connected Detail Block.

Example

Client SDK

// Full tree
const tree = await client.tree("CategoryNavigation");

// Subtree from a specific node, 2 levels deep
const subtree = await client.tree("CategoryNavigation", {
  query: { key: "shop", depth: 2 },
});

`client.page`

Fetch a Page by its slug.

Parameters

string

required

The URL slug of the page (without protocol). Example: demo-shop.com/uk/women/shoes/running.

object

See shared config object.

Returns

Page

The page payload — data, page type, and any alternate urls.

Example

Client SDK

const pageData = await client.page("demo-shop.com/uk/women/shoes", {
  requestUrl: "https://demo-shop.com/uk/women/shoes",
  contextKey: "<context-key>",
});

`client.sitemap`

Fetch a Sitemap. The Nuxt module can serve the sitemap route from your app automatically.

Parameters

string

required

The project domain for which you want the sitemap.

number

The index of a nested sitemap (only if the sitemap was split up).

object

The shared config object.

Returns

string

The XML content of the sitemap.

Example

Client SDK

const sitemap = await client.sitemap("demo-shop.com/uk");

const nestedSitemap = await client.sitemap("demo-shop.com/uk", 1);

`client.context`

Fetch a context by its token.

Parameters

string

required

The contextKey to look up. Example: 'ae0d4981-c363-4d5a-a49e-1f053d49f2f7'.

object

See shared config object.

Returns

Context

The context — region, locale, scope, token.

Example

Client SDK

const context = await client.context("<context-key>");

`client.contextList`

List the available contexts (region + currency + locales) for the project, optionally filtered by an existing context token.

Parameters

string

The contextKey whose project + scope context variations are returned. Optional.

object

See shared config object.

Returns

Context[]

Array of context options (region, currency, supported locales with URLs).

string

The active contextKey, returned in the fs-context response header.

Example

Client SDK

const [contexts, token] = await client.contextList("<context-key>");

`client.contextUpdate`

Update an existing context’s region and locale on the Frontic server. Subsequent requests using the same contextKey reflect the change.

Parameters

object

required

The context fields to update.

Hide Properties

string

required

The region key, e.g. eu.

string

required

The locale key, e.g. de-DE.

string

required

The contextKey to update.

object

See shared config object.

Returns

Context

The updated context.

Example

Client SDK

await client.contextUpdate(
  { region: "eu", locale: "de-DE" },
  "<context-key>",
);

Response

{
  "region": "eu",
  "locale": "de-DE",
  "scope": "public",
  "token": "ae0d4981-c363-4d5a-a49e-1f053d49f2f7"
}

Generate Client SDK

​Initialization

​Direct import

​Factory with configuration

​Configuration

​createClient(config?)

​Parameters

​Returns

​Methods

​Shared config object

​client.block

​Parameters

​Returns

​Example

​client.listing

​Parameters

​Returns

​Example

​client.tree

​Parameters

​Returns

​Example

​client.page

​Parameters

​Returns

​Example

​client.sitemap

​Parameters

​Returns

​Example

​client.context

​Parameters

​Returns

​Example

​client.contextList

​Parameters

​Returns

​Example

​client.contextUpdate

​Parameters

​Returns

​Example

​Response

Initialization

Direct import

Factory with configuration

Configuration

`createClient(config?)`

Parameters

Returns

Methods

Shared `config` object

`client.block`

Parameters

Returns

Example

`client.listing`

Parameters

Returns

Example

`client.tree`

Parameters

Returns

Example

`client.page`

Parameters

Returns

Example

`client.sitemap`

Parameters

Returns

Example

`client.context`

Parameters

Returns

Example

`client.contextList`

Parameters

Returns

Example

`client.contextUpdate`

Parameters

Returns

Example

Response