Fundamentos do postMessage - Comunicação segura entre origens entre janelas e iframes

Q: Por que você deve sempre verificar event.origin em todo manipulador de mensagens?

Sem uma verificação de origem, qualquer página que possa incorporar sua página (ou que sua página incorpore) pode enviar mensagens arbitrárias para seu manipulador. Esta é a principal vulnerabilidade de segurança do postMessage. Use um Set de origens conhecidas e válidas para validação rápida e correspondência exata.

Q: Armadilha: O que acontece se você enviar um postMessage para um iframe antes que ele tenha carregado?

A mensagem é descartada silenciosamente porque contentWindow não está pronto. Use o callback onLoad do iframe ou espere por uma mensagem READY do iframe antes de enviar.

Q: postMessage é síncrono ou assíncrono?

É sempre assíncrono. A mensagem passa pelo loop de eventos. postMessage não retorna um valor. Se você precisar de uma resposta, deve construir um protocolo de solicitação/resposta com IDs de correlação.

Q: Qual é a diferença entre clone estruturado e serialização JSON para postMessage?

O clone estruturado preserva Date, Map, Set, ArrayBuffer, Blob, referências circulares e mais. JSON perde esses tipos (por exemplo, Date se torna uma string, Map se torna {}). Você não precisa usar JSON.stringify antes de enviar ou JSON.parse ao receber.

Receita

// Pai envia uma mensagem para um iframe
const iframeRef = useRef<HTMLIFrameElement>(null);
 
function sendToIframe(data: unknown) {
  iframeRef.current?.contentWindow?.postMessage(
    data,
    "https://widget.example.com" // SEMPRE especifique a origem de destino
  );
}
 
// Iframe (ou qualquer janela) escuta mensagens
useEffect(() => {
  function handleMessage(event: MessageEvent) {
    // CRÍTICO: sempre valide a origem
    if (event.origin !== "https://parent.example.com") return;
    console.log("Recebido:", event.data);
  }
  window.addEventListener("message", handleMessage);
  return () => window.removeEventListener("message", handleMessage);
}, []);

Quando usar isso: Quando você precisa de comunicação entre uma página pai e um iframe incorporado, entre janelas abertas com window.open, ou entre quaisquer dois contextos de navegação que não podem compartilhar o escopo JavaScript diretamente. Casos de uso comuns incluem micro-frontends, widgets de terceiros incorporados, formulários de pagamento, popups OAuth e fluxos de autenticação entre origens.

Exemplo de Trabalho

Uma página pai envia um objeto de tema para um iframe incorporado. O iframe aplica o tema e envia de volta um reconhecimento.

App Pai

import { useEffect, useRef, useState } from "react";
 
// -- Protocolo de mensagem tipado usando uniões discriminadas --
 
type ParentMessage =
  | { type: "THEME_UPDATE"; payload: Theme }
  | { type: "PING" };
 
type IframeMessage =
  | { type: "THEME_ACK"; payload: { appliedAt: number } }
  | { type: "PONG" };
 
interface Theme {
  mode: "light" | "dark";
  primaryColor: string;
  fontSize: number;
}
 
const IFRAME_ORIGIN = "https://widget.example.com";
 
function ParentApp() {
  const iframeRef = useRef<HTMLIFrameElement>(null);
  const [acked, setAcked] = useState(false);
 
  // Escuta respostas do iframe
  useEffect(() => {
    function handleMessage(event: MessageEvent<IframeMessage>) {
      if (event.origin !== IFRAME_ORIGIN) return;
 
      switch (event.data.type) {
        case "THEME_ACK":
          console.log("Tema aplicado em:", event.data.payload.appliedAt);
          setAcked(true);
          break;
        case "PONG":
          console.log("Iframe está ativo");
          break;
      }
    }
 
    window.addEventListener("message", handleMessage);
    return () => window.removeEventListener("message", handleMessage);
  }, []);
 
  function sendTheme(mode: "light" | "dark") {
    const message: ParentMessage = {
      type: "THEME_UPDATE",
      payload: { mode, primaryColor: "#3b82f6", fontSize: 16 },
    };
    iframeRef.current?.contentWindow?.postMessage(message, IFRAME_ORIGIN);
    setAcked(false);
  }
 
  return (
    <div>
      <h1>App Pai</h1>
      <button onClick={() => sendTheme("light")}>Tema Claro</button>
      <button onClick={() => sendTheme("dark")}>Tema Escuro</button>
      {acked && <p>Tema reconhecido pelo widget</p>}
      <iframe
        ref={iframeRef}
        src={`${IFRAME_ORIGIN}/widget`}
        title="Widget Incorporado"
        style={{ width: 600, height: 400, border: "1px solid #ccc" }}
      />
    </div>
  );
}

