@macaly/bridge
v0.1.5
Published
Macaly bridge — wraps a host app to forward console, errors, navigation, screenshots, and component edit-mode events to the parent Macaly editor.
Readme
@macaly/bridge
Runtime bridge that wraps a Macaly-hosted app and forwards events to the parent editor:
- pathname / navigation sync (
usePathnameUpdate,useNavigationBridge,useUrlBridge) - console forwarding (
useConsoleBridge) - uncaught error reporting + error boundary (
useUncaughtErrorHandling,MacalyErrorLogger) - DOM screenshot capture via
modern-screenshot(useScreenshotCapture) - inspector / component edit-mode overlay (
MacalyComponentEditMode)
All side effects gate on typeof window !== "undefined" so the wrapper is safe in SSR.
Install
npm install @macaly/bridge
# or
pnpm add @macaly/bridgePeer deps: react and react-dom >= 18.
Usage
Wrap your root layout / document:
import { MacalyBridge } from "@macaly/bridge";
export function RootDocument({ children }: { children: React.ReactNode }) {
return (
<html lang="en">
<head>{/* ... */}</head>
<MacalyBridge>
<body>{children}</body>
</MacalyBridge>
</html>
);
}The bridge renders only a fragment around children on the server. On the client it mounts the hooks and the edit-mode overlay.
Extra parent domains
By default, the bridge only activates when embedded by Macaly-controlled parent origins. To allow additional parent domains, set a comma-separated public environment variable:
# Next.js
NEXT_PUBLIC_BRIDGE_PARENTS="one-whitelabel.cz,www.second-whitelabel.com"
# Vite / TanStack Start
VITE_BRIDGE_PARENTS="one-whitelabel.cz,www.second-whitelabel.com"Entries are matched as exact hostnames after normalization. List each trusted hostname explicitly.
Build
pnpm install
pnpm build # outputs dist/index.js + dist/index.d.ts
pnpm dev # watch mode
pnpm typecheck # tsc --noEmitOutput is ESM only, with react / react-dom marked external.