Cómo integrar GrapesJS en WordPress (guía completa 2026)

Cuándo usar GrapesJS con WordPress

GrapesJS es un editor independiente con licencia del MIT — no un bloque de Gutenberg. Incrustarlo en WordPress cuando necesitas un arrastrar y soltar totalmente personalizado y independiente del framework Editor con tu propio flujo de almacenamiento y exportación. Esta guía construye un pequeño plugin: una página de administración que aloja el editor, un endpoint REST que guarda contenido con un nonce y un shortcode que lo renderiza en el frontend.

1. Crear el plugin y poner en cola GrapesJS

En wp-content/plugins/gjs-editor/gjs-editor.php, registra un administrador página y poner GrapesJS en cola solo en esa pantalla. Pasa un nonce REST al guion.

<?php
/* Plugin Name: GJS Editor */

add_action('admin_menu', function () {
    add_menu_page('GrapesJS', 'GrapesJS', 'edit_pages', 'gjs-editor', function () {
        echo '<div id="gjs"><h1>Edit me</h1></div>';
    });
});

add_action('admin_enqueue_scripts', function ($hook) {
    if ($hook !== 'toplevel_page_gjs-editor') {
        return;
    }
    wp_enqueue_style('grapesjs', 'https://unpkg.com/grapesjs/dist/css/grapes.min.css');
    wp_enqueue_script('grapesjs', 'https://unpkg.com/grapesjs', [], null, true);
    wp_enqueue_script('gjs-init', plugins_url('editor.js', __FILE__), ['grapesjs'], null, true);
    wp_localize_script('gjs-init', 'GJS', [
        'root'  => esc_url_raw(rest_url('gjs/v1/page')),
        'nonce' => wp_create_nonce('wp_rest'),
    ]);
});

2. Inicializar GrapesJS con almacenamiento remoto

En editor.js, apunta el Gestor de Almacenamiento a la ruta REST y envía el nonce como X-WP-Nonce cabecera.

const editor = grapesjs.init({
  container: '#gjs',
  height: '100vh',
  fromElement: true,
  storageManager: {
    type: 'remote',
    stepsBeforeSave: 3,
    options: {
      remote: {
        urlStore: GJS.root,
        urlLoad: GJS.root,
        headers: { 'X-WP-Nonce': GJS.nonce },
      },
    },
  },
});

3. Registrar el punto final REST

Guarda el proyecto (y el html/css renderizado) con update_option. A El tipo de publicación personalizada también funciona si necesitas muchas páginas.

add_action('rest_api_init', function () {
    register_rest_route('gjs/v1', '/page', [
        [
            'methods'             => 'GET',
            'permission_callback' => '__return_true',
            'callback'            => function () {
                return get_option('gjs_project', []);
            },
        ],
        [
            'methods'             => 'POST',
            'permission_callback' => function () {
                return current_user_can('edit_pages');
            },
            'callback'            => function (WP_REST_Request $req) {
                $data = $req->get_json_params();
                update_option('gjs_project', $data);
                update_option('gjs_html', $data['gjs-html'] ?? '');
                update_option('gjs_css', $data['gjs-css'] ?? '');
                return ['status' => 'ok'];
            },
        ],
    ]);
});

El X-WP-Nonce encabezado permite a WordPress autenticar a los iniciados usuario, y permission_callback hace cumplir la comprobación de capacidad.

4. Renderizar en el frontend con un shortcode

add_shortcode('gjs_page', function () {
    $css  = get_option('gjs_css', '');
    $html = get_option('gjs_html', '');
    return '<style>' . $css . '</style>' . $html;
});

Entra [gjs_page] en cualquier publicación o página. Sanitise almacenaba el margen en Salida si los no administradores pueden editarlo.

Consejos de seguridad y rendimiento

Mantén la integración ágil y segura. Enqueuea GrapesJS solo en la pantalla del editor (la admin_enqueue_scripts comprobación de gancho), nunca a nivel de sitio, para que el frontend se mantenga rápido. Bloquea la ruta de guardado REST con un permission_callback que llama current_user_can('edit_pages') y siempre envía el X-WP-Nonce encabezado — los nonces expiran (~24h), así que actualiza o vuelve a emitir el nonce para sesiones largas. Renderiza la salida del shortcode en wp_kses_post() lugar de repetirla en bruto. Para muchas páginas, guarda cada una en un tipo de publicación personalizada en lugar de opciones para que las revisiones y capacidades sean gratuitas.