import { useEffect, useState } from "react";
 
interface Theme {
  mode: "light" | "dark";
  primaryColor: string;
  fontSize: number;
}
 
type ParentMessage =
  | { type: "THEME_UPDATE"; payload: Theme }
  | { type: "PING" };
 
type IframeMessage =
  | { type: "THEME_ACK"; payload: { appliedAt: number } }
  | { type: "PONG" };
 
const PARENT_ORIGIN = "https://parent.example.com";
 
function Widget() {
  const [theme, setTheme] = useState<Theme>({
    mode: "light",
    primaryColor: "#3b82f6",
    fontSize: 16,
  });
 
  useEffect(() => {
    function handleMessage(event: MessageEvent<ParentMessage>) {
      // CRÍTICO: valide a origem antes de processar
      if (event.origin !== PARENT_ORIGIN) return;
 
      switch (event.data.type) {
        case "THEME_UPDATE":
          setTheme(event.data.payload);
          // Envia reconhecimento de volta para o pai
          const ack: IframeMessage = {
            type: "THEME_ACK",
            payload: { appliedAt: Date.now() },
          };
          // event.source é a janela que enviou a mensagem
          (event.source as Window).postMessage(ack, event.origin);
          break;
 
        case "PING":
          (event.source as Window).postMessage(
            { type: "PONG" } satisfies IframeMessage,
            event.origin
          );
          break;
      }
    }
 
    window.addEventListener("message", handleMessage);
    return () => window.removeEventListener("message", handleMessage);
  }, []);
 
  return (
    <div
      style={{
        backgroundColor: theme.mode === "dark" ? "#1e293b" : "#ffffff",
        color: theme.mode === "dark" ? "#f1f5f9" : "#0f172a",
        fontSize: theme.fontSize,
        padding: 24,
        minHeight: "100vh",
      }}
    >
      <h2 style={{ color: theme.primaryColor }}>Conteúdo do Widget</h2>
      <p>Tema atual: {theme.mode}</p>
    </div>
  );
}

Mergulho Profundo

O que é postMessage?

window.postMessage() é a API padrão do navegador para comunicação segura entre origens entre contextos de navegação (janelas, iframes, popups, workers).
Sem postMessage, a política de mesma origem bloqueia o JavaScript em uma origem de acessar o DOM ou variáveis de outra origem. postMessage fornece um canal controlado para enviar dados serializáveis através dessa fronteira.
A assinatura do método é targetWindow.postMessage(message, targetOrigin, transfer?).

Anatomia do MessageEvent

Todo manipulador de mensagens recebe um MessageEvent com estas propriedades chave:

Propriedade	Tipo	Descrição
`data`	`any`	A carga útil da mensagem (clone estruturado do que foi enviado)
`origin`	`string`	A origem da janela remetente (por exemplo, `https://example.com`)
`source`	`Window or MessagePort or ServiceWorker or null`	Referência à janela remetente; use para responder
`ports`	`ReadonlyArray<MessagePort>`	Portas do MessageChannel transferidas com a mensagem
`lastEventId`	`string`	String vazia para postMessage (usado por SSE)

Como Funciona

O remetente chama postMessage(data, targetOrigin) no objeto da janela de destino (não na sua própria).
O navegador verifica se a origem atual da janela de destino corresponde a targetOrigin. Se não corresponder, a mensagem é silenciosamente descartada.
A carga útil da mensagem é serializada usando o algoritmo de clone estruturado (não JSON). Isso suporta Date, Map, Set, ArrayBuffer, Blob, File, RegExp, arrays tipados e objetos aninhados. Ele não suporta funções, nós DOM, Symbol, ou WeakMap/WeakSet.
A mensagem é despachada assincronamente (ela passa pelo loop de eventos). Nunca é síncrona.
O listener de evento "message" da janela receptora dispara com um MessageEvent contendo os dados clonados, a origem do remetente e uma referência à janela do remetente.

Validação de Origem é Não Negociável

Sempre verifique event.origin em todo manipulador de mensagens. Sem essa verificação, qualquer página que possa incorporar sua página (ou que sua página incorpore) pode enviar mensagens arbitrárias para seu manipulador.
Sempre especifique targetOrigin ao chamar postMessage. Usar "*" significa que qualquer origem pode receber a mensagem. Isso é perigoso quando a mensagem contém dados sensíveis (tokens, informações do usuário, etc.). Veja o documento de segurança para detalhes completos.
Use uma lista de permissão de origens conhecidas, não uma correspondência de padrão regex (regexes são fáceis de errar e podem ser contornadas).

