macaly-tagger 1.0.1 → 1.2.0

package/README.md

@@ -8,7 +8,8 @@ A webpack loader that adds location metadata to JSX elements for development deb
 - 🚀 **Zero runtime overhead**: Only runs in development mode
 - 🔧 **Easy integration**: Simple webpack configuration
 - 📦 **TypeScript support**: Works with both `.jsx` and `.tsx` files
-- 🚫 **Smart filtering**: Automatically excludes `node_modules`
+- 🚫 **Smart filtering**: Automatically excludes `node_modules`, React Fragments, and non-DOM elements
+- 🎮 **Custom renderer support**: Compatible with React Three Fiber and other custom renderers via `ignorePackages` option
 
 ## Installation
 
@@ -26,6 +27,47 @@ The loader has the following dependencies that will be installed automatically:
 
 ### Next.js Setup
 
+#### For Next.js 15.3.0+ with Turbopack
+
+Configure your `next.config.js`:
+
+```js
+/** @type {import('next').NextConfig} */
+const nextConfig = {
+  turbopack: {
+    rules: {
+      "*.{jsx,tsx}": {
+        condition: {
+          all: [
+            { not: "foreign" },  // Exclude node_modules
+            "development",        // Only in development mode
+          ],
+        },
+        loaders: [
+          {
+            loader: "macaly-tagger",
+            options: {
+              disableSourceMaps: true,  // Required to avoid Turbopack crashes
+            },
+          },
+        ],
+        as: "*",  // Preserve original file handling
+      },
+    },
+  },
+};
+
+module.exports = nextConfig;
+```
+
+> **Important Notes for Turbopack:**
+> - **`disableSourceMaps: true` is required** to prevent Turbopack crashes when processing source maps
+> - **`as: "*"`** preserves the original file type handling (don't use `"*.js"`)
+> - **Don't include `'browser'` condition** as it may exclude server components in Next.js
+> - The simple `"*.{jsx,tsx}"` glob pattern works correctly with these settings
+
+#### For Next.js with Webpack (legacy)
+
 Configure your `next.config.js`:
 
 ```js
@@ -144,6 +186,79 @@ The loader works out of the box with no configuration needed. It automatically:
 - Runs only in development mode (when configured properly)
 - Handles both regular JSX elements (`<div>`) and member expressions (`<MyLib.Button>`)
 
+### Options
+
+You can pass options to the loader:
+
+```js
+{
+  loader: 'macaly-tagger',
+  options: {
+    debug: true,              // Enable debug logging
+    disableSourceMaps: true,  // Disable source map generation (useful for Turbopack)
+    ignorePackages: [         // Skip components imported from these packages
+      '@react-three/fiber',
+      '@react-three/drei',
+    ],
+  },
+}
+```
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `debug` | `boolean` | `false` | Enable detailed console logging for debugging |
+| `disableSourceMaps` | `boolean` | `false` | Disable source map generation (recommended for Turbopack to avoid crashes) |
+| `ignorePackages` | `string[]` | `[]` | List of package names whose imports should not be tagged |
+
+### Custom Renderers (React Three Fiber, etc.)
+
+If you're using custom React renderers like [React Three Fiber](https://github.com/pmndrs/react-three-fiber), you may encounter errors because these renderers use components that don't support DOM attributes.
+
+Use the `ignorePackages` option to skip tagging components imported from these packages:
+
+```js
+{
+  loader: 'macaly-tagger',
+  options: {
+    ignorePackages: [
+      '@react-three/fiber',
+      '@react-three/drei',
+      '@react-three/postprocessing',
+      'three',
+    ],
+  },
+}
+```
+
+This will automatically skip tagging any component imported from these packages:
+
+```jsx
+import { Canvas } from '@react-three/fiber';           // Canvas will NOT be tagged
+import { OrbitControls, Html } from '@react-three/drei'; // OrbitControls, Html will NOT be tagged
+import * as Fiber from '@react-three/fiber';           // Fiber.* will NOT be tagged
+
+function Scene() {
+  return (
+    <div>                    {/* ✓ Tagged (HTML element) */}
+      <Canvas>               {/* ✗ Skipped (imported from @react-three/fiber) */}
+        <OrbitControls />    {/* ✗ Skipped (imported from @react-three/drei) */}
+        <Html>               {/* ✗ Skipped (imported from @react-three/drei) */}
+          <span>Label</span> {/* ✓ Tagged (HTML element) */}
+        </Html>
+        <mesh>               {/* ✗ Skipped (lowercase non-HTML element) */}
+          <boxGeometry />    {/* ✗ Skipped (lowercase non-HTML element) */}
+        </mesh>
+      </Canvas>
+    </div>
+  );
+}
+```
+
+The loader handles all import styles:
+- **Named imports**: `import { Canvas } from '...'`
+- **Default imports**: `import Drei from '...'` (skips `Drei.Something`)
+- **Namespace imports**: `import * as Fiber from '...'` (skips `Fiber.Something`)
+
 ## Attributes Added
 
 For each JSX element, the loader adds:
@@ -171,7 +286,7 @@ Once installed, you can:
 ### Build errors?
 
 1. **Install dependencies**: Ensure all peer dependencies are installed
-2. **Check webpack version**: Requires webpack >= 4.0.0
+2. **Check webpack version**: Requires webpack >= 4.0.0 (for webpack setup)
 3. **Verify loader path**: Make sure the loader is correctly referenced
 
 ### Performance issues?
@@ -211,6 +326,19 @@ MIT License - see LICENSE file for details.
 
 ## Changelog
 
+### 1.2.0
+
+- Added `ignorePackages` option to skip tagging components imported from specified packages
+- Added automatic filtering for React Fragments (`<Fragment>`, `<React.Fragment>`)
+- Added smart element filtering: only tags HTML/SVG elements and React components, skips unknown lowercase elements (custom renderer elements like R3F's `<mesh>`, `<boxGeometry>`, etc.)
+- Improved compatibility with React Three Fiber and other custom renderers
+
+### 1.1.0
+
+- Added `disableSourceMaps` option to prevent Turbopack crashes
+- Added comprehensive Turbopack configuration documentation
+- Tested and verified Turbopack compatibility with Next.js 15.3.0+
+
 ### 1.0.0
 
 - Initial release

package/dist/dom-elements.d.ts

@@ -0,0 +1,4 @@
+export declare const HTML_ELEMENTS: Set<string>;
+export declare const SVG_ELEMENTS: Set<string>;
+export declare function shouldTagElement(tagName: string): boolean;
+//# sourceMappingURL=dom-elements.d.ts.map

package/dist/dom-elements.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dom-elements.d.ts","sourceRoot":"","sources":["../src/dom-elements.ts"],"names":[],"mappings":"AAGA,eAAO,MAAM,aAAa,aAiHxB,CAAC;AAKH,eAAO,MAAM,YAAY,aA8DvB,CAAC;AAiBH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAgBzD"}

package/dist/dom-elements.js

@@ -0,0 +1,191 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SVG_ELEMENTS = exports.HTML_ELEMENTS = void 0;
+exports.shouldTagElement = shouldTagElement;
+exports.HTML_ELEMENTS = new Set([
+    'a',
+    'abbr',
+    'address',
+    'area',
+    'article',
+    'aside',
+    'audio',
+    'b',
+    'base',
+    'bdi',
+    'bdo',
+    'blockquote',
+    'body',
+    'br',
+    'button',
+    'canvas',
+    'caption',
+    'cite',
+    'code',
+    'col',
+    'colgroup',
+    'data',
+    'datalist',
+    'dd',
+    'del',
+    'details',
+    'dfn',
+    'dialog',
+    'div',
+    'dl',
+    'dt',
+    'em',
+    'embed',
+    'fieldset',
+    'figcaption',
+    'figure',
+    'footer',
+    'form',
+    'h1',
+    'h2',
+    'h3',
+    'h4',
+    'h5',
+    'h6',
+    'head',
+    'header',
+    'hgroup',
+    'hr',
+    'html',
+    'i',
+    'iframe',
+    'img',
+    'input',
+    'ins',
+    'kbd',
+    'label',
+    'legend',
+    'li',
+    'link',
+    'main',
+    'map',
+    'mark',
+    'menu',
+    'meta',
+    'meter',
+    'nav',
+    'noscript',
+    'object',
+    'ol',
+    'optgroup',
+    'option',
+    'output',
+    'p',
+    'picture',
+    'pre',
+    'progress',
+    'q',
+    'rp',
+    'rt',
+    'ruby',
+    's',
+    'samp',
+    'script',
+    'search',
+    'section',
+    'select',
+    'slot',
+    'small',
+    'source',
+    'span',
+    'strong',
+    'style',
+    'sub',
+    'summary',
+    'sup',
+    'table',
+    'tbody',
+    'td',
+    'template',
+    'textarea',
+    'tfoot',
+    'th',
+    'thead',
+    'time',
+    'title',
+    'tr',
+    'track',
+    'u',
+    'ul',
+    'var',
+    'video',
+    'wbr',
+]);
+exports.SVG_ELEMENTS = new Set([
+    'svg',
+    'a',
+    'animate',
+    'animateMotion',
+    'animateTransform',
+    'circle',
+    'clipPath',
+    'defs',
+    'desc',
+    'ellipse',
+    'feBlend',
+    'feColorMatrix',
+    'feComponentTransfer',
+    'feComposite',
+    'feConvolveMatrix',
+    'feDiffuseLighting',
+    'feDisplacementMap',
+    'feDistantLight',
+    'feDropShadow',
+    'feFlood',
+    'feFuncA',
+    'feFuncB',
+    'feFuncG',
+    'feFuncR',
+    'feGaussianBlur',
+    'feImage',
+    'feMerge',
+    'feMergeNode',
+    'feMorphology',
+    'feOffset',
+    'fePointLight',
+    'feSpecularLighting',
+    'feSpotLight',
+    'feTile',
+    'feTurbulence',
+    'filter',
+    'foreignObject',
+    'g',
+    'image',
+    'line',
+    'linearGradient',
+    'marker',
+    'mask',
+    'metadata',
+    'mpath',
+    'path',
+    'pattern',
+    'polygon',
+    'polyline',
+    'radialGradient',
+    'rect',
+    'set',
+    'stop',
+    'switch',
+    'symbol',
+    'text',
+    'textPath',
+    'title',
+    'tspan',
+    'use',
+    'view',
+]);
+function shouldTagElement(tagName) {
+    if (tagName === 'Fragment' || tagName.endsWith('.Fragment')) {
+        return false;
+    }
+    const firstChar = tagName[0];
+    if (firstChar && firstChar !== firstChar.toLowerCase()) {
+        return true;
+    }
+    return exports.HTML_ELEMENTS.has(tagName) || exports.SVG_ELEMENTS.has(tagName);
+}

package/dist/import-collector.d.ts

@@ -0,0 +1,8 @@
+export interface IgnoredImports {
+    namedImports: Set<string>;
+    namespaceImports: Set<string>;
+}
+export declare function createEmptyIgnoredImports(): IgnoredImports;
+export declare function collectIgnoredImports(ast: any, ignorePackages: string[]): IgnoredImports;
+export declare function isIgnoredImport(tagName: string, ignoredImports: IgnoredImports): boolean;
+//# sourceMappingURL=import-collector.d.ts.map

package/dist/import-collector.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"import-collector.d.ts","sourceRoot":"","sources":["../src/import-collector.ts"],"names":[],"mappings":"AAMA,MAAM,WAAW,cAAc;IAK7B,YAAY,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IAO1B,gBAAgB,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;CAC/B;AAKD,wBAAgB,yBAAyB,IAAI,cAAc,CAK1D;AAcD,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,GAAG,EAAE,cAAc,EAAE,MAAM,EAAE,GAAG,cAAc,CA+CxF;AASD,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,EAAE,cAAc,EAAE,cAAc,GAAG,OAAO,CAexF"}

package/dist/import-collector.js

@@ -0,0 +1,56 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createEmptyIgnoredImports = createEmptyIgnoredImports;
+exports.collectIgnoredImports = collectIgnoredImports;
+exports.isIgnoredImport = isIgnoredImport;
+const estree_walker_1 = require("estree-walker");
+function createEmptyIgnoredImports() {
+    return {
+        namedImports: new Set(),
+        namespaceImports: new Set(),
+    };
+}
+function collectIgnoredImports(ast, ignorePackages) {
+    const result = createEmptyIgnoredImports();
+    if (!ignorePackages || ignorePackages.length === 0) {
+        return result;
+    }
+    const packagesSet = new Set(ignorePackages);
+    (0, estree_walker_1.walk)(ast, {
+        enter: (node) => {
+            if (node.type !== 'ImportDeclaration')
+                return;
+            const importNode = node;
+            const source = importNode.source.value;
+            if (typeof source !== 'string' || !packagesSet.has(source)) {
+                return;
+            }
+            for (const specifier of importNode.specifiers || []) {
+                switch (specifier.type) {
+                    case 'ImportSpecifier':
+                        result.namedImports.add(specifier.local.name);
+                        break;
+                    case 'ImportDefaultSpecifier':
+                        result.namespaceImports.add(specifier.local.name);
+                        break;
+                    case 'ImportNamespaceSpecifier':
+                        result.namespaceImports.add(specifier.local.name);
+                        break;
+                }
+            }
+        },
+    });
+    return result;
+}
+function isIgnoredImport(tagName, ignoredImports) {
+    if (ignoredImports.namedImports.has(tagName)) {
+        return true;
+    }
+    if (tagName.includes('.')) {
+        const prefix = tagName.split('.')[0];
+        if (prefix && ignoredImports.namespaceImports.has(prefix)) {
+            return true;
+        }
+    }
+    return false;
+}

package/dist/macaly-tagger-loader.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"macaly-tagger-loader.d.ts","sourceRoot":"","sources":["../src/macaly-tagger-loader.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EACV,kBAAkB,EAInB,MAAM,SAAS,CAAC;AAgGjB,QAAA,MAAM,kBAAkB,EAAE,kBAqIzB,CAAC;AAEF,eAAe,kBAAkB,CAAC"}
+{"version":3,"file":"macaly-tagger-loader.d.ts","sourceRoot":"","sources":["../src/macaly-tagger-loader.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EACV,kBAAkB,EAInB,MAAM,SAAS,CAAC;AAuGjB,QAAA,MAAM,kBAAkB,EAAE,kBAiKzB,CAAC;AAEF,eAAe,kBAAkB,CAAC"}

package/dist/macaly-tagger-loader.js

@@ -40,6 +40,8 @@ const parser_1 = require("@babel/parser");
 const magic_string_1 = __importDefault(require("magic-string"));
 const path = __importStar(require("path"));
 const estree_walker_1 = require("estree-walker");
+const dom_elements_1 = require("./dom-elements");
+const import_collector_1 = require("./import-collector");
 const VALID_EXTENSIONS = new Set(['.jsx', '.tsx']);
 function getMemberExpressionName(memberExpression) {
     if (memberExpression.type === 'JSXIdentifier') {
@@ -128,8 +130,17 @@ const macalyTaggerLoader = function (code) {
             const ms = new magic_string_1.default(code);
             const fileRelative = path.relative(this.rootContext || process.cwd(), this.resourcePath);
             let transformCount = 0;
+            const ignoredImports = options.ignorePackages?.length
+                ? (0, import_collector_1.collectIgnoredImports)(ast, options.ignorePackages)
+                : (0, import_collector_1.createEmptyIgnoredImports)();
             if (options.debug) {
                 console.log('[macaly-tagger] File relative path:', fileRelative);
+                if (ignoredImports.namedImports.size > 0 || ignoredImports.namespaceImports.size > 0) {
+                    console.log('[macaly-tagger] Ignored imports:', {
+                        named: Array.from(ignoredImports.namedImports),
+                        namespaces: Array.from(ignoredImports.namespaceImports),
+                    });
+                }
             }
             (0, estree_walker_1.walk)(ast, {
                 enter: (node) => {
@@ -150,6 +161,18 @@ const macalyTaggerLoader = function (code) {
                         if (!elementInfo)
                             return;
                         const { tagName, insertPosition, location } = elementInfo;
+                        if ((0, import_collector_1.isIgnoredImport)(tagName, ignoredImports)) {
+                            if (options.debug) {
+                                console.log('[macaly-tagger] Skipping ignored import:', tagName);
+                            }
+                            return;
+                        }
+                        if (!(0, dom_elements_1.shouldTagElement)(tagName)) {
+                            if (options.debug) {
+                                console.log('[macaly-tagger] Skipping element:', tagName);
+                            }
+                            return;
+                        }
                         const macalyLoc = `${fileRelative}:${location.line}:${location.column}`;
                         if (options.debug) {
                             console.log('[macaly-tagger] Adding attributes to:', tagName, 'at', macalyLoc);
@@ -177,7 +200,7 @@ const macalyTaggerLoader = function (code) {
             }
             return {
                 code: transformedCode,
-                map: ms.generateMap({ hires: true }),
+                map: options.disableSourceMaps ? null : ms.generateMap({ hires: true }),
             };
         }
         catch (error) {
@@ -188,7 +211,7 @@ const macalyTaggerLoader = function (code) {
     transform()
         .then((result) => {
         if (result) {
-            callback(null, result.code, result.map);
+            callback(null, result.code, result.map || undefined);
         }
         else {
             callback(null, code);

package/dist/types.d.ts

@@ -1,6 +1,8 @@
 import { LoaderDefinitionFunction } from 'webpack';
 export interface MacalyTaggerLoaderOptions {
     debug?: boolean;
+    disableSourceMaps?: boolean;
+    ignorePackages?: string[];
 }
 export interface SourceLocation {
     line: number;
@@ -13,7 +15,7 @@ export interface JSXElementInfo {
 }
 export interface TransformResult {
     code: string;
-    map: any;
+    map: any | null;
 }
 export type MacalyTaggerLoader = LoaderDefinitionFunction<MacalyTaggerLoaderOptions>;
 //# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,wBAAwB,EAAE,MAAM,SAAS,CAAC;AAEnD,MAAM,WAAW,yBAAyB;IACxC,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAED,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,cAAc;IAC7B,OAAO,EAAE,MAAM,CAAC;IAChB,cAAc,EAAE,MAAM,CAAC;IACvB,QAAQ,EAAE,cAAc,CAAC;CAC1B;AAED,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,EAAE,GAAG,CAAC;CACV;AAED,MAAM,MAAM,kBAAkB,GAAG,wBAAwB,CAAC,yBAAyB,CAAC,CAAC"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,wBAAwB,EAAE,MAAM,SAAS,CAAC;AAEnD,MAAM,WAAW,yBAAyB;IACxC,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAS5B,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;CAC3B;AAED,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,cAAc;IAC7B,OAAO,EAAE,MAAM,CAAC;IAChB,cAAc,EAAE,MAAM,CAAC;IACvB,QAAQ,EAAE,cAAc,CAAC;CAC1B;AAED,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,EAAE,GAAG,GAAG,IAAI,CAAC;CACjB;AAED,MAAM,MAAM,kBAAkB,GAAG,wBAAwB,CAAC,yBAAyB,CAAC,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "macaly-tagger",
-  "version": "1.0.1",
+  "version": "1.2.0",
   "description": "A webpack loader that adds location metadata to JSX elements for development debugging",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -49,8 +49,8 @@
   "license": "MIT",
   "dependencies": {
     "@babel/parser": "^7.24.0",
-    "magic-string": "^0.30.0",
-    "estree-walker": "^2.0.2"
+    "estree-walker": "^2.0.2",
+    "magic-string": "^0.30.0"
   },
   "devDependencies": {
     "@babel/types": "^7.24.0",
@@ -61,10 +61,10 @@
     "eslint": "^8.57.0",
     "eslint-config-prettier": "^9.1.0",
     "eslint-plugin-prettier": "^5.1.3",
-    "vitest": "^1.4.0",
     "prettier": "^3.2.5",
     "rimraf": "^5.0.5",
-    "typescript": "^5.4.2"
+    "typescript": "^5.4.2",
+    "vitest": "^4.0.17"
   },
   "peerDependencies": {
     "webpack": ">=4.0.0"
@@ -84,5 +84,6 @@
   "bugs": {
     "url": "https://github.com/langtail/macaly-tagger/issues"
   },
-  "homepage": "https://github.com/langtail/macaly-tagger#readme"
+  "homepage": "https://github.com/langtail/macaly-tagger#readme",
+  "packageManager": "pnpm@9.15.9+sha512.68046141893c66fad01c079231128e9afb89ef87e2691d69e4d40eee228988295fd4682181bae55b58418c3a253bde65a505ec7c5f9403ece5cc3cd37dcf2531"
 }