excalidraw-embedding-best-practices

name	excalidraw-embedding-best-practices
description	Aplica práticas obrigatórias e prontas para produção ao incorporar o Excalidraw em aplicações React, Next.js e navegador, cobrindo instalação, SSR, temas, customização de UI, serialização, exportação, segurança e performance. Use ao integrar o Excalidraw, customizar sua UI, persistir cenas ou integrar bibliotecas e colaboração.

Excalidraw Embedding Best Practices

Aplique esta skill sempre que integrar, incorporar, customizar ou operar o componente React @excalidraw/excalidraw em software de produção.

Condições de Uso

Use esta skill quando:

• Adicionar o Excalidraw a um projeto React, Next.js, Preact ou navegador.
• Renderizar o componente <Excalidraw> dentro de outra aplicação.
• Persistir, carregar, importar ou exportar cenas ou bibliotecas do Excalidraw.
• Customizar a UI do Excalidraw via componentes filhos, render props ou variáveis CSS.
• Implementar temas, modos view/zen/grid ou gatilhos de colaboração.
• Lidar com conteúdo embedado, arquivos ou links externos dentro do Excalidraw.

Checklist Obrigatório de Pré-voo

Antes de escrever qualquer código de integração com o Excalidraw, leia as seguintes referências nesta ordem:

1. references/installation-setup.md — instalação do pacote, importação de CSS, restrições de SSR e dimensões do container.
2. references/component-api.md — props principais, excalidrawAPI, handlers de eventos e controle de estado.
3. references/security-performance.md — allowlists de embeds, validação de arquivos, CSP, debounce e gerenciamento de memória.
4. references/serialization-persistence.md — serialização de cena, restauração, armazenamento e versionamento.
5. references/export-utilities.md — exportação para PNG, SVG, canvas, clipboard e cenas embedadas.
6. references/ui-customization.md — MainMenu, Sidebar, Footer, WelcomeScreen, LiveCollaborationTrigger e temas CSS.
7. references/examples.md — exemplos completos e prontos para copiar.
8. references/checklist.md — checklist final de verificação antes do commit.

Regras Universais (Zero Exceções)

1. Instalação e Importação

• Instale React, ReactDOM e o pacote juntos: npm install react react-dom @excalidraw/excalidraw.
• Importe o CSS exatamente uma vez, no nível da aplicação ou do wrapper: import "@excalidraw/excalidraw/index.css";.
• Não importe o CSS dentro de cada componente que renderiza <Excalidraw>.
• Faça self-host das fontes quando estiver atrás de firewall, em ambiente offline ou quando o acesso a CDN for proibido. Defina window.EXCALIDRAW_ASSET_PATH para o caminho servido antes de renderizar.

2. Restrições de Renderização

• Renderize <Excalidraw> apenas dentro de um container com width e height diferentes de zero.
• Desative o server-side rendering (SSR). Em Next.js use next/dynamic com ssr: false. No App Router, adicione a diretiva "use client" e importe o wrapper dinamicamente.
• Em Preact, defina process.env.IS_PREACT como "true" na configuração do build.
• Não renderize mais de uma instância interativa de <Excalidraw> na mesma página, a menos que cada uma tenha tratamento isolado de teclado. Mantenha handleKeyboardGlobally={false} (padrão), a menos que uma única instância focada deva capturar teclas globalmente.

3. Estado e Acesso à API

• Obtenha o excalidrawAPI via prop de callback excalidrawAPI e armazene em estado ou ref.
• Use excalidrawAPI.updateScene() para modificar a cena programaticamente.
• Passe captureUpdate: CaptureUpdateAction.IMMEDIATELY para atualizações locais oriundas do usuário.
• Passe captureUpdate: CaptureUpdateAction.EVENTUALLY para atualizações assíncronas em múltiplos passos.
• Passe captureUpdate: CaptureUpdateAction.NEVER para atualizações remotas de colaboração e hidratação inicial da cena.
• Use restore() ou restoreElements()/restoreAppState() antes de alimentar dados externos em initialData ou updateScene.

4. Regras de Persistência

• Persista apenas a saída de serializeAsJSON() no backend, local storage ou arquivos.
• Nunca persista o appState cru ou arrays completos de elementos sem serialização.
• Valide e restaure dados carregados antes de chamar updateScene().
• Use getSceneVersion() ou os campos version dos elementos para detectar atualizações obsoletas antes de sobrescrever o estado local.
• Persista arquivos binários separadamente e re-injete-os via excalidrawAPI.addFiles() ou pelo campo files ao restaurar.

5. Regras de Segurança

• Sempre defina validateEmbeddable como uma allowlist explícita de hostnames, lista de RegExp ou função validadora. Não use validateEmbeddable={true} em produção.
• Use generateIdForFile apenas quando IDs determinísticos de arquivo forem necessários; caso contrário, confie no digest SHA-1 padrão.
• Sanitize todos os valores de link nos elementos antes de renderizar, especialmente quando onLinkOpen for customizado.
• Prefira event.preventDefault() em onLinkOpen para navegação interna e abra links externos com rel="noopener noreferrer".
• Trate arquivos .excalidraw e .excalidrawlib importados como entrada não confiável. Valide via restore() e nunca execute código proveniente de customData.