Padrão de Integração React

// Padrão useEffect limpo para listeners de postMessage
useEffect(() => {
  const ALLOWED_ORIGINS = new Set([
    "https://widget-a.example.com",
    "https://widget-b.example.com",
  ]);
 
  function handleMessage(event: MessageEvent) {
    if (!ALLOWED_ORIGINS.has(event.origin)) return;
 
    // Estreita o tipo com base na união discriminada
    const msg = event.data;
    if (typeof msg !== "object" || msg === null || !("type" in msg)) return;
 
    switch (msg.type) {
      case "THEME_UPDATE":
        // lidar com...
        break;
      // ...
    }
  }
 
  window.addEventListener("message", handleMessage);
  return () => window.removeEventListener("message", handleMessage);
}, []); // Dependências vazias: listener é estável, sem closures obsoletas necessárias

Uniões Discriminadas do TypeScript para Protocolos de Mensagem

// Define todas as mensagens em uma união. O campo "type" é o discriminante.
type AppMessage =
  | { type: "NAVIGATE"; payload: { path: string } }
  | { type: "AUTH_TOKEN"; payload: { token: string; expiresAt: number } }
  | { type: "RESIZE"; payload: { width: number; height: number } }
  | { type: "READY" }; // nenhum payload necessário
 
// Type guard para validar dados de entrada desconhecidos
function isAppMessage(data: unknown): data is AppMessage {
  if (typeof data !== "object" || data === null) return false;
  if (!("type" in data)) return false;
  const d = data as { type: string };
  return ["NAVIGATE", "AUTH_TOKEN", "RESIZE", "READY"].includes(d.type);
}
 
// Uso no manipulador
function handleMessage(event: MessageEvent) {
  if (event.origin !== EXPECTED_ORIGIN) return;
  if (!isAppMessage(event.data)) return;
 
  // TypeScript agora estreita corretamente em cada caso
  switch (event.data.type) {
    case "AUTH_TOKEN":
      // event.data.payload é { token: string; expiresAt: number }
      setToken(event.data.payload.token);
      break;
    case "NAVIGATE":
      // event.data.payload é { path: string }
      router.push(event.data.payload.path);
      break;
  }
}

Armadilhas

Esquecer as verificações de origem é a principal vulnerabilidade de segurança do postMessage. Nunca pule a validação de event.origin, mesmo em desenvolvimento. Crie o hábito cedo.
"*" como origem de destino transmite para qualquer origem. Use-o apenas para mensagens verdadeiramente públicas e não sensíveis (e mesmo assim, pense duas vezes).
Mensagens são assíncronas. postMessage não retorna um valor. Se você precisar de uma resposta, deve implementar um protocolo de solicitação/resposta com IDs de mensagem (abordado no guia intermediário).
event.source pode ser nulo se a janela remetente foi fechada antes que seu manipulador dispare. Sempre verifique se há nulo antes de responder.
O Iframe deve ser carregado antes que você possa enviar mensagens para ele. Enviar para contentWindow antes que o evento load do iframe dispare falhará silenciosamente. Use o callback onLoad do iframe ou espere por uma mensagem READY do iframe.
Múltiplos listeners podem entrar em conflito. Se você adicionar um listener de mensagem em vários componentes, cada listener disparará para cada mensagem. Use o campo type da mensagem para rotear para o manipulador correto.
Clone estruturado não é JSON. O clone estruturado preserva objetos Date, Map, Set, ArrayBuffer, Blob, etc., mas lançará um erro em funções e nós DOM. Se você precisar verificar o que é clonável, use structuredClone() localmente para testar.
React StrictMode dispara efeitos duas vezes em desenvolvimento, o que significa que seu listener será adicionado duas vezes (depois limpo e readicionado). Isso não é um problema porque a função de limpeza remove o antigo, mas esteja ciente disso ao depurar.

Alternativas

Abordagem	Quando Usar
BroadcastChannel	Guias ou janelas de mesma origem que precisam compartilhar estado (sem suporte a cross-origin)
Channel Messaging (MessageChannel)	Porta dedicada de via dupla entre exatamente dois contextos (abordado no guia avançado)
SharedWorker	Múltiplos guias de mesma origem compartilhando um único worker para coordenação de estado
Custom Events	Comunicação dentro do mesmo documento (sem cross-origin, sem cross-frame)
Server-Sent Events ou WebSocket	Quando você precisa de comunicação mediada por servidor entre clientes
Fragmento de URL ou parâmetros de consulta	Passagem de dados única para um iframe (sem comunicação contínua)

