@archie/devtools

DevTools for Archie generated applications. Route sync with the editor and optional element inspector script.

Installation

npm install @archie/devtools
# or
pnpm add @archie/devtools

Features

• Route synchronization – Current route is sent to the Archie editor for live preview.
• Inspector script (optional) – Injects the element inspector at runtime (no URL, bundled).
• Vite plugin (optional) – Build-time hook for future features.

Usage

1. Configure Vite Plugin (Optional)

// vite.config.ts
import { defineConfig } from "vite";
import { archieDevTools } from "@archie/devtools";

export default defineConfig({
  plugins: [archieDevTools()],
});

2. Inspector script (optional)

Injects the inspector when the client bundle runs. Safe in SSR (no-op on server). One line, no useEffect:

// App root, e.g. layout.tsx or main.tsx
import "@archie/devtools/client/inject-inspector/auto";

¿Afecta que la función tenga opciones? No. El auto-import llama injectInspector() sin argumentos. Por defecto se usan orígenes Archie + localhost en dev y el target desde el parent (iframe). Solo si quieres cambiar algo pasas opciones:

import { injectInspector } from "@archie/devtools/client";

// Igual que el auto: sin argumentos, valores por defecto seguros
injectInspector();

// Opcional: incluir localhost explícitamente, o fijar orígenes/target
injectInspector({ dev: true });
injectInspector({ id: "my-inspector" });
injectInspector({ allowedOrigins: ["https://app.archie.com"], targetOrigin: "https://app.archie.com" });

Paths:

• @archie/devtools/client – route listener + injectInspector
• @archie/devtools/client/inject-inspector/auto – side-effect only (import and it runs)

3. Route listener (required for preview sync)

// e.g. src/main.tsx
import { setupArchieRouteListener } from "@archie/devtools/client";
import App, { router } from "./App";

setupArchieRouteListener(router);
createRoot(document.getElementById("root")!).render(<App />);

4. Export router from App

// src/App.tsx
import { createBrowserRouter, RouterProvider } from "react-router-dom";

export const router = createBrowserRouter([
  // ... your routes
]);

export default function App() {
  return <RouterProvider router={router} />;
}

Message Format

The route listener broadcasts messages to the parent window with this structure:

interface ArchieRouteUpdateMessage {
  type: "ARCHIE_ROUTE_UPDATE";
  payload: {
    path: string;
    search: string;
    hash: string;
    matches: Array<{
      id: string | undefined;
      pathname: string;
      params: Record<string, string | undefined>;
    }>;
    timestamp: number;
  };
}

Host (editor) integration

If your editor receives postMessage from the inspector iframe:

1. Validate origin with an allowlist (recommended)
   In the host, allow the iframe’s origins (localhost for dev + your app URLs in production) so it works everywhere. Archie host origins: https://app.dev.archie-platform.com, https://app.staging.archie-platform.com, https://app.archie.com. For local testing use getAllowedOrigins(true) (adds localhost). Example:

   import { getAllowedOrigins } from "@archie/devtools/constants";
   const ALLOWED_ORIGINS = getAllowedOrigins(true); // true = include localhost for local dev
   window.addEventListener("message", (e) => {
     if (!ALLOWED_ORIGINS.includes(e.origin)) return;
     // handle e.data
   });

2. Inspector origins (iframe): Only configured domains are allowed; "*" is never used. If you use injectInspector() (recommended), it sets Archie host origins + localhost in dev by default. You can override with allowedOrigins and targetOrigin (or set window.__ARCHIE_INSPECTOR_ALLOWED_ORIGINS__ / __ARCHIE_INSPECTOR_TARGET_ORIGIN__ before the script runs).

3. Globals (backward compatible)
   The inspector still sets window._inspectorDebug, window._inspectorSelectedElement, window._inspectorMessageHandler, and window._inspectorQuerySelectorProtected.
   Prefer the namespace: window.__ARCHIE_INSPECTOR__ with debug, selectedElement, messageHandler (same values, no DOM pollution on the namespace object).

4. Message types (from iframe to parent)
   INSPECTOR_SCRIPT_LOADED, ELEMENT_SELECTED, STOP_INSPECTION, INSPECTION_CANCELLED, ELEMENT_POSITION_UPDATE, STYLE_CHANGE_APPLIED / STYLE_CHANGE_FAILED, TEXT_CHANGE_APPLIED / TEXT_CHANGE_FAILED, ELEMENT_REMOVED / ELEMENT_REMOVAL_FAILED.
   Payload shapes are unchanged; only the postMessage targetOrigin is configurable.

To activate the inspector from the parent (the site that contains the iframe): you don't call runInspector() from the parent. The app inside the iframe already loads the inspector; from the parent send iframe.contentWindow.postMessage({ type: "START_INSPECTION" }, iframeOrigin) to start inspection. See docs/HOST_INTEGRATION.md for full flow, local testing, and all commands.

Linking locally

# In the app repo
pnpm add file:../archie-devtools
# After changing the lib: run `pnpm run build` in archie-devtools

Requirements

• React 18+
• React Router DOM 6.4+ (Data Router API)
• Vite 5+ (for plugin)

License

MIT