Skip to main content
The Client SDK is generated specifically for your project using the Frontstack CLI.
Client SDK Hero

Generate Client SDK

Follow this guide to generate the Client SDK for your project

​
Initialization

The generated client can be used in two ways:

​
Direct client import

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

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

​
Factory function with configuration

For global configuration like proxy URLs: 
import { createClient } from "./.frontstack/generated-client";

const client = createClient({
  proxyUrl: 'https://www.example.com/api/frontstack'
  // or with relative path (does NOT work on server side!)
  proxyUrl: '/api/frontstack'
});

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

​
Configuration

​
createClient(config?)

Create a configured client instance.

​
Parameters

  • config (object, optional): Global configuration options.
    • proxyUrl (string, optional): Proxy URL to use for all requests (e.g., /api/frontstack). The client will concatenate this with the original API path (e.g., /api/frontstack/block). The proxy should forward requests to the target URL specified in the fs-target-url header. This is useful to prevent CORS issues when making requests from a browser.

​
Returns

  • A configured client instance with all client methods.

​
Methods

​
client.block

Fetch a block by its key.

​
Parameters

  • name (string): The name of the block to fetch.
    • Example: 'ProductCard'
  • key (string): The key of the block to fetch.
    • Example: '123'
  • config (object, optional): Additional configuration options.
    • requestUrl (string, optional): A URL that will be used to track the origin of the request.
    • contextKey (string, optional): A token that identifies the user’s context state (locale, region).
    • proxyUrl (string, optional): Proxy URL to use for this request, overriding any global configuration.

​
Returns

  • A promise that resolves to the block response.
/**
 * Fetch a block with a key
 *
 * @param name The name of the block to fetch
 * @example 'VariantCard'
 * @param key The key identifier for the block
 * @example '<variant-id>'
 * @param config Additional configuration options
 */
block: <ApiName extends keyof Blocks>(
  name: ApiName,
  key: string,
  config?: RequestOptions
) => Promise<Responses[ApiName]> => {
  let endpoint: string = `${servers[0].url}${endpoints[name]}`;

  // If payload contains `key` replace '{key}' in the endpoint
  if (key) {
    endpoint = endpoint.replace('{key}', key);
  }

  let headers: Record<string, string> = {};

  if (config== undefined) {
    headers['fs-request-url'] = config.requestUrl;
  }
  if (configKey !== undefined) {
    headers["fs-context"] = config.contextKey;
  }

  return (await invoke(endpoint, 'POST', payload, headers))._data;
}

​
Usage

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

​
client.listing

Fetch a listing with optional parameters and query options.

​
Parameters

  • name (string): The name of the block to fetch.
    • Example: 'CategoryListing'
  • params (object, optional): The parameters to pass to the listing.
    • Example: { categoryId: '<category-id>' }
  • config (object, optional): Additional configuration options.
    • query (object, optional): Query parameters to pass to the listing.
      • filter (array): An array of filter objects to filter results.
      • sort (array): An array of sorting options to sort results.
      • search (string): A text search query.
      • limit (number): Limit the number of results returned.
      • page (number): Paginate results.
    • requestUrl (string, optional): A URL that will be used to track the origin of the request.
    • contextKey (string, optional): A token that identifies the user’s context state (locale, region).
    • proxyUrl (string, optional): Proxy URL to use for this request, overriding any global configuration.

​
Returns

  • A promise that resolves to the listing response.
/**
 * Fetch a listing with optional parameters and query options
 *
 * @param name The name of the listing to fetch
 * @example 'ProductList'
 * @param parameters The parameters to pass to the listing
 * @example { categoryId: '<category-id>' }
 * @param config Additional configuration options
 * @example {
 *  query: {
 *    filter: [{ type: 'equals', field: 'color', value: 'Red' }],
 *    sort: [{
 *      'field': 'publishedAt',
 *      'order': 'asc'
 *    }]
 *  }
 * }
 */
listing: <ApiName extends keyof Listings>(
  name: ApiName,
  parameters: ListingParameters[ApiName],
  config?: {
    /**
     * Query parameters to pass to the listing:
     * - `filter` accepts an array of filter objects to filter results
     * - `sort` accepts a string, a sorting option object, or an array of sorting option objects to sort results
     * - `search` to perform a text search
     * - `limit` to limit the number of results returned
     * - `page` to paginate results
     */
    query?: Query<ListingQueryFilters[ApiName], ListingQuerySorts[ApiName]>
  } & RequestOptions
) => Promise<Responses[ApiName]> => {
  let endpoint: string = `${servers[0].url}${endpoints[blockName]}`;

  // Merge block parameters with query
  let payload = { ...blockParameters, ...config?.query };

  let headers: Record<string, string> = {};

  if (config== undefined) {
    headers['fs-request-url'] = config.requestUrl;
  }
  if (configKey !== undefined) {
    headers["fs-context"] = config.contextKey;
  }

  return (await invoke(endpoint, 'POST', payload, headers))._data;
}

