A local development environment for PTC ThingWorx that lets you write, run, and debug service scripts on your machine before deploying them to a ThingWorx instance.

Each service is a plain .ts file — no imports, no exports, no framework. The code you write here is identical to what you paste into the ThingWorx Composer.

Features

• Run any ThingWorx service locally with a single command
• Full TypeScript autocomplete for Things, me, logger, and input
• me is automatically typed to the correct Thing in each service file
• Service metadata (parameter names, types, defaults, return type) defined in .meta.json files alongside each service
• Services that call Things not defined locally are transparently forwarded to a remote ThingWorx instance via the REST API
• Download Things and their service stubs directly from a ThingWorx server with pull-things.js
• Input can be passed as inline JSON, a JSON file, a number, a string, or a boolean

Requirements

• Node.js 18 or later
• npm

Getting started

# 1. Clone the repository
git clone https://github.com/ssilvestri15/thingworx-local-dev.git
cd thingworx-local-dev

# 2. Install dependencies
npm install

# 3. Copy the environment template and fill in your credentials
# Unix / macOS / Git Bash:
cp .env.example .env
# Windows PowerShell:
# Copy-Item .env.example .env

Edit .env with your ThingWorx server URL and application key:

TWX_BASE_URL=https://your-server.com/Thingworx
TWX_APP_KEY=your-app-key-here

Project structure

thingworx-local-dev/
├── src/
│   ├── Things/
│   │   └── MyThing/               # One directory per Thing
│   │       ├── MyService.ts       # One file per service
│   │       ├── MyService.meta.json# Service metadata (optional)
│   │       ├── me.d.ts            # Auto-generated: types for `me`
│   │       └── tsconfig.json      # Auto-generated: per-Thing compiler config
│   └── types/
│       └── thingworx.d.ts         # Auto-generated: global ambient declarations
├── bootstrap.ts                   # VM runtime: Things proxy, transpiler, remote API
├── pull-things.js                 # Downloads Things from a ThingWorx server
├── run-local.ts                   # CLI entry point
├── sync-types.js                  # Type generation script
├── watch.js                       # File watcher: auto-syncs on save
├── .env                           # Local credentials (not committed)
├── .env.example                   # Credentials template
└── tsconfig.json                  # Root compiler config (bootstrap + runner only)

Adding a Thing and its services

1. Create a directory under src/Things/ with the exact name of the Thing as it appears in ThingWorx.
2. Add one .ts file per service. The filename must match the service name.
3. Optionally add a .meta.json file with the same base name to define parameter types and the return type.
4. Run npm run sync to regenerate the type declarations (or keep npm run watch running).

src/Things/
└── AssetManager/
    ├── GetAssetById.ts
    ├── GetAssetById.meta.json
    └── UpdateAssetStatus.ts

After syncing, Things["AssetManager"] will be fully typed and me inside those files will resolve to the IAssetManager interface.

Writing a service

Service files are plain scripts. The following globals are available without any import:

The value of the last expression in the file is used as the return value, exactly as in ThingWorx.

// src/Things/AssetManager/GetAssetById.ts

logger.info("Fetching asset: " + input.id);

var asset = Things["AssetRepository"].FindById({ id: input.id });

asset;

Service metadata

Place a <ServiceName>.meta.json file alongside a service to enable typed autocomplete, input validation, default value injection, and a richer runner header.

{
  "description": "Returns an asset by its identifier.",
  "inputs": [
    { "name": "id",     "type": "STRING",  "description": "Asset ID", "required": true },
    { "name": "active", "type": "BOOLEAN", "description": "Filter",   "required": false, "defaultValue": true }
  ],
  "result": {
    "type": "INFOTABLE",
    "description": "Matching asset rows",
    "dataShape": "AssetShape"
  }
}

Supported types match ThingWorx base types: STRING, NUMBER, INTEGER, LONG, BOOLEAN, DATETIME, JSON, INFOTABLE, THINGNAME, LOCATION, and others.

When a metadata file is present:

• The runner header shows the full typed signature: GetAssetById(id: STRING, active?: BOOLEAN = true): INFOTABLE
• Required parameters are validated before execution
• Optional parameters with a defaultValue are injected automatically if not provided

Running a service

npx ts-node run-local.ts -- src/Things/AssetManager/GetAssetById.ts

With input:

npx ts-node run-local.ts -- src/Things/AssetManager/GetAssetById.ts --input '{"id":"ASSET-001"}'

Input from a JSON file:

npx ts-node run-local.ts -- src/Things/AssetManager/GetAssetById.ts --input ./test-data/asset.json

List all available Things and services:

npx ts-node run-local.ts -- --list

Input formats

Remote fallback

If a service calls Things["SomeThing"] and SomeThing does not exist locally, the call is automatically forwarded to the remote ThingWorx instance configured in .env. This lets you develop one Thing locally while the rest of the application runs on the server.

Services that call remote Things must use await:

var result = await Things["RemoteThing"].GetData({ id: input.id });
result;

Pulling Things from ThingWorx

Instead of writing service stubs manually, you can download them directly from a running ThingWorx instance.

Download one or more Things by name:

node pull-things.js --thing AssetManager
node pull-things.js --thing AssetManager ProductionLine Dashboard

Download all Things belonging to a project:

node pull-things.js --project MyProject

By default, existing .ts files are not overwritten so that local changes are preserved. Metadata files (.meta.json) are always refreshed from the server. To replace existing service files as well:

node pull-things.js --thing AssetManager --overwrite

After pulling, sync-types.js runs automatically to regenerate the type declarations.

If TWX_BASE_URL or TWX_APP_KEY are not configured, the script runs in mock mode and generates realistic sample files so the workflow can be tested without a live server.

What gets created

For each service defined directly on the Thing (inherited services from templates and shapes are skipped):

• src/Things/<ThingName>/<ServiceName>.ts — a stub with the service signature in comments and a // TODO placeholder
• src/Things/<ThingName>/<ServiceName>.meta.json — full metadata including parameter names, types, required flags, default values, and the result type

npm scripts

VS Code integration

The repository includes a .vscode/ configuration that:

• Runs sync-types.js automatically when a .ts file inside src/Things/ is saved
• Runs sync-types.js automatically before every service execution, so types are always up to date
• Provides a Run TWX Service launch configuration that executes the currently open service file with F5

Contributing

Contributions are welcome. Please open an issue before submitting a pull request for significant changes.

License

BSD 2-Clause

Made with ❤️ by Simone Silvestri