babel-plugin-reactylon 1.2.0 → 1.3.0

package/README.md

@@ -3,11 +3,24 @@
 A Babel plugin designed to enable **tree shaking** in a Reactylon application. It statically analyzes Reactylon JSX elements and automatically manages imports and registrations of the relative Babylon.js classes, ensuring only the necessary parts of the Babylon.js library are included in the final bundle.
 
 ## Features
-- Automatic detection of Babylon.js components used in JSX
-- Automatic import of Babylon.js classes from `@babylonjs/core` e `@babylonjs/gui`
-- Implicit side effects management (detect prototype-level side effects in Babylon.js and ensures proper runtime behaviour)
-- Explicit side effects support (allows users to define custom side effects manually)
-- Automatic registration (ensures that used Babylon.js classes are registered within Reactylon's internal registry)
+- **Automatic JSX component resolution & import generation**
+  
+    Automatically detects the Babylon.js components used in JSX (e.g. `<box />`, `<arcRotateCamera />`, `<directionalLight />`) and generates the correct tree-shakable ES6 imports from `@babylonjs/core` and `@babylonjs/gui`.
+
+- **Automatic Babylon.js side-effect handling**
+  
+    Identifies all Babylon.js features that require side-effect imports and injects them automatically, including:
+
+  - **JSX-prop–based side effects**
+  
+    Triggered by props like `checkCollisions`, `physicsOptions`, `showBoundingBox`, or by specific JSX elements such as `<audio>` or `<highlightLayer>`.
+  
+  - **Prototype-based side effects** 
+    
+    Derived from method calls such as `scene.createDefaultCameraOrLight()` that rely on prototype extensions.
+  
+  - **Constructor-based side effects** like `new ShadowGenerator(...)` that require additional runtime modules.
+
 
 ## Configuration
 
@@ -82,18 +95,6 @@ export default defineConfig({
 })
 ```
 
-### Additional configurations
-Additionally you can manually define extra side effects (see [Babylon.js ES6 support FAQ](https://doc.babylonjs.com/setup/frameworkPackages/es6Support/#faq)).
-
-```js
-['babel-plugin-reactylon', {
-  // additional side effects (optional)
-  sideEffects: [
-    '@babylonjs/core/Engines/Extensions/engine.query.js'
-  ]
-}]
-```
-
 ## How it works
 The plugin analyzes your JSX code by scanning for Reactylon components. When a component is detected, it automatically imports the corresponding Babylon.js class and registers it with Reactylon, making it available in the rendering context. To remain consistent with Babylon.js modular architecture, the plugin selects the *deepest available class* implementation by recursively scanning the directory tree. This approach ensures that the most specific and optimized module is used, preventing unwanted side effects that could compromise tree shaking.
 

package/build/index.js

@@ -2,14 +2,60 @@ import { types as t } from '@babel/core';
 import { declare } from "@babel/helper-plugin-utils";
 import { BabylonPackages, builders, CollidingComponents, ReversedCollidingComponents } from 'reactylon';
 import ParserUtils from './ParserUtils.js';
+/**
+ * Internal test purpose only: reset to isolate each test
+*/
+export function __resetReactylonBabelPluginStateForTests() {
+    babylonImportsSpecifiers.clear();
+    fileSideEffects.clear();
+    lastImport = null;
+    shouldSkipFile = false;
+    initialized = false;
+}
+/**
+ * JSX tag name -> ImportSpecifier Babel
+ * Es: "box" -> import { _CreateBox } from "@babylonjs/core/Meshes/Builders/boxBuilder"
+ */
 const babylonImportsSpecifiers = new Map();
-const sideEffects = [];
+/**
+ * Specific file side-effects for single file
+ */
+let fileSideEffects = new Set();
 let lastImport = null;
 let initialized = false;
 let coreExportsMap = {};
 let coreSideEffectsMap = {};
 let guiExportsMap = {};
 //let guiSideEffectsMap: Record<string, string> = {};
+/**
+ * Reactylon "root" components: they are used as structural/entry-point
+ * components and for side-effect detection, but they must NOT be imported
+ * from Babylon or registered in Reactylon's inventory.
+ */
+const ROOT_REACTYLON_COMPONENTS = new Set([
+    'Engine',
+    'NativeEngine',
+    'Scene',
+    'Microgestures'
+]);
+/**
+ * Manual mapping for constructor-based side effects.
+ *
+ * This map exists specifically for side effects that are triggered when a
+ * class is instantiated (e.g. `new ShadowGenerator(...)`). These cases do
+ * not appear in the prototype-based analysis performed by
+ * `ParserUtils.getExportsAndSideEffects`, which detects only side effects
+ * added through prototype mutations or `defineProperty`.
+ *
+ * Reference: Babylon.js ES6 support FAQ (lists both prototype- and
+ * constructor-based side effects; only the constructor-based ones go in this map)
+ * https://doc.babylonjs.com/setup/frameworkPackages/es6Support/#faq
+ *
+ */
+const constructorCoreSideEffectsMap = {
+    ShadowGenerator: ['@babylonjs/core/Lights/Shadows/shadowGeneratorSceneComponent']
+};
+let shouldSkipFile = false;
 function capitalizeFirstLetter(str) {
     return `${str.charAt(0).toUpperCase()}${str.slice(1)}`;
 }
@@ -20,32 +66,32 @@ export default declare((api) => {
             options.plugins.push('jsx');
         },
         pre() {
-            var _a;
             if (!initialized) {
-                const options = this.opts;
                 const coreExportsAndSideEffects = ParserUtils.generateExportsAndSideEffects('@babylonjs/core');
                 coreExportsMap = coreExportsAndSideEffects.exports;
                 coreSideEffectsMap = coreExportsAndSideEffects.sideEffects;
                 const guiExportsAndSideEffects = ParserUtils.generateExportsAndSideEffects('@babylonjs/gui');
                 guiExportsMap = guiExportsAndSideEffects.exports;
                 //guiSideEffectsMap = guiExportsAndSideEffects.sideEffects;
-                // Add explicit side effects (additional side effects declared by user)
-                (_a = options === null || options === void 0 ? void 0 : options.sideEffects) === null || _a === void 0 ? void 0 : _a.forEach((sideEffect) => {
-                    sideEffects.push(t.importDeclaration([], t.stringLiteral(sideEffect)));
-                });
                 initialized = true;
             }
         },
         post() {
             babylonImportsSpecifiers.clear();
             lastImport = null;
+            fileSideEffects.clear();
+            shouldSkipFile = false;
         },
         visitor: {
             ImportDeclaration(importPath) {
+                if (shouldSkipFile)
+                    return;
                 lastImport = importPath;
             },
             JSXOpeningElement(path) {
                 var _a;
+                if (shouldSkipFile)
+                    return;
                 // Don't include non-React JSX
                 // https://github.com/facebook/jsx/issues/13
                 const { name, attributes } = path.node;
@@ -88,7 +134,8 @@ export default declare((api) => {
                 // Don't include colliding React JSX components
                 if (type in ReversedCollidingComponents)
                     return;
-                if (!babylonImportsSpecifiers.has(type)) {
+                const shouldRegisterComponent = !ROOT_REACTYLON_COMPONENTS.has(type);
+                if (shouldRegisterComponent && !babylonImportsSpecifiers.has(type)) {
                     const normalizedType = type in CollidingComponents ? CollidingComponents[type] : type;
                     const isBuilder = builders.includes(normalizedType);
                     const className = isBuilder ? `Create${capitalizeFirstLetter(normalizedType)}` : capitalizeFirstLetter(normalizedType);
@@ -98,38 +145,93 @@ export default declare((api) => {
                     }
                 }
                 // Add implicit side effects (derived from static parse of JSX Reactylon code)
-                const isMultipleCanvas = type === 'Engine' && attributes.some(attr => t.isJSXAttribute(attr) && attr.name.name === "isMultipleCanvas");
+                // Don't restrict the check on Engine component (type === 'Engine' && ...) because the user can create an alias of Engine's Reactylon component
+                const isMultipleCanvas = attributes.some(attr => t.isJSXAttribute(attr) && attr.name.name === "isMultipleCanvas");
                 if (isMultipleCanvas) {
-                    sideEffects.push(t.importDeclaration([], t.stringLiteral('@babylonjs/core/Engines/AbstractEngine/abstractEngine.views.js')));
+                    fileSideEffects.add('@babylonjs/core/Engines/AbstractEngine/abstractEngine.views');
                 }
-                const isPhysicsEngine = type === 'Scene' && attributes.some(attr => t.isJSXAttribute(attr) && attr.name.name === "physicsOptions");
+                // Don't restrict the check on Scene component (type === 'Scene' && ...) because the user can create an alias of Scene's Reactylon component
+                const isPhysicsEngine = attributes.some(attr => t.isJSXAttribute(attr) && attr.name.name === "physicsOptions");
                 if (isPhysicsEngine) {
-                    sideEffects.push(t.importDeclaration([], t.stringLiteral('@babylonjs/core/Physics/physicsEngineComponent.js')));
+                    fileSideEffects.add('@babylonjs/core/Physics/physicsEngineComponent');
                 }
                 const isAudio = type === 'sound';
                 if (isAudio) {
                     // Audio v1
-                    sideEffects.push(t.importDeclaration([], t.stringLiteral('@babylonjs/core/Audio/audioSceneComponent.js')));
-                    // sideEffects.push(t.importDeclaration([], t.stringLiteral('@babylonjs/core/Audio/audioEngine.js')));
+                    fileSideEffects.add('@babylonjs/core/Audio/audioSceneComponent');
+                    // fileSideEffects.add('@babylonjs/core/Audio/audioEngine');
                 }
                 const isCheckCollisions = attributes.some(attr => t.isJSXAttribute(attr) && attr.name.name === "checkCollisions");
                 if (isCheckCollisions) {
-                    sideEffects.push(t.importDeclaration([], t.stringLiteral('@babylonjs/core/Collisions/collisionCoordinator.js')));
+                    fileSideEffects.add('@babylonjs/core/Collisions/collisionCoordinator');
                 }
                 const isHighlightLayer = type === 'highlightLayer';
                 if (isHighlightLayer) {
-                    sideEffects.push(t.importDeclaration([], t.stringLiteral('@babylonjs/core/Layers/effectLayerSceneComponent.js')));
+                    fileSideEffects.add('@babylonjs/core/Layers/effectLayerSceneComponent');
                 }
                 const isBoundingBox = attributes.some(attr => t.isJSXAttribute(attr) && attr.name.name === "showBoundingBox");
                 if (isBoundingBox) {
-                    sideEffects.push(t.importDeclaration([], t.stringLiteral('@babylonjs/core/Rendering/boundingBoxRenderer.js')));
+                    fileSideEffects.add('@babylonjs/core/Rendering/boundingBoxRenderer');
                 }
-                // add here other side effects (https://doc.babylonjs.com/setup/frameworkPackages/es6Support/#faq)
             },
             Program: {
+                enter(path) {
+                    var _a, _b;
+                    const filename = ((_b = (_a = this.file) === null || _a === void 0 ? void 0 : _a.opts) === null || _b === void 0 ? void 0 : _b.filename) || '';
+                    if (filename.includes('node_modules')) {
+                        //console.log(this.file?.opts?.filename);
+                        shouldSkipFile = true;
+                        path.stop();
+                        return;
+                    }
+                    shouldSkipFile = false;
+                },
                 exit(path) {
-                    if (!babylonImportsSpecifiers.size)
+                    if (shouldSkipFile)
                         return;
+                    path.traverse({
+                        // Add implicit prototype-based side effects detected from call expressions, e.g. scene.createDefaultCameraOrLight()
+                        CallExpression(callPath) {
+                            const callee = callPath.node.callee;
+                            if (t.isMemberExpression(callee)) {
+                                const property = callee.property;
+                                if (t.isIdentifier(property)) {
+                                    const sideEffectPath = coreSideEffectsMap[property.name];
+                                    // exclude assets folder containing .wasm and relative .js files
+                                    if (typeof sideEffectPath === 'string' && !sideEffectPath.startsWith('@babylonjs/core/assets/')) {
+                                        fileSideEffects.add(sideEffectPath);
+                                        // callPath.stop();
+                                    }
+                                }
+                            }
+                        },
+                        // Add constructor-based side effects detected from "new" expressions, e.g. new ShadowGenerator(...)
+                        NewExpression(newPath) {
+                            const callee = newPath.node.callee;
+                            let name;
+                            if (t.isIdentifier(callee)) {
+                                // e.g.: new ShadowGenerator(...)
+                                name = callee.name;
+                            }
+                            else if (t.isMemberExpression(callee) && t.isIdentifier(callee.property)) {
+                                // new BABYLON.ShadowGenerator(...)
+                                name = callee.property.name;
+                            }
+                            if (!name)
+                                return;
+                            const sideEffectPaths = constructorCoreSideEffectsMap[name];
+                            if (!sideEffectPaths)
+                                return;
+                            for (const sideEffectPath of sideEffectPaths) {
+                                fileSideEffects.add(sideEffectPath);
+                            }
+                        }
+                    });
+                    const hasJSXReactylon = babylonImportsSpecifiers.size > 0;
+                    const hasFileSideEffects = fileSideEffects.size > 0;
+                    if (!hasJSXReactylon && !hasFileSideEffects) {
+                        return;
+                    }
                     const babylonImports = [];
                     babylonImportsSpecifiers.forEach((importSpecifier, type) => {
                         let packageName = null;
@@ -146,37 +248,28 @@ export default declare((api) => {
                         const importDeclaration = t.importDeclaration([importSpecifier], t.stringLiteral(importPath));
                         babylonImports.push([type, importDeclaration, packageName]);
                     });
-                    const registerSpecifier = t.importSpecifier(path.scope.generateUidIdentifier('register'), t.identifier('register'));
-                    const registerImportDeclaration = t.importDeclaration([registerSpecifier], t.stringLiteral('reactylon'));
-                    const registerCall = t.expressionStatement(t.callExpression(registerSpecifier.local, [
-                        t.objectExpression(babylonImports.map(([type, importDeclaration, packageName]) => {
-                            const importSpecifier = importDeclaration.specifiers[0];
-                            return t.objectProperty(t.stringLiteral(type), t.arrayExpression([
-                                importSpecifier.local,
-                                t.numericLiteral(packageName)
-                            ]), false, false);
-                        })),
-                    ]));
-                    const babylonImportDeclarations = babylonImports.map(([, importDeclaration]) => importDeclaration);
-                    // Add implicit prototype-level side effects (derived from static parse of JavaScript code, e.g. scene.createDefaultCameraOrLight)
-                    path.traverse({
-                        CallExpression(callPath) {
-                            const callee = callPath.node.callee;
-                            if (t.isMemberExpression(callee)) {
-                                const property = callee.property;
-                                if (t.isIdentifier(property)) {
-                                    const sideEffectPath = coreSideEffectsMap[property.name];
-                                    // exclude assets folder containing .wasm and relative .js files
-                                    if (sideEffectPath && !sideEffectPath.startsWith('@babylonjs/core/assets/')) {
-                                        sideEffects.push(t.importDeclaration([], t.stringLiteral(sideEffectPath)));
-                                        // callPath.stop();
-                                    }
-                                }
-                            }
-                        }
-                    });
+                    const nodes = [];
+                    if (hasJSXReactylon) {
+                        const registerSpecifier = t.importSpecifier(path.scope.generateUidIdentifier('register'), t.identifier('register'));
+                        const registerImportDeclaration = t.importDeclaration([registerSpecifier], t.stringLiteral('reactylon'));
+                        const registerCall = t.expressionStatement(t.callExpression(registerSpecifier.local, [
+                            t.objectExpression(babylonImports.map(([type, importDeclaration, packageName]) => {
+                                const importSpecifier = importDeclaration.specifiers[0];
+                                return t.objectProperty(t.stringLiteral(type), t.arrayExpression([
+                                    importSpecifier.local,
+                                    t.numericLiteral(packageName)
+                                ]), false, false);
+                            })),
+                        ]));
+                        const babylonImportDeclarations = babylonImports.map(([, importDeclaration]) => importDeclaration);
+                        nodes.push(registerCall, registerImportDeclaration, ...babylonImportDeclarations);
+                    }
+                    // Add all file side effects (explicit, implicit prototype-based)
+                    for (const pathStr of fileSideEffects) {
+                        nodes.push(t.importDeclaration([], t.stringLiteral(pathStr)));
+                    }
                     // Add imports and call register
-                    for (const node of [registerCall, registerImportDeclaration, ...babylonImportDeclarations, ...sideEffects]) {
+                    for (const node of nodes) {
                         if (lastImport) {
                             lastImport.insertAfter(node);
                         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "babel-plugin-reactylon",
-  "version": "1.2.0",
+  "version": "1.3.0",
   "description": "Babel plugin to enable tree-shaking of Babylon.js classes within a Reactylon application.",
   "main": "build/index.js",
   "type": "module",