@promakeai/inspector

Visual element inspector React component with AI prompt support.

Features

• 🎯 Visual element selection
• ✏️ Text editing
• 🖼️ Image URL editing
• 🎨 Style editing (colors, spacing, typography, display, borders)
• 🔍 Element stack navigation (select overlapping elements)
• 🌐 i18n support via labels
• 🎨 Customizable theme
• 📱 Responsive design
• ⚡ React version independent - Works with React 18, 19, and any future versions
• 🎨 No external UI dependencies - All components built in-house for maximum compatibility

Installation

npm install @promakeai/inspector
# or
yarn add @promakeai/inspector
# or
pnpm add @promakeai/inspector
# or
bun add @promakeai/inspector

Peer Dependencies

Only React is required:

{
  "react": ">=18.0.0"
}

That's it! No need for:

• ❌ React version matching
• ❌ Dependency deduplication
• ❌ Version resolution conflicts
• ❌ Additional UI library installations

Usage

1. Add Vite Plugin (Optional - for component tracking)

// vite.config.ts
import { defineConfig } from "vite";
import react from "@vitejs/plugin-react";
import { inspectorDebugger } from "@promakeai/inspector/plugin";

export default defineConfig({
  plugins: [
    inspectorDebugger({ enabled: true }), // Must be BEFORE react() plugin
    react(),
  ],
});

⚠️ Important: inspectorDebugger must be placed before the react() plugin to properly track components.

Note: The Vite plugin is optional but recommended for better component tracking.

2. Use Inspector Component

import { Inspector } from "@promakeai/inspector";
import "@promakeai/inspector/style.css";

function App() {
  return (
    <>
      <YourApp />
      <Inspector />
    </>
  );
}

The Inspector will inspect the current page and allow you to edit elements visually.

Customization (Optional):

You can customize labels and theme via the inspector store or by listening to inspector events. See the Hook API section below for programmatic control.

3. Programmatic Control (Advanced)

Access the inspector store for programmatic control:

import { Inspector } from "@promakeai/inspector";
import { useInspectorStore } from "@promakeai/inspector";

function App() {
  const { setTheme, setLabels } = useInspectorStore();

  useEffect(() => {
    // Customize theme
    setTheme({
      primaryColor: "rgb(58, 18, 189)",
      backgroundColor: "#ffffff",
      textColor: "#000000",
    });

    // Customize labels
    setLabels({
      editText: "Edit Text",
      editImage: "Edit Image",
      editStyle: "Edit Style",
    });
  }, []);

  return (
    <>
      <YourApp />
      <Inspector />
    </>
  );
}

Configuration

Inspector Store

The Inspector component uses Zustand for state management. All configuration is done through the store:

import { useInspectorStore } from "@promakeai/inspector";

const { theme, labels, setTheme, setLabels } = useInspectorStore();

Note: The <Inspector /> component accepts no props. All customization is done via the store.

Theme Options

interface InspectorTheme {
  primaryColor?: string;
  backgroundColor?: string;
  textColor?: string;
  borderColor?: string;
  buttonColor?: string;
  buttonTextColor?: string;
  inputBackgroundColor?: string;
  // ... and more
}

Label Options

All UI text can be customized via the labels prop. See TypeScript types for complete list.

Browser Support

• Chrome/Edge 90+
• Firefox 88+
• Safari 14+

Troubleshooting

Styles not working?

Make sure to import the CSS:

import "@promakeai/inspector/style.css";

Inspector not appearing?

1. Check that the inspector root element is rendered
2. Open browser console for any errors
3. Clear Vite cache: rm -rf node_modules/.vite

Elements not selectable?

1. Make sure elements don't have pointer-events: none
2. Check z-index conflicts with your app (inspector uses z-index 2147483640+)
3. Verify elements are not inside shadow DOM

React Version Compatibility

This package is built with zero external UI dependencies, making it compatible with:

• ✅ React 18.x
• ✅ React 19.x
• ✅ React 19 Canary
• ✅ Future React versions

No version conflicts, ever! All UI components are custom-built pure React components.

Migration from v1.0.6

If you're upgrading from v1.0.6 or earlier:

1. Remove old Vite config workarounds:

   - resolve: {
   -   dedupe: ["react", "react-dom"],
   - },
   - optimizeDeps: {
   -   exclude: ["@promakeai/inspector"],
   -   needsInterop: [],
   - },

2. That's it! The package now works out of the box with any React version.

Changelog

v1.1.0

• ✨ Removed all Radix UI dependencies
• ✨ Built custom Select and ColorPicker components
• ✨ React version independent (18+)
• ✨ Fixed dropdown positioning issues
• ✨ Improved Select label display
• ✨ Smaller bundle size
• 🐛 Fixed ControlBox overflow issues
• 🐛 Fixed color picker positioning

v1.0.7

• Previous version with Radix UI dependencies