Use the Quickshops TypeScript SDK in your framework

The Quickshops TypeScript SDK works in any framework that gives you a server-side execution context — loaders, server components, server actions, or API routes. The pattern is the same everywhere: instantiate the client once with your API key in a server-only module, then call methods in your server boundary and pass only the response data to your UI.

Import Quickshops from @quickshops/sdk only in server-only modules. Use @quickshops/starter-templates for storefront types and theme helpers in client code.

Next.js (App Router)
Astro
Remix
TanStack Start

Next.js App Router gives you three natural places to call the SDK: Server Components for read operations, Server Actions for mutations, and Route Handlers for custom API endpoints.1. Create the shared client

lib/quickshops.ts

import "server-only";

import { Quickshops } from "@quickshops/sdk";

export const qs = new Quickshops({
  serverURL: process.env.HEADLESS_API_URL ?? "https://api.quickshops.app",
  bearerAuth: process.env.HEADLESS_API_KEY!,
});

2. Fetch data in a Server Component

app/page.tsx

import { qs } from "@/lib/quickshops";
import { ProductList } from "./product-list";

export default async function Page() {
  const [storeResponse, productsResponse] = await Promise.all([
    qs.store.storeGet(),
    qs.products.productsGetAll(),
  ]);
  const store = storeResponse.data;
  const products = productsResponse.data;

  return (
    <main>
      <h1>{store.name}</h1>
      <ProductList products={products} />
    </main>
  );
}

product-list.tsx

"use client";

type Product = { id: string; name: string };

export function ProductList({ products }: { products: Product[] }) {
  return (
    <ul>
      {products.map((p) => (
        <li key={p.id}>{p.name}</li>
      ))}
    </ul>
  );
}

3. Mutate cart state in a Server Action

app/actions.ts

"use server";

import { qs } from "@/lib/quickshops";

export async function addToCartAction(
  cartId: string,
  productId: string,
  quantity: number,
) {
  return qs.cart.cartAddLine({
    cartId,
    body: { productId, quantity },
  });
}

In Astro, call the SDK inside frontmatter in .astro files or inside server-rendered API endpoints. The frontmatter block runs on the server at request time (or build time for static pages).

src/pages/index.astro

---
import { Quickshops } from "@quickshops/sdk";

const qs = new Quickshops({
  serverURL: import.meta.env.HEADLESS_API_URL ?? "https://api.quickshops.app",
  bearerAuth: import.meta.env.HEADLESS_API_KEY!,
});
const { data: products } = await qs.products.productsGetAll();
---

Use import.meta.env instead of process.env to access Astro environment variables. Do not construct Quickshops in client-side scripts.

In Remix, call the SDK inside loader and action functions. These always run on the server and are the right boundary for SDK usage.

app/routes/_index.tsx

import { Quickshops } from "@quickshops/sdk";

const qs = new Quickshops({
  serverURL: process.env.HEADLESS_API_URL ?? "https://api.quickshops.app",
  bearerAuth: process.env.HEADLESS_API_KEY!,
});

export async function loader() {
  const { data: products } = await qs.products.productsGetAll();
  return Response.json(products);
}

Instantiate the client at module scope so it is reused across requests in the same server process.

In TanStack Start, call the SDK inside server loaders or server functions — never at the top level of a shared module that client code imports.

app/routes/index.tsx

import { Quickshops } from "@quickshops/sdk";

export async function loader() {
  const qs = new Quickshops({
  serverURL: process.env.HEADLESS_API_URL ?? "https://api.quickshops.app",
  bearerAuth: process.env.HEADLESS_API_KEY!,
});
  const { data: store } = await qs.store.storeGet();
  return { store };
}

Get Started

Your Store

Products & Sales

Integrations

Developers

Use the Quickshops TypeScript SDK in your framework