feat: new babel plugin with component metadata (#1)

This PR adds a Babel plugin that injects metadata into
`registerPreview()` calls in Rozenite Preview. It captures file path,
line, column, and other details, enabling better tracking and tooling
support.

Key changes:

* **New Babel plugin** (`preview-babel-plugin-metadata.cjs`) adds
metadata automatically.
* **DevTools panel** now shows file locations and adds a "View in
VSCode" button.
* **`registerPreview`** updated to accept injected metadata by babel and
warn if called inside a React component.
* **README updated** with babel configuration and HMR limitations.
* **Type and config updates** to support the new plugin and metadata
handling.

Author: matinzd

README.md

@@ -22,6 +22,17 @@ npm install --save-dev rozenite-preview@alpha
 yarn add -D rozenite-preview@alpha
 ```
 
+## Configuration
+
+Add the following to your `babel.config.js` to get more insights and metadata in your previews:
+
+```js
+module.exports = {
+  presets: ["module:metro-react-native-babel-preset"],
+  plugins: ["rozenite-preview/babel-plugin"]
+};
+```
+
 ## Usage
 
 1. **Register your components for preview:**
@@ -39,20 +50,16 @@ registerPreview("UserCard", UserCard);
 import { PreviewHost } from "rozenite-preview";
 
 export default function App() {
-  return (
-    <PreviewHost>
-      {/* your app */}
-    </PreviewHost>
-  );
+  return <PreviewHost>{/* your app */}</PreviewHost>;
 }
 ```
 
 3. **Open React Native DevTools and use the "Preview" panel**  
-Select and interact with your registered components in real time.
+   Select and interact with your registered components in real time.
 
-## Configuration
+## Known Issues
 
-No additional configuration is required. The plugin is automatically discovered by Rozenite when installed.
+- **HMR Support**: Hot Module Replacement (HMR) is not fully supported yet. You need to refresh the DevTools to see changes in deleted previews. Adding or modifying previews works for now.
 
 ## API
 
@@ -61,8 +68,8 @@ No additional configuration is required. The plugin is automatically discovered
 
 ## Requirements
 
-- React Native 0.76+
-- React 18+
+- React Native 0.79+
+- React 19+
 
 ## License
 

babel-plugin/preview-babel-plugin-metadata.cjs

@@ -0,0 +1,230 @@
+const path = require("path");
+const crypto = require("crypto");
+const { isInsideReactComponent } = require("./react-helper.cjs");
+
+/**
+ * Babel plugin that automatically injects the file path and other metadata
+ * to registerPreview() calls imported from "rozenite-preview"
+ */
+const ROZENITE_PREVIEW_MODULE = "rozenite-preview";
+const TARGET_FUNCTION = "registerPreview";
+const EXPECTED_ARGS_COUNT = 2;
+
+const cache = {};
+
+function getOrCreateId(file, line) {
+  const key = `${file}:${line}`;
+  if (cache[key]) return cache[key];
+
+  const hash = crypto.createHash("md5").update(key).digest("hex").slice(0, 6);
+  const id = `${path
+    .basename(file, path.extname(file))
+    .toLowerCase()}_${line}_${hash}`;
+  cache[key] = id;
+  return id;
+}
+
+module.exports = function ({ types: t }) {
+  return {
+    visitor: {
+      Program(path, state) {
+        const rozenitePreviewImports = collectRozenitePreviewImports(path, t);
+
+        if (rozenitePreviewImports.size === 0) {
+          return;
+        }
+
+        injectFilePathIntoRegisterPreviewCalls(
+          path,
+          state,
+          rozenitePreviewImports,
+          t
+        );
+      },
+    },
+  };
+};
+
+/**
+ * Collects all identifiers imported from "rozenite-preview"
+ * @param {Object} programPath - The program AST path
+ * @param {Object} t - Babel types helper
+ * @returns {Set} Set of imported identifier names
+ */
+function collectRozenitePreviewImports(programPath, t) {
+  const imports = new Set();
+
+  programPath.get("body").forEach((statement) => {
+    if (!isRozenitePreviewImportDeclaration(statement)) {
+      return;
+    }
+
+    statement.node.specifiers.forEach((specifier) => {
+      if (isValidImportSpecifier(specifier, t)) {
+        imports.add(specifier.local.name);
+      }
+    });
+  });
+
+  return imports;
+}
+
+/**
+ * Checks if a statement is an import from "rozenite-preview"
+ * @param {Object} statement - AST statement node
+ * @returns {boolean}
+ */
+function isRozenitePreviewImportDeclaration(statement) {
+  return (
+    statement.isImportDeclaration() &&
+    statement.node.source.value === ROZENITE_PREVIEW_MODULE
+  );
+}
+
+/**
+ * Checks if a specifier is a valid import specifier (named or default)
+ * @param {Object} specifier - Import specifier node
+ * @param {Object} t - Babel types helper
+ * @returns {boolean}
+ */
+function isValidImportSpecifier(specifier, t) {
+  return (
+    t.isImportSpecifier(specifier) || t.isImportDefaultSpecifier(specifier)
+  );
+}
+
+/**
+ * Traverses the AST and injects file paths into registerPreview calls
+ * @param {Object} programPath - The program AST path
+ * @param {Object} state - Babel plugin state
+ * @param {Set} rozenitePreviewImports - Set of imported identifiers from rozenite-preview
+ * @param {Object} t - Babel types helper
+ */
+function injectFilePathIntoRegisterPreviewCalls(
+  programPath,
+  state,
+  rozenitePreviewImports,
+  t
+) {
+  const filename = state.file.opts.filename || "";
+  const relativeFilename = path.relative(process.cwd(), filename);
+
+  programPath.traverse({
+    CallExpression(callPath) {
+      if (isTargetRegisterPreviewCall(callPath, rozenitePreviewImports)) {
+        const metadata = getMetadata(callPath);
+        const filePath = t.stringLiteral(filename);
+        const id = getOrCreateId(relativeFilename, metadata.line);
+        const argument = t.objectExpression([
+          t.objectProperty(t.identifier("id"), t.stringLiteral(id)),
+          t.objectProperty(t.identifier("filePath"), filePath),
+          t.objectProperty(
+            t.identifier("relativeFilename"),
+            t.stringLiteral(relativeFilename)
+          ),
+          t.objectProperty(
+            t.identifier("isInsideReactComponent"),
+            t.booleanLiteral(isInsideReactComponent(callPath))
+          ),
+          t.objectProperty(
+            t.identifier("name"),
+            t.stringLiteral(metadata.name)
+          ),
+          t.objectProperty(
+            t.identifier("nameType"),
+            t.stringLiteral(metadata.nameType)
+          ),
+          t.objectProperty(
+            t.identifier("callId"),
+            t.stringLiteral(metadata.callId)
+          ),
+          t.objectProperty(
+            t.identifier("componentType"),
+            t.stringLiteral(metadata.componentType)
+          ),
+          t.objectProperty(
+            t.identifier("line"),
+            t.numericLiteral(metadata.line)
+          ),
+          t.objectProperty(
+            t.identifier("column"),
+            t.numericLiteral(metadata.column)
+          ),
+        ]);
+        callPath.node.arguments.push(argument);
+      }
+    },
+  });
+}
+
+/**
+ * Determines the component type from the second argument
+ * @param {Object} componentArg - Component argument AST node
+ * @returns {string} Component type description
+ */
+function getComponentType(componentArg) {
+  if (!componentArg) return "unknown";
+
+  switch (componentArg.type) {
+    case "Identifier":
+      return `component:${componentArg.name}`;
+    case "ArrowFunctionExpression":
+    case "FunctionExpression":
+      return "inline-function";
+    case "CallExpression":
+      return "call-expression";
+    default:
+      return componentArg.type.toLowerCase();
+  }
+}
+
+/**
+ * Extracts detailed information from a registerPreview call
+ * @param {Object} callPath - The call expression AST path
+ * @returns {Object} Preview details including name, location, and arguments
+ */
+function getMetadata(callPath) {
+  const firstArg = callPath.node.arguments[0];
+  const secondArg = callPath.node.arguments[1];
+  const loc = callPath.node.loc;
+
+  let name = null;
+  let nameType = "unknown";
+
+  if (firstArg && firstArg.type === "StringLiteral") {
+    name = firstArg.value;
+    nameType = "literal";
+  } else if (firstArg && firstArg.type === "Identifier") {
+    name = `<dynamic:${firstArg.name}>`;
+    nameType = "identifier";
+  }
+
+  // Create a unique identifier for this specific call
+  const callId = `${name}:${loc?.start?.line || 0}:${loc?.start?.column || 0}`;
+
+  return {
+    name,
+    nameType,
+    callId,
+    line: loc?.start?.line || 0,
+    column: loc?.start?.column || 0,
+    componentType: getComponentType(secondArg),
+  };
+}
+
+/**
+ * Determines if a call expression is a registerPreview call that needs modification
+ * @param {Object} callPath - The call expression AST path
+ * @param {Set} rozenitePreviewImports - Set of imported identifiers from rozenite-preview
+ * @returns {boolean}
+ */
+function isTargetRegisterPreviewCall(callPath, rozenitePreviewImports) {
+  const callee = callPath.get("callee");
+
+  return (
+    callee.isIdentifier() &&
+    callee.node.name === TARGET_FUNCTION &&
+    rozenitePreviewImports.has(callee.node.name) &&
+    callPath.node.arguments.length === EXPECTED_ARGS_COUNT
+  );
+}

babel-plugin/react-helper.cjs

@@ -0,0 +1,100 @@
+function hasJSXInFunction(functionPath) {
+  let hasJSX = false;
+  functionPath.traverse({
+    JSXElement() {
+      hasJSX = true;
+    },
+    JSXFragment() {
+      hasJSX = true;
+    },
+  });
+  return hasJSX;
+}
+
+function isInsideJSXExpression(path) {
+  return (
+    path.findParent(
+      (parent) =>
+        parent.isJSXExpressionContainer() ||
+        parent.isJSXElement() ||
+        parent.isJSXFragment()
+    ) !== null
+  );
+}
+
+function isInsideReactComponent(path) {
+  if (!path.isCallExpression()) return false;
+
+  // Check if inside JSX
+  if (isInsideJSXExpression(path)) return true;
+
+  const functionParent = path.getFunctionParent();
+  if (!functionParent) return false;
+
+  // React hooks pattern
+  if (isInsideReactHook(path)) return true;
+
+  // Class component lifecycle methods
+  if (functionParent.isClassMethod()) {
+    const methodName = functionParent.node.key?.name;
+    const reactMethods = [
+      "render",
+      "componentDidMount",
+      "componentDidUpdate",
+      "componentWillUnmount",
+      "getSnapshotBeforeUpdate",
+      "componentDidCatch",
+      "getDerivedStateFromError",
+      "shouldComponentUpdate",
+      "getInitialState",
+    ];
+    return reactMethods.includes(methodName);
+  }
+
+  // Functional component (function that returns JSX)
+  if (functionParent.isFunction()) {
+    return isLikelyFunctionalComponent(functionParent);
+  }
+
+  return false;
+}
+
+function isInsideReactHook(path) {
+  return (
+    path.findParent((parent) => {
+      if (!parent.isCallExpression()) return false;
+      const callee = parent.node.callee;
+      if (callee.type !== "Identifier") return false;
+      return /^use[A-Z]/.test(callee.name);
+    }) !== null
+  );
+}
+
+function isLikelyFunctionalComponent(functionPath) {
+  // Check if function name starts with capital letter (component convention)
+  const functionName = functionPath.node.id?.name;
+  if (functionName && /^[A-Z]/.test(functionName)) {
+    return hasJSXInFunction(functionPath);
+  }
+
+  // Check if assigned to a variable with capital letter
+  if (
+    functionPath.isArrowFunctionExpression() ||
+    functionPath.isFunctionExpression()
+  ) {
+    const parent = functionPath.parent;
+    if (
+      parent.type === "VariableDeclarator" &&
+      parent.id.name &&
+      /^[A-Z]/.test(parent.id.name)
+    ) {
+      return hasJSXInFunction(functionPath);
+    }
+  }
+
+  return false;
+}
+
+module.exports = {
+  isInsideReactComponent,
+};