6. Regras de Exportação

• Use exportToBlob() ou exportToSvg() para exportações de imagem voltadas ao usuário.
• Defina exportEmbedScene: true apenas quando a imagem exportada precisar ser reimportada como cena.
• Mantenha exportPadding explícito; não confie nos padrões em código de produção.
• Para exportações para clipboard, prefira exportToClipboard() com type, mimeType e quality explícitos.

7. Regras de Customização de UI

• Use os componentes filhos oficiais (MainMenu, Sidebar, Footer, WelcomeScreen, LiveCollaborationTrigger) em vez de render props obsoletas.
• Ao renderizar um MainMenu customizado, inclua <MainMenu.DefaultItems> ou substitua explicitamente cada item padrão. Não renderize um menu vazio.
• Forneça docked e onDock juntos para tornar um Sidebar dockável; caso contrário, ele permanece undocked e fecha ao clicar fora.
• Renderize filhos de Footer apenas no desktop. Para mobile, renderize ações do footer dentro de MainMenu usando useEditorInterface().
• Use variáveis CSS nos seletores .excalidraw e .excalidraw.theme--dark para temas; garanta que os seletores tenham especificidade maior que os padrões.

8. Regras de Performance e Robustez

• Faça debounce nos callbacks de persistência em onChange. Não escreva no storage a cada mutação de elemento.
• Throttle handlers de pointer, scroll e paste quando executarem trabalho pesado.
• Evite chamar updateScene() dentro de onChange; isso cria loops infinitos.
• Chame excalidrawAPI.refresh() após qualquer reposicionamento do container que não seja scroll ou resize (por exemplo, colapso de sidebar, transições de layout).
• Remova as inscrições de eventos retornadas por excalidrawAPI.onChange(), excalidrawAPI.onPointerDown() e excalidrawAPI.onPointerUp() no unmount.
• Limpe object URLs e caches grandes de arquivos binários quando os componentes forem desmontados.

9. Regras de Colaboração

• Defina isCollaborating={true} apenas enquanto uma sessão ao vivo estiver ativa.
• Atualize collaborators via updateScene({ collaborators }) a partir de uma fonte confiável do servidor; nunca aceite posições de colaboradores de clientes não confiáveis sem validação.
• Use LiveCollaborationTrigger apenas quando um backend de colaboração estiver implementado e seguro.

10. Internacionalização e Acessibilidade

• Defina langCode para uma localidade suportada quando a aplicação host for localizada.
• Importe defaultLang e languages do pacote para validar códigos de localidade.
• Use useI18n() apenas dentro de filhos de <Excalidraw>.
• Garanta que o container do Excalidraw tenha um label acessível e gerenciamento de foco quando autoFocus estiver habilitado.

Procedure

Quando solicitado a integrar ou modificar o Excalidraw, execute os seguintes passos em ordem:

1. Determine o framework (React, Next.js Pages, Next.js App Router, Preact ou apenas navegador).
2. Leia references/installation-setup.md e aplique o padrão de instalação para aquele framework.
3. Leia references/component-api.md e selecione as props e métodos de API necessários para a tarefa.
4. Leia references/security-performance.md e aplique os controles de segurança obrigatórios.
5. Leia references/serialization-persistence.md e implemente a persistência usando serializeAsJSON() e restore().
6. Leia references/export-utilities.md se a tarefa envolver exportação de imagem ou clipboard.
7. Leia references/ui-customization.md se a tarefa envolver alterações de UI.
8. Leia references/examples.md e use o exemplo correspondente como template inicial.
9. Leia references/checklist.md e verifique todos os itens antes de finalizar.
10. Execute scripts/validate-excalidraw-embedding.py nos arquivos modificados e corrija todas as violações reportadas.

Tratamento de Erros

• Se <Excalidraw> não renderizar, verifique se o container pai tem width e height explícitos e se o CSS foi importado.
• Se o Next.js lançar erro de window/document, confirme que o componente é importado dinamicamente com ssr: false e, no App Router, marcado com "use client".
• Se onChange disparar atualizações infinitas, remova qualquer chamada a updateScene() de dentro dele.
• Se as exportações estiverem em branco ou cortadas, passe appState explicitamente e defina exportPadding.
• Se iframes embedados carregarem sites inesperados, restrinja validateEmbeddable para uma allowlist de hostnames.
• Se arquivos falharem ao carregar após restauração, garanta que os arquivos binários sejam readicionados via addFiles() e que os IDs de arquivo correspondam.

Padrões Proibidos

Nunca commitar código que:

• Importe <Excalidraw> diretamente em uma página server-rendered sem ssr: false.
• Defina validateEmbeddable={true} em produção.
• Persista arrays crus de elementos em vez da saída de serializeAsJSON().
• Chame updateScene() dentro de onChange.
• Use render props obsoletas como renderFooter em vez de Footer.
• Exponha métodos de excalidrawAPI a entrada não confiável do usuário sem validação.