GrapesJS TypeScript: Vollständiger Integrationsleitfaden

Zwölf Schritte, in der Reihenfolge. Jeder führt zu dem Abschnitt, der ihn behandelt, sodass du dort starten kannst, wo dein Projekt tatsächlich steht.

1. 01GrapesJS mit TypeScript installierenEine Abhängigkeit, kein Typpaket und der Unterschied zwischen einem Laufzeitimport und einem reinen Typimport.
2. 02TypeScript konfigurierenDie vier Compiler-Optionen, die für Editor-Arbeit wichtig sind – und warum strictNullChecks die eigentliche Arbeit macht.
3. 03Den Editor typisierengrapesjs.init gibt Editor zurück. Wenn man es als Editor | null hält, verhindert man den häufigsten Absturz.
4. 04Arbeit mit KomponentenComponent, ComponentDefinition und die addType-Signatur, die die meisten Tutorials falsch bekommen.
5. 05Blöcke typisierenBlockProperties wurde vom Editor getrennt deklariert, sodass ein Block für sich genommen überprüft wird.
6. 06Events verwalteneditor.on leitet seine Rückbelehnung aus dem Namen des Events ab – und bleibt für eigene Events offen.
7. 07Bau-PluginsPlugin<Options> gibt beide Parameter ein, und das Exportieren der Optionsoberfläche macht es nutzbar.
8. 08Erstellen Sie benutzerdefinierte KomponentenEin komponiertes Hero, einmal als Schnittstelle beschrieben und von Editor, API und Renderer wiederverwendet.
9. 09Storage und API-Daten typisierenProjectData ist das JSON des Editors. ProjectRecord ist deine Reihe. Sie sind nicht vom gleichen Typ.
10. 10Verwende GrapesJS mit ReactDie offizielle Verpackung und die manuelle useEffect-Version – mit der Reinigung, die StrictMode erfordert.
11. 11Verwende GrapesJS mit Next.jsWo die Client-Grenze verläuft und warum der Editor nicht darüber erstellt werden kann.
12. 12Strukturierung eines ProduktionseditorsEine Naht zwischen deiner Anwendung und dem Editor, sodass keine in die andere übergeht.

Es gibt ein Paket. Die Typen kommen mit, sodass es keine zweite Installation und keinen @types Eintrag in deinem devDependencies gibt.

npm install grapesjs

Der Befehl, nicht zu fliehen

@types/grapesjs ist weder veraltet, ersetzt noch optional – es fehlt im npm-Register. Das Ausführen dieses Tutorials gibt einen 404 zurück, und wenn man es in einem älteren Tutorial sieht, ist das ein zuverlässiges Signal, dass der Rest dieses Tutorials auch älter ist als die mitgelieferten Typen.

# Don't. This package is not published — npm returns E404.
npm install --save-dev @types/grapesjs

Laufzeit-Importe vs. Typ-only-Importe

grapesjs selbst ist ein Wert: Sie rufen grapesjs.init() auf. Editor, Component und Block sind Typen: Sie existieren nur während der Kompilierung. Wenn Sie sie mit import type markieren, wird das explizit und garantiert, dass der Import gelöscht wird und nicht in Ihr Bundle gezogen wird – was im Framework-Code am wichtigsten ist, wo ein zufälliger Laufzeit-Import des Editors ihn in ein Server-Rendering ziehen kann.

// Runtime import: the value you actually call.
import grapesjs from 'grapesjs';

// Type-only import: erased at compile time, ships nothing to the bundle.
import type { Editor, Component, Block } from 'grapesjs';

// Editor styles. Without them the canvas renders unstyled.
import 'grapesjs/dist/css/grapes.min.css';

Du brauchst keine spezielle Konfiguration für GrapesJS. Du musst vier Optionen richtig eingestellt haben – der Rest deiner tsconfig kann das bleiben, was dein Projekt bereits nutzt.

{
  "compilerOptions": {
    // GrapesJS's bundled .d.ts uses const type parameters, a TypeScript 5.0
    // feature. On 4.9 and below the file fails to *parse*, and every import
    // from 'grapesjs' reports "Cannot find module".
    "target": "ES2020",
    "module": "ESNext",
    "moduleResolution": "bundler",

    // The editor manipulates real DOM nodes: container elements, iframes,
    // drag events. Without the DOM lib none of that type-checks.
    "lib": ["ES2020", "DOM", "DOM.Iterable"],

    // strict is what makes the typings worth having. In particular
    // strictNullChecks is what forces you to handle "editor not created yet",
    // which is the single most common GrapesJS runtime crash.
    "strict": true,

    "skipLibCheck": true,
    "esModuleInterop": true
  }
}

Ziel und Modul

Alles ab ES2020 und aufwärts. Die Deklarationsdatei verwendet Template-Literal-Typen und Const-Typ-Parameter, sodass die Constraint die TypeScript-Version ist, nicht das Emitt-Ziel.

Bibliothek muss DOM enthalten

Der Editor arbeitet mit realen Elementen, iframes und Drag-Events. Ohne die DOM-Bibliothek kontrolliert grapesjs.init({ container: element }) nicht den Typ, und der Fehler sieht eher wie ein GrapesJS-Problem als ein Konfigurationsproblem aus.

streng – speziell strictNullChecks

