Cómo crear un plugin personalizado de GrapesJS (paso a paso, 2026)

Qué es realmente un plugin GrapesJS

Un plugin de GrapesJS es simplemente una función que recibe el editor y unas opciones Objeto: (editor, opts) => { /* register things */ }. Dentro de él Añade bloques, comandos, componentes, paneles o almacenamiento. No hay clase especial para extender. Esta guía crea un plugin pequeño pero real y lo empaqueta para npm.

1. La función de plugins

// src/index.js
export default (editor, opts = {}) => {
  const options = {
    label: 'My Block',
    category: 'My Plugin',
    ...opts,                       // caller overrides win
  };

  editor.BlockManager.add('my-block', {
    label: options.label,
    category: options.category,
    content: '<section class="my-block"><h2>Hello</h2></section>',
  });
};

2. Úsalo en un editor

import grapesjs from 'grapesjs';
import myPlugin from './src/index.js';

grapesjs.init({
  container: '#gjs',
  plugins: [myPlugin],
  pluginsOpts: {
    // keyed by plugin name when loaded by string; for a function, pass opts here
  },
});

Cuando cargas un plugin por la cadena de nombre de su paquete, GrapesJS lee sus opciones de pluginsOpts['package-name'].

3. Añadir un comando y un botón

editor.Commands.add('say-hi', {
  run: () => editor.Modal.open({ title: 'Hi', content: 'From my plugin' }),
});

editor.Panels.addButton('options', {
  id: 'say-hi',
  className: 'fa fa-smile-o',
  command: 'say-hi',
});

4. Empaquetarlo para npm

• Exporta la función del plugin como el paquete por defecto.
• Listar grapesjs como peerDependency, no como dependencia.
• Crea un paquete ESM + UMD (Rollup, o el inicio oficial del plugin GrapesJS).
• Corre npm publish.

Consejos para plugins robustos

Algunos hábitos separan un script desechable de un plugin que se puede enviar. Espacia todos los id que registres (bloques, comandos, componentes) con un prefijo para que dos plugins nunca colisionen. Siempre fusiona un objeto por defecto con el que opts entra y lee el resultado, para que los llamantes puedan anular el comportamiento sin editar tu código. Declara grapesjs como , peerDependencyno como dependencia, para que la app anfitriona controle la versión. Limpia todo lo que adjuntes (oyentes del DOM, temporizadores) en el evento del destroy editor. Y documenta tus opciones: un plugin que nadie puede configurar se bifurca, no se reutiliza.

Requisitos previos

Necesitas una configuración de GrapesJS funcional y JavaScript básico. Un plugin es solo una función (editor, opts) => {} — no hay clase que extender ni paso de construcción Empieza. Solo necesitas un bundler (Vite, Webpack o Rollup) cuando empaquetas el plugin para distribución.

Un plugin más completo: bloquear + comando + botón

Los plugins reales suelen registrar varias cosas a la vez. Aquí un único plugin añade un bloque, un comando y un botón de barra de herramientas:

export default (editor, opts = {}) => {
  const options = { label: 'Hi', ...opts };

  editor.BlockManager.add('callout', {
    label: 'Callout',
    category: 'Custom',
    content: '<div class="callout">Note</div>',
  });

  editor.Commands.add('say-hi', {
    run: () => editor.Modal.open({ title: options.label, content: 'From my plugin' }),
  });

  editor.Panels.addButton('options', {
    id: 'say-hi', className: 'fa fa-smile-o', command: 'say-hi',
  });
};

Limpiar sobre destruir

Si tu plugin conecta escuchadores DOM, temporizadores o recursos externos, libéralos en el evento del destroy editor incrustando repetidamente al editor (común en enrutamiento SPA) no tiene fugas:

const onScroll = () => {/* … */};
window.addEventListener('scroll', onScroll);
editor.on('destroy', () => window.removeEventListener('scroll', onScroll));

Mejores prácticas

Escribe un espacio de nombres a cada id que registres (bloques, comandos, componentes) con un prefijo, es decir, dos Los plugins nunca colisionan. Siempre fusiona un objeto por defecto con el que entra opts. Declara grapesjs como así peerDependency La app anfitriona controla la versión. Mantener una responsabilidad por cada plugin y documento Sus opciones — un plugin que nadie puede configurar se bifurca, no se reutiliza.

Empaquetalo para NPM

Exporta la función como paquete por defecto, construye un paquete ESM + UMD (Rollup o el inicio oficial de plugins GrapesJS), listados grapesjs como dependencia entre pares, y corre. npm publish Los consumidores la cargan por nombre y pasan las opciones a través de pluginsOpts.

Próximos pasos

¿Quieres adelantarte? Genera un andamiaje de plugins con el GJS. Generador de plugins de mercado y luego sumérgete en ello añadir bloques personalizados y Componentes personalizados. Consulta el libro completo Catálogo de plugins GrapesJS o partir del GJS. Página principal del mercado.

Preguntas frecuentes

¿Qué es un plugin GrapesJS?

Una función (editor, opts) => {} que registra bloques, comandos, componentes, paneles o almacenamiento. Se lo pasas a grapesjs.init través del plugins Arreglo.

¿Cómo añado opciones a un plugin?

Fusiona un objeto por defecto con el que opts entra y lee desde el resultado. Los llamantes los configuran mediante pluginsOpts.

¿Cómo publico en NPM?

Exporta la función como predeterminada, declara grapesjs como par dependencia, construir un paquete y ejecutar npm publish.