babel-plugin-reactylon 1.0.0

package/LICENSE.md

@@ -0,0 +1,21 @@
+# MIT License
+
+Copyright (c) 2024-2025 Simone De Vittorio.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,145 @@
+# Babel Plugin Reactylon
+
+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)
+
+## Configuration
+
+### Babel
+
+Add the plugin to your Babel configuration:
+
+```js
+// babel.config.js
+module.exports = {
+  plugins: [
+    ['babel-plugin-reactylon']
+  ]
+};
+```
+
+### Webpack
+Add the plugin to your Webpack configuration. The following configuration demonstrates how to integrate the plugin using both `ts-loader` and `babel-loader`:
+
+```ts
+// webpack.config.js
+module.exports = {
+module: {
+        rules: [
+            {
+                test: /\.tsx?$/,
+                use: [
+                    {
+                        loader: 'ts-loader',
+                        options: {
+                            transpileOnly: true
+                        }
+                    },
+                    {
+                        loader: "babel-loader",
+                        options: {
+                            presets: [
+                                ["@babel/preset-env"],
+                                ["@babel/preset-react", { runtime: "automatic" }],
+                                "@babel/preset-typescript"
+                            ],
+                            plugins: [
+                                ['babel-plugin-reactylon']
+                            ]
+                        }
+                    },
+                ],
+                exclude: '/node_modules/',
+            },
+        ],
+    },
+};
+```
+
+### Additional configurations
+Additionally you can manually define extra side effects (see [Babylon.js ES6 support FAQ](https://doc.babylonjs.com/setup/frameworkPackages/es6Support/#faq)) or specify a custom `node_modules` path (useful if you are working with a monorepo setup).
+
+```js
+['babel-plugin-reactylon', {
+  // additional side effects (optional)
+  sideEffects: [
+    '@babylonjs/core/Engines/Extensions/engine.query.js'
+  ]
+  // node modules path (optional)
+  nodeModulesPath: '../../node_modules'
+}]
+```
+
+## 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.
+
+### Example
+
+#### Input
+
+```jsx
+<>
+    <standardMaterial name='material'>
+        <texture url='texture-url' />
+    </standardMaterial>
+    <box />
+    <sphere />
+    <text3D />
+    <standardMaterial name='material-1' />
+    <standardMaterial name='material-2' />
+    <pointLight 
+        name='point'
+        position={new Vector3(0, 1, 0)}
+        diffuse={Color3.Red()}
+        specular={Color3.Green()}
+    />
+    <directionalLight
+        name='directional'
+        direction={new Vector3(0, -1, 0)}
+        diffuse={Color3.Red()}
+        specular={Color3.Green()}
+    />
+</>;
+```
+#### Output
+```js
+import { DirectionalLight as _DirectionalLight } from "@babylonjs/core/Lights/directionalLight";
+import { PointLight as _PointLight } from "@babylonjs/core/Lights/pointLight";
+import { CreateText as _CreateText } from "@babylonjs/core/Meshes/Builders/textBuilder";
+import { CreateSphere as _CreateSphere } from "@babylonjs/core/Meshes/Builders/sphereBuilder";
+import { CreateBox as _CreateBox } from "@babylonjs/core/Meshes/Builders/boxBuilder";
+import { Texture as _Texture } from "@babylonjs/core/Materials/Textures/texture";
+import { StandardMaterial as _StandardMaterial } from "@babylonjs/core/Materials/standardMaterial";
+import { register as _register } from "reactylon";
+_register({
+  "standardMaterial": [_StandardMaterial, 0],
+  "texture": [_Texture, 0],
+  "box": [_CreateBox, 0],
+  "sphere": [_CreateSphere, 0],
+  "text3D": [_CreateText, 0],
+  "pointLight": [_PointLight, 0],
+  "directionalLight": [_DirectionalLight, 0]
+});
+<>
+    <standardMaterial name='material'>
+        <texture url='texture-url' />
+    </standardMaterial>
+    <box /> 
+    <sphere /> 
+    <text3D /> 
+    <standardMaterial name='material-1' />
+    <standardMaterial name='material-2' /> 
+    <pointLight name='point' position={new Vector3(0, 1, 0)} diffuse={Color3.Red()} specular={Color3.Green()} /> 
+    <directionalLight name='directional' direction={new Vector3(0, -1, 0)} diffuse={Color3.Red()} specular={Color3.Green()} />
+</>;
+```
+
+## Acknowledgements
+This project is highly inspired by [React Three Babel](https://github.com/pmndrs/react-three-babel).
+Special thanks to the authors for their work, which served as a foundation and reference for this implementation.

package/build/ParserUtils.js

@@ -0,0 +1,102 @@
+import path from 'path';
+import fs from 'fs';
+class ParserUtils {
+    /**
+    * It extracts exports and side effects from a file
+    * @param filePath - file path to analyze
+    * @returns an object containing the discovered exports and side effects
+    */
+    static getExportsAndSideEffects(filePath) {
+        const content = fs.readFileSync(filePath, 'utf-8');
+        const exports = new Set();
+        const sideEffects = new Set();
+        // Default export
+        if (/export\s+default\s+/g.test(content)) {
+            exports.add('default');
+        }
+        // Named export
+        const namedExports = content.match(/export\s+{([^}]+)}/g);
+        if (namedExports) {
+            namedExports.forEach(exp => {
+                //@ts-ignore
+                exp.replace(/export\s+{([^}]+)}/, (_, group) => {
+                    group.split(',').forEach((e) => exports.add(e.trim()));
+                });
+            });
+        }
+        // Other export
+        const individualExports = content.match(/export\s+(const|let|var|function|class)\s+([a-zA-Z0-9_]+)/g);
+        if (individualExports) {
+            individualExports.forEach(exp => {
+                //@ts-ignore
+                exp.replace(/export\s+(const|let|var|function|class)\s+([a-zA-Z0-9_]+)/, (_, __, name) => {
+                    exports.add(name);
+                });
+            });
+        }
+        // Component.prototype.method
+        const prototypeMatches = content.match(/(\w+)\.prototype\.(\w+)\s*=/g);
+        if (prototypeMatches) {
+            prototypeMatches.forEach(prototype => {
+                const methodName = prototype.match(/\.prototype\.(\w+)/)[1];
+                sideEffects.add(methodName);
+            });
+        }
+        // Object.defineProperty(Class.prototype, "method", { })'
+        const definePropertyMatches = content.match(/Object\.defineProperty\(\s*(\w+)\.prototype\s*,\s*["'](\w+)["']/g);
+        if (definePropertyMatches) {
+            definePropertyMatches.forEach(prototype => {
+                const methodName = prototype.match(/Object\.defineProperty\(\s*\w+\.prototype\s*,\s*["'](\w+)["']/)[1];
+                sideEffects.add(methodName);
+            });
+        }
+        return {
+            exports: Array.from(exports),
+            sideEffects: Array.from(sideEffects)
+        };
+    }
+    /**
+    * It scans a directory and it creates a map of exports and side effects
+    * @param dir - directory to scan
+    * @param exportsMap - exports map to populate
+    * @param sideEffectsMap - side effects map to populate
+    */
+    static scanDirectory(dir, exportsMap, sideEffectsMap) {
+        const files = fs.readdirSync(dir);
+        files.forEach(file => {
+            const fullPath = path.join(dir, file);
+            if (fs.statSync(fullPath).isDirectory()) {
+                this.scanDirectory(fullPath, exportsMap, sideEffectsMap);
+            }
+            else if (file.endsWith('.js') || file.endsWith('.mjs') || file.endsWith('.ts')) {
+                const importPath = (fullPath.replace(/\.(js|mjs|ts)$/, '')).replace(/^node_modules\//, '');
+                const { exports, sideEffects } = this.getExportsAndSideEffects(fullPath);
+                exports.forEach(exp => {
+                    exportsMap[exp] = importPath;
+                });
+                sideEffects.forEach(sideEffect => {
+                    sideEffectsMap[sideEffect] = importPath;
+                });
+            }
+        });
+    }
+    /**
+    * High level function used to generate the maps of exports and side effects for a given module
+    * @param moduleName - module name to analyze
+    * @returns an object containing the discovered exports and side effects maps
+    */
+    static generateExportsAndSideEffects(moduleName, nodeModulesPath) {
+        const modulePath = path.join(nodeModulesPath, moduleName);
+        if (!fs.existsSync(modulePath)) {
+            console.error(`The module "${moduleName}" doesn't exist.`);
+        }
+        const exportsMap = {};
+        const sideEffectsMap = {};
+        this.scanDirectory(modulePath, exportsMap, sideEffectsMap);
+        return {
+            exports: exportsMap,
+            sideEffects: sideEffectsMap
+        };
+    }
+}
+export default ParserUtils;

package/build/index.js

@@ -0,0 +1,172 @@
+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';
+const babylonImportsSpecifiers = new Map();
+const sideEffects = [];
+let lastImport = null;
+let initialized = false;
+let coreExportsMap = {};
+let coreSideEffectsMap = {};
+let guiExportsMap = {};
+//let guiSideEffectsMap: Record<string, string> = {};
+function capitalizeFirstLetter(str) {
+    return `${str.charAt(0).toUpperCase()}${str.slice(1)}`;
+}
+export default declare((api) => {
+    api.assertVersion(7);
+    return {
+        manipulateOptions(_, options) {
+            options.plugins.push('jsx');
+        },
+        pre() {
+            var _a;
+            if (!initialized) {
+                const options = this.opts;
+                const nodeModulesPath = options.nodeModulesPath || 'node_modules';
+                const coreExportsAndSideEffects = ParserUtils.generateExportsAndSideEffects('@babylonjs/core', nodeModulesPath);
+                coreExportsMap = coreExportsAndSideEffects.exports;
+                coreSideEffectsMap = coreExportsAndSideEffects.sideEffects;
+                const guiExportsAndSideEffects = ParserUtils.generateExportsAndSideEffects('@babylonjs/gui', nodeModulesPath);
+                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;
+        },
+        visitor: {
+            ImportDeclaration(importPath) {
+                lastImport = importPath;
+            },
+            JSXOpeningElement(path) {
+                var _a;
+                // Don't include non-React JSX
+                // https://github.com/facebook/jsx/issues/13
+                const { name, attributes } = path.node;
+                if (t.isJSXNamespacedName(name))
+                    return;
+                // Parse identifiers (e.g. <mesh />, <animated.mesh />)
+                let type = 'property' in name ? name.property.name : name.name;
+                const declaration = (_a = path.scope.getBinding(type)) === null || _a === void 0 ? void 0 : _a.path.node;
+                if (t.isVariableDeclarator(declaration)) {
+                    if (t.isStringLiteral(declaration.init)) {
+                        // const Comp = 'value'
+                        // <Comp />
+                        type = declaration.init.value;
+                    }
+                    else if (t.isTemplateLiteral(declaration.init)) {
+                        // const Comp = `value${var}`
+                        // <Comp />
+                        type = declaration.init.quasis.map((n) => n.value.cooked).join('\\w*');
+                    }
+                    else if (t.isBinaryExpression(declaration.init) || t.isAssignmentExpression(declaration.init)) {
+                        // const Comp = 'left' + 'right' || (left += 'right')
+                        // <Comp />
+                        type = [declaration.init.left, declaration.init.right]
+                            .map((o) => (t.isStringLiteral(o) ? o.value : '\\w*'))
+                            .join('');
+                    }
+                    else if (t.isConditionalExpression(declaration.init)) {
+                        // const Comp = test ? 'consequent' : 'alternate'
+                        // <Comp />
+                        type = [declaration.init.consequent, declaration.init.alternate]
+                            .map((o) => (t.isStringLiteral(o) ? o.value : '\\w*'))
+                            .join('|');
+                    }
+                    else {
+                        // const Comp = var
+                        // <Comp />
+                        type = '\\w+';
+                    }
+                }
+                // Don't include colliding React JSX components
+                if (type in ReversedCollidingComponents)
+                    return;
+                if (!babylonImportsSpecifiers.has(type)) {
+                    const normalizedType = type in CollidingComponents ? CollidingComponents[type] : type;
+                    const isBuilder = builders.includes(normalizedType);
+                    const className = isBuilder ? `Create${capitalizeFirstLetter(normalizedType)}` : capitalizeFirstLetter(normalizedType);
+                    if (className in coreExportsMap || className in guiExportsMap) {
+                        const local = path.scope.generateUidIdentifier(className);
+                        babylonImportsSpecifiers.set(type, t.importSpecifier(local, t.identifier(className)));
+                    }
+                }
+                // Add implicit side effects (derived from static parse of JSX Reactylon code)
+                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')));
+                }
+                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')));
+                }
+                // add here other side effects (https://doc.babylonjs.com/setup/frameworkPackages/es6Support/#faq)
+            },
+            Program: {
+                exit(path) {
+                    if (!babylonImportsSpecifiers.size)
+                        return;
+                    const babylonImports = [];
+                    babylonImportsSpecifiers.forEach((importSpecifier, type) => {
+                        let packageName = null;
+                        const importName = importSpecifier.imported.name;
+                        let importPath = '';
+                        if (coreExportsMap[importName]) {
+                            importPath = coreExportsMap[importName];
+                            packageName = BabylonPackages.CORE;
+                        }
+                        else {
+                            importPath = guiExportsMap[importName];
+                            packageName = BabylonPackages.GUI;
+                        }
+                        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 Babylon.js code)
+                    path.traverse({
+                        CallExpression(callPath) {
+                            const callee = callPath.node.callee;
+                            if (t.isMemberExpression(callee)) {
+                                const property = callee.property;
+                                if (t.isIdentifier(property)) {
+                                    if (property.name in coreSideEffectsMap) {
+                                        sideEffects.push(t.importDeclaration([], t.stringLiteral(coreSideEffectsMap[property.name])));
+                                        // callPath.stop();
+                                    }
+                                }
+                            }
+                        }
+                    });
+                    // Add imports and call register
+                    for (const node of [registerCall, registerImportDeclaration, ...babylonImportDeclarations, ...sideEffects]) {
+                        if (lastImport) {
+                            lastImport.insertAfter(node);
+                        }
+                        else {
+                            path.unshiftContainer('body', node);
+                        }
+                    }
+                },
+            },
+        },
+    };
+});

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "babel-plugin-reactylon",
+  "version": "1.0.0",
+  "description": "Babel plugin to enable tree-shaking of Babylon.js classes within a Reactylon application.",
+  "main": "build/index.js",
+  "type": "module",
+  "scripts": {
+    "build": "rm -rf build && tsc",
+    "test": "NODE_OPTIONS=--experimental-vm-modules jest",
+    "test:debug": "NODE_OPTIONS=--experimental-vm-modules node --inspect-brk node_modules/.bin/jest --runInBand"
+  },
+  "dependencies": {
+    "@babel/helper-plugin-utils": "^7.26.5"
+  },
+  "devDependencies": {
+    "@babel/core": "^7.26.10",
+    "@babylonjs/core": "^8.0.0",
+    "@babylonjs/gui": "^8.0.0",
+    "@types/babel__helper-plugin-utils": "^7.10.3",
+    "@types/jest": "^29.5.14",
+    "@types/node": "^20.1.7",
+    "jest": "^29.7.0",
+    "ts-jest": "^29.3.1",
+    "typescript": "^5.8.3"
+  },
+  "peerDependencies": {
+    "@babel/core": "^7.26.10",
+    "@babylonjs/core": "^7.0.0 || ^8.0.0",
+    "@babylonjs/gui": "^7.0.0 || ^8.0.0",
+    "reactylon": "^2.0.0"
+  },
+  "keywords": [
+    "babel",
+    "react",
+    "babylonjs",
+    "reactylon",
+    "plugin",
+    "transform"
+  ],
+  "author": "Simone De Vittorio",
+  "license": "MIT"
+}