> ## 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.

# Bibliotecas de terceiros

> Como instalar npm packages (Flickity, Embla, Swiper, etc.) em um tema Corvex e fazer funcionar no Editor, preview e vitrine.

Este guia explica como um dev de tema instala uma lib npm (carrossel, animação, utilitários) e garante que o **mesmo código** rode no **Editor**, no **`/preview`** e na **vitrine publicada**.

A Corvex **não precisa conhecer** a biblioteca — ela compila e serve o **bundle do tema**. A lógica da lib fica no **seu repositório**, não no core da plataforma.

***

## Modelo mental

```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
┌─────────────────────────────────────────────────────────────┐
│  SEU TEMA (Git)                                              │
│  package.json  →  npm install flickity / embla / …          │
│  sections/ + lib/  →  import da lib no JSX do tema           │
│  corvex build  →  .corvex/theme.js (lib INLINE no bundle)   │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼ corvex sync
┌─────────────────────────────────────────────────────────────┐
│  CORVEX (API)                                               │
│  bundleSource + bundleCss  (node_modules NÃO sobe)          │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼ themeBundleImporter
┌─────────────────────────────────────────────────────────────┐
│  RUNTIME (browser)                                          │
│  React + @corvex/runtime  ← host injeta             │
│  theme.js  ← seu código + libs empacotadas                  │
│  → Builder iframe · /preview · vitrine                      │
└─────────────────────────────────────────────────────────────┘
```

***

## Passo a passo

### 1. `package.json` no tema

O `corvex init` já cria um `package.json` no scaffold. Se o projeto for antigo, adicione manualmente na raiz do tema:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "name": "meu-tema",
  "private": true,
  "type": "module",
  "engines": { "node": ">=18" }
}
```

### 2. Instalar a lib

Na pasta do tema:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
npm install embla-carousel-react
# ou: npm install flickity flickity-fade
# ou: npm install swiper
```

### 3. Usar na section (código do tema)

Prefira encapsular em `lib/` ou hook local — não espalhe lógica imperativa no JSX da section.

```jsx theme={"theme":{"light":"github-light","dark":"github-dark"}}
// sections/slider/section.jsx
import { SectionChrome } from '@corvex/runtime';
import { useThemeSlider } from '../../lib/useThemeSlider.js';

export default function SliderSection({ children, autoplay = true }) {
  const { trackRef, activeIndex } = useThemeSlider({
    active: true,
    autoplay,
  });

  return (
    <SectionChrome label="Slider">
      <div ref={trackRef} className="my-slider">
        {children}
      </div>
    </SectionChrome>
  );
}
```

