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.

Building with Lovable or v0.dev? Copy the one-prompt from the TypeScript SDK page. For buttons and grids, see React components.

Import useStore / Quickshops from @quickshops/sdk only in server-only modules. Keep API keys server-side. Use @quickshops/sdk/react for client UI.

Next.js (App Router)
Astro
Remix
TanStack Start

Prefer useStore() on the server and @quickshops/sdk/react for UI.1. Create the store

lib/quickshops.ts

import "server-only";
import { useStore } from "@quickshops/sdk";

export const store = useStore();

2. Buy-now Server Action

app/actions.ts

"use server";

import { redirect } from "next/navigation";
import { store } from "@/lib/quickshops";

export async function buyProduct(productId: string) {
  const { url } = await store.buyNow({ productId });
  redirect(url);
}

3. Catalog page with Storefront composition

app/page.tsx

import { Storefront, toStoreProducts } from "@quickshops/sdk/react";
import { store } from "@/lib/quickshops";
import { buyProduct } from "./actions";

export default async function Page() {
  const { store: shop, products } = await store.loadCatalog();
  const list = toStoreProducts(products);

  return (
    <main>
      <h1>{(shop as { name: string }).name}</h1>
      <Storefront.Provider products={list} actions={{ buy: buyProduct }}>
        <Storefront.Grid />
      </Storefront.Provider>
    </main>
  );
}

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