Das ist die Option, die sich ihren Platz verdient. Sie zwingt dich, das Fenster zu verwalten, in dem der Editor noch nicht existiert: vor Init, nach Destroy und beim ersten Rendering einer Ref. Diese Lücke ist die mit Abstand häufigste Ursache für Laufzeitfehler bei Framework-Integrationen.

moduleResolution

bundler für Vite, Next.js und die meisten modernen Setups; node16 oder nodenext, wenn du mit dem eigenen Algorithmus von Node auflösst. Beide finden das Typfeld des Pakets.

Das sind die Namen, die Sie tatsächlich importieren werden. Jeder wurde mit der Deklarationsdatei von grapesjs 0.23.6 überprüft, anstatt von der Dokumentationsseite kopiert zu werden, die JavaScript API beschreibt und nicht immer die gleichen Namen verwendet.

Alle diese sind mit Namen importierbar: import type { Editor, Component, BlockProperties } von 'grapesjs'. Nur grapesjs selbst benötigt einen Laufzeit-Import.

grapesjs.init() gibt einen Editor zurück. Das Annotieren der Variablen ist optional – die Schlussfolgerung macht es bereits richtig – aber die Benennung des Typs ermöglicht es dir, den Editor über Modulgrenzen hinweg zu führen, ohne ihn auf irgendwelche zu erweitern.

import grapesjs from 'grapesjs';
import type { Editor } from 'grapesjs';
import 'grapesjs/dist/css/grapes.min.css';

const editor: Editor = grapesjs.init({
  container: '#gjs',
  height: '100vh',
  storageManager: false,
});

// Both return values are typed, and they are not the same shape:
// getHtml() always returns a string, getCss() can return undefined.
const html: string = editor.getHtml();
const css: string | undefined = editor.getCss();

• Autovervollständigung folgt der Instanz: Editor. listet jeden Manager auf, und jeder Manager listet seine eigenen Methoden mit seinen echten Signaturen auf.
• getHtml() gibt String zurück; getCss() gibt String | undefiniert zurück. Der Unterschied ist real, und der strenge Modus lässt dich damit umgehen.
• destroy() ist Teil des API, kein Zusatz. Die Framework-Bereinigung hängt davon ab.

Nullable Referenzen, bei denen der Wert ist

In einem Framework existiert der Editor beim ersten Rendern noch nicht und darf nach dem Unmount nicht mehr existieren. Die Variable, die ihn hält, als Editor | null zu typisieren zwingt den Compiler, an jeder Aufrufstelle nach beiden Momenten zu fragen. Sie als Editor zu typisieren und das per Assertion wegzuräumen verschiebt diese Frage in die Produktion.

import type { Editor } from 'grapesjs';

// Not `let editor: Editor` — before init there is no editor, and the type
// should say so. Every call site is then forced to handle the empty case.
let editor: Editor | null = null;

export function exportHtml(): string {
  if (!editor) throw new Error('Editor is not initialised yet');
  return editor.getHtml(); // narrowed to Editor here
}

export function destroy(): void {
  editor?.destroy();
  editor = null;
}

Erreichen der Manager

Jeder Manager hängt am Editor ab – editor.Blocks, editor.Components, editor.Storage, editor.Commands – und jeder Getter wird typisiert, sodass Autocomplete von der Instanz nach unten funktioniert. Was du nicht tun kannst, ist, die Manager-Klassen nach Namen zu importieren; sie stattdessen über Editor alias.

import type { Editor } from 'grapesjs';

// These names are NOT exported from 'grapesjs' — importing them by name is a
// compile error. Index into Editor instead and you get the same classes.
type BlockManager = Editor['Blocks'];
type StorageManager = Editor['Storage'];
type ComponentManager = Editor['Components'];

export function countBlocks(blocks: BlockManager): number {
  return blocks.getAll().length;
}

editor.on ist generisch über dem Ereignisnamen, sodass die Callback-Signatur aus dem String, den du passierst, abgeleitet wird. In der Praxis bedeutet das, dass du fast nichts annotieren solltest – die Inferenz liefert dir die richtigen Parametertypen, und eine Annotation, die nicht übereinstimmt, ist ein Kompilierungsfehler und kein stilles Fehlmatch.

import type { Editor } from 'grapesjs';

export function wireEditorEvents(editor: Editor): void {
  // No annotation needed. `component` is inferred as Component and
  // `options` carries `action`, which tells add from move from clone.
  editor.on('component:add', (component, options) => {
    console.log(component.get('type'), options.action);
  });

  // A different event, a different payload — the callback signature changes
  // with the event name, so a wrong parameter list is a compile error.
  editor.on('component:selected', (component) => {
    console.log(component.getId());
  });

  editor.on('storage:end:store', () => {
    console.log('Project saved');
  });
}

Die Eventfamilien, die Sie nutzen werden

Component-Events

component:add, component:remove, component:update, component:selected, component:mount. Das erste Argument ist das Component; component:add erhält außerdem ein Optionsobjekt, dessen Aktion einen Add von einem Zug eines Klons unterscheidet.

Editor-Lebenszyklus

Laden, sobald der Editor bereit ist, bei jeder Änderung am Projekt aktualisieren, beim Teardown zerstören. Hier hängst du deinen eigenen Speicherindikator oder die Dirty-State-Flagge an.

Speicherereignisse

storage:start:store, storage:end:store, storage:error. Gerade deshalb sind sie nützlich, weil sie um deine eigene Speicherimplementierung herum laufen, sodass ein fehlerhafter Speicherstand im UI statt in der Konsole auftauchen kann.

