GrapesJS Vue: Construye un editor visual con Vue 3

Sí. GrapesJS es independiente del framework y puede integrarse directamente en aplicaciones Vue 3. Puedes inicializar el editor con ganchos de ciclo de vida Vue, mantener la instancia del editor en un composable o componente, conectar eventos GrapesJS a tu aplicación Vue y persistir los datos del proyecto a través de tu propio backend.

Dos formas de hacerlo

GrapesJS publica un wrapper oficial de framework, @grapesjs/react, para React. No existe un paquete equivalente de Vue del proyecto GrapesJS, así que cualquier wrapper de Vue que encuentres en npm es un proyecto comunitario. Consulta sus rangos de pares Vue y GrapesJS antes de adoptarlo.

Vue 3 es un framework de aplicaciones. GrapesJS es un motor de edición visual. Resuelven diferentes problemas y la integración es limpia precisamente porque no se solapan.

Cinco de estos son tuyos. El resto ya existe, y los dos restantes son de configuración y no de construcción.

Una dependencia. GrapesJS incluye sus propias definiciones de TypeScript, así que no hay un paquete de @types separado para añadir.

Copia esto en un componente y se ejecuta. Todo lo que viene después de esta sección es una adición, no una reescritura.

<template>
  <div ref="editorContainer" class="editor-shell"></div>
</template>

<script setup lang="ts">
import { onMounted, onUnmounted, shallowRef, ref } from 'vue';
import grapesjs, { type Editor } from 'grapesjs';
import 'grapesjs/dist/css/grapes.min.css';

// A template ref: the name matches the ref="" attribute above.
const editorContainer = ref<HTMLDivElement | null>(null);

// shallowRef, not ref — see "Performance" further down the page.
const editor = shallowRef<Editor | null>(null);

onMounted(() => {
  if (!editorContainer.value) return;

  editor.value = grapesjs.init({
    container: editorContainer.value,
    height: '100%',
    fromElement: false,
    storageManager: false,
  });
});

onUnmounted(() => {
  editor.value?.destroy();
  editor.value = null;
});
</script>

<style scoped>
.editor-shell {
  height: 100vh;
}
</style>

Toda la integración es un mapeo del ciclo de vida. Vue te dice cuándo existe el nodo DOM y cuándo está a punto de desaparecer; GrapesJS necesita exactamente esos dos momentos.

Lee de arriba a abajo, ese es todo el contrato entre las dos bibliotecas.

Ni onMounted ni onUnmounted se ejecutan en el servidor, por eso una SPA Vue simple no necesita nada extra. Una aplicación renderizada en servidor necesita un protector más — la sección Nuxt lo cubre.

Cuando una segunda pantalla necesite un editor, mueve el ciclo de vida a un composable. El componente entonces dice lo que quiere, no cómo está cableado el editor.

// composables/useGrapesJS.ts
import { onMounted, onUnmounted, shallowRef, type Ref } from 'vue';
import grapesjs, { type Editor, type EditorConfig } from 'grapesjs';
import 'grapesjs/dist/css/grapes.min.css';

type EditorOptions = Omit<EditorConfig, 'container'>;

export function useGrapesJS(
  container: Ref<HTMLElement | null>,
  options: EditorOptions = {},
) {
  const editor = shallowRef<Editor | null>(null);

  const init = (): Editor | undefined => {
    if (editor.value || !container.value) return;

    editor.value = grapesjs.init({
      container: container.value,
      height: '100%',
      fromElement: false,
      storageManager: false,
      ...options,
    });

    return editor.value;
  };

  const destroy = (): void => {
    editor.value?.destroy();
    editor.value = null;
  };

  onMounted(init);
  onUnmounted(destroy);

  return { editor, init, destroy };
}

<template>
  <div ref="editorContainer" class="editor-shell"></div>
</template>

<script setup lang="ts">
import { ref } from 'vue';
import { useGrapesJS } from '~/composables/useGrapesJS';

const editorContainer = ref<HTMLElement | null>(null);

const { editor } = useGrapesJS(editorContainer, {
  blockManager: {
    blocks: [
      {
        id: 'hero',
        label: 'Hero',
        category: 'Sections',
        content: '<section>…</section>',
      },
    ],
  },
});
</script>

Resiste que esto crezca más de lo necesario. Un composable que envuelve cada módulo GrapesJS en una fachada reactiva es una segunda API para aprender y una segunda cosa para mantener sincronizada.

GrapesJS gestiona el estado del editor. Vue gestiona el estado de la aplicación. Los eventos son la costura: suscríbete a los pocos que tu interfaz realmente refleja y escríbelos en referencias normales.

import { onMounted, ref, shallowRef } from 'vue';
import type { Editor, Component } from 'grapesjs';

const isReady = ref(false);
const isDirty = ref(false);
const saveState = ref<'idle' | 'saving' | 'saved' | 'error'>('idle');
const selectedName = ref<string | null>(null);

