Skip to main content

Developer setup tips for working with ExD

This guide covers practical setup tips for developing extensions in Experience Designer. It'll help you avoid common pitfalls and understand how presets, configuration files, hot reload, and build behavior work together.

Extensions are refered to as (remote) components in the code.

1. Refresh Experience Designer after starting dev script​

After starting yarn run dev, open or refresh Experience Designer for developers at orca-experience.zoovu.com/developer. You only need to refresh it once while the dev script is running. After that, you can restart the dev script freely without losing the connection.

2. Match preset and configuration file structure​

Preset files define which elements can be customized in the right-side panel (e.g. visibility of an image, selected color, spacing). The configuration file needs to match the preset file exactly so that the extension behaves correctly.

Here’s an example of matching .preset.ts and .configuration.ts files:

src/components/answer/answer.preset.ts
import { boolean, color, EmbeddedComponentParameterFormat, object } from "@zoovu/theme-editor-parameter-types";

export const answerPreset = object({
    isImageVisible: boolean({ label: "Is image visible", default: true }),
    color: color({
        label: "Color",
        default: "#D2EDFF",
    }),
    selectedColor: color({
        label: "Selected color",
        default: "#9ECAE1",
    }),
}, { label: "Answers", format: EmbeddedComponentParameterFormat.ACCORDION })

Configuration with the same property names:

src/components/answer/answer.configuration.ts
export class AnswerConfiguration {
    isImageVisible = true;
    color = "#D2EDFF"
    selectedColor = "#9ECAE1"
}

3. Use the latest extension version for hot reload​

Hot reload only works with themes that use the latest version of the extension. Make sure your extension is up to date in Experience Designer.

https://orca-experience.zoovu.com/developer

zoovu.manifest.js

4. Restart the server to fix TypeScript errors​

Sometimes TypeScript shows false-positive errors if webpack doesn't detect recent file changes. Restart the server with yarn run dev and refresh Experience Designer for developers.

Overriding faulty extension version​

Experience Designer does not allow uploading an extension with the same name and version number. If your extension build has an issue and you need to upload a fixed version, you must bump the version number first.

https://orca-experience.zoovu.com/developer

zoovu.manifest.js

To override an existing version:

  1. Open your extension’s root folder.
  2. Run yarn bump-version to increase the version in package.json.
  3. Build the extension using yarn build.
  4. Upload the new version to Experience Designer by dragging and dropping the generated .zip file into the right panel of the developer view. Learn more.

5. Expect larger bundle size in development​

The bundle size is larger when using yarn run dev compared to yarn build. This is expected in development mode. For production builds, always use yarn build.

6. Local dev server must run on same machine​

If you're using a virtual machine or remote environment, the browser running Experience Designer for developers must be on the same machine as the dev server.

Run yarn run dev and open https://orca-experience.zoovu.com/developer from the same device.