Pluggable Widgets Tools

About

A toolset to build, test, format, run, release and lint your Pluggable Widgets

How to install

Install via NPM using npm install @mendix/pluggable-widgets-tools (use node.js version >= 12). When installing via NPM v7.x.x, use npm install @mendix/pluggable-widgets-tools --legacy-peer-deps. Even better is creating your widget using Pluggable Widgets Generator which scaffolds the correct project setup.

How to use

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

Available tasks

• 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 @mendix/pluggable-widgets-tools/configs/eslint.ts.base.json
  • prettier.config.js - configuration for Prettier. We recommend to just re-export @mendix/pluggable-widgets-tools/configs/prettier.base.json
  • tsconfig.json - configuration for TypeScript. We recommend to just extend @mendix/pluggable-widgets-tools/configs/tsconfig.base.json
  • rollup.config.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)

Migrating from previous versions

• 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.