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.).
- Open a terminal in the folder where the project folder should be created
- Run
npm create @combeenation/custom-code@latest - Enter the name of your project. This will also be the name of the new folder, the script aborts if it already exists.
- Choose whether the 3d viewer should be included. If so, the project also contains the
@combeenation/3d-viewerpackage and a 3d specific starting point. - Go into the new folder and install the dependencies with
npm install - Open the project in VS Code with
code <project-name>.code-workspace
Project structure
| File / folder | Description |
|---|---|
src/index.ts | Entry point of your custom code |
src/typings/cfgr-defs.generated.ts | Typings of the components and controls of your configurator. This file is generated, see Link and sync the configurator. |
cbn.config.json | Holds the link between your project and your configurator(s) |
vite.config.js | Build 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.json | Launch configurations for VS Code |
The package.json provides the following scripts:
| Script | Description |
|---|---|
npm run dev | Starts the local dev server, see Local development |
npm run build | Checks the code and creates the production build |
npm run build:dev | Same as build, but in Vite's development mode |
npm run check-code | Runs the linter (ESLint) and the TypeScript compiler |
npm run format | Formats 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.
- Open your configurator draft in the editor and go to the Custom Code page
- In the section Upload script click Upload (or Replace, if there is already an uploaded script)
- Select the file
dist/cfgr.jsof 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.
The ports 5173 and 5174 have to be available and cannot be changed.
Connect the configurator editor
- Make sure the dev server is running
- Open your configurator draft in the editor and go to the Custom Code page
- In the section Connect to local IDE click Connect
Link and sync the configurator
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.
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=trueto the URL of the preview manually.
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
consoleoutput 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.
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 devor removelocal-dev=truefrom 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.