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

# Theme SDK

> @corvex/theme-sdk — hooks, carrinho, páginas e helpers para temas Corvex.

Pacote npm público: **`@corvex/theme-sdk`**. É a interface que o tema usa para ler a loja e o carrinho.

Versão da API storefront: `2026-08` · Detalhes por recurso: [Dados da vitrine](https://docs-loja.usecorvex.com.br/data/overview.md).

***

## Import

```js theme={"theme":{"light":"github-light","dark":"github-dark"}}
import {
  createStorefront,
  useStorefront,
  usePage,
  useCorvexCart,
  useCaptureLead,
  defineSection,
  defineSectionData,
  formatPrice,
  useTranslation,
  useLocalization,
} from '@corvex/theme-sdk';
```

O **Corvex CLI** marca `@corvex/theme-sdk` como external no bundle — a plataforma injeta o módulo no runtime da loja.

| Import | Status |
| - | - |
| `@corvex/theme-sdk` | **Canônico** |
| `@corvex/sdk` | Alias legado (mesmo módulo) |

Chrome do Editor e hooks de integração: [`@corvex/runtime`](https://docs-loja.usecorvex.com.br/reference/runtime-api) — fronteira documentada separada.

***

## Storefront client

```js theme={"theme":{"light":"github-light","dark":"github-dark"}}
const storefront = createStorefront({ storeId: 'uuid-da-loja' });

const products = await storefront.products.list({
  first: 8,
  sortBy: 'BEST_SELLING',
});

const product = await storefront.products.getByHandle('camiseta');
```

Na vitrine, prefira hooks (`usePage`, `useStorefront`) em sections React.

### API surface

| Namespace | Métodos |
| - | - |
| `storefront.products` | `list`, `get`, `getByHandle` |
| `storefront.categories` e `storefront.collections` | `list`, `get`, `getByHandle`. São duas instâncias da mesma API de categorias |
| `storefront.search` | `query` |
| `storefront.reviews` | `list`, `summary`, `create` |
| `storefront.recommendations` | `list` |
| `storefront.leads` | `capture` |
| `storefront.discountRanges` | `list` |
| `storefront.paymentDiscounts` | `list` |
| `storefront.coupons` | `list`, `validate` |
| `storefront.cart` | `ensure`, `addItem`, `updateItem`, `removeItem`, `checkout`, … |
| `storefront.menus` | `list`, `get` |
| `storefront.blogs` | `list`, `get`, `listArticles`, `getArticle` |
| `storefront.shop` | `get` — inclui `localization` (moeda, idioma, moneyFormat) |
| `storefront.pages` | `get` |

Helpers: `defineSection`, `defineSectionData`, `SECTION_DATA_KEYS`, `usePage`.

***

## Hooks React

| Hook | Uso |
| - | - |
| `useStorefront()` | Cliente da loja atual |
| `usePage('product')` | Contexto de página |
| `useCorvexCart()` | Carrinho na vitrine |
| `useCaptureLead(source)` | Captura de leads |
| `useStorefrontMenus(handles)` | Menus publicados |
| `useTranslation()` | Traduções do tema (`locales/*.json`) → `t(key, vars?)` |
| `useLocalization()` | Moeda/idioma da loja → `formatMoney`, `localization` |

Ver [Locales e internacionalização](https://docs-loja.usecorvex.com.br/themes/locales.md).

***

## Sections

```js theme={"theme":{"light":"github-light","dark":"github-dark"}}
export const schema = defineSection({ name: '...', settings: [...] });

export const data = defineSectionData(async ({ storefront, settings, page }) => ({
  products: await storefront.products.list({ first: settings.limit }),
}));
```

***

## Componentes UI (SDK)

| Componente | Uso |
| - | - |
| `StorefrontNav` | Navegação + mega menu |
| `ColorSchemeScope` | Escopo de `color_scheme` |
| `Link`, `Image`, `ProductCard` | Primitivos de vitrine |

***

## Tipos públicos

O pacote exporta tipos TypeScript para:

* `Product`, `ProductSummary`, `ProductVariant`
* `Collection`, `Category`
* `Review`, `ReviewsSummary`
* `StorefrontCart`, `StorefrontMenu`, `StorefrontBlog`
* `PageContextMap`, `SectionDataKey`

Use apenas campos documentados em [Product Contract](https://docs-loja.usecorvex.com.br/reference/contracts/product.md) e [resources](https://docs-loja.usecorvex.com.br/data/resources/product.md).

***

## Próximos passos

* [Locales e i18n](https://docs-loja.usecorvex.com.br/themes/locales.md)
* [Erros comuns](https://docs-loja.usecorvex.com.br/data/pitfalls.md)
* [Product list section](https://docs-loja.usecorvex.com.br/data/sections/product-list.md)
* [products.list](https://docs-loja.usecorvex.com.br/data/queries/products-list.md)
* [Cookbooks](https://docs-loja.usecorvex.com.br/cookbook/overview.md)


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