> ## Documentation Index
> Fetch the complete documentation index at: https://docs.quickshops.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Use the Quickshops TypeScript SDK in your framework

> Step-by-step examples for integrating the Quickshops TypeScript SDK with Next.js, Astro, Remix, and TanStack Start in server-side contexts.

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.

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

<Tabs>
  <Tab title="Next.js (App Router)">
    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**

    ```ts lib/quickshops.ts theme={null}
    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**

    ```tsx app/page.tsx theme={null}
    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>
      );
    }
    ```

    ```tsx product-list.tsx theme={null}
    "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**

    ```ts app/actions.ts theme={null}
    "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 },
      });
    }
    ```
  </Tab>

  <Tab title="Astro">
    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).

    ```astro src/pages/index.astro theme={null}
    ---
    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.
  </Tab>

  <Tab title="Remix">
    In Remix, call the SDK inside `loader` and `action` functions. These always run on the server and are the right boundary for SDK usage.

    ```ts app/routes/_index.tsx theme={null}
    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.
  </Tab>

  <Tab title="TanStack Start">
    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.

    ```ts app/routes/index.tsx theme={null}
    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 };
    }
    ```
  </Tab>
</Tabs>