Visual Data Previews with Svelte

Svelte re-renders a component when its reactive state changes, so a Visual Data Preview in Svelte comes down to assigning CloudCannon's latest data to reactive state. The connector wraps the sequence described in our documentation on using Visual Data Previews with vanilla JavaScript: it listens for CloudCannon's events, calls enableEvents(), reads the latest data with value(), and hands it to a callback you supply.

@cloudcannon/svelte-connector re-exports onCloudCannonChanges and stopCloudCannonChanges from @cloudcannon/visual-editor-connector without changing them. Both packages behave identically, so an existing Site importing either one keeps working.

What your Site needs#

• The component you want to preview has to render on a page CloudCannon can open. The Visual Editor opens files, not components, and a SvelteKit route is a good example of a file that outputs to its own page.
• The component must read its data from a data or content file in your project, rather than holding it internally.
• Collection configuration decides whether a file has a URL the Visual Editor can open. For what to check, please read our documentation on what Visual Data Previews are.
• The connector runs on the client and needs tearing down when your component goes away, which Svelte's onMount and onDestroy functions handle.

Installation#

This package targets the deprecated v0 Visual Editor API. For new Sites, please read our documentation on initializing the Visual Editor API.

npm i @cloudcannon/svelte-connector

Connecting a component#

Call onCloudCannonChanges() when your component mounts, passing a callback. The connector runs that callback on load and after every change, handing it the file's structured data, and you assign what it receives to reactive state. The code below goes inside your route's <script> block.

import { onDestroy, onMount } from 'svelte';
import { onCloudCannonChanges, stopCloudCannonChanges } from '@cloudcannon/svelte-connector';

let { data } = $props(); 
let pageDetails = $state(data); 

onMount(() => {
  onCloudCannonChanges((latestValue) => {
    pageDetails = latestValue; 
  });
});

onDestroy(() => {
  stopCloudCannonChanges(); 
});

The example uses Svelte 5 runes. On Svelte 3 or 4, declare the prop with export let data; and the state with let pageDetails = data;. Reassignment is reactive in those versions without $state.

You do not need to call enableEvents() yourself. onCloudCannonChanges() does it, and also covers the case where CloudCannon has already loaded by the time your component mounts.

To cover that case, onCloudCannonChanges() reads window.CloudCannon. If other code on your page calls useVersion('v1'), CloudCannon reassigns that global to the v1 object, which has no enableEvents(), so the connector fails to start and your preview never updates. Pass true as the second argument, useVersion('v1', true), to get the v1 object without reassigning the global. For more information, please read our documentation on initializing the Visual Editor API.

Tearing down listeners#

stopCloudCannonChanges() removes every update listener registered through the package, not only the one belonging to the component that calls it. If two components each call onCloudCannonChanges(), the first to unmount stops updates for both.

Call onCloudCannonChanges() in one component per page, or accept that unmounting any one of them ends previews for the rest until the page reloads.

Getting help#

If the connector does not behave as described, contact support with your Site name, the Svelte and SvelteKit versions your project uses, and what you expected to happen. You can also raise an issue on the GitHub repository.