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

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.

​
Use the client

You can now import the client into your project and start using it.

// src/index.ts

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

const data = await client.block("CategoryDetail", categoryId);

​
Next Steps

→ Explore Blocks