Block-Events

block:drag:start, block:drag:stop und das eigene Hinzufügen und Entfernen des Block Manager. Praktisch für Analysen darüber, welche Blöcke man tatsächlich angreifen sollte.

Wo die Schlussfolgerung endet

Der Ereignisname ist eine offene String-Union, absichtlich: Plugins definieren ihre eigenen Kanäle, die sich ständig kompilieren müssen. Der Nachteil ist, dass ein Tippfehler im Kern-Ereignisnamen weiterhin gültig ist als TypeScript – der Rückruf fällt einfach auf eine lose Signatur zurück und wird nie ausgelöst. Wenn ein Event Handler auf mysteriöse Weise nichts tut, überprüfen Sie die Rechtschreibung, bevor Sie die API überprüfen.

import type { Editor } from 'grapesjs';

export function wireCustomEvents(editor: Editor): void {
  // Your own events are allowed — the event name is a string union that stays
  // open, so plugins can define their own channels.
  editor.on('my-plugin:published', (...args: unknown[]) => {
    console.log(args);
  });

  // Which is also the trade-off: this typo compiles. The callback simply falls
  // back to (...args: any[]) and never fires.
  // editor.on('component:selcted', (component) => { ... });
}

Ein Komponententyp registriert neues Verhalten auf der Canvas: ein Tag, sein traits, was es als Kinder akzeptiert, wie es erkannt wird, wenn HTML wieder eingelesen wird. Hier findet die meiste Arbeit in benutzerdefinierten Editoren statt, und dort muss die Grenze zwischen den GrapesJS-Typen und deinen gezogen werden.

Die richtige Unterschrift

editor.Components.addType (Typ, Optionen) nimmt AddComponentTypeOptions – model, view, isComponent, extend – nicht ein ComponentDefinition. ComponentDefinition beschreibt einen deklarierten Knoten innerhalb eines Baums: die Kinder einer Komponente oder den Inhalt eines Blocks. Tutorials, die einen ComponentDefinition an addType weitergeben, zitieren eine ältere Form, und der Fehler, den man daraus erhält, ist nicht offensichtlich.

import type { Editor, Component } from 'grapesjs';

// YOUR domain model. GrapesJS knows nothing about it, and that is the point:
// this is the shape your API, your database and your React props agree on.
export interface HeroContent {
  headline: string;
  subheadline?: string;
  ctaLabel: string;
  ctaHref: string;
}

const HERO_DEFAULTS: HeroContent = {
  headline: 'Your headline',
  ctaLabel: 'Get started',
  ctaHref: '#',
};

// addType takes AddComponentTypeOptions — model / view / isComponent — not a
// ComponentDefinition. Tutorials that pass a ComponentDefinition here are
// describing an API that no longer exists.
export function registerHero(editor: Editor): void {
  editor.Components.addType('hero', {
    isComponent: (el) => el.dataset?.gjsType === 'hero',
    model: {
      defaults: {
        tagName: 'section',
        droppable: false,
        attributes: { 'data-gjs-type': 'hero' },
        traits: [
          { type: 'text', name: 'headline', label: 'Headline' },
          { type: 'text', name: 'ctaLabel', label: 'Button label' },
          { type: 'text', name: 'ctaHref', label: 'Button link' },
        ],
        ...HERO_DEFAULTS,
      },
    },
  });
}

// The bridge back to your model. component.get() is intentionally loose —
// this function is where that looseness stops and HeroContent begins.
export function readHero(component: Component): HeroContent {
  return {
    headline: component.get('headline') ?? HERO_DEFAULTS.headline,
    subheadline: component.get('subheadline'),
    ctaLabel: component.get('ctaLabel') ?? HERO_DEFAULTS.ctaLabel,
    ctaHref: component.get('ctaHref') ?? HERO_DEFAULTS.ctaHref,
  };
}

• Eigenschaften sind das Einstellungspanel. Jeder Eintrag nennt ein Modellfeld, sodass das Panel und deine Benutzeroberfläche im Einklang bleiben.
• isComponent ist der Weg, wie eine gespeicherte Seite beim Laden erkannt wird. Ohne es verwandelt das Neuladen deinen benutzerdefinierten Abschnitt wieder in eine einfache Div.
• droppable und draggable sind Booleans oder Selektoren – hier verhindert man, dass jemand einen hero in einen Knopf legt.

Ein Block ist das, was im linken Regal erscheint und was ein Nutzer zieht. Es ist keine Komponente – es ist eine Erklärung, was eingefügt werden soll. Es lohnt sich, die beiden frühzeitig im Gleichgewicht zu halten, da ihre Typen nicht austauschbar sind und die Fehlermeldung dies nicht angibt.

import type { Editor, Block, BlockProperties } from 'grapesjs';

// BlockProperties is exported, so the block can be declared away from the
// editor and checked on its own — label, category, media, content.
const heroBlock: BlockProperties = {
  label: 'Hero',
  category: 'Sections',
  media: '<svg viewBox="0 0 24 24"><rect width="24" height="24" /></svg>',
  // A block's content can be a component definition rather than an HTML
  // string, which is how a block and a custom component type stay in sync.
  content: { type: 'hero' },
};

export function addHeroBlock(editor: Editor): Block {
  // Blocks.add(id, props) returns the created Block.
  return editor.Blocks.add('hero', heroBlock);
}

Was eine Blockerklärung betrifft

