@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 from anywhere inside a WinCC OA project:

cd <project>
npx @wincc-oa/create-backend-service my-service

If you omit the service name, you will be prompted to enter one:

npx @wincc-oa/create-backend-service
# Enter service name: my-service

This creates the service at <project>/javascript/webserver-js/services/my-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 | | --skip-install | Skip running npm install after scaffolding |

If service-name is omitted, you will be prompted to enter one interactively.

Important: run in the main project

This tool must be run from within a WinCC OA project that contains a config/config file, because it reads that file to locate the WinCC OA installation path. It will not work when run inside a sub-project, since sub-projects do not have their own config/config.

If you need the service in a sub-project, run the scaffolding in the main project first and move the created directory to the sub-project afterwards.

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

The scaffolder automatically detects your WinCC OA installation, configures the webserver-js TypeScript path in tsconfig.json, and runs npm install (use --skip-install to skip this step in restricted environments). After that:

1. Build

cd <project>/javascript/webserver-js/services/<service-name>
npm run build

Or start a watcher for automatic re-compilation:

npm run watch

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

Before the first service has been created, the directory <project>/javascript/webserver-js/services/ usually does not exist yet, and webserver.js cannot watch this directory. Therefore, the first service will not be detected automatically until webserver.js is restarted.

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.

Requirements

• Node.js >= 20
• Must be run from within a WinCC OA project directory tree (a directory that has a config/config file in its ancestry)
• The WinCC OA installation must have the Node.js addon installed (provides winccoa-manager and @types/winccoa-manager)