Handle components that cannot render in the Visual Editor

Astro

Replace the component in the Visual Editor

Register a different component under the name your templates already use.

To replace a component in the Visual Editor:

1. Create a simpler version of your component in your local development environment.
2. Register your replacement under the name your templates already use.
3. Save your changes and rebuild your Site.

import { registerAstroComponent } from '@cloudcannon/editable-regions/astro';
import EditorFriendlyCard from '../components/editor-friendly/Card.astro';

registerAstroComponent('card', EditorFriendlyCard); 

CloudCannon will render your replacement in the Visual Editor, and the original component on your live Site.

Detect the Visual Editor

The Astro integration defines a global boolean called ENV_CLIENT, which is true when your code runs in CloudCannon's renderer and false in a normal build.

To render a fallback when your component cannot run in the Visual Editor:

1. Open the component that cannot render in your local development environment.
2. Add a condition on ENV_CLIENT that returns a fallback instead of the code that cannot run.
3. Save your changes and rebuild your Site.

---
import WeatherWidget from "./WeatherWidget.astro";
---

{ENV_CLIENT
  ? <p>Weather is not available while editing.</p>
  : <WeatherWidget />}

CloudCannon will show your fallback in the Visual Editor, and render the component normally on your live Site.

Eleventy

Replace an include in the Visual Editor

CloudCannon resolves component names the same way your templates resolve includes. Use the components option to point a component name at a different template, which CloudCannon uses instead of the one it found.

To replace an include in the Visual Editor:

1. Create a simpler version of your include in your local development environment.
2. Map your component name to your replacement with the components option.
3. Save your changes and rebuild your Site.

eleventyConfig.addPlugin(editableRegions, {
  liquid: {
    components: {
      "author-card": "./src/_includes/editor-friendly/author-card.liquid", 
    },
  },
});

CloudCannon will render your replacement in the Visual Editor, and the original include on your live Site.

Replace a helper in the Visual Editor

CloudCannon copies your filters, shortcodes, paired shortcodes, and custom tags out of your Eleventy configuration file. Any that depend on a Node package cannot be copied, so provide a browser version and register it under the same name.

To replace a helper in the Visual Editor:

1. Create a browser version of your filter, shortcode, paired shortcode, or tag in your local development environment.
2. Map its name to your browser version in the Editable Regions plugin options.
3. Save your changes and rebuild your Site.

export default () => "Image adjustments are not previewed while editing";

eleventyConfig.addPlugin(editableRegions, {
  liquid: {
    filters: {
      sharpen: "./img/sharpen-browser.js", 
    },
  },
});

CloudCannon will use your browser version in the Visual Editor, and exclude the original from the copy it sends to the browser.

Stub a package

CloudCannon always stubs Node built-in modules and the Eleventy toolchain out of the browser bundle. If your configuration file uses another package that cannot run in a browser, name it with the browserStub option.

To stub a package out of the browser bundle:

1. Open your Eleventy configuration file in your local development environment.
2. Add the package name to the browserStub option.
3. Save your changes and rebuild your Site.

eleventyConfig.addPlugin(editableRegions, {
  liquid: {
    browserStub: ["sharp"],
  },
});

CloudCannon will replace that package with a stub when it builds the browser bundle.

Stubbing stops a package from breaking the bundle, but it does not make the code that uses it work. If a filter, shortcode, or tag calls the stubbed package while CloudCannon renders your template, it will still throw. Provide a browser version for that helper as well.

Pass build data to the Visual Editor

Templates rendered in the Visual Editor cannot read the global data your build provides. Pass any values they need with the globals option. Values must be JSON-serializable, because CloudCannon embeds them at build time.

To pass global data to your templates in the Visual Editor:

1. Open your Eleventy configuration file in your local development environment.
2. Add the values your templates need to the globals option.
3. Save your changes and rebuild your Site.

eleventyConfig.addPlugin(editableRegions, {
  globals: {
    env: { API_BASE: process.env.API_BASE },
  },
});

CloudCannon will expose those values to your templates in the Visual Editor.

Hugo

Replace a template in the Visual Editor

Use the templates_overrides option to swap a template for a simpler version. The key is the path of the template CloudCannon found, and the value is the path of the replacement. Relative paths resolve against the root of your Hugo project.

To replace a template in the Visual Editor:

1. Create a simpler version of your template in your local development environment.
2. Map the path of the original template to your replacement with the templates_overrides option.
3. Save your changes and rebuild your Site.

[params.editable_regions.templates_overrides]
  "layouts/partials/card.html" = "overrides/card.html"

CloudCannon will render your replacement in the Visual Editor, and the original template on your live Site.

Detect the Visual Editor

The Hugo module defines a site parameter called ENV_CLIENT, which is true when your code runs in CloudCannon's renderer and false in a normal build.

To render a fallback when your template cannot run in the Visual Editor:

1. Open the template that cannot render in your local development environment.
2. Add a condition on site.Params.ENV_CLIENT that outputs a fallback instead of the code that cannot run.
3. Save your changes and rebuild your Site.

{{ if site.Params.ENV_CLIENT }}
  <p>Weather is not available while editing.</p>
{{ else }}
  {{ partial "weather-widget" . }}
{{ end }}

CloudCannon will show your fallback in the Visual Editor, and render the template normally on your live Site.

Bundle extra files

CloudCannon finds your templates, configuration files, and internationalization files automatically, and reads your content and datasets from your Site. Anything else your templates read is not included.

To bundle extra files for the Visual Editor:

1. Open your Hugo configuration file in your local development environment.
2. Name individual files with the additional_paths option, or directories and their file extensions with the additional_dirs option. CloudCannon walks each directory recursively.
3. Save your changes and rebuild your Site.

[params.editable_regions]
  additional_paths = ["lookups/pricing.json"]

  [params.editable_regions.additional_dirs]
    "lookups" = ["json", "csv"]

CloudCannon will read those files when it renders your templates in the Visual Editor.

Vendor your modules

CloudCannon rebuilds your Site from the files bundled at build time, so module imports resolve only against files inside your project. Themes in your themes directory are covered automatically, but modules from Hugo's module cache are not.

To make your module templates available in the Visual Editor:

1. Open your website project in your local development environment.
2. Run the hugo mod vendor command in your terminal.
3. Save your changes and rebuild your Site.

hugo mod vendor

CloudCannon will discover your vendored templates like your own, and bundle the module graph file, _vendor/modules.txt, so it can resolve your module imports.

Your vendored files are part of your website project, so commit the _vendor directory alongside your other changes.

JavaScript frameworks

Replace the component in the Visual Editor

Next.js, Nuxt, SvelteKit, and single-page applications built with React, Vue, or Svelte register each component under a name, the same way Astro does. Register a different component under the name your templates already use.

To replace a component in the Visual Editor:

1. Create a simpler version of your component in your local development environment.
2. Register your replacement under the name your templates already use.
3. Save your changes and rebuild your Site.

"use client";

import { useEffect } from "react";
import { registerReactComponent } from "@cloudcannon/editable-regions/react";
import EditorFriendlyCard from "./editor-friendly/Card.jsx";

export default function CloudCannon() {
  useEffect(() => {
    if (window.inEditorMode) {
      registerReactComponent("card", EditorFriendlyCard); 
    }
  }, []);

  return null;
}

CloudCannon will render your replacement in the Visual Editor, and the original component on your live Site.

Detect the Visual Editor

These frameworks define no ENV_CLIENT global. To render a fallback, check window.inEditorMode, which CloudCannon sets before any of your own scripts run. For more information, please read our documentation on detecting the Visual Editor.