@wincc-oa/create-backend-service

Scaffolds a new SIMATIC WinCC Open Architecture webserver.js dynamic service with example request handlers and HTTP endpoints.

Dynamic services are loaded by the webserver.js service manager at runtime -- no rebuild or restart of the webserver required.

Quick start

Run the scaffolder inside the services/ directory of a WinCC OA (sub-)project that has webserver.js running:

mkdir -p <project>/javascript/webserver-js/services
cd <project>/javascript/webserver-js/services
npx @wincc-oa/create-backend-service my-service

This creates a my-service directory containing a ready-to-build service.

Important: Always use the version of create-backend-service that matches your WinCC OA installation. The correct version can be found in javascript/webserver-js/package.json inside your installation directory. To install a specific version:

npx @wincc-oa/[email protected] my-service

Usage

npx @wincc-oa/create-backend-service <service-name>

| Argument | Description | | ---------------- | ------------------------------------------------------------------- | | <service-name> | Name of the service directory to create (e.g. my-weather-service) | | -h, --help | Show help |

Generated structure

<service-name>/
  src/
    exampleHandler.ts    # WebSocket request handler (ping, type.name, connect/disconnect)
    exampleRoutes.ts     # HTTP endpoint (/status)
  package.json           # Service manifest (webserverjs-service)
  tsconfig.json          # TypeScript configuration
  .gitignore

Setup after scaffolding

1. Configure TypeScript paths

The generated tsconfig.json contains a paths mapping for webserver-js that must be adjusted to point at your WinCC OA installation:

// tsconfig.json
{
  "compilerOptions": {
    "paths": {
      "webserver-js": ["<path-to-installation>/javascript/webserver-js"]
    }
  }
}

Replace <path-to-installation> with the absolute or relative path to your WinCC OA installation directory. This allows TypeScript to resolve the types exported by webserver-js during compilation. At runtime, webserver-js is provided by the webserver process itself -- no npm install needed for it.

2. Build

cd <service-name>
npm run build

Or start a watcher for automatic re-compilation:

npm run watch

3. Verify

Browse to these URLs to check that the service is loaded and responding:

• https://<host>:<port>/_services — lists all discovered services
• https://<host>:<port>/<service-name>/status — service health check

Included examples

| File | What it demonstrates | | ------------------- | ------------------------------------------------------------------------------------------------------ | | exampleHandler.ts | Request handler with one-shot (ping, type.name) and subscription (connect/disconnect) commands | | exampleRoutes.ts | HTTP endpoint (/status) with injected Router factory |

How services work

A dynamic service is a directory with a package.json that contains a "webserverjs-service" manifest. The manifest declares:

• requestHandlers -- WebSocket command handlers (extend WsjRequestHandlerBase)
• httpEndpoints -- HTTP routes mounted on the Express app
• acl -- access control rules for the service's endpoints
• outDir -- directory containing compiled JavaScript (default: dist)

The service imports types and base classes from webserver-js, which is the main webserver package available in every WinCC OA installation. No additional npm dependencies are required for basic services.

License

MIT