FAQs

Qual é o primeiro argumento para window.postMessage e quais tipos de dados ele pode carregar?

O primeiro argumento é a carga útil da mensagem, que é serializada através do algoritmo de clone estruturado.
Tipos suportados incluem primitivos, objetos simples, arrays, Date, Map, Set, ArrayBuffer, Blob, File e RegExp.
Funções, nós DOM, Symbol, WeakMap e WeakSet não são suportados e lançarão um DataCloneError.

Por que você deve sempre verificar event.origin em todo manipulador de mensagens?

Sem uma verificação de origem, qualquer página que possa incorporar sua página (ou que sua página incorpore) pode enviar mensagens arbitrárias para seu manipulador.
Esta é a principal vulnerabilidade de segurança do postMessage.
Use um Set de origens conhecidas e válidas para validação rápida e correspondência exata.

O que acontece se você usar "*" como targetOrigin?

O navegador entrega a mensagem para a janela de destino, independentemente de sua origem atual.
Se o iframe navegou para outra página, sua mensagem (potencialmente contendo tokens ou dados do usuário) vai para qualquer página que esteja carregada agora.
Use "*" apenas para mensagens verdadeiramente públicas e não sensíveis.

Como você tipa um manipulador postMessage em TypeScript usando uniões discriminadas?

type AppMessage =
  | { type: "NAVIGATE"; payload: { path: string } }
  | { type: "READY" };
 
function handleMessage(event: MessageEvent<AppMessage>) {
  if (event.origin !== EXPECTED_ORIGIN) return;
  switch (event.data.type) {
    case "NAVIGATE":
      // event.data.payload é { path: string }
      break;
  }
}

Como você cria um type guard para dados postMessage de entrada desconhecidos em TypeScript?

function isAppMessage(data: unknown): data is AppMessage {
  if (typeof data !== "object" || data === null) return false;
  if (!("type" in data)) return false;
  const d = data as { type: string };
  return ["NAVIGATE", "READY"].includes(d.type);
}

Armadilha: O que acontece se você enviar um postMessage para um iframe antes que ele tenha carregado?

A mensagem é descartada silenciosamente porque contentWindow não está pronto.
Use o callback onLoad do iframe ou espere por uma mensagem READY do iframe antes de enviar.

postMessage é síncrono ou assíncrono?

É sempre assíncrono. A mensagem passa pelo loop de eventos.
postMessage não retorna um valor. Se você precisar de uma resposta, deve construir um protocolo de solicitação/resposta com IDs de correlação.

Por que usar um Set de permissão em vez de um regex para validação de origem?

Regexes são fáceis de errar (por exemplo, pontos não escapados, âncoras ausentes) e podem ser contornados.
Uma pesquisa Set é uma correspondência exata de string, que é mais segura e mais rápida.

Como o React StrictMode afeta os listeners de postMessage?

StrictMode dispara efeitos duas vezes em desenvolvimento, então seu listener é adicionado duas vezes.
A função de limpeza remove o listener antigo, então funciona corretamente.
Esteja ciente disso ao depurar logs de mensagens duplicados em desenvolvimento.

Qual é a diferença entre clone estruturado e serialização JSON para postMessage?

O clone estruturado preserva Date, Map, Set, ArrayBuffer, Blob, referências circulares e mais.
JSON perde esses tipos (por exemplo, Date se torna uma string, Map se torna {}).
Você não precisa usar JSON.stringify antes de enviar ou JSON.parse ao receber.

Armadilha: event.source pode ser nulo e quando isso acontece?

Sim. Se a janela remetente foi fechada antes que seu manipulador dispare, event.source é null.
Sempre verifique se event.source é nulo antes de chamar postMessage nele para responder.

Qual é o padrão de limpeza useEffect correto para listeners de postMessage em React?

useEffect(() => {
  function handleMessage(event: MessageEvent) {
    if (event.origin !== EXPECTED) return;
    // lidar com a mensagem
  }
  window.addEventListener("message", handleMessage);
  return () => window.removeEventListener("message", handleMessage);
}, []);

Relacionados

Padrões Intermediários de postMessage - padrão de solicitação/resposta, hook de barramento de mensagens e comunicação bidirecional
Padrões Avançados de postMessage - MessageChannel, transferíveis, camada RPC, arquitetura de micro-frontend
Segurança do postMessage - validação de origem, CSP, sandboxing e incorporação segura de widgets

