Skip to main content
Frontstack’s API Client (also referred to as “Client SDK” or “SDK”) is a type-safe, auto-generated JavaScript library that allows you to interact with your API. It is generated from your API schema (blocks, listings, pages, etc.) using the Frontstack CLI. You don’t have to use the SDK to use Frontstack, but you will miss out on some really nice features, such as:
  • Types for all API responses and payloads
  • Autocompletion and type checking for queries and parameters
  • Dynamic resolving of API endpoints
  • Authentication and header management
  • Convenience methods for tracking API usage and monitoring performance
  • Token management for releases
1

API Schema

Frontstack generates a schema for your API, based on the blocks and pages that you have defined.
openapi.yml
openapi: 3.1.0
  info:
    title: Fetch API Specification (Nexus Project)
    description: 'Release 12/03/2025 20:48'
    version: c0d3d4-flexing-monkey
# ...
The cool part - this schema is a fully compliant OpenAPI 3.1.0 specification, so you can use it with any OpenAPI tooling - for example import it into Postman or generate server stubs in other languages.
2

Translate into TypeScript definitions

The schema is then transformed into a set of TypeScript interfaces and types that define your API.
.frontstack/generated-types.d.ts
// Extract from the file

export type CategoryDetail {
  id: string
  name: string
  description: string
  products: Product[]
}

export type Responses = {
  CategoryDetail: CategoryDetail
}
3

Generate client module

A client module is generated that provides convenient, typesafe and annotated methods for interacting with the API.
.frontstack/generated-client.js
// Extract from the file
import type { Blocks, RequestOptions, Responses } from './generated-types';

client = {
  block: <ApiName extends keyof Blocks>(
    name: ApiName,
    key: string,
    config?: RequestOptions
  ) => Promise<Responses[ApiName]>
};

export default client;
4

Use the client

You can now use the client library in your frontend project
index.ts
import { client } from './.frontstack/generated-client'

const data = await client.block('CategoryDetail', 'running-shoes')
The final user code in your project will look something like this: 
const result = await client.listing(
  "ProductList",
  {
    categoryId: "123e4567-e89b-12d3-a456-426614174000",
  },
  {
    query: {
      filter: [
        {
          type: "equals",
          field: "attributes.size",
          value: "10",
          // ^? (property) value: string | undefined
        },
      ],
      sort: {
        field: "name",
        order: "desc",
      },
      // ^? (property) sort: 'label' | 'price' | 'createdAt' | 'updatedAt'
    },
  }
);

console.log(result);
//          ^? const result: ProductList

​
Prerequisites

In order to complete this guide, you will need:
  • Node.js installed on your machine
  • An existing Node.js project (or run pnpm init to create one), ideally with TypeScript
  • A Frontstack account
  • The Frontstack CLI installed globally or using npx
  • We recommend that you use pnpm as your package manager

​
Login and connect project

Before we proceed, we need to open our current project directory in the terminal. It is wherever you have your package.json file. A browser window will open, and you will be prompted to login to your Frontstack account. 
# From your project root
frontstack login

> Please continue login in your browser at ...
> [SUCCESS] Login successful
Verify that you are logged in by running the info command: 
frontstack info

> Status: No project selected.
>
> Run frontstack project to select a Frontstack project
Finally, you can connect your project using the project command: 
frontstack project

> ? Pick a project › - Use arrow-keys. Return to submit.
>   ❯   Nexus Project
>   ❯   Quantum Project
>   ❯   Frontstack Project
>
> Project Nexus Project selected
Done - you will notice that the CLI has created a .frontstack-local directory that contains your project configuration.
We recommend that you add this directory to your .gitignore file, because it contains sensitive information, such as your Frontstack API token.
.gitignore
# Frontstack local configuration
.frontstack-local/

​
Generate client

Now that you have connected your project, you can generate the client. 
frontstack generate

> Javascript client generated for ...
This command will generate four files into a .frontstack directory in your project root:
  • generated-client.js - The client that you can import into your project
  • fetch-api.d.t - Type definitions for the client
  • generated-types.d.ts - Type definitions for the schema
  • query-types.ts - Type definitions for queries
These files should be committed to your repository, as they represent the API contract between your project and the Frontstack API. In other words - any changes to these files indicate that the API has changed.
In case you get an error, you can try to delete the .frontstack-local directory and run the login and project commands again.If you are using the frontstack command, make sure that it is installed globally and updated to the latest version (run pnpm add -g @frontstackdev/cli).Check that you are using the latest version using frontstack --version or npx @frontstackdev/cli --version.When using npx, you can always use the @latest tag to ensure that you are using the latest version of the CLI.

​
Use the client

You can now import the client into your project and start using it. There are two ways to use the generated client:

​
Option 1: Direct client import (simple projects)

For simple use cases without global configuration: 
// src/index.ts

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

const data = await client.block("CategoryDetail", categoryId);
For projects that need global configuration (e.g., proxy URL for CORS prevention): 
// src/index.ts

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("CategoryDetail", categoryId);

​
Domain

Indicate the domain you’re using by passing the config object to all client calls and setting requestUrl to your currently requested URL: 
const data = await client.block("CategoryDetail", categoryId, { requestUrl: 'https://my.app.tld/some/page' });
With the given URL, Frontstack will match your call to the correct domain (and thus region and locale configuration) and will return correct links for any Page Route fields. If you’re using a development domain alias, this configuration is essential for correctly accessing any page URLs.

​
Proxy URL (CORS prevention)

If you’re making requests from a browser and experiencing CORS issues, you can configure a proxy URL either globally or per-request. The client will concatenate the proxy URL with the original API path. For example, if the original request would go to https://api.frontstack.com/block and you set proxyUrl: '/api', the request will be sent to /api/block on your current domain. Global configuration (recommended): 
import { createClient } from "./.frontstack/generated-client";

const client = createClient({
  proxyUrl: 'https://www.example.com/api/frontstack'
});

// Request will be sent to: https://www.example.com/api/frontstack/block
const data = await client.block("CategoryDetail", categoryId);
Per-request override: 
import client from "./.frontstack/generated-client";

// Request will be sent to: /api/frontstack/block
const data = await client.block("CategoryDetail", categoryId, {
  proxyUrl: '/api/frontstack'
});
Your proxy endpoint must forward the entire request (including headers and body) to the target URL specified in the fs-target-url header.

​
Next Steps

→ Explore Blocks