Headless Design Engine

Prerequisites#

Use Node.js 22 or later and a supported browser with WebGL. The engine runs in the browser and requires a DOM even though it mounts no editor UI. Request a license from IMG.LY.

npx degit imgly/starterkit-headless-ts-web starterkit-headless
cd starterkit-headless
npm install

npx degit imgly/starterkit-headless-ts-web starterkit-headless
cd starterkit-headless
npm install

git clone https://github.com/imgly/starterkit-headless-ts-web.git .headless-starterkit
mkdir -p src
cp -R .headless-starterkit/src/imgly src/imgly
cp .headless-starterkit/src/demo.ts .headless-starterkit/src/presets.ts .headless-starterkit/src/highlight-code.ts .headless-starterkit/src/style.css src/
mkdir -p public
cp -R .headless-starterkit/public/designs public/designs
npm install @cesdk/engine@1.86.0

git clone https://github.com/imgly/starterkit-headless-ts-web.git .headless-starterkit
mkdir -p src
cp -R .headless-starterkit/src/imgly src/imgly
cp .headless-starterkit/src/demo.ts .headless-starterkit/src/presets.ts .headless-starterkit/src/highlight-code.ts .headless-starterkit/src/style.css src/
mkdir -p public
cp -R .headless-starterkit/public/designs public/designs
npm install @cesdk/engine@1.86.0

Step 2: Serve Engine Assets#

The kit uses baseURL: '/assets' in exportDesign in both imgly/index.ts and the editable example in presets.ts. Copy the matching engine assets below. Adjust both URLs if your application uses a deployment prefix.

Copy the installed engine’s matching assets to serve them at /assets:

mkdir -p public
cp -R node_modules/@cesdk/engine/assets public/assets

mkdir -p public
cp -R node_modules/@cesdk/engine/assets public/assets

Step 3: Configure the Engine#

Set your license in src/demo.ts. The demo passes it to exportDesign(license). The asset location stays inside exportDesign in src/imgly/index.ts:

import CreativeEngine from '@cesdk/engine';
import { configureDesign } from './configure-design';


export async function exportDesign(license: string): Promise<Blob> {
  const config = {
    license: license,
    baseURL: '/assets'
  };
  const engine = await CreativeEngine.init(config);
  try {
    await engine.scene.loadFromArchiveURL(
      new URL('designs/marketing-design.imgly', document.baseURI).href
    );
    await configureDesign(engine);
    const [page] = engine.scene.getPages();
    return await engine.block.export(page, { mimeType: 'image/png' });
  } finally {
    engine.dispose();
  }
}

const config = {
  license: license,
  baseURL: '/assets'
};

The export function receives the license as its argument and uses it in this configuration. Each export creates a fresh engine and releases it when the operation finishes.

Step 4: Run the Demo#

npm run dev

npm run dev

Open the local application. Choose one of the five presets: personalize a campaign, apply photo effects, append a text block, change brand colors, or start fully custom with an empty configureDesign(engine). Edit the JavaScript in the single middle-panel editor. Both exportDesign(license) and configureDesign(engine) are editable together with JavaScript syntax highlighting. The preview exports automatically when the demo opens, when you select an application, and when you reset the code. Code edits trigger export after a 400ms pause. The export function includes engine creation and disposal in finally. Switching applications loads its complete example; Reset code restores both functions. Only one export runs at a time. New changes replace the pending source; an active run finishes and disposes its engine before the latest source runs. Superseded results and errors are discarded. The right panel shows the exported design. Every export starts from the original template, so edits do not accumulate.

Customize the Headless Workflow#

For the editable demo, set your license in demo.ts. The runner passes it to exportDesign(license) so the code editor contains no embedded license key. Edit the asset and design URLs inside the export function; update exportDesignCode in presets.ts to persist those defaults. When using the reusable TypeScript workflow outside the playground, pass your license to exportDesign(license) directly.

The demo interface belongs to demo.ts. It passes the complete edited source to imgly/run-design.ts, which executes the source in the browser and calls exportDesign(license). CreativeEngine is provided to the edited code; use plain JavaScript without imports or TypeScript annotations. The default export function mirrors the reusable TypeScript workflow in imgly/index.ts, which has no framework dependency:

import CreativeEngine from '@cesdk/engine';
import { configureDesign } from './configure-design';


export async function exportDesign(license: string): Promise<Blob> {
  const config = {
    license: license,
    baseURL: '/assets'
  };
  const engine = await CreativeEngine.init(config);
  try {
    await engine.scene.loadFromArchiveURL(
      new URL('designs/marketing-design.imgly', document.baseURI).href
    );
    await configureDesign(engine);
    const [page] = engine.scene.getPages();
    return await engine.block.export(page, { mimeType: 'image/png' });
  } finally {
    engine.dispose();
  }
}

