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

# Installation

> Install dependencies and structure your app for Crave UI components.

Crave UI components are local React components that sit inside your storefront app. They pair with the [Storefront SDK](/docs/getting-started/storefront-sdk.md), Tailwind CSS, and shadcn/ui conventions so you can own the markup, styling, and ordering flows.

Choose the setup that matches your starting point.

> [card] [Public API setup](/docs/getting-started/storefront-sdk.md)
>
> Configure the API origin, merchant slug, and location ID without a browser
> credential.

> [card] [Use the CLI](#use-the-cli)
>
> Inspect one of the current legacy public storefront examples locally.

> [card] [Existing app](#existing-app)
>
> Add the SDK, shared UI dependencies, and component source to an app you
> already own.

> [card] [Project structure](#project-structure)
>
> See where components, API helpers, and shared utilities should live.

## Use the CLI

The released CLI 1.x can clone one of the current legacy public examples and write its public storefront settings. These examples do not define the current production SDK or component contract and require migration and review before deployment.

```bash theme={null}
npx @craveup/cli init
```

Then run the generated app:

```bash theme={null}
cd crave-storefront
pnpm install
pnpm dev
```

For new production work, use the exact-pinned Storefront SDK guide and the component contracts in these docs as the source of truth. Treat the CLI 1.x examples as implementation references only.

## Existing app

For an existing React or Next.js app, install the SDK first:

```bash theme={null}
pnpm add --save-exact @craveup/storefront-sdk@2.0.1
```

If your app does not already use shadcn/ui, initialize it before copying component source:

```bash theme={null}
pnpm dlx shadcn@latest init
```

Install the shared UI utilities used by the component examples:

```bash theme={null}
pnpm add class-variance-authority clsx tailwind-merge lucide-react
```

Then adapt the documented component examples inside your app's `components` directory and keep the SDK transport, ordering state, and presentation boundaries explicit.

## Project structure

Use a structure that keeps UI, data access, and ordering state separate:

```txt theme={null}
src/
  app/
    menu/
    cart/
    checkout/
  components/
    menu/
    cart/
    checkout/
    fulfillment/
    modifiers/
    post-order/
    ui/
  lib/
    storefront-client.ts
    utils.ts
  types/
    storefront.ts
```

## Configure the SDK

Create a shared Storefront SDK client and import it from your data loaders, hooks, or server actions.

Get the published location ID and merchant slug from Crave Business Manager. Configure the public API origin explicitly.

```ts filename="src/lib/storefront-client.ts" theme={null}
import { createStorefrontClient } from "@craveup/storefront-sdk";

export const storefrontClient = createStorefrontClient({
  baseUrl: process.env.NEXT_PUBLIC_CRAVEUP_API_URL!,
  sessionStore,
  getAuthToken,
  getMerchantSlug: () => merchantSlug,
});
```

For customer flows, source `getAuthToken` from the active Clerk session with
the `crave-customer` token template. Clerk owns token persistence and refresh;
do not store the JWT in application storage. `getMerchantSlug` is required for
customer operations so Crave can route the same Clerk diner to the correct
restaurant organization.

Add the required environment variables:

```env filename=".env.local" theme={null}
NEXT_PUBLIC_CRAVEUP_API_URL=https://api.craveup.com
NEXT_PUBLIC_CRAVEUP_LOCATION_ID=loc_abc123
NEXT_PUBLIC_CRAVEUP_MERCHANT_SLUG=demo-cafe
```

## Import components

Crave component docs use local imports so you can customize the implementation:

```tsx theme={null}
import { CartPanel } from "@/components/cart/cart-panel";
import { Item } from "@/components/menu/item";
import { MenuSwitcher } from "@/components/menu/menu-switcher";
```

Keep the component source in your app, then pass SDK data and callbacks from your own routes or state layer.

## Next steps

> [card] [Components Overview](/docs/components/overview.md)
>
> Browse the full component catalog.

> [card] [Storefront SDK](/docs/getting-started/storefront-sdk.md)
>
> Configure the typed API client used by the components.

> [card] [Display Menu](/docs/guides/display-menu.md)
>
> Fetch menu data and render categories, products, and modifiers.

> [card] [Manage Cart](/docs/guides/manage-cart.md)
>
> Wire cart creation, item updates, discounts, and checkout handoff.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.