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

config

object

Global configuration options.

Show Properties

proxyUrl

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

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.

config

object

Per-request overrides. Optional.

Show Properties

requestUrl

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.

contextKey

string

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

contextDomain

string

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

proxyUrl

string

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

`client.block`

Fetch a Detail Block by its key.

Parameters

name

string

required

The block name. Example: 'ProductCard'.

key

string

required

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

config

object

See shared config object.

Returns

data

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

name

string

required

The listing name. Example: 'CategoryListing'.

parameters

object

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

config

object

Per-request overrides plus listing-specific query options.

Show Properties

query

object

Query options applied to the listing.

Show query properties

filter

array | object

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

sort

array | object

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

string

Free-text search query.

limit

number

Maximum number of results.

page

number

Page index for pagination.

requestUrl

string

See shared config object.

contextKey

string

See shared config object.

proxyUrl

string

See shared config object.

Returns

data

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

name

string

required

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

config

object

Tree-specific query options plus the shared config object.

Show Properties

query

object

Show query properties

key

string

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

depth

number

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

Returns

tree

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

slug

string

required

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

config

object

See shared config object.

Returns

page

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.context`

Fetch a context by its token.

Parameters

token

string

required

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

config

object

See shared config object.

Returns

context

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

token

string

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

config

object

See shared config object.

Returns

contexts

Context[]

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

token

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

context

object

required

The context fields to update.

Hide Properties

region

string

required

The region key, e.g. eu.

locale

string

required

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

token

string

required

The contextKey to update.

config

object

See shared config object.

Returns

context

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"
}

Overview

CLI & SDKs

MCP Server

Data Model

Ingest API

Fetch API

Documentation Index

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.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.context`

Parameters

Returns

Example

`client.contextList`

Parameters

Returns

Example

`client.contextUpdate`

Parameters

Returns

Example

Response