webserver.js Customer Extensions

Extension Packages

Two npm packages are available for extending webserver.js:

@wincc-oa/backend — Provides the base classes and utilities for customizing the webserver.js backend. This package is not intended to be used standalone.
@wincc-oa/create-backend — A scaffolding tool that generates a ready-to-use extension project with example code for both TypeScript and CTRL customizations.

Important:

The version of these packages must match the version of the WinCC OA installation. Check the version in javascript/webserver-js/package.json of your installation. If you need to install @wincc-oa/backend manually, specify the exact version:

npm install @wincc-oa/backend@x.y.z

Creating an Extension Project

Use the scaffolding tool to generate a new extension project:

npx @wincc-oa/create-backend my-backend

To ensure compatibility, use the version that matches your WinCC OA installation:

npx @wincc-oa/create-backend@x.y.z my-backend

You can also scaffold into an existing empty directory:

mkdir my-backend
cd my-backend
npx @wincc-oa/create-backend .

This creates the following directory structure in your project:

<project-dir>/
├── javascript/
│   └── customer-webserver-example/    (TypeScript extensions)
│       ├── src/
│       │   ├── index.ts                     (entry point exports)
│       │   ├── customerDashboardServer.ts
│       │   ├── customerTsRequestHandler.ts
│       │   ├── customerRoutes.ts
│       │   ├── connectionsRoute.ts
│       │   └── connectionsController.ts
│       ├── run.js                           (JavaScript Manager entry point)
│       ├── package.json
│       └── tsconfig.json
└── scripts/
    └── libs/
        └── classes/
            └── wsjServer/             (CTRL extensions)
                ├── CustomerCtrlRequestHandler.ctl
                ├── CustomerCtrlHttpEndpoints.ctl
                └── WsjEmbeddedCtrlUser.ctl

TypeScript Extensions

TypeScript extensions allow you to customize the webserver.js backend using modern web development patterns. The scaffolded project includes the following example files:


File	Description
customerDashboardServer.ts	A subclass of `WsjDashboardServer` that demonstrates how to extend the main server class with custom initialization and behavior.
customerTsRequestHandler.ts	Custom request handlers based on `WsjRequestHandlerBase`, supporting both one-shot request/response patterns and live WebSocket subscriptions for real-time data.
customerRoutes.ts	Express-style route definitions using `WsjRoutes` for registering custom HTTP endpoints.
connectionsController.ts	An example controller demonstrating responses in multiple formats (JSON, Markdown, HTML).

Key base classes and utilities available from the @wincc-oa/backend package:

WsjDashboardServer — Main server class to subclass for custom behavior.
WsjRequestHandlerBase — Base class for custom request handlers.
WsjRequestHandlerRegistry — Registry for managing request handlers.
WsjRoutes — Route registration utilities.
WsjStaticLiveDirectoryRoute — Route for serving static files with live reload support.
WsjCtrlEndpointRoute — Route for CTRL-based HTTP endpoints.
WsjAccessControlList — Access control management.
WsjServerGlobal — Global server utilities and configuration.

CTRL Extensions

For developers familiar with the WinCC OA CTRL language, webserver.js also supports CTRL-based extensions. The scaffolded project includes the following CTRL example files:


File	Description
CustomerCtrlRequestHandler.ctl	A CTRL-based request handler that processes HTTP requests using CTRL scripts.
CustomerCtrlHttpEndpoints.ctl	Defines custom HTTP endpoints implemented in CTRL.
WsjEmbeddedCtrlUser.ctl	Registers CTRL handlers and routes CTRL endpoint calls within the webserver.js context.

Setting Up a Custom Extension

After scaffolding, follow these steps to integrate the extension into your WinCC OA project:

Add the extension as a sub-project in your project config/config file.
Install the npm dependencies:
```
npm install
npm install --save-dev <path-to-installation>/javascript/@types/winccoa-manager
```
Replace <path-to-installation> with the path to your WinCC OA installation directory.
Build the TypeScript code:
```
npm run build
```
For automatic recompilation during development, use the watch mode instead:
```
npm run watch
```
Add a JavaScript Manager in the WinCC OA Console with the script path pointing to the extension entry point:
```
node customer-webserver-example/run.js
```

The custom webserver.js instance now runs with your extensions loaded, handling requests through your custom handlers and routes in addition to the standard functionality.