Custom code
  • 16 May 2024
  • 6 Minutes to read
  • Contributors
  • Dark

Custom code

  • Dark

Article summary


Custom code is based on TypeScript and fully replaces the (now deprecated) CustomJS projects.
It should still provide all the features from CustomJS but in a more sophisticated manner.

Please be aware that this is still at an early stage of development and new versions are more likely to have breaking changes.

With custom code you can extend your configurators capabilities in many ways. It allows you to write TypeScript which then runs in your configurator.

The following are just a few examples of the countless possibilities which open up with this feature:

  • Extend functionalities for existing components and controls (see custom code utils)
  • Extend functionalities for the viewer control (see 3d viewer)
  • Add new controls like a date time picker etc.
  • Fetch data from external services like real-time prices calculated on your servers or real-time inventory from your CMS etc.
  • Send live analytics to external services like Google Tag Manager etc.

How to get started

1. Prepare your configurator

  • Create a new configurator if you don't already have one.
  • See if your configurator has 2 components named CustomJS and CustomJSCmps.
    If yes: You can skip the following steps and go to the next section.
  • Create a resource component of type JavaScript named CustomJS and upload some dummy file to a resource named cfgr.
  • Create a value component named CustomJSCmps and paste the following into the rule of the component:
    // In this component, you have to tell the server which components you're
    // accessing (reading or writing to) in your custom code.
    // By default the server only sends the result value of the listed components to
    // the client. If more data like the list of all records etc. is needed, a "+"
    // needs to be prepended to the name.
    // Examples for how to use this. Replace with real cmp names...
      // Retrieve all records of a component
      "+" + #MyRecords.Name
    // Why do we need this?
    // In published configurators, the server optimizes the used network bandwidth
    // and only sends information about components to the client when actually
    // needed.
    // Since the server has no way of knowing which components are used in custom JS,
    // we need to give him this information manually here so that he can optimize
    // properly.
    See What is the CustomJSCmps component down below for some more details.

2. Setup a TypeScript project

Theoretically you can upload any .js file to your configurator.

However, we provide a starter project which comes with our recommended configuration (build tools, config, pre-installed packages etc.) and gives you everything you need to get started quickly.


All of the following assumes that you have a current version of Node.js & npm (or some equivalent) installed on your computer.

  • Open a terminal (e.g. command line in windows) in the folder where you want to create your project
  • Run npm create @combeenation/custom-code@latest
  • Follow the instructions of the script to create a starter project using TypeScript

How to use it

Where to start writing code

The main starting point is usually the callback to CfgrUtils.onCfgrReady within src/index.ts in which you have the guarantee that you can safely access all components & controls.

You can either write all your TypeScript logic within this function or spread it over as many functions/modules/files as you like.


Always ensure that you only access components & controls after the callback to CfgrUtils.onCfgrReady was called. Otherwise there is no guarantee that all components and controls are fully bootstrapped and you could run into undefined behavior or errors.

How to run & debug during development

There are 2 ways to run & debug your application during development:

  • Debugging in Chrome dev tools:
    • Run npm run dev which will start a local dev server
    • Open the preview of your configurator draft
    • Click the "TS icon" in the upper right to connect to the local instance
      • As alternative you can also add the URI parameter &localcts=true manually
    • Debug in browser dev tools (F12)
  • Debugging in VS Code:
    • Open the view "Run and debug" in VSCode & select "Start dev" in dropdown at the top (this is only needed once).
    • Press F5 to start debugging. This will automatically open a new Chrome window and run npm run dev in the background.
    • Open the preview of your configurator draft
    • Click the "TS icon" in the upper right to connect to the local instance
      • As alternative you can also add the URI parameter &localcts=true manually
    • Debug directly in VSCode

The steps above won't persist your custom code in the configurator but will load it from the hard drive of your computer.

If you'd like to share the configurator with someone else or want to publish it, you always have to upload your custom code to the CustomJS component as explained in how to upload custom code to the configurator.

How to upload custom code to the configurator

Uploading your custom code to the configurator is always required when you want to share your configurator with someone else or want to publish it.

  • Run npm run build in your custom code project on your computer
  • Upload the built file under dist/cfgr.js to your CustomJS component by clicking on the "edit" icon next to its cfgr resource

Update component typings

The required typings to work with Components can be retrieved in your Configurator editor or the preview.
The recommended way is to run the development server (as explained above) as it allows you to directly connect this local environment with your Configurator.
The UI controls should automatically be available as soon as you open a preview which is connected to the local TS.
Configurator Preview

Configurator Editor

Update them manually

  • Open your configurator draft
  • Expand the menu of the Components-list on the left
  • Select Download custom code definitions
  • Save/Replace the file in your code project

How to access components & controls

The custom code utils package is mandatory to interact between your custom code and the configurator.

It allows you to read values from components, write new input values to them and interact with the controls in your configurator and many other features.
To work with a component ensure that your "configurator definitions file" is up to date (see previous step).
This file basically represents your components list.
If you want to access a component simply import the variable which has the identical name as your component.
This variable then provides all the available functions and properties you need.

const myValue = await MyCmp.getValue();

See the utils API documentation for more details on how to use them.

The custom code utils come pre-installed with our TypeScript start project.

You can also install them manually using npm install @combeenation/custom-code-utils.

How to interact with the 3d viewer

Combeenation has built its own 3d viewer, which is used in the 3d viewer control.

If the functionality of this 3d viewer control and its SigSlos is not sufficient, it can be extended in custom code using the API of the 3d viewer package itself.

See 3d viewer control with custom JS for more details.


What is the CustomJSCmps component

In this component, you have to tell the server which components you're accessing (reading or writing to) in your custom code.

You'll get a warning in the configurator preview if you access components which are not listed in it. Always ensure that you list all required components as published configurators will fail silently if components are missing.

See this section above for an example of how the content of this component has to look like.

What is the config file cbn.config.json

This file can hold information specific to the Combeenation platform.
One of its usages is, that it can create a link between your code project and the configurator. This way, the typings (cfgr-defs.generated.ts) can be automatically transferred during development.

Was this article helpful?

What's Next