The Visual Editor API is designed for experienced CloudCannon developers. If you need help with custom integrations or your CloudCannon setup in general, please contact our friendly support team.
The An abbreviation of Integrated Development Environment, an IDE is software that provides developers with tools for writing, editing, and managing code. Common examples include VS Code, Cursor, and JetBrains IDEs. When developers edit website files in an IDE and push changes to their Git Repository, CloudCannon automatically syncs those updates to your Site. CloudCannon's Visual Editor API is a public JavaScript API for building custom integrations with the Visual Editor. It lets you run your own code inside the Visual Editor to read and write content, listen for changes, and upload files using code running inside your website files.@cloudcannon/visual-editor-api package includes TypeScript declarations that give your IDEIDE
Visual Editor API
This article assumes you know how to initialize the Visual Editor API and have already installed the @cloudcannon/visual-editor-api package. For a complete list of API objects and methods, please read our reference documentation on the Visual Editor API.
This approach requires your project to have a TypeScript compilation pipeline. Some SSGs (such as Astro, Next.js, SvelteKit, and Nuxt) include one out of the box. For others (such as Eleventy, Jekyll, and Hugo), you will need to add a build step (for example, using esbuild or Rollup) to compile the helper module to JavaScript before it runs in the browser. Install typescript as a dev dependency if you have not already.
Declare CloudCannon's globals on the Window type#
The package alone does not teach TypeScript that window includes CloudCannonAPI. Default Window typings omit CloudCannon's globals, so a raw window.CloudCannonAPI reference is often flagged as an error or widened to any. You can address this by importing the CloudCannonVisualEditorWindow type from the package and re-declaring window with that type in the module that talks to the API.
To declare CloudCannon's globals:
- Open your website files in your local development environment.
- Open the script where your Visual Editor API integration runs.
- Add a
declare const windowstatement at the top of the file, then usewindow.CloudCannonAPIas normal:
import type { CloudCannonVisualEditorWindow } from '@cloudcannon/visual-editor-api';
declare const window: CloudCannonVisualEditorWindow & { inEditorMode: true | undefined };
const api = window.CloudCannonAPI?.useVersion('v1', true); import type pulls the TypeScript declarations from @cloudcannon/visual-editor-api.
declare const window re-declares the window global for this module. Combining CloudCannonVisualEditorWindow with { inEditorMode: true | undefined } tells TypeScript that both window.CloudCannonAPI and window.inEditorMode are available without needing a cast. The declaration applies to this file only. Repeat it in any other module that talks to the API.
?. skips the call when CloudCannonAPI is missing, returning undefined (for example, outside the Visual Editor). Passing true as the second argument to useVersion() prevents the API Object from being assigned to window.CloudCannon; see Initialize the Visual Editor API for context.
Once you have declared CloudCannon's globals, window.CloudCannonAPI and window.inEditorMode work with full autocomplete and type checking in the same module.
If you call the API from many modules, you can wrap the window.CloudCannonAPI?.useVersion('v1', true) call in a helper function and import it where you need it, rather than re-declaring window in every file.