Vídeos Relacionados

Como Enviar Dados de iframe para Página Pai - Tutorial JavaScript postMessage

Protocolo Window postMessage() usando React - #1 Tutoriais JavaScript

Receita

// Pai envia uma mensagem para um iframe
const iframeRef = useRef<HTMLIFrameElement>(null);
 
function sendToIframe(data: unknown) {
  iframeRef.current?.contentWindow?.postMessage(
    data,
    "https://widget.example.com" // SEMPRE especifique a origem de destino
  );
}
 
// Iframe (ou qualquer janela) escuta mensagens
useEffect(() => {
  function handleMessage(event: MessageEvent) {
    // CRÍTICO: sempre valide a origem
    if (event.origin !== "https://parent.example.com") return;
    console.log("Recebido:", event.data);
  }
  window.addEventListener("message", handleMessage);
  return () => window.removeEventListener("message", handleMessage);
}, []);

Exemplo de Trabalho

Uma página pai envia um objeto de tema para um iframe incorporado. O iframe aplica o tema e envia de volta um reconhecimento.

App Pai

import { useEffect, useRef, useState } from "react";
 
// -- Protocolo de mensagem tipado usando uniões discriminadas --
 
type ParentMessage =
  | { type: "THEME_UPDATE"; payload: Theme }
  | { type: "PING" };
 
type IframeMessage =
  | { type: "THEME_ACK"; payload: { appliedAt: number } }
  | { type: "PONG" };
 
interface Theme {
  mode: "light" | "dark";
  primaryColor: string;
  fontSize: number;
}
 
const IFRAME_ORIGIN = "https://widget.example.com";
 
function ParentApp() {
  const iframeRef = useRef<HTMLIFrameElement>(null);
  const [acked, setAcked] = useState(false);
 
  // Escuta respostas do iframe
  useEffect(() => {
    function handleMessage(event: MessageEvent<IframeMessage>) {
      if (event.origin !== IFRAME_ORIGIN) return;
 
      switch (event.data.type) {
        case "THEME_ACK":
          console.log("Tema aplicado em:", event.data.payload.appliedAt);
          setAcked(true);
          break;
        case "PONG":
          console.log("Iframe está ativo");
          break;
      }
    }
 
    window.addEventListener("message", handleMessage);
    return () => window.removeEventListener("message", handleMessage);
  }, []);
 
  function sendTheme(mode: "light" | "dark") {
    const message: ParentMessage = {
      type: "THEME_UPDATE",
      payload: { mode, primaryColor: "#3b82f6", fontSize: 16 },
    };
    iframeRef.current?.contentWindow?.postMessage(message, IFRAME_ORIGIN);
    setAcked(false);
  }
 
  return (
    <div>
      <h1>App Pai</h1>
      <button onClick={() => sendTheme("light")}>Tema Claro</button>
      <button onClick={() => sendTheme("dark")}>Tema Escuro</button>
      {acked && <p>Tema reconhecido pelo widget</p>}
      <iframe
        ref={iframeRef}
        src={`${IFRAME_ORIGIN}/widget`}
        title="Widget Incorporado"
        style={{ width: 600, height: 400, border: "1px solid #ccc" }}
      />
    </div>
  );
}

import { useEffect, useState } from "react";
 
interface Theme {
  mode: "light" | "dark";
  primaryColor: string;
  fontSize: number;
}
 
type ParentMessage =
  | { type: "THEME_UPDATE"; payload: Theme }
  | { type: "PING" };
 
type IframeMessage =
  | { type: "THEME_ACK"; payload: { appliedAt: number } }
  | { type: "PONG" };
 
const PARENT_ORIGIN = "https://parent.example.com";
 
