feat(core): Include component name annotation plugin with all bundler plugins except esbuild (#469)

* Add hook function for annotate plugin in core index
* Add options and typing
* Add to rollup, vite, webpack
* Allow conditional rendering of options in docs based on supported bundlers

Author: 0Calories

packages/bundler-plugin-core/package.json

@@ -52,17 +52,18 @@
     "fix": "eslint ./src ./test --format stylish --fix"
   },
   "dependencies": {
+    "@babel/core": "7.18.5",
     "@sentry/cli": "^2.22.3",
     "@sentry/node": "^7.60.0",
     "@sentry/utils": "^7.60.0",
+    "@sentry/component-annotate-plugin": "2.10.3",
     "dotenv": "^16.3.1",
     "find-up": "5.0.0",
     "glob": "9.3.2",
     "magic-string": "0.27.0",
     "unplugin": "1.0.1"
   },
   "devDependencies": {
-    "@babel/core": "7.18.5",
     "@babel/preset-env": "7.18.2",
     "@babel/preset-typescript": "7.17.12",
     "@rollup/plugin-babel": "5.3.1",

packages/bundler-plugin-core/src/index.ts

@@ -1,8 +1,10 @@
 import SentryCli from "@sentry/cli";
+import { transformAsync } from "@babel/core";
+import { componentNameAnnotatePlugin } from "@sentry/component-annotate-plugin";
 import * as fs from "fs";
 import * as path from "path";
 import MagicString from "magic-string";
-import { createUnplugin, UnpluginOptions } from "unplugin";
+import { createUnplugin, TransformResult, UnpluginOptions } from "unplugin";
 import { normalizeUserOptions, validateOptions } from "./options-mapping";
 import { createDebugIdUploadFunction } from "./debug-id-upload";
 import { releaseManagementPlugin } from "./plugins/release-management";
@@ -22,9 +24,12 @@ import {
 } from "./utils";
 import * as dotenv from "dotenv";
 import { glob } from "glob";
+import pkg from "@sentry/utils";
+const { logger } = pkg;
 
 interface SentryUnpluginFactoryOptions {
   releaseInjectionPlugin: (injectionCode: string) => UnpluginOptions;
+  componentNameAnnotatePlugin?: () => UnpluginOptions;
   moduleMetadataInjectionPlugin?: (injectionCode: string) => UnpluginOptions;
   debugIdInjectionPlugin: () => UnpluginOptions;
   debugIdUploadPlugin: (upload: (buildArtifacts: string[]) => Promise<void>) => UnpluginOptions;
@@ -60,6 +65,7 @@ interface SentryUnpluginFactoryOptions {
  */
 export function sentryUnpluginFactory({
   releaseInjectionPlugin,
+  componentNameAnnotatePlugin,
   moduleMetadataInjectionPlugin,
   debugIdInjectionPlugin,
   debugIdUploadPlugin,
@@ -317,6 +323,20 @@ export function sentryUnpluginFactory({
       );
     }
 
+    if (options.reactComponentAnnotation) {
+      if (!options.reactComponentAnnotation.enabled) {
+        logger.info(
+          "The component name annotate plugin is currently disabled. Skipping component name annotations."
+        );
+      } else if (options.reactComponentAnnotation.enabled && !componentNameAnnotatePlugin) {
+        logger.warn(
+          "The component name annotate plugin is currently not supported by '@sentry/esbuild-plugin'"
+        );
+      } else {
+        componentNameAnnotatePlugin && plugins.push(componentNameAnnotatePlugin());
+      }
+    }
+
     return plugins;
   });
 }
@@ -346,7 +366,6 @@ export function sentryCliBinaryExists(): boolean {
 
 export function createRollupReleaseInjectionHooks(injectionCode: string) {
   const virtualReleaseInjectionFileId = "\0sentry-release-injection-file";
-
   return {
     resolveId(id: string) {
       if (id === virtualReleaseInjectionFileId) {
@@ -510,6 +529,60 @@ export function createRollupDebugIdUploadHooks(
   };
 }
 
+export function createComponentNameAnnotateHooks() {
+  type ParserPlugins = NonNullable<
+    NonNullable<Parameters<typeof transformAsync>[1]>["parserOpts"]
+  >["plugins"];
+
+  return {
+    async transform(this: void, code: string, id: string): Promise<TransformResult> {
+      // id may contain query and hash which will trip up our file extension logic below
+      const idWithoutQueryAndHash = stripQueryAndHashFromPath(id);
+
+      if (idWithoutQueryAndHash.match(/\\node_modules\\|\/node_modules\//)) {
+        return null;
+      }
+
+      // We will only apply this plugin on jsx and tsx files
+      if (![".jsx", ".tsx"].some((ending) => idWithoutQueryAndHash.endsWith(ending))) {
+        return null;
+      }
+
+      const parserPlugins: ParserPlugins = [];
+      if (idWithoutQueryAndHash.endsWith(".jsx")) {
+        parserPlugins.push("jsx");
+      } else if (idWithoutQueryAndHash.endsWith(".tsx")) {
+        parserPlugins.push("jsx", "typescript");
+      }
+
+      try {
+        const result = await transformAsync(code, {
+          plugins: [[componentNameAnnotatePlugin]],
+          filename: id,
+          parserOpts: {
+            sourceType: "module",
+            allowAwaitOutsideFunction: true,
+            plugins: parserPlugins,
+          },
+          generatorOpts: {
+            decoratorsBeforeExport: true,
+          },
+          sourceMaps: true,
+        });
+
+        return {
+          code: result?.code ?? code,
+          map: result?.map,
+        };
+      } catch (e) {
+        logger.error(`Failed to apply react annotate plugin`, e);
+      }
+
+      return { code };
+    },
+  };
+}
+
 export function getDebugIdSnippet(debugId: string): string {
   return `;!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof self?self:{},n=(new Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="${debugId}",e._sentryDebugIdIdentifier="sentry-dbid-${debugId}")}catch(e){}}();`;
 }

packages/bundler-plugin-core/src/options-mapping.ts

@@ -29,6 +29,7 @@ export function normalizeUserOptions(userOptions: UserOptions) {
       cleanArtifacts: userOptions.release?.cleanArtifacts ?? false,
     },
     bundleSizeOptimizations: userOptions.bundleSizeOptimizations,
+    reactComponentAnnotation: userOptions.reactComponentAnnotation,
     _experiments: userOptions._experiments ?? {},
   };
 

packages/bundler-plugin-core/src/types.ts

@@ -278,6 +278,20 @@ export interface Options {
     excludeReplayWorker?: boolean;
   };
 
+  /**
+   * Options related to react component name annotations.
+   * Disabled by default, unless a value is set for this option.
+   * When enabled, your app's DOM will automatically be annotated during build-time with their respective component names.
+   * This will unlock the capability to search for Replays in Sentry by component name, as well as see component names in breadcrumbs and performance monitoring.
+   * Please note that this feature is not currently supported by the esbuild bundler plugins, and will only annotate React components
+   */
+  reactComponentAnnotation?: {
+    /**
+     * Whether the component name annotate plugin should be enabled or not.
+     */
+    enabled?: boolean;
+  };
+
   /**
    * Options that are considered experimental and subject to change.
    *

packages/component-annotate-plugin/package.json

@@ -47,8 +47,7 @@
     "clean:build": "rimraf ./dist *.tgz",
     "clean:deps": "rimraf node_modules",
     "test": "jest",
-    "lint": "eslint ./src ./test",
-    "prepack": "ts-node ./src/prepack.ts"
+    "lint": "eslint ./src ./test"
   },
   "dependencies": {},
   "devDependencies": {

packages/dev-utils/src/generate-documentation-table.ts

@@ -1,8 +1,11 @@
+type Bundler = "webpack" | "vite" | "rollup" | "esbuild";
+
 type OptionDocumentation = {
   name: string;
   fullDescription: string;
   type?: string;
   children?: OptionDocumentation[];
+  supportedBundlers?: Bundler[];
 };
 
 const options: OptionDocumentation[] = [
@@ -332,6 +335,24 @@ type IncludeEntry = {
       },
     ],
   },
+  {
+    name: "reactComponentAnnotation",
+    fullDescription: `Options related to react component name annotations.
+      Disabled by default, unless a value is set for this option.
+      When enabled, your app's DOM will automatically be annotated during build-time with their respective component names.
+      This will unlock the capability to search for Replays in Sentry by component name, as well as see component names in breadcrumbs and performance monitoring.
+      Please note that this feature is not currently supported by the esbuild bundler plugins, and will only annotate React components
+    `,
+    supportedBundlers: ["webpack", "vite", "rollup"],
+    children: [
+      {
+        name: "enabled",
+        type: "boolean",
+        fullDescription: "Whether the component name annotate plugin should be enabled or not.",
+        supportedBundlers: ["webpack", "vite", "rollup"],
+      },
+    ],
+  },
   {
     name: "_experiments",
     type: "string",
@@ -351,17 +372,22 @@ type IncludeEntry = {
 function generateTableOfContents(
   depth: number,
   parentId: string,
-  nodes: OptionDocumentation[]
+  nodes: OptionDocumentation[],
+  bundler: Bundler
 ): string {
   return nodes
     .map((node) => {
+      if (node.supportedBundlers && !node.supportedBundlers?.includes(bundler)) {
+        return "";
+      }
+
       const id = `${parentId}-${node.name.toLowerCase()}`;
       let output = `${"    ".repeat(depth)}-   [\`${node.name}\`](#${id
         .replace(/-/g, "")
         .toLowerCase()})`;
       if (node.children && depth <= 0) {
         output += "\n";
-        output += generateTableOfContents(depth + 1, id, node.children);
+        output += generateTableOfContents(depth + 1, id, node.children, bundler);
       }
       return output;
     })
@@ -370,10 +396,15 @@ function generateTableOfContents(
 
 function generateDescriptions(
   parentName: string | undefined,
-  nodes: OptionDocumentation[]
+  nodes: OptionDocumentation[],
+  bundler: Bundler
 ): string {
   return nodes
     .map((node) => {
+      if (node.supportedBundlers && !node.supportedBundlers?.includes(bundler)) {
+        return "";
+      }
+
       const name = parentName === undefined ? node.name : `${parentName}.${node.name}`;
       let output = `### \`${name}\`
 
@@ -382,18 +413,18 @@ ${node.type === undefined ? "" : `Type: \`${node.type}\``}
 ${node.fullDescription}
 `;
       if (node.children) {
-        output += generateDescriptions(name, node.children);
+        output += generateDescriptions(name, node.children, bundler);
       }
       return output;
     })
     .join("\n");
 }
 
-export function generateOptionsDocumentation(): string {
+export function generateOptionsDocumentation(bundler: Bundler): string {
   return `## Options
 
-${generateTableOfContents(0, "", options)}
+${generateTableOfContents(0, "", options, bundler)}
 
-${generateDescriptions(undefined, options)}
+${generateDescriptions(undefined, options, bundler)}
 `;
 }

packages/esbuild-plugin/src/prepack.ts

@@ -3,5 +3,8 @@ import * as fs from "fs";
 import * as path from "path";
 
 const readmeTemplate = fs.readFileSync(path.join(__dirname, "..", "README_TEMPLATE.md"), "utf-8");
-const readme = readmeTemplate.replace(/#OPTIONS_SECTION_INSERT#/, generateOptionsDocumentation());
+const readme = readmeTemplate.replace(
+  /#OPTIONS_SECTION_INSERT#/,
+  generateOptionsDocumentation("esbuild")
+);
 fs.writeFileSync(path.join(__dirname, "..", "README.md"), readme, "utf-8");

packages/integration-tests/fixtures/build-information-injection/build-information-injection.test.ts

@@ -22,7 +22,7 @@ function checkBundle(bundlePath: string): void {
         "webpack4",
         "webpack5",
       ]) as string[],
-      depsVersions: { rollup: 3, vite: 3 },
+      depsVersions: { rollup: 3, vite: 3, react: 18 },
       // This will differ based on what env this is run on
       nodeVersion: expectedNodeVersion,
     })

packages/integration-tests/fixtures/component-name-annotate/component-name-annotate.test.ts

@@ -0,0 +1,37 @@
+import childProcess from "child_process";
+import path from "path";
+import { testIfNodeMajorVersionIsLessThan18 } from "../../utils/testIf";
+
+// prettier-ignore
+const SNAPSHOT = `"<div><span data-sentry-component=\\"ComponentA\\" data-sentry-source-file=\\"component-a.jsx\\">Component A</span></div>"`
+const ESBUILD_SNAPSHOT = `"<div><span>Component A</span></div>"`;
+
+function checkBundle(bundlePath: string, snapshot = SNAPSHOT): void {
+  const processOutput = childProcess.execSync(`node ${bundlePath}`, { encoding: "utf-8" });
+  expect(processOutput.trim()).toMatchInlineSnapshot(snapshot);
+}
+
+test("esbuild bundle", () => {
+  expect.assertions(1);
+  checkBundle(path.join(__dirname, "./out/esbuild/index.js"), ESBUILD_SNAPSHOT);
+});
+
+test("rollup bundle", () => {
+  expect.assertions(1);
+  checkBundle(path.join(__dirname, "./out/rollup/index.js"));
+});
+
+test("vite bundle", () => {
+  expect.assertions(1);
+  checkBundle(path.join(__dirname, "./out/vite/index.js"));
+});
+
+testIfNodeMajorVersionIsLessThan18("webpack 4 bundle if node is < 18", () => {
+  expect.assertions(1);
+  checkBundle(path.join(__dirname, "./out/webpack4/index.js"));
+});
+
+test("webpack 5 bundle", () => {
+  expect.assertions(1);
+  checkBundle(path.join(__dirname, "./out/webpack5/index.js"));
+});

packages/integration-tests/fixtures/component-name-annotate/input/app.jsx

@@ -0,0 +1,14 @@
+import { renderToString } from "react-dom/server";
+import { ComponentA } from "./component-a";
+
+export default function App() {
+  return <ComponentA />;
+}
+
+console.log(
+  renderToString(
+    <div>
+      <App />
+    </div>
+  )
+);