@wincc-oa/create-backend

Scaffolds a new SIMATIC WinCC Open Architecture webserver.js customization project with working examples for custom request handlers, HTTP endpoints, and routes in both TypeScript and CTRL.

Quick start

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

This creates a my-backend sub-directory containing a ready-to-use WinCC OA sub-project structure. You can also scaffold into an existing (empty) directory:

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

Important: Always use the version of create-backend 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-backend

Project name

The name you pass to the scaffolder is used twice: once for the WinCC OA sub-project directory, and once for the npm package directory inside it. Scaffolding my-backend therefore produces the TypeScript sources and the package definition in my-backend/javascript/my-backend/.

Throughout this document, <project-name> stands for that name. When you scaffold into the current directory with ., the name of the current directory is used.

Usage

npx @wincc-oa/create-backend <project-directory>

| Argument | Description | | --------------------- | ----------------------------------------------------------------- | | <project-directory> | Name of the directory to create, or . for the current directory | | -h, --help | Show help |

Generated project structure

<project-name>/
  README.md
  customer/
    data/
      example.json                  # Sample file served by the static route
  javascript/
    <project-name>/
      src/
        index.ts                    # Entry point exports
        customerDashboardServer.ts  # Custom WsjDashboardServer subclass
        customerTsRequestHandler.ts # Example TypeScript request handler
        customerRoutes.ts           # Example Express-style routes
        connectionsRoute.ts         # Example route definition
        connectionsController.ts    # Example controller (JSON/Markdown/HTML)
      run.js                        # JavaScript Manager entry point
      package.json
      tsconfig.json
      eslint.config.mjs
      .prettierrc
      .gitignore
  scripts/
    libs/classes/wsjServer/
      WsjEmbeddedCtrlUser.ctl         # CTRL extension point (registers handlers)
      CustomerCtrlRequestHandler.ctl  # Example CTRL request handler
      CustomerCtrlHttpEndpoints.ctl   # Example CTRL HTTP endpoint

Setup after scaffolding

1. Add the project to your WinCC OA project

   Add the project directory to the list of sub-projects in config/config.

2. Install dependencies

   cd <project-directory>/javascript/<project-name>
   npm install
   npm install --save-dev "<path-to-installation>/javascript/@types/winccoa-manager"

   Quote the path. The default WinCC OA installation directory on Windows contains spaces (C:\Program Files\...), and an unquoted path makes npm treat each fragment as a separate package name.

3. Build

   npm run build

   Or start a watcher for automatic re-compilation:

   npm run watch

4. Replace the standard webserver.js manager

   The scaffolded server is a full replacement for the standard webserver.js, not an addition to it. Both read the same httpsPort from config/config, so they cannot run at the same time.

   In the WinCC OA Console, set the existing JavaScript Manager running webserver-js/run.js to start mode manual (or remove it), then add a JavaScript Manager with

   <project-name>/run.js

   as its parameter.

   Leaving both managers running produces symptoms that are easy to misread: on Linux the second manager fails to bind the port and exits, so your customizations appear to be ignored. On Windows both may bind, and requests are then served by either process at random, so customizations appear to work intermittently.

5. Lint and format (optional)

   npm run lint
   npm run format

6. Modify

   After you're familiar with the example project, you likely will rename it and replace the example code with the final webserver.js modifications

Included examples

The template contains working examples for the most common customization scenarios:

TypeScript

| File | What it demonstrates | | ----------------------------- | -------------------------------------------------------------------------------------------------------------------------------- | | customerDashboardServer.ts | Subclassing WsjDashboardServer to register custom handlers and routes | | customerTsRequestHandler.ts | Implementing a request handler with one-shot (type.name) and live-subscription (connect/disconnect via dpConnect) commands | | customerRoutes.ts | Adding Express-style HTTP routes (static files, dynamic endpoints, CTRL endpoints) | | connectionsController.ts | A controller that queries WinCC OA data and returns JSON, Markdown, or HTML |

CTRL

| File | What it demonstrates | | -------------------------------- | -------------------------------------------------------------------------- | | CustomerCtrlRequestHandler.ctl | Implementing a request handler in CTRL (customization.example.disk.free) | | CustomerCtrlHttpEndpoints.ctl | Implementing an HTTP endpoint in CTRL (HTML page) | | WsjEmbeddedCtrlUser.ctl | Registering CTRL handlers and routing CTRL endpoint calls |

Once the server is running, the examples are reachable at:

| URL | Served by | | -------------------------------------------------- | -------------------------------------------------- | | https://<host>:<port>/customer/data/example.json | customer/data/ via WsjStaticLiveDirectoryRoute | | https://<host>:<port>/customer/connections | connectionsController.ts | | https://<host>:<port>/customer/diskfree | CustomerCtrlHttpEndpoints.ctl |

All three are declared unauthenticated by the /customer/* ACL entry in customerRoutes.ts.

If one of these URLs answers 401 Unauthorized, the standard webserver.js served the request, not the scaffolded server. The standard server has no /customer/* entry, and with httpAuth enabled its access control challenges the request before any route is matched. See step 4 above.

Dependencies

The generated project depends on @wincc-oa/backend, which provides base classes and utilities for webserver.js backend development:

• WsjDashboardServer - base server class
• WsjRequestHandlerBase / WsjRequestHandlerRegistry - request handler infrastructure
• WsjRoutes, WsjStaticLiveDirectoryRoute, WsjCtrlEndpointRoute - routing utilities
• WsjAccessControlList - access control
• WsjServerGlobal - global server state and WinCC OA API access

Dynamic services created with @wincc-oa/create-backend-service must be compiled against the same package as the server that loads them. See How services work in that package's README.

License

MIT