function Widget() {
  const [theme, setTheme] = useState<Theme>({
    mode: "light",
    primaryColor: "#3b82f6",
    fontSize: 16,
  });
 
  useEffect(() => {
    function handleMessage(event: MessageEvent<ParentMessage>) {
      // CRÍTICO: valide a origem antes de processar
      if (event.origin !== PARENT_ORIGIN) return;
 
      switch (event.data.type) {
        case "THEME_UPDATE":
          setTheme(event.data.payload);
          // Envia reconhecimento de volta para o pai
          const ack: IframeMessage = {
            type: "THEME_ACK",
            payload: { appliedAt: Date.now() },
          };
          // event.source é a janela que enviou a mensagem
          (event.source as Window).postMessage(ack, event.origin);
          break;
 
        case "PING":
          (event.source as Window).postMessage(
            { type: "PONG" } satisfies IframeMessage,
            event.origin
          );
          break;
      }
    }
 
    window.addEventListener("message", handleMessage);
    return () => window.removeEventListener("message", handleMessage);
  }, []);
 
  return (
    <div
      style={{
        backgroundColor: theme.mode === "dark" ? "#1e293b" : "#ffffff",
        color: theme.mode === "dark" ? "#f1f5f9" : "#0f172a",
        fontSize: theme.fontSize,
        padding: 24,
        minHeight: "100vh",
      }}
    >
      <h2 style={{ color: theme.primaryColor }}>Conteúdo do Widget</h2>
      <p>Tema atual: {theme.mode}</p>
    </div>
  );
}

Mergulho Profundo

O que é postMessage?

window.postMessage() é a API padrão do navegador para comunicação segura entre origens entre contextos de navegação (janelas, iframes, popups, workers).
Sem postMessage, a política de mesma origem bloqueia o JavaScript em uma origem de acessar o DOM ou variáveis de outra origem. postMessage fornece um canal controlado para enviar dados serializáveis através dessa fronteira.
A assinatura do método é targetWindow.postMessage(message, targetOrigin, transfer?).

Anatomia do MessageEvent

Todo manipulador de mensagens recebe um MessageEvent com estas propriedades chave:

Propriedade	Tipo	Descrição
`data`	`any`	A carga útil da mensagem (clone estruturado do que foi enviado)
`origin`	`string`	A origem da janela remetente (por exemplo, `https://example.com`)
`source`	`Window or MessagePort or ServiceWorker or null`	Referência à janela remetente; use para responder
`ports`	`ReadonlyArray<MessagePort>`	Portas do MessageChannel transferidas com a mensagem
`lastEventId`	`string`	String vazia para postMessage (usado por SSE)

Como Funciona

O remetente chama postMessage(data, targetOrigin) no objeto da janela de destino (não na sua própria).
O navegador verifica se a origem atual da janela de destino corresponde a targetOrigin. Se não corresponder, a mensagem é silenciosamente descartada.
A carga útil da mensagem é serializada usando o algoritmo de clone estruturado (não JSON). Isso suporta Date, Map, Set, ArrayBuffer, Blob, File, RegExp, arrays tipados e objetos aninhados. Ele não suporta funções, nós DOM, Symbol, ou WeakMap/WeakSet.
A mensagem é despachada assincronamente (ela passa pelo loop de eventos). Nunca é síncrona.
O listener de evento "message" da janela receptora dispara com um MessageEvent contendo os dados clonados, a origem do remetente e uma referência à janela do remetente.

Validação de Origem é Não Negociável

Sempre verifique event.origin em todo manipulador de mensagens. Sem essa verificação, qualquer página que possa incorporar sua página (ou que sua página incorpore) pode enviar mensagens arbitrárias para seu manipulador.
Sempre especifique targetOrigin ao chamar postMessage. Usar "*" significa que qualquer origem pode receber a mensagem. Isso é perigoso quando a mensagem contém dados sensíveis (tokens, informações do usuário, etc.). Veja o documento de segurança para detalhes completos.
Use uma lista de permissão de origens conhecidas, não uma correspondência de padrão regex (regexes são fáceis de errar e podem ser contornadas).

Padrão de Integração React

// Padrão useEffect limpo para listeners de postMessage
useEffect(() => {
  const ALLOWED_ORIGINS = new Set([
    "https://widget-a.example.com",
    "https://widget-b.example.com",
  ]);
 
  function handleMessage(event: MessageEvent) {
    if (!ALLOWED_ORIGINS.has(event.origin)) return;
 
    // Estreita o tipo com base na união discriminada
    const msg = event.data;
    if (typeof msg !== "object" || msg === null || !("type" in msg)) return;
 
    switch (msg.type) {
      case "THEME_UPDATE":
        // lidar com...
        break;
      // ...
    }
  }
 
  window.addEventListener("message", handleMessage);
  return () => window.removeEventListener("message", handleMessage);
}, []); // Dependências vazias: listener é estável, sem closures obsoletas necessárias

Uniões Discriminadas do TypeScript para Protocolos de Mensagem

// Define todas as mensagens em uma união. O campo "type" é o discriminante.
type AppMessage =
  | { type: "NAVIGATE"; payload: { path: string } }
  | { type: "AUTH_TOKEN"; payload: { token: string; expiresAt: number } }
  | { type: "RESIZE"; payload: { width: number; height: number } }
  | { type: "READY" }; // nenhum payload necessário
 