​
Usage

const data = await client.listing(
  "CategoryListing",
  { categoryId: "<category-id>" },
  {
    query: {
      filter: { type: "equals", field: "name", value: "Red Dress" },
    },
    requestUrl: "https://demo-shop.com/sunglasses",
    contextToken: "<context-token>",
  }
);

​
client.page

Fetch a page by its slug.

​
Parameters

  • slug (string): The URL slug of the page (without protocol).
    • Example: demo-shop.com/uk/women/shoes/running
  • config (object, optional): Configuration options.
    • requestUrl (string, optional): A URL that will be used to track the origin of the request.
    • contextKey (string, optional): A token that identifies the user’s context state (locale, region).
    • proxyUrl (string, optional): Proxy URL to use for this request, overriding any global configuration.

​
Returns

  • A promise that resolves to the page data.
/**
 * Fetch a page by its slug
 * @param slug The URL slug of the page (without protocol)
 * @example demo-shop.com/uk/women/shoes/running
 *
 * @returns The page data
 * @example { data: { title: 'Running Shoes' }, type: 'ProductCategory', urls: [] }
 */
page: (
  slug: string,
  config?: RequestOptions
) => Promise<Page> => {
  let endpoint: string = `${servers[0].url}/page/${slug}`;

let headers: Record<string, string> = {};

if (config?.requestUrl !== undefined) {
headers['fs-request-url'] = config.requestUrl;
}
if (config?.contextKey !== undefined) {
headers["fs-context"] = config.contextKey;
}

return (await invoke(endpoint, 'GET', null, headers)).\_data;
}

​
Usage

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

​
client.context

Fetch a context by its token.

​
Parameters

  • token (string): The token of the context.
    • Example: 'ae0d4981-c363-4d5a-a49e-1f053d49f2f7'
  • config (object, optional): Configuration options.
    • proxyUrl (string, optional): Proxy URL to use for this request, overriding any global configuration.

​
Returns

  • A promise that resolves to the context and token.
/**
  * Fetch a context by its token
  * @param token The token of the context
  * @example 'ae0d4981-c363-4d5a-a49e-1f053d49f2f7'
  *
  * @returns The context and token
  */
context: async (
  token: ContextToken
): Promise<Context> => {
  let endpoint: string = `${servers[0].url}/context/token`;

let headers: Record<string, string> = {
'fs-context': token
}

return (await invoke(endpoint, 'GET', null, headers)).\_data
}

​
client.contextList

Fetch a list of contexts, optionally using a token.

​
Parameters

  • token (string, optional): The token of the context.
    • Example: 'ae0d4981-c363-4d5a-a49e-1f053d49f2f7'
  • config (object, optional): Configuration options.
    • proxyUrl (string, optional): Proxy URL to use for this request, overriding any global configuration.

​
Returns

  • A promise that resolves to an array of contexts and a context token.
/**
  * Fetch a list of contexts, optionally using a token
  * @param token The token of the context (optional)
  * @example 'ae0d4981-c363-4d5a-a49e-1f053d49f2f7'
  *
  * @returns An array of contexts and a context token
  */
contextList: async (
  token?: ContextToken
): Promise<[Context[], ContextToken]> => {
  let endpoint: string = `${servers[0].url}/context`;

const requestHeaders: Record<string, string> = {}

if (token) {
requestHeaders["fs-context"] = token;
}

const {
\_data,
headers: responseHeaders
} = await invoke(endpoint, 'GET', null, requestHeaders)

return [_data, responseHeaders.get('fs-context')!]
}

​
client.contextUpdate

Update a context with new region and locale.

​
Parameters

  • context (object): The context details to update.
    • region (string): The region to update.
    • locale (string): The locale to update.
  • token (string): The token of the context.
  • config (object, optional): Configuration options.
    • proxyUrl (string, optional): Proxy URL to use for this request, overriding any global configuration.

​
Returns

  • A promise that resolves to the updated context.
/**
  * Update a context with new region and locale
  * @param context The context details to update
  * @param token The token of the context
  * @example { region: 'US', locale: 'en-US' }
  *
  * @returns The updated context
  */
contextUpdate: async (
  context: {
    region: string
    locale: string
  },
  token: ContextToken
): Promise<Context> => {
  let endpoint: string = `${servers[0].url}/context`;

let headers: Record<string, string> = {
'fs-context': token
}

return (await invoke(endpoint, 'PATCH', context, headers)).\_data
}