GrapesJS Vue: Baue einen visuellen Editor mit Vue 3

Ja. GrapesJS ist framework-agnostisch und kann direkt in Vue-3-Anwendungen integriert werden. Man kann den Editor mit Vue-Lebenszyklus-Hooks initialisieren, die Editor-Instanz in einem Composable oder einer Komponente speichern, GrapesJS-Ereignisse mit der Vue-Anwendung verbinden und Projektdaten über das eigene Backend speichern.

Zwei Möglichkeiten, es zu tun.

GrapesJS veröffentlicht einen offiziellen Framework-Wrapper, @grapesjs/react, für React. Es gibt kein äquivalentes Vue-Paket aus dem GrapesJS-Projekt, daher ist jeder Vue-Wrapper, den du auf npm findest, ein Community-Projekt. Überprüfe die Vue- und GrapesJS-Peer-Bereiche, bevor du ihn einsetzt.

Vue 3 ist ein Anwendungsframework. GrapesJS ist eine visuelle Bearbeitungs-Engine. Sie lösen verschiedene Probleme, und die Integration ist sauber, gerade weil sie sich nicht überlappen.

Fünf davon gehören dir. Der Rest existiert bereits, und die beiden übrigen sind Konfiguration und nicht Konstruktion.

Eine Abhängigkeit. GrapesJS liefert seine eigenen TypeScript-Definitionen aus, daher gibt es kein separates @types-Paket hinzuzufügen.

Kopiere das in eine Komponente und es läuft. Alles nach diesem Abschnitt ist eine Ergänzung, keine Neuschreibung.

<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>

Die gesamte Integration ist eine Lebenszyklus-Kartierung. Vue zeigt an, wann der DOM-Knoten existiert und wann er kurz davor ist zu verschwinden; GrapesJS benötigt genau diese beiden Momente.

Lies es von oben bis unten, das ist der gesamte Vertrag zwischen den beiden Bibliotheken.

Weder onMounted noch onUnmounted laufen auf dem Server, weshalb ein einfaches Vue-SPA nichts Zusätzliches benötigt. Eine servergerenderte App benötigt einen zusätzlichen Schutz – der Abschnitt Nuxt behandelt das.

Sobald ein zweiter Bildschirm einen Editor braucht, verschiebe den Lebenszyklus in ein Composable. Die Komponente sagt dann, was sie will, nicht wie der Editor verdrahtet ist.

// 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>

Widerstehe es, das weiter auszubauen, als nötig. Ein Composable, das jedes GrapesJS-Modul in eine reaktive Fassade umhüllt, ist eine zweite API zum Lernen und eine zweite Sache, die man synchron halten muss.

GrapesJS verwaltet den Editor-Zustand. Vue verwaltet den Anwendungszustand. Ereignisse sind die Naht: Abonniere die wenigen, die deine Benutzeroberfläche tatsächlich widerspiegelt, und schreibe sie in gewöhnliche Referenzen.

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';
  });
}

Spiegele das, was du anzeigst, nicht das, was der Editor enthält. Das Kopieren des Komponentenbaums in einen Vue-Store liefert dir zwei Quellen der Wahrheit und einen Synchronisationsfehler.

GrapesJS basiert auf Browser-DOM-APIs, daher sollte die Editor-Initialisierung nur im Browserkontext erfolgen. In Nuxt bedeutet das, den Editor aus dem Server-Rendering fernzuhalten – alles andere ist die gleiche Integration, die du bereits hast.

<!-- 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>

Zwei richtige Optionen

Beides ist gültig und kombiniert sich. Keines von beiden ist von GrapesJS vorgeschrieben – was GrapesJS verlangt, ist einfach, dass init() dort läuft, wo das Dokument existiert.

Nein. Direkte Integration ist eine vollständige, unterstützte Methode zur Nutzung von GrapesJS, und genau das tun die Beispiele auf dieser Seite. Ein Wrapper ist eine Bequemlichkeit, keine Voraussetzung.

Für Vue 3 ist heute das Composable oben der Wrapper. Es umfasst gut zwanzig Zeilen, nutzt die GrapesJS-API direkt und kann keinem Release hinterherhinken, von dem du abhängst.

Das Mounten des Editors ist der erste Nachmittag. Ein Seitenbauer, dem deine Nutzer vertrauen, ist der Rest der Arbeit, und es ist hauptsächlich die Konfiguration der Module, die GrapesJS bereits offenlegt.