// Type guard para validar dados de entrada desconhecidos
function isAppMessage(data: unknown): data is AppMessage {
  if (typeof data !== "object" || data === null) return false;
  if (!("type" in data)) return false;
  const d = data as { type: string };
  return ["NAVIGATE", "AUTH_TOKEN", "RESIZE", "READY"].includes(d.type);
}
 
// Uso no manipulador
function handleMessage(event: MessageEvent) {
  if (event.origin !== EXPECTED_ORIGIN) return;
  if (!isAppMessage(event.data)) return;
 
  // TypeScript agora estreita corretamente em cada caso
  switch (event.data.type) {
    case "AUTH_TOKEN":
      // event.data.payload é { token: string; expiresAt: number }
      setToken(event.data.payload.token);
      break;
    case "NAVIGATE":
      // event.data.payload é { path: string }
      router.push(event.data.payload.path);
      break;
  }
}

Armadilhas

Esquecer as verificações de origem é a principal vulnerabilidade de segurança do postMessage. Nunca pule a validação de event.origin, mesmo em desenvolvimento. Crie o hábito cedo.
"*" como origem de destino transmite para qualquer origem. Use-o apenas para mensagens verdadeiramente públicas e não sensíveis (e mesmo assim, pense duas vezes).
Mensagens são assíncronas. postMessage não retorna um valor. Se você precisar de uma resposta, deve implementar um protocolo de solicitação/resposta com IDs de mensagem (abordado no guia intermediário).
event.source pode ser nulo se a janela remetente foi fechada antes que seu manipulador dispare. Sempre verifique se há nulo antes de responder.
O Iframe deve ser carregado antes que você possa enviar mensagens para ele. Enviar para contentWindow antes que o evento load do iframe dispare falhará silenciosamente. Use o callback onLoad do iframe ou espere por uma mensagem READY do iframe.
Múltiplos listeners podem entrar em conflito. Se você adicionar um listener de mensagem em vários componentes, cada listener disparará para cada mensagem. Use o campo type da mensagem para rotear para o manipulador correto.
Clone estruturado não é JSON. O clone estruturado preserva objetos Date, Map, Set, ArrayBuffer, Blob, etc., mas lançará um erro em funções e nós DOM. Se você precisar verificar o que é clonável, use structuredClone() localmente para testar.
React StrictMode dispara efeitos duas vezes em desenvolvimento, o que significa que seu listener será adicionado duas vezes (depois limpo e readicionado). Isso não é um problema porque a função de limpeza remove o antigo, mas esteja ciente disso ao depurar.

Alternativas

Abordagem	Quando Usar
BroadcastChannel	Guias ou janelas de mesma origem que precisam compartilhar estado (sem suporte a cross-origin)
Channel Messaging (MessageChannel)	Porta dedicada de via dupla entre exatamente dois contextos (abordado no guia avançado)
SharedWorker	Múltiplos guias de mesma origem compartilhando um único worker para coordenação de estado
Custom Events	Comunicação dentro do mesmo documento (sem cross-origin, sem cross-frame)
Server-Sent Events ou WebSocket	Quando você precisa de comunicação mediada por servidor entre clientes
Fragmento de URL ou parâmetros de consulta	Passagem de dados única para um iframe (sem comunicação contínua)

FAQs

Qual é o primeiro argumento para window.postMessage e quais tipos de dados ele pode carregar?

O primeiro argumento é a carga útil da mensagem, que é serializada através do algoritmo de clone estruturado.
Tipos suportados incluem primitivos, objetos simples, arrays, Date, Map, Set, ArrayBuffer, Blob, File e RegExp.
Funções, nós DOM, Symbol, WeakMap e WeakSet não são suportados e lançarão um DataCloneError.

Por que você deve sempre verificar event.origin em todo manipulador de mensagens?

Sem uma verificação de origem, qualquer página que possa incorporar sua página (ou que sua página incorpore) pode enviar mensagens arbitrárias para seu manipulador.
Esta é a principal vulnerabilidade de segurança do postMessage.
Use um Set de origens conhecidas e válidas para validação rápida e correspondência exata.

O que acontece se você usar "*" como targetOrigin?

O navegador entrega a mensagem para a janela de destino, independentemente de sua origem atual.
Se o iframe navegou para outra página, sua mensagem (potencialmente contendo tokens ou dados do usuário) vai para qualquer página que esteja carregada agora.
Use "*" apenas para mensagens verdadeiramente públicas e não sensíveis.