function bindEditorEvents(editor: Editor): void {
  editor.on('load', () => {
    isReady.value = true;
  });

  editor.on('component:selected', (component: Component) => {
    selectedName.value = component?.getName?.() ?? null;
  });

  editor.on('component:update', () => {
    isDirty.value = true;
  });

  editor.on('storage:start:store', () => {
    saveState.value = 'saving';
  });

  editor.on('storage:end:store', () => {
    saveState.value = 'saved';
    isDirty.value = false;
  });

  editor.on('storage:error', () => {
    saveState.value = 'error';
  });
}

Imita lo que muestras, no lo que tenga el editor. Copiar el árbol de componentes en una tienda Vue te da dos fuentes de verdad y un error de sincronización.

GrapesJS depende de las APIs DOM del navegador, así que la inicialización del editor solo debería ocurrir en un contexto de navegador. En Nuxt eso significa mantener el editor fuera del renderizado del servidor — todo lo demás es la misma integración que ya tienes.

<!-- pages/editor.vue -->
<template>
  <ClientOnly>
    <VisualEditor />

    <template #fallback>
      <p class="editor-placeholder">Loading the editor…</p>
    </template>
  </ClientOnly>
</template>

<!-- components/VisualEditor.client.vue -->
<template>
  <div ref="editorContainer" class="editor-shell"></div>
</template>

<script setup lang="ts">
import { ref } from 'vue';
import { useGrapesJS } from '~/composables/useGrapesJS';

// Reached only in the browser: the .client suffix keeps this
// component out of the server render, and onMounted never runs
// on the server anyway.
const editorContainer = ref<HTMLElement | null>(null);
const { editor } = useGrapesJS(editorContainer);
</script>

Dos opciones correctas

Ambos son válidos y se combinan. Ninguno es necesario para GrapesJS — lo que GrapesJS requiere es simplemente que init() se ejecute donde existe el documento.

No. La integración directa es una forma completa y soportada de usar GrapesJS, y es lo que hacen los ejemplos de esta página. Un envoltorio es una comodidad, no un requisito.

Para Vue 3 hoy, el componible anterior es el envoltorio. Son unas veinte líneas, usa directamente la API de GrapesJS y no puede quedarse atrás de una versión de la que dependes.

Montar el editor es la primera tarde. Un creador de páginas en el que tus usuarios confíen es el resto del trabajo, y en su mayoría es la configuración de los módulos que GrapesJS ya extiene.

• Canvas

  La superficie editable y los anchos de sus dispositivos.

• Components

  Los tipos que tus usuarios pueden situar y sus rasgos.

• Blocks

  La paleta de la que se arrastran.

• Style Manager

  Qué propiedades CSS están expuestas y a quién.

• Asset Manager

  Imágenes y medios, desde tu almacenamiento.

• Storage Manager

  Donde se cargan y guardan los datos del proyecto.

• Commands

  Acciones nombradas, vinculables a tu propia interfaz.

• Device Manager

  Puntos de interrupción responsivos para la edición y la producción.

• Plugins

  Todo lo anterior, empaquetado y reutilizable.

El mismo núcleo del editor, configurado de forma diferente. Cada uno de estos es un conjunto distinto de bloques, un destino de almacenamiento distinto y un paso de publicación distinto.

Tres cosas que son fáciles de confundir y caras de confundir. Acertar desde el primer día es lo que hace que un documento pueda ser reeditado un año después.

1. User edits
2. ↓→
3. GrapesJS project data
4. ↓→
5. Your API / database
6. ↓→
7. HTML + CSS
8. ↓→
9. Preview / publish

Almacena datos editables del proyecto. Genera HTML y CSS cuando necesites renderizar o publicar.

// Editable state — store this, it is what the editor reloads.
const projectData = editor.getProjectData();

// Rendered output — regenerate this whenever you publish.
const html = editor.getHtml();
const css = editor.getCss();

await fetch(`/api/projects/${projectId}/publish`, {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ projectData, html, css }),
});

// Sanitize `html` on the server before it is served to anyone.

A GrapesJS no le importa cuál sea tu backend. Un adaptador de almacenamiento son dos funciones asíncronas — una que devuelve los datos del proyecto y otra que los acepta — así que el editor se comunica con la API que ya tienes.

1. Vue
2. ↓→
3. GrapesJS storage
4. ↓→
5. REST API
6. ↓→
7. Backend
8. ↓→
9. Database

import grapesjs, { type ProjectData } from 'grapesjs';

// Wherever your app keeps it — a route param, a prop, a store.
const projectId = props.projectId;

const editor = grapesjs.init({
  container: editorContainer.value!,
  fromElement: false,
  storageManager: {
    type: 'app-api',
    autosave: true,
    stepsBeforeSave: 10,
  },
  // Registered as a plugin so the adapter exists before
  // GrapesJS performs its first load.
  plugins: [
    (ed) => {
      ed.Storage.add('app-api', {
        async load(): Promise<ProjectData> {
          const res = await fetch(`/api/projects/${projectId}`);
          if (!res.ok) {
            throw new Error(`Load failed: ${res.status}`);
          }
          return await res.json();
        },

        async store(data: ProjectData) {
          const res = await fetch(`/api/projects/${projectId}`, {
            method: 'PUT',
            headers: { 'Content-Type': 'application/json' },
            body: JSON.stringify({ projectData: data }),
          });
          if (!res.ok) {
            throw new Error(`Save failed: ${res.status}`);
          }
        },
      });
    },
  ],
});

