Enqueue Custom Scripts in Etch

Sometimes your frontend relies on JavaScript from plugins or external sources, but those scripts aren’t loaded inside the Etch editor. That can cause a mismatch between how your page behaves while you’re building it and how it behaves for visitors.

Etch exposes a hook that lets you enqueue additional scripts specifically for the editor canvas so your preview matches your frontend more closely.

The hook is etch/canvas/enqueue_assets. This runs inside Etch’s canvas load, and anything you enqueue there via wp_enqueue_script() will be detected and injected into the editor iframe.

How it works

Under the hood, Etch temporarily clears the normal WordPress script/style queues, fires etch/canvas/enqueue_assets, and then inspects what you’ve enqueued. Any scripts it finds are converted into a list and added to the iframe as additional scripts.

A few key points:

• Scope: Scripts enqueued on etch/canvas/enqueue_assets are used only in the Etch canvas iframe.
• Frontend/editor: This hook does not automatically enqueue scripts on the frontend or in the block editor. You still need to handle those with the usual WordPress APIs (wp_enqueue_script() on the right actions).
• Standard WP API: You use the normal wp_enqueue_script() function, just attached to Etch’s canvas hook.
• Global vs. conditional: Scripts loaded this way run globally in the editor. If you need scripts to load conditionally based on whether specific elements are on the page, use Etch’s built-in JavaScript editor instead.

On to the Code!

Here’s a simple example that loads a local script and an external script into the Etch canvas:

add_action( 'etch/canvas/enqueue_assets', function () {
    // Enqueue a script that lives in your theme
    wp_enqueue_script(
        'my-custom-canvas-script',
        get_stylesheet_directory_uri() . '/assets/js/canvas-preview.js',
        array( 'jquery' ),     // Dependencies (optional)
        '1.0.0',
        true                   // Load in footer
    );

    // Enqueue an external script (for example, a library CDN)
    wp_enqueue_script(
        'my-external-library',
        'https://example.com/path/to/library.js',
        array(),
        null,
        true
    );
} );

add_action( 'etch/canvas/enqueue_assets', function () {
    // Enqueue a script that lives in your theme
    wp_enqueue_script(
        'my-custom-canvas-script',
        get_stylesheet_directory_uri() . '/assets/js/canvas-preview.js',
        array( 'jquery' ),     // Dependencies (optional)
        '1.0.0',
        true                   // Load in footer
    );

    // Enqueue an external script (for example, a library CDN)
    wp_enqueue_script(
        'my-external-library',
        'https://example.com/path/to/library.js',
        array(),
        null,
        true
    );
} );

What this does:

• my-custom-canvas-script is loaded into the Etch canvas so any behaviors you rely on there (animations, custom interactions, etc.) work while you’re designing.
• my-external-library ensures third‑party scripts you use on the frontend are also present in the editor canvas.

Don’t forget the frontend

To keep everything consistent, you’ll typically want to enqueue the same scripts on the frontend as well. A clean way to do this is to put your enqueue logic in a single function and attach it to both hooks.

/**
 * Enqueue scripts used both on the frontend and in the Etch canvas.
 */
function mytheme_enqueue_shared_scripts() {
    // Script in your theme
    wp_enqueue_script(
        'my-custom-canvas-script',
        get_stylesheet_directory_uri() . '/assets/js/canvas-preview.js',
        array( 'jquery' ),
        '1.0.0',
        true
    );

    // External library (for example, a CDN)
    wp_enqueue_script(
        'my-external-library',
        'https://example.com/path/to/library.js',
        array(),
        null,
        true
    );
}

// Frontend
add_action( 'wp_enqueue_scripts', 'mytheme_enqueue_shared_scripts' );

// Etch editor
add_action( 'etch/canvas/enqueue_assets', 'mytheme_enqueue_shared_scripts' );

/**
 * Enqueue scripts used both on the frontend and in the Etch canvas.
 */
function mytheme_enqueue_shared_scripts() {
    // Script in your theme
    wp_enqueue_script(
        'my-custom-canvas-script',
        get_stylesheet_directory_uri() . '/assets/js/canvas-preview.js',
        array( 'jquery' ),
        '1.0.0',
        true
    );

    // External library (for example, a CDN)
    wp_enqueue_script(
        'my-external-library',
        'https://example.com/path/to/library.js',
        array(),
        null,
        true
    );
}

// Frontend
add_action( 'wp_enqueue_scripts', 'mytheme_enqueue_shared_scripts' );

// Etch editor
add_action( 'etch/canvas/enqueue_assets', 'mytheme_enqueue_shared_scripts' );

This way:

• mytheme_enqueue_shared_scripts() defines your full script set.
• wp_enqueue_scripts loads them for site visitors.
• etch/canvas/enqueue_assets loads the same set inside the Etch canvas, so behavior matches.

Wrapping it up

By hooking into etch/canvas/enqueue_assets and using wp_enqueue_script() as you normally would, you can ensure that any important JavaScript your site relies on is also available inside the Etch canvas. Pairing this with your regular wp_enqueue_scripts logic keeps behavior consistent between the editor and the live site.

If you also need to load extra CSS alongside your scripts, check out this related snippet for enqueuing custom stylesheets into Etch.