create-thingworx-widget

Scaffold a production-ready ThingWorx custom widget project in seconds — just like npm create vite@latest.

Usage

npm create thingworx-widget2@latest
# or
npx create-thingworx-widget2

The CLI will ask you a few questions (widget name, description, ThingWorx server, chart library, etc.) and generate a complete project folder.

What gets generated

MyWidget/
├── src/
│   ├── MyWidget.ide.js        ← Composer (IDE) behaviour & property definitions
│   ├── MyWidget.runtime.js    ← Mashup runtime rendering & data handling
│   ├── MyWidget.ide.css       ← Composer styles
│   ├── MyWidget.runtime.css   ← Runtime styles
│   └── echarts.min.js         ← (placeholder if ECharts selected)
├── build/                     ← Gulp output (gitignored)
├── zip/                       ← Extension .zip ready for TWX import
├── metadata.xml               ← ThingWorx extension manifest
├── gulpfile.js                ← Build pipeline (clean → copy → babel → minify → zip)
├── package.json
├── .gitignore
└── README.md

Generated npm scripts

| Command | Description | | -------------------------- | ------------------------------------------- | | npm run build | Dev build (unminified) → zip/ | | npm run buildProduction | Production build (concat + minify) → zip/ | | npm run upload | Dev build + upload to ThingWorx | | npm run uploadProduction | Production build + upload to ThingWorx |

Publishing to npm

npm login
npm publish --access public

Once published, anyone can run:

npm create thingworx-widget@latest

Local development / testing

# Inside this package folder
node bin/create-thingworx-widget.js

# Or link globally
npm link
create-thingworx-widget

How the build pipeline works

The Gulp pipeline (gulpfile.js) mirrors the proven pattern from the LinearGradientWidget:

1. cleanBuildDir — wipes build/, zip/, lib/
2. copy — copies src/** → build/ui/<PackageName>/ and metadata.xml → build/
3. prepareBuild
   • Babel transpiles all JS (removes ES module import/export for TWX compatibility)
   • In --p (production) mode: reads metadata.xml, groups JS files by IDE/Runtime, concatenates + minifies with Terser, updates metadata.xml references
   • Zips build/ → zip/<PackageName>-dev|min-<version>.zip
4. upload (optional) — POSTs the zip to ThingWorx via the Extension Package Uploader servlet