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

# Overview

> React hooks and components for building a storefront on the Colossal Storefront GraphQL API.

The `@colossal-sh/storefront-sdk` provides React hooks and components for building storefronts. It wraps the Colossal Storefront GraphQL API.

For a reference implementation, see the [Storefront Starter Template](https://github.com/colossalhq/colossal-storefront-starter-vite).

## Installation

<CodeGroup>
  ```bash npm theme={null}
  npm install @colossal-sh/storefront-sdk
  ```

  ```bash pnpm theme={null}
  pnpm add @colossal-sh/storefront-sdk
  ```

  ```bash yarn theme={null}
  yarn add @colossal-sh/storefront-sdk
  ```
</CodeGroup>

## Setup

Initialize the client and wrap your app in the required providers:

```tsx theme={null}
// main.tsx
import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
import { CartProvider, initStorefrontClient } from "@colossal-sh/storefront-sdk";

initStorefrontClient();

const queryClient = new QueryClient();

function App() {
  return (
    <QueryClientProvider client={queryClient}>
      <CartProvider storeUid="your-store-uid" currency="USD">
        {/* Your storefront components */}
      </CartProvider>
    </QueryClientProvider>
  );
}
```

## Store

Fetch project details by UID or for the current context.

| Name                  | Type   | Purpose                         |
| --------------------- | ------ | ------------------------------- |
| `useStore({ uid })`   | Hook   | Fetch store details by UID      |
| `useCurrentStore()`   | Hook   | Fetch the current store         |
| `fetchStore({ uid })` | Method | Server-side store fetch         |
| `fetchCurrentStore()` | Method | Server-side current store fetch |

```tsx theme={null}
import { useStore, useCurrentStore } from "@colossal-sh/storefront-sdk";

// By UID
const { data } = useStore({ uid: "store-uid" });
const store = data?.storeDetails;

// Current store
const { data } = useCurrentStore();
const store = data?.currentStore;
```

For SSR or data loaders:

```tsx theme={null}
import { fetchStore, fetchCurrentStore } from "@colossal-sh/storefront-sdk";

const storeData = await fetchStore({ uid: "store-uid" });
const currentData = await fetchCurrentStore();
```

<ResponseField name="store" type="Store">
  <Expandable title="properties">
    <ResponseField name="uid" type="string">
      Unique project identifier.
    </ResponseField>

    <ResponseField name="name" type="string">
      Project display name.
    </ResponseField>

    <ResponseField name="slug" type="string">
      URL-safe project identifier.
    </ResponseField>

    <ResponseField name="domain" type="string">
      Custom domain, if configured.
    </ResponseField>

    <ResponseField name="currency" type="string">
      Project currency code (e.g. `USD`).
    </ResponseField>
  </Expandable>
</ResponseField>

## Explore main parts of Colossal SDK

<CardGroup cols={3}>
  <Card title="Products" icon="box" href="/react-sdk/products">
    Fetch and display products with simplified or full data hooks.
  </Card>

  <Card title="Cart" icon="cart-shopping" href="/react-sdk/cart">
    Manage shopping carts with add, update, and remove operations.
  </Card>

  <Card title="Checkout" icon="credit-card" href="/react-sdk/checkout">
    Create checkout sessions and redirect to hosted checkout.
  </Card>
</CardGroup>