• Canvas

  Die editierbare Oberfläche und ihre Gerätebreiten.

• Components

  Die Typen, die deine Nutzer einordnen können, und deren Eigenschaften.

• Blocks

  Die Palette, von der sie ziehen.

• Style Manager

  Welche CSS-Eigenschaften sind offen und wem?

• Asset Manager

  Bilder und Medien aus deinem Lager.

• Storage Manager

  Wo Projektdaten geladen und gespeichert werden.

• Commands

  Benannte Aktionen, die an deine eigene Benutzeroberfläche gebunden werden können.

• Device Manager

  Reaktionsschnelle Breakpoints für Bearbeitung und Ausgabe.

• Plugins

  Alles oben ist verpackt und wiederverwendbar.

Derselbe Editor-Core, anders konfiguriert. Jeder dieser Blöcke ist ein anderer Satz von Blöcken, ein anderes Speicherziel und ein anderer Veröffentlichungsschritt.

Drei Dinge, die leicht zu vermischen und teuer zu vermischen sind. Das am ersten Tag richtig zu machen, macht ein Dokument auch ein Jahr später wieder bearbeitbar.

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

Speichere editierbare Projektdaten. Generiere HTML und CSS, wenn du rendern oder veröffentlichen musst.

// 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.

GrapesJS ist egal, was dein Backend ist. Ein Speicheradapter besteht aus zwei asynchronen Funktionen – eine, die Projektdaten zurückgibt, eine, die sie akzeptiert – sodass der Editor mit der bereits vorhandenen API kommuniziert.

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}`);
          }
        },
      });
    },
  ],
});

Die Registrierung des Adapters über das Plugin-Array ist wichtig: Es garantiert, dass der Speicher existiert, bevor GrapesJS erstmals geladen wird.

Der Asset Manager ist eine Benutzeroberfläche über einem Endpunkt. Zeigt man ihn auf seinen eigenen und jede bestehende Regel – Authentifizierung, Validierung, Quoten, CDN – gilt weiterhin.

// 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;
      }
    },
  },
});

Ein benutzerdefinierter Komponententyp ist der Weg, wie der Editor dein Produkt lernt. Er bekommt ein eigenes Einstellungspanel, eigene Drop-Regeln und einen eigenen Block in der Palette.

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] })

Ein Plugin ist eine Funktion, die den Editor empfängt – dieselbe Funktionssignatur, egal ob sie von npm, GJS.Market oder deinem eigenen Repository stammt. Keiner von ihnen interessiert sich dafür, dass die Host-Anwendung Vue ist.

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,
  ],
});

Kein Argument, dass Bauen falsch ist – sondern eine Bestandsaufnahme dessen, was Bauen bedeutet. Jede Reihe ist ein Subsystem, das existiert, egal ob man es geplant hat oder nicht.

Vue gibt dir das Anwendungs-Framework. GrapesJS gibt dir die visuelle Bearbeitungs-Engine.

Der Editor ist ein Blatt in diesem Baum, nicht die Wurzel. Alles darüber ist Code, den du sowieso geschrieben hättest.

Fast jedes Integrationsproblem, das für diese Kombination gemeldet wurde, gehört zu diesen sieben.

Bei Vue 2 verwendet dieselbe Integration mounted() und beforeDestroy() anstelle von onMounted() und onUnmounted(); die GrapesJS-Seite bleibt unverändert. Neue Arbeiten sollten Vue 3 anvisieren – alles auf dieser Seite geht davon aus.

Die Reihenfolge entspricht ungefähr der Reihenfolge, die diese Seite eingeführt hat.

1. ✓GrapesJS installieren
2. ✓Initialisieren nach der Halterung
3. ✓Zerstören beim Absteigen
4. ✓Importiere das GrapesJS CSS
5. ✓SSR / Client-only Ausführung übernehmen
6. ✓Entscheide dich über direkte Integration vs. Wrapper
7. ✓Erstelle ein wiederverwendbares Composable, wo es nützlich ist
8. ✓Verbinden Sie die Editor-Events, die Ihre Benutzeroberfläche widerspiegelt
9. ✓Speicher konfigurieren
10. ✓Assets konfigurieren
11. ✓Fügen Sie benutzerdefinierte Komponenten hinzu
12. ✓Füge die Plugins hinzu, die dein Produkt benötigt
13. ✓Berechtigungen serverseitig implementieren
14. ✓Veröffentlichte Inhalte säubern
15. ✓Test-responsives Schneiden
16. ✓Teste die Produktionsversion