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

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

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):

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
• Arquitetura do tema
• Cookbook Slider — carrossel sem lib npm
• Runtime API — @corvex/runtime no Editor
• Pitfalls do Editor — blocks, marquee, hidratação no builder