Pluggable Widgets Tools for Bun

⚠️ IMPORTANT DISCLAIMER: This is NOT an official Mendix tool. This is a community-maintained fork of the original @mendix/pluggable-widgets-tools that has been optimized for the Bun runtime. For the official Mendix tool, please use @mendix/pluggable-widgets-tools.

About

A community-maintained fork of the official Mendix pluggable widgets tools, optimized for Bun runtime to build, test, format, run, release and lint your Pluggable Widgets. This fork provides faster installation and execution compared to the original npm version while maintaining full compatibility with Mendix widgets.

How to install

Using Bun (Recommended):

bun add @gg-o-bp/mendix-pluggable-widgets-tools-bun

Using npm (for compatibility only):

npm install @gg-o-bp/mendix-pluggable-widgets-tools-bun

Note: This package is optimized for Bun. Using npm is only supported for legacy compatibility. We strongly recommend using Bun for optimal performance.

Requirements:

• Bun: Version 1.2.0 or higher (recommended for faster performance)
• Node.js: Version 20 or higher with npm 8 or higher

Even better is creating your widget using the Bun-optimized Pluggable Widgets Generator which scaffolds the correct project setup:

bunx @gg-o-bp/mendix-generator-widget-bun MyWidget

How to use

In your package.json scripts, use the following command with the desired task: pluggable-widgets-tools task

Available tasks

All tasks are executed using bun run:

• start:web Build and watch the changes of your Web widget. Your web app will reload automatically to reflect changes. You need to run the command on the same machine as Studio Pro.
• start:native Build and watch the changes of your Native widget. Your native app will reload automatically to reflect changes.
• build:web Build your Web widget
• build:native Build your Native widget
• release:web Create a release build of your Web widget
• release:native Create a release build of your Native widget
• lint Lint your project using ESLint and Prettier
• lint:fix Fix lint problems/warning of ESLint and Prettier
• format Format your code using Prettier
• test:unit:web Run unit tests for your Web widget. Accepts option --u to update snapshots, --no-cache to remove existing caches, --ci assumes use of a CI environment, --coverage to support coverage test.
• test:unit:native Run unit tests for your Native widget. Accepts option --u to update snapshots, --no-cache to remove existing caches, --ci assumes use of a CI environment, --coverage to support coverage test.

Example

  "name": "MyWidget",
  "widgetName": "com.company.widgets.MyWidget",
  "version": "1.0.0",
  "config": {
    "projectPath": "../MxTestProject/",
    "mendixHost": "http://localhost:8080",
    "developmentPort": "3000"
  },
  "scripts": {
    "build": "pluggable-widgets-tools build:web",
    "lint": "pluggable-widgets-tools lint",
    "lint:fix": "pluggable-widgets-tools lint:fix",
    "test:unit": "pluggable-widgets-tools test:unit --coverage"
  }

Project layout

• src/
  • MyWidget.xml - widget definition
  • MyWidget.[tj]sx - widget client component
  • MyWidget.editorPreview.[tj]sx - (optional) widget preview
  • MyWidget.editorConfig.[tj]s - (optional) widget editor configuration
  • components/
    • MyComponent.[tj]s - code of widget's components
    • __tests__/
      • MyComponent.spec.[tj]s - tests for widget's components
  • .eslint.js - configuration for ESLint. We recommend to just re-export @gg-o-bp/mendix-pluggable-widgets-tools-bun/configs/eslint.ts.base.json
  • prettier.config.js - configuration for Prettier. We recommend to just re-export @gg-o-bp/mendix-pluggable-widgets-tools-bun/configs/prettier.base.json
  • tsconfig.json - configuration for TypeScript. We recommend to just extend @gg-o-bp/mendix-pluggable-widgets-tools-bun/configs/tsconfig.base.json
  • rollup.config.[m]js - (optional) custom configurations for rollup bundler. The standard configuration is passed as an argument named configDefaultConfig.
  • package.json - widget package definitions, including its dependencies, scripts, and basic configuration (widgetName and config.projectPath in particular)

Performance Benefits

Using Bun provides:

• Faster installation: Up to 10x faster package installation
• Reduced disk usage: More efficient package management
• Better performance: Faster script execution and build times
• Built-in TypeScript support: No additional configuration needed

Migrating from @mendix/pluggable-widgets-tools

1. Replace the package:

   bun remove @mendix/pluggable-widgets-tools
   bun add @gg-o-bp/mendix-pluggable-widgets-tools-bun

2. Update your scripts to use bun run instead of npm run for better performance

3. All commands and configurations remain the same

Migrating from previous versions

• 10.17 includes an upgrade from Rollup 2 to 3. Custom rollup.config.js files likely require changes.
• Webpack bundler is changed to a Rollup. You must migrate your custom configuration.
• Update pluggable-widgets-tools commands used in your package.json file to one of the described in this readme. In particular start:js, start:ts, and start:server commands should be changed to start:web.
• You now can use named exports in your widget. That is, you can write export MyWidget; instead of export default MyWidget;.
• You should not use react-hot-loader anymore. You can remove the call it, which is anyway replaced with a noop function.

Issues and Support

• For issues related to this Bun-optimized fork, please report them on GitHub
• For issues related to the widget tools functionality itself, please refer to the official Mendix widgets-tools repository

Acknowledgments

This project is based on the excellent work by the Mendix team on the official pluggable-widgets-tools. We are grateful for their open-source contribution to the Mendix community.