id

Erstes Argument zu Blocks.add, nicht zu einem Feld. Einzigartig pro Editor; das Wiederhinzufügen derselben ID ersetzt den Block.

Label

Was der Nutzer im Regal liest. Das eine Feld hier, das in deine Locale-Dateien gehört.

Kategorie

Gruppiert das Regal. Eine Zeichenkette oder ein Objekt, wenn du es standardmäßig kollabieren möchtest.

Inhalt

Was eingefügt wird: ein HTML-String oder eine Komponentendefinition. Bevorzuge die Definition – sie hält den Block an einen Komponententyp gebunden, statt an einen Ausschnitt des Markups.

Medien

Das Thumbnail, als Inline-SVG. Nichts hindert dich daran, einen <img> zu verwenden, aber Inline-SVG folgt dem Thema des Editors.

Eigenschaften

Angewandt auf das Regalelement selbst – nützlich für Test-IDs und Analyse-Hooks, nicht für das eingefügte Element.

Blocks.add gibt das erstellte Block zurück, sodass Sie es später erfassen und das Regal anpassen können – also durch Neuordnung, das Ausstecken von Blöcken, die der Nutzerplan nicht enthält, oder das Tauschen eines Kategorielabels zur Laufzeit.

Ein GrapesJS-Plugin ist eine Funktion, die den Editor und ein Options-Objekt empfängt. Das ist der ganze Vertrag – weshalb Plugins die natürliche Einheit für alles sind, was man über Editoren hinweg wiederverwenden, an ein anderes Team verschicken oder verkaufen möchte.

Eine Form, die Wachstum überdauert

Eine Datei pro Registrierungsart. Der Grund ist nicht die Ordentlichkeit: blocks.ts exportiert BlockProperties-Objekte, die ohne Editor im Umfang typprüfen, sodass sie unit-getestet und wiederverwendet werden können, ohne überhaupt einen Editor zu starten.

import type { Editor, Plugin } from 'grapesjs';

// Export the options type. A consumer cannot configure your plugin safely if
// the shape of `options` lives only inside your implementation.
export interface SectionsPluginOptions {
  category?: string;
  blockPrefix?: string;
}

// Plugin<T> is (editor: Editor, config: T) => PluginResult. Typing the
// function as Plugin<SectionsPluginOptions> checks both parameters for you.
const sectionsPlugin: Plugin<SectionsPluginOptions> = (editor, options) => {
  // Defaults belong here, not in the type — an optional field plus a
  // destructured default is what makes the call site free to omit them.
  const { category = 'Sections', blockPrefix = 'sec' } = options;

  editor.Blocks.add(`${blockPrefix}-hero`, {
    label: 'Hero',
    category,
    content: { type: 'hero' },
  });

  editor.Commands.add(`${blockPrefix}:reset`, {
    run(ed: Editor) {
      ed.setComponents('');
    },
  });
};

export default sectionsPlugin;

Was der Typ dir kauft

Optionen

Exportiere die Benutzeroberfläche. Ein Verbraucher, der die Form deiner Optionen nicht sehen kann, muss deine Quellcode lesen, um dein Plugin zu konfigurieren.

Standardeinstellungen

Optionale Felder im Typ, Standardwerte destrukturiert im Body. Standardmäßig in den Typ einzufügen, macht stattdessen jedes Feld am Callsite erforderlich.

Der Editor-Parameter

Für Sie von Plugin<T> typisiert. Alles, was Sie darin registrieren – Blöcke, Komponententypen, Befehle – wird mit den echten Manager-Signaturen überprüft.

Registrierung

Blocks, Komponententypen, Befehle und Ereignishandler gehören alle zur gleichen Funktion. Ein Plugin, das zum Aufruf nichts registriert und auf ein Ereignis wartet, ist ebenfalls in Ordnung.

Registrierung

Eine Closure zu übergeben hält deine Optionen an der Aufrufstelle typisiert. Die Alternative – das Plugin in plugins und seine Einstellungen in pluginsOpts aufzulisten – typisiert diese Einstellungen als loses Record, sodass ein falsch geschriebener Schlüssel kompiliert und stillschweigend nichts tut.

import grapesjs from 'grapesjs';
import sectionsPlugin, { type SectionsPluginOptions } from './my-grapesjs-plugin';

const options: SectionsPluginOptions = { category: 'Marketing' };

grapesjs.init({
  container: '#gjs',
  // Passing a closure keeps the options typed at the call site. The alternative
  // — plugins: [sectionsPlugin] with pluginsOpts — types options as
  // Record<string, any>, so a misspelled key compiles and silently does nothing.
  plugins: [(editor) => sectionsPlugin(editor, options)],
});

Ein Design-System-Abschnitt ist keine einzelne Komponente – es ist ein kleiner Baum mit einer Form, für die Ihr Produkt bereits einen Namen hat. Diese Form einmal als Schnittstelle zu beschreiben, ist das, was verhindert, dass Editor, API und Renderer auseinanderdriften.

Ein Abschnitt, vier Typen

import type { Editor, ComponentDefinition } from 'grapesjs';

// The composed shape, described once. Every layer below — the editor default,
// the API payload, the renderer — is checked against this one interface.
export interface HeroContent {
  headline: string;
  description: string;
  ctaLabel: string;
  ctaHref: string;
}

