Skip to content

Creating a ThingWorx Widget Extension

Creating a ThingWorx Extension

The following topic covers the process of using the ThingWorx Visual SDK Utility to create a widget extension. You can use the utility as a global CLI tool from any location on your system.

Setting Up Your Environment for the CLI

  • Download and extract the twx-wc-sdk-utility-[VERSION].zip file, and then run the following commands:

    Change your directory to the utility folder:

      cd twx-wc-sdk-utility

    then run:

    npm link

Using the Command Line Interface

Utility input

Before running the utility, create a working folder. You can create the folder on any location on your system. Your working folder should have the following file structure:

  • input/widgets.json - Specifies the web component widgets that you want to include
  • .npmrc - Specifies the configuration options that are required to connect your component to an npm registry. Make sure the file contains the following configuration options:

  • input/widgets/ - Specifies properties for the widget extension

  • input/ui/ - Specifies ThingWorx-related wrapping code that adapts the web components to ThingWorx widgets. All components inherit from the widgetWrapper code (which is also in this folder).
  • input/styles - Contains theming files for the widget

Running the utility

  • Open a command prompt, and then change your directory to your working folder.
  • Run the following command to create the extension:


The utility creates a ThingWorx a extension that can you can import and use in Mashup Builder.

You can use the following options to configure the utility:

Parameter Description
--debug Sets the logger level to debug.
--skip-pack Creates the extension without compressing the output into a ZIP archive.
-s, --skip-install Skips the installation step when running the utility. The install step is only required for the first time.
--lock Generates a package-json.lock file (don't use --no-lock mode)'.
--excludelibraries Specifies the library names to exclude. See mub/input/static/ootbLibs.json to check what libraries are already included or excluded from the ptcs-widgets package. You should specify the excluded folder names as they appear in node_modules. For example: gulp --excludelibraries @polymer,mocha,@webcomponents
clean Removes the latest artifact and all temporary code that is used to build it.

Running the utility without using an npm registry

Before using the SDK utility, we recommend that you publish your web components to an npm registry. By default, the SDK utility retrieves the web component using the link and user credentials that are stored in the .npmrc file. You can run the utility without this file, unless it is required by a dependency in your widgets.json file. To use the utility without using a .npmrc file, perform the following steps:

  1. Create a folder named tmp/ on the same level as your input/ folder.
  2. Copy your web component folder manually to the tmp/ folder.
  3. Edit the htmlImports section in the <web_component>.json file of your web component input/widgets folder to specify the location of your component:

    "htmlImports": [
        "from": "npm",
        "id": "simple-el",
        "version": "file:simple-el",
        "url": "simple-el/simple-el.js"
  4. Run the SDK utility using the mub command.

Utility output

When you run the utility, the generated files are placed under the dist folder:

  • By default, the generated files are compressed into a ZIP file named dist/{package name or extension name}.zip that you can import into the ThingWorx Platform.
  • When you run the utility with the --skip-pack parameter, a folder is created and the extension files are placed under dist/target.

Viewing logs

You can view the logs for the utility under the log folder of your working folder. The folder contains two files:

  • combined.log - Contains all log messages
  • error.log - Contains error log messages

Advanced configuration

For more detailed information about widget configuration, refer to Packaging a Web Component as a ThingWorx Widget.