Skip to main content

Introduction

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 SDK)
  • 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.

Custom Code SDK​

The Custom Code SDK (@combeenation/custom-code-sdk) is the central library for communicating with the configurator. It's installed as npm package into your custom code project and provides all functionality for interacting with a configurator, as mentioned above.

Deprecated libaries​

The Custom Code SDK is the successor of the following, now deprecated, utility libraries. They can't be used for new projects anymore:

  • Custom JS utils (docs) (@combeenation/custom-js-utils)
  • Custom code utils (docs) (@combeenation/custom-code-utils)

Setup​

Prerequisites​

  • A configurator draft in the Combeenation platform
  • Node.js 22 or newer (includes npm)
  • Visual Studio Code (recommended, but not mandatory)

Create the project​

We provide a starter project which comes with our recommended configuration (build tools, TypeScript & lint config, pre-installed packages, etc.).

  1. Open a terminal in the folder where the project folder should be created
  2. Run npm create @combeenation/custom-code@latest
  3. Enter the name of your project. This will also be the name of the new folder, the script aborts if it already exists.
  4. Choose whether the 3d viewer should be included. If so, the project also contains the @combeenation/3d-viewer package and a 3d specific starting point.
  5. Go into the new folder and install the dependencies with npm install
  6. Open the project in VS Code with code <project-name>.code-workspace

Project structure​

File / folderDescription
src/index.tsEntry point of your custom code
src/typings/cfgr-defs.generated.tsTypings of the components and controls of your configurator. This file is generated, see Link and sync the configurator.
cbn.config.jsonHolds the link between your project and your configurator(s)
vite.config.jsBuild configuration. It bundles src/index.ts into the single file dist/cfgr.js and includes the Vite plugin for the connection to the configurator editor.
.vscode/launch.jsonLaunch configurations for VS Code

The package.json provides the following scripts:

ScriptDescription
npm run devStarts the local dev server, see Local development
npm run buildChecks the code and creates the production build
npm run build:devSame as build, but in Vite's development mode
npm run check-codeRuns the linter (ESLint) and the TypeScript compiler
npm run formatFormats the code with Prettier

Production build​

Run the following command in your project folder:

npm run build

This first checks your code (ESLint and TypeScript compiler) and only creates the build if there are no errors.
The result is a single JavaScript file: dist/cfgr.js.

Upload to the configurator​

The production build has to be uploaded to the configurator draft. This is always required if you want to share the configurator with someone else or if you want to publish it.

  1. Open your configurator draft in the editor and go to the Custom Code page
  2. In the section Upload script click Upload (or Replace, if there is already an uploaded script)
  3. Select the file dist/cfgr.js of your project

Local development​

During development you don't have to build and upload your code after every change. Instead, the configurator loads your code directly from the local dev server of your project.

Start the dev server​

Run the following command in your project folder:

npm run dev

This starts two processes in parallel:

  • Vite dev server which serves your code. The configurator expects it at http://localhost:5173.
  • TypeScript compiler in watch mode, which reports type errors while you are coding.

The Vite plugin @combeenation/vite-plugin-custom-code-sync additionally opens a WebSocket server at ws://localhost:5174. It is used for the communication between the configurator editor and your project.

note

The ports 5173 and 5174 have to be available and cannot be changed.

Connect the configurator editor​

  1. Make sure the dev server is running
  2. Open your configurator draft in the editor and go to the Custom Code page
  3. In the section Connect to local IDE click Connect

When connecting for the first time, the editor shows "Local IDE connected, configurator not linked". The link ensures that the typings of the correct configurator are synchronized into your project. Without a valid link, the typings can't be synchronized.

Click Link configurator to add the configurator to the cbn.config.json of your project. If the file can't be parsed, fix its syntax errors or delete it.

Once linked, the section Custom Code definitions offers a Synchronize button. It writes the typings of the components and controls of your configurator into src/typings/cfgr-defs.generated.ts. Synchronize again whenever you change components or controls in the configurator. The editor indicates when the definitions are outdated.

warning

Don't edit cfgr-defs.generated.ts manually, as it is overwritten with every synchronization.

Preview with local code​

To run your local code in the preview of the configurator:

  • Open the dropdown next to the Preview button of the editor and select Preview with local dev server. The dropdown is available as soon as the configurator is connected and linked.
  • Alternatively, add the URI parameter local-dev=true to the URL of the preview manually.
info

The local code is never persisted in the configurator. As long as local-dev=true is part of the URL, the uploaded script is ignored. Remove the parameter to test the uploaded script.

Debugging​

Start the dev server with npm run dev, open the preview with the local dev server and open the dev tools of the browser (F12).

Browser dev tools​

The dev server provides source maps, so your code appears as the original TypeScript files in the Sources panel of the browser dev tools, instead of generated JavaScript. This allows you to:

  • Set breakpoints and step through your code
  • Inspect variables, call stacks and console output with the correct file and line number
  • Analyze network requests your code sends to external services

The starter project also exposes the object window.CbnCustomCode in src/index.ts. Everything you add to it can be called directly from the browser console, which is helpful for testing functions during development.

info

Source maps are only provided by the dev server. The production build (dist/cfgr.js) doesn't contain source maps.

Combeenation DevTools extension​

The Combeenation DevTools extension for Chrome adds a dedicated panel to the browser dev tools of configurators (e.g. the preview). It provides the following features:

  • Use local custom code: Toggles the local dev server for the opened configurator, without changing the URL manually (see Preview with local code).
  • Start new configuration: Resets the configurator to a new configuration, e.g. to quickly test your code with the initial state.
  • Watches: Evaluates Hive expressions in the context of the opened configurator and shows their result live. This allows you to check values of components while testing your code. Watches can be organized in groups and are stored per configurator in your browser.
  • Show Babylon.js inspector: Opens the inspector of a 3d viewer in the configurator. Only available if the configurator contains a 3d viewer and the viewer is a development build. If there are multiple viewers, you can select the viewer instance.

Combeenation DevTools in the Chrome Web Store

Troubleshooting​

If the preview is opened with local-dev=true, the configurator shows a dialog in the following cases:

  • Local dev server not reachable: The dev server isn't running. Start it with npm run dev or remove local-dev=true from the URL to use the uploaded script.
  • Custom code failed to load: The dev server is running, but the code could not be loaded. Check the output of the dev server and the browser console for build or runtime errors.