// ComponentDefinition is what goes *inside* a tree: the children of a
// component, or the `content` of a block. It is not what addType takes.
const heroChildren = (content: HeroContent): ComponentDefinition[] => [
  { type: 'text', tagName: 'h1', content: content.headline },
  { type: 'text', tagName: 'p', content: content.description },
  {
    type: 'link',
    content: content.ctaLabel,
    attributes: { href: content.ctaHref },
  },
];

export function registerDesignSystem(
  editor: Editor,
  defaults: HeroContent
): void {
  editor.Components.addType('hero', {
    model: {
      defaults: {
        tagName: 'section',
        droppable: false,
        // Children are declared, not hand-written as an HTML string, so a
        // renamed field is a compile error rather than a silently stale block.
        components: heroChildren(defaults),
        traits: [
          { type: 'text', name: 'headline', label: 'Headline' },
          { type: 'text', name: 'ctaHref', label: 'Button link' },
        ],
      },
    },
  });
}

Was typisiert werden sollte – und was nicht

Die Inhaltsoberfläche

Deins. Schlagzeile, Beschreibung, Aufruf zum Handeln – die Felder, die ein Marketer ausfüllt, und dein API speichert.

Der Bauteiltyp

GrapesJS's. Einmal bei addType registriert und das Tag, das traits und die Kinder deklariert.

Merkmale

Die Brücke. Jedes Merkmal benennt ein Feld im Modell, daher sollte das Umbenennen eines Feldes in deiner Benutzeroberfläche die Eigenschaftsliste zerstören – und mit den Standardwerten ist das auch so.

Kinder

ComponentDefinition-Objekte statt eines HTML-Strings. Ein String kompiliert, egal was man eingibt; eine Definition wird überprüft.

Eigenschaften

Wo der Data-GJS-Typ lebt, was isComponent beim Nachladen übereinstimmt.

Der Vorteil ist heute nicht weniger Fehler – sondern dass sechs Monate später das Hinzufügen eines Feldes zu HeroContent eine Liste aller Stellen erzeugt, die geändert werden müssen, anstatt im gesamten Code nach dem String 'Headline' zu suchen.

Speicher ist der Ort, an dem sich die beiden Typen von Systemen auf die folgenschwerste Weise treffen, weil dies die Grenze ist, die in Ihrer Datenbank landet. Fehler zu machen ist später teuer; Richtig zu machen sind etwa zwanzig Zeilen.

Zwei Formen, nicht eine

ProjectData ist das eigene JSON des Editors. Seine interne Struktur gehört zu GrapesJS, ändert sich zwischen Versionen und ist nicht etwas, das man manuell migrieren kann. Dein ProjectRecord ist eine Zeile: eine ID, ein Besitzer, ein Name, eine Version, Zeitstempel – plus dieser undurchsichtige Blob in einer Spalte. Speichere es, lade es und lasse das Innere in Ruhe.

import type { ProjectData } from 'grapesjs';

// The editor's own JSON. ProjectData is deliberately open — its internal shape
// is GrapesJS's business and changes between versions, so treat it as opaque:
// store it, load it, never reach into it or migrate it by hand.

// YOUR row. This is the type your API returns and your database stores, and it
// is not a GrapesJS type. Keeping the two apart is what lets you add a column,
// change a version scheme or move providers without touching editor code.
export interface ProjectRecord {
  id: string;
  name: string;
  userId: string;
  version: number;
  updatedAt: string;
  projectData: ProjectData;
}

import grapesjs from 'grapesjs';
import type { Editor, ProjectData } from 'grapesjs';
import type { ProjectRecord } from './types/projects';