Como você tipa um manipulador postMessage em TypeScript usando uniões discriminadas?

type AppMessage =
  | { type: "NAVIGATE"; payload: { path: string } }
  | { type: "READY" };
 
function handleMessage(event: MessageEvent<AppMessage>) {
  if (event.origin !== EXPECTED_ORIGIN) return;
  switch (event.data.type) {
    case "NAVIGATE":
      // event.data.payload é { path: string }
      break;
  }
}

Como você cria um type guard para dados postMessage de entrada desconhecidos em TypeScript?

function isAppMessage(data: unknown): data is AppMessage {
  if (typeof data !== "object" || data === null) return false;
  if (!("type" in data)) return false;
  const d = data as { type: string };
  return ["NAVIGATE", "READY"].includes(d.type);
}

Armadilha: O que acontece se você enviar um postMessage para um iframe antes que ele tenha carregado?

A mensagem é descartada silenciosamente porque contentWindow não está pronto.
Use o callback onLoad do iframe ou espere por uma mensagem READY do iframe antes de enviar.

postMessage é síncrono ou assíncrono?

É sempre assíncrono. A mensagem passa pelo loop de eventos.
postMessage não retorna um valor. Se você precisar de uma resposta, deve construir um protocolo de solicitação/resposta com IDs de correlação.

Por que usar um Set de permissão em vez de um regex para validação de origem?

Regexes são fáceis de errar (por exemplo, pontos não escapados, âncoras ausentes) e podem ser contornados.
Uma pesquisa Set é uma correspondência exata de string, que é mais segura e mais rápida.

Como o React StrictMode afeta os listeners de postMessage?

StrictMode dispara efeitos duas vezes em desenvolvimento, então seu listener é adicionado duas vezes.
A função de limpeza remove o listener antigo, então funciona corretamente.
Esteja ciente disso ao depurar logs de mensagens duplicados em desenvolvimento.

Qual é a diferença entre clone estruturado e serialização JSON para postMessage?

O clone estruturado preserva Date, Map, Set, ArrayBuffer, Blob, referências circulares e mais.
JSON perde esses tipos (por exemplo, Date se torna uma string, Map se torna {}).
Você não precisa usar JSON.stringify antes de enviar ou JSON.parse ao receber.

Armadilha: event.source pode ser nulo e quando isso acontece?

Sim. Se a janela remetente foi fechada antes que seu manipulador dispare, event.source é null.
Sempre verifique se event.source é nulo antes de chamar postMessage nele para responder.

Qual é o padrão de limpeza useEffect correto para listeners de postMessage em React?

useEffect(() => {
  function handleMessage(event: MessageEvent) {
    if (event.origin !== EXPECTED) return;
    // lidar com a mensagem
  }
  window.addEventListener("message", handleMessage);
  return () => window.removeEventListener("message", handleMessage);
}, []);

Relacionados

Padrões Intermediários de postMessage - padrão de solicitação/resposta, hook de barramento de mensagens e comunicação bidirecional
Padrões Avançados de postMessage - MessageChannel, transferíveis, camada RPC, arquitetura de micro-frontend
Segurança do postMessage - validação de origem, CSP, sandboxing e incorporação segura de widgets

Vídeos Relacionados

Como Enviar Dados de iframe para Página Pai - Tutorial JavaScript postMessage

Protocolo Window postMessage() usando React - #1 Tutoriais JavaScript

Fundamentos do postMessage - Comunicação segura entre origens entre janelas e iframes

Receita

Exemplo de Trabalho

App Pai

Widget Iframe

Mergulho Profundo

O que é postMessage?

Anatomia do MessageEvent

Como Funciona

Validação de Origem é Não Negociável

Padrão de Integração React

Uniões Discriminadas do TypeScript para Protocolos de Mensagem

Armadilhas

Alternativas

FAQs

Relacionados

Vídeos Relacionados

Fundamentos do postMessage - Comunicação segura entre origens entre janelas e iframes

Receita

Exemplo de Trabalho

App Pai

Widget Iframe

Mergulho Profundo

O que é postMessage?

Anatomia do MessageEvent

Como Funciona

Validação de Origem é Não Negociável

Padrão de Integração React

Uniões Discriminadas do TypeScript para Protocolos de Mensagem

Armadilhas

Alternativas

FAQs

Relacionados

Vídeos Relacionados

Fundamentos do postMessage - Comunicação segura entre origens entre janelas e iframes

Buscar na documentação

Fundamentos do postMessage - Comunicação segura entre origens entre janelas e iframes