### 4. Build

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
corvex build .
```

O CLI (`corvex build`) usa **esbuild** e gera:

| Artefato | Conteúdo |
| - | - |
| `.corvex/theme.js` | Sections, blocks, **e código das libs npm** (bundled) |
| `.corvex/theme.css` | CSS de `sections/*/styles.css` e `assets/*.css` |
| `.corvex/locales.json` | Traduções do tema |

### 5. Sync na loja

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
corvex sync --open
```

Isso faz build, envia o bundle para a API, instala na loja vinculada e abre o Editor.

**Importante:** `node_modules` **nunca** é enviado. Só o que foi compilado em `.corvex/theme.js`.

***

## O que entra no bundle vs. o que o host fornece

| Empacotado no `theme.js` | Fornecido pelo host (external) |
| - | - |
| `flickity`, `embla`, `gsap`, lodash, etc. | `react`, `react-dom` |
| Código em `sections/`, `blocks/`, `lib/` | `@corvex/runtime`, `@corvex/theme-sdk` (re-exports) |

O host carrega seu bundle e injeta dependências externas — uma única instância de React e runtime Corvex para Editor e vitrine. Não importe o pacote do editor. Use só `@corvex/runtime` e `@corvex/theme-sdk`.

***

## CSS de libs npm

O esbuild trata `import 'lib/dist/style.css'` como **texto** — esse CSS **não** entra automaticamente em `.corvex/theme.css`.

| Abordagem | Quando usar |
| - | - |
| Copiar regras necessárias para `sections/{id}/styles.css` | Poucas regras, controle total |
| Colocar arquivo em `assets/` | CSS compartilhado entre sections |
| Injetar `<link>` no hook (CDN ou path) | Libs imperativas (ex.: Flickity) no iframe do Editor |
| Import dinâmico + string no build | Avançado — raro |

Para carrossel **sem lib imperativa**, prefira o [cookbook Slider](https://docs-loja.usecorvex.com.br/cookbook/slider.md) (React + CSS) — zero dependência npm.

***

## Editor vs. preview vs. vitrine

| Superfície | Bundle usado | Observação |
| - | - | - |
| **Editor (iframe)** | Draft da loja (`preferDraftBundle`) | Após `corvex sync` ou build no Editor |
| **`/preview`** | Versão do catálogo na URL (`version=…`) | Rode `corvex sync` para alinhar com o draft |
| **Vitrine publicada** | Versão da revisão publicada | O lojista publica no editor |

**Regra:** depois de `corvex build`, rode **`corvex sync`** para Builder e `/preview` mostrarem o mesmo artifact.

***

## Libs que mexem no DOM (Flickity, Swiper imperativo)

A plataforma reparenta blocks ao mover/deletar no editor. Libs que montam viewport/slider próprio podem quebrar no builder.

**Contrato do tema:** prefira carrossel em React + CSS. Lib que monta o slider no DOM não tem evento público de teardown.

1. Implemente mount/unmount no **tema** (`lib/useSlideshowFlickity.js` ou similar) e destrua a instância no cleanup do `useEffect`.
2. No **iframe do Editor**, sincronize estilos antes de medir altura (viewport 0 quebra mount):

```jsx theme={"theme":{"light":"github-light","dark":"github-dark"}}
import {
  isEditorPreviewDocument,
  syncEditorPreviewStyles,
} from '@corvex/runtime';

if (isEditorPreviewDocument(mountDoc)) {
  await syncEditorPreviewStyles(mountDoc);
  await waitForStylesheets(mountDoc); // implementação no tema
}
```

A plataforma não monta Flickity nem verifica a saúde do carrossel. Isso fica no tema.

***

## Carrossel no editor

`useBuilderBlockEditLayout()` existe e **sempre retorna `false`**. Não desligue o carrossel nem troque a árvore com esse hook. O inspecionar não muda o layout. Detalhe: [Runtime API](https://docs-loja.usecorvex.com.br/reference/runtime-api.md).

### Blocks + carrossel horizontal

**Erro comum:** tratar `children` como lista de slides. No editor, `children` é quase sempre **um** `BlockCanvasRoot` com todos os blocks dentro.

| ❌ Evite | ✅ Faça |
| - | - |
| `Children.toArray(children).map(wrapSlide)` | `{children}` direto no `.my-carousel__track` / viewport Embla |
| `Children.count(children)` para `slideCount` | `useSectionBlockCount()` |
| Classe `__slide` num wrapper em volta de `children` | Classe `__slide` no **block** (`.cx-block`) ou só em slides estáticos de `blocks`/`block_order` |

```jsx theme={"theme":{"light":"github-light","dark":"github-dark"}}
import { useSectionBlockCount } from '@corvex/runtime';

const blockCount = useSectionBlockCount();
const slideCount = hasChildren ? Math.max(blockCount, 1) : items.length;

// WYSIWYG — children = BlockCanvasRoot (display:contents no runtime)
<div className="my-carousel__viewport" ref={emblaRef}>
  <div className="my-carousel__track">{children}</div>
</div>
```

CSS: flex no track e largura em `.my-carousel__track > .cx-block`. Armadilhas: [Erros do editor](https://docs-loja.usecorvex.com.br/data/pitfalls.md).

**Carrossel com vídeo da biblioteca:** leia [Carrossel de vídeos (Reels)](https://docs-loja.usecorvex.com.br/guides/video-carousel.md) — HLS, marquee e loop de requisições são armadilhas comuns na vitrine.

***

## Checklist antes de publicar

* [ ] `npm install` na raiz do tema (não na pasta da section)
* [ ] `corvex validate .` passa
* [ ] `corvex build .` passa sem erro de resolução de módulo
* [ ] CSS da lib coberto (`styles.css`, `assets/` ou injeção no hook)
* [ ] Testado no **Editor** (iframe) e em **`/preview`**
* [ ] Lib imperativa: `destroy` no cleanup do `useEffect`
* [ ] `corvex sync` após build para alinhar draft e catálogo
* [ ] `.corvex/` e `node_modules/` no `.gitignore`

***

## Limitações atuais

| Limitação | Mitigação |
| - | - |
| `node_modules` não sobe para a API | Sempre `corvex build` local antes do sync |
| Bundle size — tudo inline | Escolha libs leves; tree-shake no `lib/` |
| Draft vs. versão URL no `/preview` | `corvex sync` após mudanças |
| CSS de `node_modules` não vai para `theme.css` | Copiar para `styles.css` / `assets/` |
| Preview local com hot reload | `corvex dev` / `npm run dev` — ver [CLI](https://docs-loja.usecorvex.com.br/cli/commands.md#corvex-dev) |

***

## Referências

* [CLI — fluxo build/sync](https://docs-loja.usecorvex.com.br/cli/overview.md)
* [Arquitetura do tema](https://docs-loja.usecorvex.com.br/themes/structure.md)
* [Cookbook Slider](https://docs-loja.usecorvex.com.br/cookbook/slider.md) — carrossel sem lib npm
* [Runtime API](https://docs-loja.usecorvex.com.br/reference/runtime-api.md) — `@corvex/runtime` no Editor
* [Pitfalls do Editor](https://docs-loja.usecorvex.com.br/data/pitfalls.md) — blocks, marquee, hidratação no builder


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