Registrar el adaptador a través del array de plugins importa: garantiza que el almacenamiento exista antes de que GrapesJS realice su primera carga.

El gestor de activos es una interfaz de usuario sobre un endpoint. Apúntalo a la tuya y todas las reglas existentes — autenticación, validación, cuotas, CDN — siguen aplicándose.

// Fetched from your own API before the editor is created.
const assets = await fetch('/api/assets').then((res) => res.json());

const editor = grapesjs.init({
  container: editorContainer.value!,
  assetManager: {
    assets,

    // Uploads go to your endpoint, with your auth and
    // your validation.
    upload: '/api/assets',
    uploadName: 'files',
    multiUpload: true,
    autoAdd: true,
    headers: { Authorization: `Bearer ${token.value}` },
    credentials: 'same-origin',

    // Reject what the backend would reject anyway,
    // before the round trip.
    beforeUpload: (files: File[]) => {
      const limit = 5 * 1024 * 1024;
      const tooBig = files.some((f) => f.size > limit);
      if (tooBig) {
        toast.error('Images must be under 5 MB');
        return false;
      }
    },
  },
});

Un tipo de componente personalizado es la forma en que el editor aprende tu producto. Tiene su propio panel de ajustes, sus propias reglas de caída y su propio bloque en la paleta.

import type { Editor } from 'grapesjs';

export function pricingCardPlugin(editor: Editor): void {
  editor.Components.addType('pricing-card', {
    isComponent: (el) => el.dataset?.gjsType === 'pricing-card',
    model: {
      defaults: {
        tagName: 'section',
        attributes: { 'data-gjs-type': 'pricing-card' },
        // Traits become the settings panel for this component.
        traits: [
          { type: 'text', name: 'plan', label: 'Plan name' },
          { type: 'text', name: 'price', label: 'Price' },
          { type: 'checkbox', name: 'featured', label: 'Featured' },
        ],
        components: `
          <h3 data-gjs-type="text">Starter</h3>
          <p data-gjs-type="text">$0 / month</p>
          <a href="#">Choose plan</a>
        `,
      },
    },
  });

  editor.Blocks.add('pricing-card', {
    label: 'Pricing card',
    category: 'Marketing',
    content: { type: 'pricing-card' },
  });
}

// Pass it to the editor like any other plugin:
// grapesjs.init({ container, plugins: [pricingCardPlugin] })

Un plugin es una función que recibe el editor — la misma firma de función, ya sea que venga de npm, de GJS.Market o de tu propio repositorio. A ninguno le importa que la aplicación anfitriona sea Vue.

import grapesjs from 'grapesjs';
import basicBlocks from 'grapesjs-blocks-basic';
import { pricingCardPlugin } from '~/editor/pricing-card';

const editor = grapesjs.init({
  container: editorContainer.value!,
  plugins: [
    // Options go through a wrapper function: `pluginsOpts`
    // is keyed by string, so it only reaches plugins that
    // were passed to `plugins` by name.
    (ed) => basicBlocks(ed, { flexGrid: true }),
    pricingCardPlugin,
  ],
});

No es un argumento de que construir está mal, sino un inventario de lo que significa construir. Cada fila es un subsistema que existe, lo hayas planeado o no.

Vue te da el marco de la aplicación. GrapesJS te da el motor de edición visual.

El editor es una hoja en ese árbol, no la raíz. Todo lo que está encima es código que habrías escrito de todas formas.

Casi todos los problemas de integración reportados para esta combinación son uno de estos siete.

En Vue 2 la misma integración usa mounted() y beforeDestroy() en lugar de onMounted() y onUnmounted(); el lado GrapesJS no ha cambiado. El nuevo trabajo debería dirigirse a Vue 3 — todo en esta página lo asume.

El orden coincide más o menos con el orden en que esta página los presentó.

1. ✓Instalar GrapesJS
2. ✓Inicializar después de la montura
3. ✓Destruir al desmontar
4. ✓Importar el CSS del GrapesJS
5. ✓Gestionar la ejecución SSR / solo cliente
6. ✓Decidir integración directa vs envoltorio
7. ✓Crea un composable reutilizable cuando sea útil
8. ✓Conecta los eventos del editor que refleja tu interfaz
9. ✓Configurar almacenamiento
10. ✓Configurar activos
11. ✓Añadir componentes personalizados
12. ✓Añade los plugins que tu producto necesite
13. ✓Implementar permisos en el lado del servidor
14. ✓Sanitizar el contenido publicado
15. ✓Edición responsiva a pruebas
16. ✓Prueba la versión de producción