export function createEditor(projectId: string): Editor {
  const editor = grapesjs.init({
    container: '#gjs',
    storageManager: {
      // The id of the storage you register below.
      type: 'remote-api',
      autosave: true,
      stepsBeforeSave: 5,
    },
  });

  editor.Storage.add('remote-api', {
    async load(): Promise<ProjectData> {
      const res = await fetch(`/api/projects/${projectId}`);
      // Throwing here is what makes the editor emit storage:error. Returning
      // an empty object instead loses the reader's work without telling them.
      if (!res.ok) throw new Error(`Load failed: ${res.status}`);
      const record = (await res.json()) as ProjectRecord;
      return record.projectData;
    },

    async store(data: ProjectData): Promise<void> {
      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}`);
    },
  });

  editor.on('storage:error', (error) => console.error(error));

  return editor;
}

Was der Adapter bewältigen muss

Last

Geben Sie den ProjectData für das aktuelle Projekt zurück. Eine fehlgeschlagene Antwort ist der Grund, warum der Editor storage:error ausgibt, anstatt lautlos eine leere Canvas zu öffnen.

Laden

Senden Sie die Daten so, wie sie sind. Formen Sie sie nicht beim Aussteigen neu – was auch immer Sie entfernen, der Editor erwartet beim Laden eine Wiederbewahrung.

Autosave

autosave mit stepsBeforeSave-Batches ändert sich. Jeder Tastendruck ist keine Anfrage, und die Nummer gehört dir, um sie einzustellen.

Versionierung

Eine Versionsspalte in deiner Zeile, serverseitig erhöht. Version des Datensatzes, niemals des JSON des Editors.

Mehrfach-Mietverhältnisse

Die Projekt-ID ist eine Variable aus der Closure des Adapters, und die Zugehörigkeit wird serverseitig geprüft. Der Editor kennt keine Benutzer und sollte auch keine bekommen.

Es gibt einen offiziellen React-Wrapper – @grapesjs/react, MIT-lizenziert, derzeit 2.0.0 – und er liefert eine eigene Deklarationsdatei. Er rendert keine React-Komponenten innerhalb der Canvas; er mountet den Editor und übergibt dir die Instanz.

'use client';

import { useRef } from 'react';
import grapesjs from 'grapesjs';
import type { Editor, ProjectData } from 'grapesjs';
import GjsEditor from '@grapesjs/react';
import 'grapesjs/dist/css/grapes.min.css';

interface PageEditorProps {
  projectId: string;
  onSave: (projectId: string, data: ProjectData) => void;
}

export default function PageEditor({ projectId, onSave }: PageEditorProps) {
  const editorRef = useRef<Editor | null>(null);

  return (
    <GjsEditor
      // Required. The wrapper does not import grapesjs itself — you pass the
      // module (or a CDN URL), which is what lets you control the version.
      grapesjs={grapesjs}
      options={{ height: '100vh', storageManager: false }}
      onEditor={(editor) => {
        editorRef.current = editor;
      }}
      // projectData is typed as ProjectData, so it lines up with the record
      // type your save endpoint expects.
      onUpdate={(projectData) => onSave(projectId, projectData)}
    />
  );
}

Das grapesjs-Requisit ist erforderlich. Der Wrapper importiert absichtlich den Editor selbst nicht, sodass die Version in deinem Bundle die in deinem package.json bleibt – und du kannst sie stattdessen auf einen CDN-Build verweisen.

Oder ohne die Verpackung

Der Wrapper ist eine Bequemlichkeit, keine Voraussetzung. Ein useEffect mit Ref erledigt denselben Zweck in etwa fünfzehn Zeilen und ist auch dann verständlich, wenn man den Wrapper verwendet, weil er die beiden Regeln explizit macht: den Ref bewachen und beim Aufräumen zerstören.

'use client';

import { useEffect, useRef } from 'react';
import grapesjs from 'grapesjs';
import type { Editor } from 'grapesjs';
import 'grapesjs/dist/css/grapes.min.css';

export default function PageEditor() {
  const containerRef = useRef<HTMLDivElement | null>(null);
  const editorRef = useRef<Editor | null>(null);

  useEffect(() => {
    // strictNullChecks forces this guard, and it is not ceremony: the ref is
    // null on the first render, before React has attached the div.
    if (!containerRef.current) return;

    const editor = grapesjs.init({
      container: containerRef.current,
      height: '100vh',
      storageManager: false,
    });
    editorRef.current = editor;

    // Without destroy(), React 18's development StrictMode double-mount leaves
    // two editors bound to one container.
    return () => {
      editor.destroy();
      editorRef.current = null;
    };
  }, []);

  return <div ref={containerRef} />;
}

• Die Container-Ref ist beim ersten Rendern null. strictNullChecks lässt dich sagen, was dann passiert.
• Gib eine Cleanup zurück, die destroy() aufruft. React 18s Entwicklungs-StrictMode mountet zweimal, und ohne sie hast du zwei Editoren in einem Div.
• Der Peer-Bereich des Wrappers ist React ^18.0.0 || ^19.0.0. Bei React 17 befindet man sich auf dem manuellen Weg.

Die ganze Next.js-Frage ist eine einzige Grenze. grapesjs.init benötigt ein echtes DOM-Element, plus Dokument und Fenster; ein Server Component hat keine davon. Der Editor legt also einen Client Component, und alles darüber kann auf dem Server bleiben.

Wo die Linie verläuft

'use client' ist oben in der Komponente, die den Editor erstellt, und nirgendwo höher. Die Seite darüber bleibt ein Server Component: Es wartet auf Params, überprüft die Sitzung, lädt das Projekt und gibt einfache Requisiten weiter. Diese Aufteilung ist es wert, geschützt zu werden, denn wenn man 'use client' um eine Datei nach oben verschiebt, wird das Datenladen leise zu Client-Code.

// app/editor/[id]/editor-client.tsx
'use client';

import { useEffect, useRef } from 'react';
import grapesjs from 'grapesjs';
import type { Editor } from 'grapesjs';
import 'grapesjs/dist/css/grapes.min.css';

export default function EditorClient({ projectId }: { projectId: string }) {
  const containerRef = useRef<HTMLDivElement | null>(null);
  const editorRef = useRef<Editor | null>(null);

  // grapesjs.init needs a real element, document and window. Calling it in a
  // module body — or in a Server Component — runs it during the server render,
  // where none of those exist. useEffect only runs in the browser, which is
  // the whole requirement.
  useEffect(() => {
    if (!containerRef.current) return;
    const editor = grapesjs.init({
      container: containerRef.current,
      height: '100vh',
    });
    editorRef.current = editor;
    return () => {
      editor.destroy();
      editorRef.current = null;
    };
  }, [projectId]);

  return <div ref={containerRef} />;
}

// app/editor/[id]/page.tsx  — a Server Component, no 'use client'
import EditorClient from './editor-client';

interface PageProps {
  params: Promise<{ id: string }>;
}

export default async function EditorPage({ params }: PageProps) {
  const { id } = await params;

  // Auth, data loading and permissions stay on the server, fully typed.
  // Only the editor itself crosses into the client.
  return <EditorClient projectId={id} />;
}

useEffect, nicht der Modulkörper

Das Importieren von grapesjs auf dem Server ist harmlos – es ist das Aufrufen von init(), das fehlschlägt. useEffect läuft nur im Browser, was die gesamte Voraussetzung ist.

Dynamischer Import ist optional

next/dynamic mit ssr: false ist eine Bundle-Size-Entscheidung, keine Korrektheitsentscheidung, und es ist in einem Server Component nicht verfügbar. Greifen Sie dazu, wenn der Editor nur ein kleiner Teil einer großen Seite ist; überspringen Sie ihn auf einer Route, die nur der Editor ist.

CSS

Importiere grapesjs/dist/css/grapes.min.css aus der Client-Komponente. Ohne sie rendert die Canvas unstyled und sieht eher kaputt als unstylet aus.

Aufräumarbeiten

Dasselbe wie bei React: destroy() bei der Rückkehr des Effekts. Routenübergänge demounten die Komponente, und ein Editor, der seinen Container überlebt, leakt seine Hörer.

Beide funktionieren und folgen der gleichen Form wie die manuelle React-Version: eine Vorlagenreferenz, Initialisierung nach dem Vorhandensein des Elements, Zerstörung beim Zerlegen. Die framework-spezifischen Mechaniken haben hier eigene Leitfäden, nicht eine komprimierte Version.

In beiden Fällen sind die Typen dieselben, die diese Seite verwendet hat: Editor, Component, ProjectData. Das Framework ändert, wo init() genannt wird, nicht das, was es zurückgibt.

Alles oben liegt in einer Datei. Es passt nicht mehr bei etwa der dritten benutzerdefinierten Komponente, und entscheidend darüber, ob das nächste Jahr angenehm wird, ist, wo du die Naht zwischen deiner Anwendung und dem Editor platzierst.

Eine Struktur, die Bestand hat

Eine Naht, erklärt

Anwendungscode sollte nicht direkt von 'grapesjs' importiert werden. Gib ihm ein einziges Modul, das die wenigen Editor-Typen, die dein Produkt wirklich kennt, erneut exportiert, die Manager, die nicht exportiert werden, und die enge Schnittstelle deklariert, auf die dein UI tatsächlich angewiesen ist. Dann nimmt ein Toolbar-Button diese Schnittstelle ein, nicht ein ganzes Editor – und kann nicht einmal versehentlich in die Editor-Internen eindringen.

// src/types/editor.ts — the single seam between your app and the editor.
import type { Editor, ProjectData } from 'grapesjs';

// Re-export what your application is allowed to know about.
export type { Editor, ProjectData };

// Manager classes are not exported by name; alias them here once so no other
// file has to remember that.
export type BlockManager = Editor['Blocks'];
export type StorageManager = Editor['Storage'];

// The surface your UI actually depends on. Application code takes this, not a
// full Editor, so a toolbar button cannot quietly reach into editor internals.
export interface EditorFacade {
  getHtml(): string;
  getCss(): string;
  save(): Promise<void>;
  destroy(): void;
}

Deine Anwendung oben, deine Typen in der Mitte, der Editor darunter. Abhängigkeiten zeigen nach unten und gehen nie zurück.

1. 01

   Anwendung

   Deins. Weiß nichts über GrapesJS.

   • Routing
   • Authentifizierung
   • Anwendungszustand
   • Dein UI
   ↓
2. 02

   Typen

   Die Naht. Der einzige Ort, an dem beide Welten benannt sind.

   • Domänenmodell
   • Projektunterlagen
   • API-Verträge
   ↓
3. 03

   Editor-Schicht

   Deiner. Der einzige Code, der aus dem Editor importiert wird.

   • createEditor
   • Plugins
   • Component-Typen
   • Speicheradapter
   ↓
4. 04

   GrapesJS

   Der Lektor. Nach dem Paket typisiert.

   • Canvas
   • Trainer
   • Veranstaltungen

Ein Page-Builder-Produkt ist meist kein Page Builder. GrapesJS deckt ein Feld in dieser Kette ab; der Rest ist eine Anwendung, die du sowieso schreiben wolltest, und das Tippen der Joins zwischen ihnen ist das, worauf dieser Guide hinausgearbeitet hat.

GrapesJS besitzt die Bearbeitungsfläche. Authentifizierung, Speicherung, Mietverhältnisse, Abrechnung und Veröffentlichung gehören Ihnen.

Der Editor ist ein Bestandteil deines Produkts, kein Ersatz dafür.

Elf Fehlschläge, die wiederholt auftreten, die meisten sind spezifisch für dieses Paar und nicht für TypeScript im Allgemeinen. Jeder ist ein Symptom, gegen das du dich abgleichen kannst, und die Änderung, die es behebt.

Keines davon sind TypeScript-Probleme. Es sind Stellen, an denen das Modell des Editors und das Modell deines Produkts miteinander verwechselt werden, und das Typsystem ist nur das, was die Verwirrung frühzeitig sichtbar macht.

Vier Fehlerformen decken fast alles ab. In jedem Fall ist der nützliche Schritt, die Deklarationsdatei in node_modules zu betrachten, anstatt nach einer zu greifen – die Antwort ist dort enthalten, und jede verschiebt nur die Frage.

Für framework-spezifische Typfehler gehen die React- und Next.js-Anleitungen tiefer als diese Seite.

Exakte Versionen, die mit dem Register und der installierten Deklarationsdatei überprüft wurden. Der TypeScript-Floor wurde insbesondere gemessen, indem er mit jeder Version kompiliert wurde und nicht aus einem Changelog abgeleitet wurde.

Verifizierte 2026-09-03 mit registry.npmjs.org und node_modules/grapesjs/dist/index.d.ts. Jeder Codebeispiel auf dieser Seite wurde vor der Veröffentlichung im strengen Modus gegen diese Versionen kompiliert.

Sobald du den Kern von API verstehst, können Plugins zusätzliche Funktionen bieten, ohne dass du jedes Feature von Grund auf neu bauen musst. Dies sind aktuelle Einträge auf GJS.Market, gruppiert nach dem Teil der typisierten Oberfläche, die jeder berührt.

Speicherung und Persistenz

Wo ProjectData auf deine Datenbank trifft. Die Schicht, um die sich der Speicherabschnitt dieses Leitfadens handelt.

Kategorie ansehen

Directus Storage

Ein Speicheradapter für ein headless CMS-Backend – derselbe Load/Store-Vertrag, den man von Hand implementieren würde.

KostenlosPlugin ansehen

IndexedDB Storage

Browser-lokale Persistenz. Nützlich als Entwurfsschicht vor einem entfernten Adapter.

KostenlosPlugin ansehen

Cloud Firestore

Firestore als Projektspeicher, wobei das Dokument für dein ProjectRecord steht.

KostenlosPlugin ansehen

Grapesjs Firebase Storage

Firebase-gestützter Speicher für Projekte, verkabelt über den Storage Manager.

KostenlosPlugin ansehen

Components und Inhalt

Component-Typen, die du sonst bei addType registrieren würdest.

Kategorie ansehen

Tabs Component

Ein tabierter Komponententyp mit eigenem traits – ein ausgearbeitetes Beispiel für addType, das man lesen kann.

KostenlosPlugin ansehen

Grapesjs Component Icon

Eine Icon-Komponente mit einem Picker-Merkmal, das zeigt, wie ein Merkmal ein Komponentenfeld steuert.

50,00 $Plugin ansehen

Symbols

Wiederverwendbare verknüpfte Instanzen, sodass eine Bearbeitung über Seiten hinweg verbreitet wird.

KostenlosPlugin ansehen

Typed Text

Ein Schreibmaschineneffekt-Komponenten-Wrapping Typed.js – eine Drittanbieterbibliothek, die als Komponententyp offengelegt wird.

KostenlosPlugin ansehen

Entwickler-Tools

Codebearbeitung, Skriptbearbeitung und Projektmanagement im Editor.

Kategorie ansehen

Grapesjs Component Code Editor

Bearbeiten Sie die HTML und CSS eines Bauteils, das ist der schnellste Weg, um zu sehen, was Ihre Bauteiltypen tatsächlich produzieren.

KostenlosPlugin ansehen

Grapesjs Script Editor

Fügen Sie Komponentenskripte aus dem Editor an und bearbeiten Sie sie.

KostenlosPlugin ansehen

Grapesjs Plugin Toolbox

Eine Reihe von Editor-Tools, die sich an Menschen richten, die auf GrapesJS aufbauen, und nicht an Endnutzer.

KostenlosPlugin ansehen

Grapesjs Project Manager

Multiprojekt-Handling im Editor, angrenzend an die Speicherschicht darüber.

KostenlosPlugin ansehen

React und UI

Starter und Presets für React-basierte Editor-Stacks.

Kategorie ansehen

React UI for GrapesJS

React-basierter Editor UI rund um die GrapesJS-Canvas.

KostenlosPlugin ansehen

GrapesJS React Demo — Starter Integration for React Developers

Eine funktionierende React-Integration kannst du zusammen mit dem React-Abschnitt dieses Leitfadens lesen.

KostenlosPlugin ansehen

Hero React Component GrapesJS

Eine hero-Komponente für React-basierte Stacks – der Abschnitt, den dieser Guide von Hand erstellt.

KostenlosPlugin ansehen

Reactor Preset for GrapesJS

Ein Preset, das sich an React-Entwickler richtet und Blöcke und Komponenten bündelt.

KostenlosPlugin ansehen

Die Zeile bezieht sich nicht auf die Schwierigkeit. Es geht darum, ob das Verhalten spezifisch für Ihr Produkt ist – denn das entscheidet, wer es in zwei Jahren warten muss.

In der Praxis sind die meisten Editoren beides: eine Handvoll Plugins für die Teile, die jeder Editor benötigt, und eigene typisierte Komponententypen für die Teile, die das Produkt zu Ihrem machen.

Wohin als Nächstes, je nachdem, ob du den Editor noch lernst, ihn in ein Framework einbindest oder ein Produkt darum herum baust.

Wenn der Architekturbereich der eigentliche Standort Ihres Projekts ist, besteht die verbleibende Arbeit meist aus Integration und nicht aus Editor-Funktionen. Das ist es, was wir tun.

• TypeScript-Plugins
• Benutzerdefinierte Bauteiltypen
• React-Integration
• Next.js-Integration
• Speicher- und API-Integration
• SaaS-Editoren
• White-Label-Editoren
• Benutzerdefinierter Editor UI
• Migrationen von älteren Versionen
• Produktionsarchitektur-Review

Beginne mit dem typisierten GrapesJS API, baue eigene Komponenten und Plugins, verbinde deine Anwendungsinfrastruktur und erweitere den Editor, wenn dein Produkt mehr Funktionalität benötigt.