Bibliotecas de terceiros

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

┌─────────────────────────────────────────────────────────────┐
│  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:

{
  "name": "meu-tema",
  "private": true,
  "type": "module",
  "engines": { "node": ">=18" }
}

2. Instalar a lib

Na pasta do tema:

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.

// 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

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

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

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

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.

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`

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. Carrossel com vídeo da biblioteca: leia Carrossel de vídeos (Reels) — 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

Referências

CLI — fluxo build/sync
Estrutura do tema
Cookbook Slider — carrossel sem lib npm
Runtime API — @corvex/runtime no Editor
Pitfalls do Editor — blocks, marquee, hidratação no builder

Introdução

Temas

Seções

Guias

Exemplos

Storefront Components

Schema

CLI

Dados

SDK

Contratos

Marketplace

Bibliotecas de terceiros

Bibliotecas de terceiros

Modelo mental

Passo a passo

1. `package.json` no tema

2. Instalar a lib

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

4. Build

5. Sync na loja

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

CSS de libs npm

Editor vs. preview vs. vitrine

Libs que mexem no DOM (Flickity, Swiper imperativo)

Carrossel no editor

Blocks + carrossel horizontal

Checklist antes de publicar

Limitações atuais

Referências

​Bibliotecas de terceiros

​Modelo mental

​Passo a passo

​1. package.json no tema

​2. Instalar a lib

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

​4. Build

​5. Sync na loja

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

​CSS de libs npm

​Editor vs. preview vs. vitrine

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

​Carrossel no editor

​Blocks + carrossel horizontal

​Checklist antes de publicar

​Limitações atuais

​Referências

Bibliotecas de terceiros

Modelo mental

Passo a passo

1. `package.json` no tema

2. Instalar a lib

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

4. Build

5. Sync na loja

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

CSS de libs npm

Editor vs. preview vs. vitrine

Libs que mexem no DOM (Flickity, Swiper imperativo)

Carrossel no editor

Blocks + carrossel horizontal

Checklist antes de publicar

Limitações atuais

Referências