exportDesign(license) receives the license as a string argument. The asset location and design URL remain explicit inside the function. It loads the archive into a fresh engine, calls await configureDesign(engine), and exports its first page as a PNG. The configureDesign implementation reads the demo textarea (#code), executes its JavaScript in the browser, and awaits the configuration before export. The included marketing design comes from the Design Editor starter kit. It bundles its images and fonts in public/designs/marketing-design.imgly. Keep that directory available next to the application’s entry URL. For nested routes or subpath hosting, change the URL literal inside exportDesign(license) to the public archive location. Packaged Electron renderers should use an absolute HTTP(S) URL.

The Personalize a campaign preset supplies this configuration. It replaces the headline with {{name}}, let us plan your next education event and sets name to Alex:

// The editable JavaScript mirrors the documented TypeScript workflow.
export const exportDesignCode = String.raw`async function exportDesign(license) {
  const config = {
    license: license,
    baseURL: '/assets'
  };
  const engine = await CreativeEngine.init(config);
  try {
    await engine.scene.loadFromArchiveURL(
      new URL('designs/marketing-design.imgly', document.baseURI).href
    );
    await configureDesign(engine);
    const [page] = engine.scene.getPages();
    return await engine.block.export(page, { mimeType: 'image/png' });
  } finally {
    engine.dispose();
  }
}`;

/** Editable examples run against the bundled Design Editor marketing template. */
export const presets = [
  {
    title: 'Personalize a campaign',
    description:
      'Turn a template into a personal invitation with text variables.',
    tag: 'Variables',
    code: String.raw`
function configureDesign(engine) {
  const title = engine.block.findByType('text')
    .find(id => engine.block.getString(id, 'text/text')
      .includes('education'));

  engine.block.replaceText(title,
    '{{name}}, let us plan\nyour next\neducation event');
  engine.variable.setString('name', 'Alex');
}
`
      .replace(/\/\/ highlight-headless-configure\n/g, '')
      .trim()
  },
  {
    title: 'Create a photo treatment',
    description: 'Give every image an editorial, black-and-white finish.',
    tag: 'Effects',
    code: String.raw`function configureDesign(engine) {
  const images = engine.block.findByType('graphic')
    .filter(id => engine.block.getType(engine.block.getFill(id))
      .endsWith('/image'));

  for (const image of images) {
    const effect = engine.block.createEffect('adjustments');
    engine.block.setFloat(effect,
      'effect/adjustments/saturation', -1);
    engine.block.appendEffect(image, effect);
  }
}`
  },
  {
    title: 'Add a message',
    description: 'Append a text block to announce an offer or a launch.',
    tag: 'Composition',
    code: String.raw`function configureDesign(engine) {
  const [page] = engine.block.findByType('page');
  const message = engine.block.create('text');
  engine.block.replaceText(message, 'MAKE SOMETHING GREAT.');
  engine.block.setTextFontSize(message, 32);
  engine.block.setTextColor(message,
    { r: 0.12, g: 0.12, b: 0.12, a: 1 });
  engine.block.setWidth(message, 900);
  engine.block.setHeightMode(message, 'Auto');
  engine.block.setPositionX(message, 45);
  engine.block.setPositionY(message, 1160);
  engine.block.appendChild(page, message);
}`
  },
  {
    title: 'Make it your brand',
    description: 'Recolor the graphic fills and outlines with teal accents.',
    tag: 'Brand colors',
    code: String.raw`function configureDesign(engine) {
  const teal = { r: 0.05, g: 0.68, b: 0.58, a: 1 };

  for (const graphic of engine.block.findByType('graphic')) {
    const fill = engine.block.getFill(graphic);
    const type = engine.block.getType(fill);

    if (type.endsWith('/color') && engine.block.isFillEnabled(graphic)) {
      engine.block.setColor(fill, 'fill/color/value', teal);
    }
    if (engine.block.isStrokeEnabled(graphic)) {
      engine.block.setStrokeColor(graphic, teal);
    }
  }
}`
  },
  {
    title: 'Fully custom',
    description:
      'Start with an empty configuration and make the design your own.',
    tag: 'Custom',
    code: String.raw`function configureDesign(engine) {

}`
  }
];

function configureDesign(engine) {
  const title = engine.block.findByType('text')
    .find(id => engine.block.getString(id, 'text/text')
      .includes('education'));

  engine.block.replaceText(title,
    '{{name}}, let us plan\nyour next\neducation event');
  engine.variable.setString('name', 'Alex');
}

presets.ts contains five editable examples. Each defines configureDesign(engine), which can be async and receives the current engine instance. The edited JavaScript runs in the page’s browser context, with access to browser APIs. It uses the regular engine API without an additional engine sandbox or execution limits.

If your application sets a Content Security Policy, the editable demo needs 'unsafe-eval' in script-src to compile the JavaScript entered in the textarea. A fixed configuration function can be called directly without runtime compilation.

The function awaits export before disposing the engine in finally. Loading, script, and export failures reject its promise. The demo displays the thrown message as plain text below the preview and lets the user edit and retry. A failed run leaves the previous result available. Editing code or switching presets automatically retries with the latest source. Errors from superseded runs are discarded.

For your own interface, copy src/imgly/, set the asset configuration and archive URL, and replace the #code textarea lookup in imgly/configure-design.ts with your JavaScript source string. Call exportDesign(license) from your export handler, handle rejection, and consume the Blob. The complete demo also needs demo.ts, presets.ts, highlight-code.ts, style.css, and public/designs/. It retains the latest export promise as window.headlessExport for inspection.

Build and Deploy#

Build your application with its normal production command. Serve the generated files and matching engine assets over HTTP(S). Configure a license for the deployment origin. See Serve Assets for asset-hosting guidance.

This kit uses @cesdk/engine. It does not load @cesdk/cesdk-js or its editor UI. A DOM-free server needs a server engine package instead; see Headless Mode for runtime choices.

Troubleshooting#

• Keep both function names, return a PNG Blob from exportDesign(license), and preserve engine disposal in finally.

• Read the error below the preview and fix the code or asset configuration. The preview retries automatically after editing.

• Keep the configureDesign function name. Syntax errors and thrown messages appear below the preview.