Requisitos previos

Necesitarás WordPress 6+ y PHP 7.4+. Esta guía crea un pequeño plugin, tan básico familiaridad con la API del plugin (hooks, scripts de enqueue, la API REST, nonces, y capacidades) es suficiente. No se requiere ningún paso de compilación: GrapesJS carga desde una CDN o un activo agrupado.

Añadir bloques personalizados al editor

Registrar bloques arrastrables con el Gestor de bloques después grapesjs.initde:

editor.BlockManager.add('hero', {
  label: 'Hero section',
  category: 'Sections',
  content: '<section class="hero"><h1>Headline</h1><p>Copy</p></section>',
});

Saca librerías de bloques y presets listos de GJS. Haz marketing para un conjunto más rico.

Almacenar páginas en un tipo de publicación personalizado

Las opciones funcionan para una sola página, pero un tipo de publicación personalizada te da muchas páginas más revisiones y capacidades gratuitas. Regístrate y guarda el proyecto en postproducción meta, y luego leerlo de nuevo en las referencias de REST mostradas antes. Quédate con el proyecto, renderizado HTML y CSS juntos para que una página se reabra exactamente como guardada.

Consejos de rendimiento

Poner GrapesJS en cola solo en la pantalla de tu editor (la admin_enqueue_scripts Comprobación de gancho), nunca a toda la zona, así que la parte delantera se mantiene firme. Almacenar en caché el código corto Sácalo y lo rompes en la partida. Pospone el script de editor para que nunca bloquee al administrador UI.

Consideraciones de seguridad

Bloquea la ruta de guardado REST con un permission_callback que llama current_user_can('edit_pages') y siempre envía el X-WP-Nonce Encabezado — los nonces expiran (~24h), así que revísalos o reeditalos para sesiones largas. Renderizar la salida del front-end a través wp_kses_post() de en lugar de repetir el margen en bruto.

Resolución de errores comunes

403 (rest_cookie_invalid_nonce) significa que falta el nonce o caducado. Un lienzo sin estilo significa que la hoja de estilo no estaba en cola. Un editor en blanco significa que el elemento contenedor no estaba en el admin Página. Si los guardados fallan silenciosamente, confirma que la comprobación de capacidad pasa para la corriente usuario.

Cuándo usar GrapesJS con WordPress

GrapesJS se adapta a un editor visual totalmente personalizado y independiente del framework, integrado en tu administrador propio o producto — cuando quieres tu propio almacenamiento y salida HTML en lugar de extendiendo Gutenberg. Si solo necesitas editar contenido dentro de WordPress con su modelo de bloques, Gutenberg es la elección nativa; para una página de propiedad propia y incrustable constructor, GrapesJS es el más adecuado.

Próximos pasos

Añade bloques y plugins para que encajen con tu tema. Véase el relacionado Guía GrapesJS + Laravel , Compara editores en GrapesJS con Builder.io, navega por el mercado de GrapesJS, o empieza desde el GJS. Página principal del mercado.

Preguntas frecuentes

¿Cómo guardo contenido de GrapesJS en WordPress?

Registrar una ruta REST, enviar la solicitud con la X-WP-Nonce cabecera, y guardar el proyecto/html/css con update_option (o una publicación personalizada tipo).

¿Puede GrapesJS reemplazar el editor de bloques de WordPress?

GrapesJS es un editor independiente que incrustas tú mismo, no un bloque de Gutenberg. Úsalo Cuando necesitas un editor totalmente personalizado, independiente del framework, con tu propio almacenamiento y exportar en lugar de ampliar Gutenberg.

¿Cómo autentifico la solicitud de guardado?

Pasa un nuce desde wp_create_nonce('wp_rest') la vía wp_localize_script, entonces envíalo como el X-WP-Nonce para que el REST permission_callback tenga éxito.