npm package: @gg-o-bp/mendix-pluggable-widgets-tools-bun
Description: Community fork of Mendix Pluggable Widgets Tools optimized for Bun runtime (NOT an official Mendix tool)
Latest version: 10.21.2

# Pluggable Widgets Tools for Bun

![npm version](https://badge.fury.io/js/%40gg-o-bp%2Fmendix-pluggable-widgets-tools-bun.svg)
![Mendix 8](https://img.shields.io/badge/mendix-8.0.0-brightgreen.svg)
![Bun Compatible](https://img.shields.io/badge/bun->=1.2.0-brightgreen.svg)
![npm](https://img.shields.io/npm/dm/@gg-o-bp/mendix-pluggable-widgets-tools-bun)

> ⚠️ **IMPORTANT DISCLAIMER**: This is NOT an official Mendix tool. This is a community-maintained fork of the original [@mendix/pluggable-widgets-tools](https://www.npmjs.com/package/@mendix/pluggable-widgets-tools) that has been optimized for the [Bun](https://bun.sh/) runtime. For the official Mendix tool, please use [@mendix/pluggable-widgets-tools](https://www.npmjs.com/package/@mendix/pluggable-widgets-tools).

## About

A community-maintained fork of the official Mendix pluggable widgets tools, optimized for [Bun](https://bun.sh/) runtime to build, test, format, run, release and lint your [Pluggable Widgets](https://docs.mendix.com/apidocs-mxsdk/apidocs/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):
```bash
bun add @gg-o-bp/mendix-pluggable-widgets-tools-bun
```

### Using npm (for compatibility only):
```bash
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](https://www.npmjs.com/package/@gg-o-bp/mendix-generator-widget-bun) which scaffolds the correct project setup:
```bash
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

```json
  "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](https://docs.mendix.com/apidocs-mxsdk/apidocs/property-types-pluggable-widgets)
    -   `MyWidget.[tj]sx` - widget [client component](https://docs.mendix.com/apidocs-mxsdk/apidocs/client-apis-for-pluggable-widgets)
    -   `MyWidget.editorPreview.[tj]sx` - (optional) widget [preview](https://docs.mendix.com/apidocs-mxsdk/apidocs/studio-apis-for-pluggable-widgets)
    -   `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](https://rollupjs.org/guide/en/) 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:
   ```bash
   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](./docs/rollup3-guide.md).
-   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](https://github.com/GG-O-BP/mendix-widgets-tools-forbun/issues)
- For issues related to the widget tools functionality itself, please refer to the [official Mendix widgets-tools repository](https://github.com/mendix/widgets-tools/issues)

## Acknowledgments

This project is based on the excellent work by the Mendix team on the [official pluggable-widgets-tools](https://github.com/mendix/widgets-tools). We are grateful for their open-source contribution to the Mendix community.