GrapesJS TypeScript: Complete Integration Guide

Twelve steps, in order. Each one links to the section that covers it, so you can start where your project actually is.

1. 01Install GrapesJS with TypeScriptOne dependency, no types package, and the difference between a runtime import and a type-only import.
2. 02Configure TypeScriptThe four compiler options that matter for editor work — and why strictNullChecks is the one doing real work.
3. 03Type the editorgrapesjs.init returns Editor. Holding it as Editor | null is what stops the most common crash.
4. 04Work with componentsComponent, ComponentDefinition, and the addType signature that most tutorials get wrong.
5. 05Type blocksBlockProperties declared away from the editor, so a block is checked on its own.
6. 06Handle eventseditor.on infers its callback from the event name — and stays open for your own events.
7. 07Build pluginsPlugin<Options> types both parameters, and exporting the options interface is what makes it usable.
8. 08Create custom componentsA composed Hero, described once as an interface and reused by editor, API and renderer.
9. 09Type storage and API dataProjectData is the editor's JSON. ProjectRecord is your row. They are not the same type.
10. 10Use GrapesJS with ReactThe official wrapper, and the manual useEffect version — with the cleanup StrictMode requires.
11. 11Use GrapesJS with Next.jsWhere the client boundary goes, and why the editor cannot be created above it.
12. 12Structure a production editorOne seam between your application and the editor, so neither leaks into the other.

There is one package. The types come with it, so there is no second install and no @types entry in your devDependencies.

npm install grapesjs

The command not to run

@types/grapesjs is not deprecated, superseded or optional — it is absent from the npm registry. Running this returns a 404, and if you see it in an older tutorial that is a reliable signal the rest of that tutorial predates the bundled types too.

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

Runtime imports vs type-only imports

grapesjs itself is a value: you call grapesjs.init(). Editor, Component and Block are types: they exist only during compilation. Marking them with import type makes that explicit, and guarantees the import is erased rather than pulled into your bundle — which matters most in the framework code, where a stray runtime import of the editor can drag it into a server render.

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

You do not need a special configuration for GrapesJS. You need four options set correctly — the rest of your tsconfig can stay whatever your project already uses.

{
  "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
  }
}

target and module

Anything from ES2020 up. The declaration file uses template literal types and const type parameters, so the constraint is the TypeScript version, not the emit target.

lib must include DOM

The editor works on real elements, iframes and drag events. Without the DOM lib, grapesjs.init({ container: element }) does not type-check and the failure looks like a GrapesJS problem rather than a config one.

strict — specifically strictNullChecks

This is the option that earns its keep. It forces you to handle the window where the editor does not exist yet: before init, after destroy, and on a ref's first render. That gap is the single most common source of runtime errors in framework integrations.

moduleResolution

bundler for Vite, Next.js and most modern setups; node16 or nodenext if you are resolving through Node's own algorithm. Both find the package's types field.

These are the names you will actually import. Each one was checked against grapesjs 0.23.6's declaration file rather than copied from the documentation site, which describes the JavaScript API and does not always use the same names.

All of these are importable by name: import type { Editor, Component, BlockProperties } from 'grapesjs'. Only grapesjs itself needs a runtime import.

grapesjs.init() returns an Editor. Annotating the variable is optional — inference already gets it right — but naming the type is what lets you pass the editor across module boundaries without widening it to any.

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();

• Autocomplete follows the instance: editor. lists every manager, and each manager lists its own methods with their real signatures.
• getHtml() returns string; getCss() returns string | undefined. The difference is real, and strict mode makes you handle it.
• destroy() is part of the API, not an extra. Framework cleanup depends on it.

Nullable references, which is where the value is

In a framework the editor does not exist for the first render, and must not exist after unmount. Typing the holder as Editor | null makes the compiler ask about both moments at every call site. Typing it as Editor and asserting it away moves that question to production.

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

Reaching the managers

Every manager hangs off the editor — editor.Blocks, editor.Components, editor.Storage, editor.Commands — and each getter is typed, so autocomplete works from the instance down. What you cannot do is import the manager classes by name; alias them through Editor instead.

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 is generic over the event name, so the callback signature is derived from the string you pass. In practice that means you should annotate almost nothing — inference gives you the right parameter types, and an annotation that disagrees is a compile error rather than a silent mismatch.

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

The event families you will use

Component events

component:add, component:remove, component:update, component:selected, component:mount. The first argument is the Component; component:add also gets an options object whose action distinguishes an add from a move from a clone.

Editor lifecycle

load once the editor is ready, update on any change to the project, destroy on teardown. These are where you hook your own save indicator or dirty-state flag.

Storage events

storage:start:store, storage:end:store, storage:error. Useful precisely because they fire around your own storage implementation, so a failing save can surface in the UI rather than in the console.

Block events

block:drag:start, block:drag:stop and the Block Manager's own add and remove. Handy for analytics on which blocks people actually reach for.

Where inference stops

The event name is an open string union, deliberately: plugins define their own channels and those must keep compiling. The cost is that a typo in a core event name is still valid TypeScript — the callback just falls back to a loose signature and never fires. When an event handler mysteriously does nothing, check the spelling before you check the API.

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) => { ... });
}

A component type registers new behaviour in the canvas: a tag, its traits, what it accepts as children, how it is recognised when HTML is parsed back in. This is where most custom editor work happens, and where the boundary between GrapesJS's types and yours has to be drawn.

The signature to get right

editor.Components.addType(type, options) takes AddComponentTypeOptions — model, view, isComponent, extend — not a ComponentDefinition. ComponentDefinition describes a declared node inside a tree: the children of a component, or the content of a block. Tutorials that pass a ComponentDefinition to addType are quoting an older shape, and the error you get from it is not obvious.

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

• Traits are the settings panel. Each entry names a model field, so the panel and your interface stay in step.
• isComponent is how a saved page is recognised on load. Without it, reloading turns your custom section back into a plain div.
• droppable and draggable are booleans or selectors — this is where you stop people dropping a hero inside a button.

A block is what appears in the left-hand shelf and what a user drags. It is not a component — it is a declaration of what to insert. Keeping the two straight is worth doing early, because their types are not interchangeable and the error message does not say so.

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

What a block declaration holds

id

First argument to Blocks.add, not a field. Unique per editor; re-adding the same id replaces the block.

label

What the user reads on the shelf. The one field here that belongs in your locale files.

category

Groups the shelf. A string, or an object when you want it collapsed by default.

content

What gets inserted: an HTML string, or a component definition. Prefer the definition — it keeps the block bound to a component type instead of to a snippet of markup.

media

The thumbnail, as inline SVG. Nothing stops you using an <img>, but inline SVG follows the editor's theme.

attributes

Applied to the shelf item itself — useful for test ids and analytics hooks, not for the inserted element.

Blocks.add returns the created Block, so you can capture it and adjust the shelf later — reordering, hiding blocks a user's plan does not include, or swapping a category label at runtime.

A GrapesJS plugin is a function that receives the editor and an options object. That is the whole contract — which is why plugins are the natural unit for anything you want to reuse across editors, ship to another team, or sell.

A shape that survives growth

One file per registration kind. The reason is not tidiness: blocks.ts exports BlockProperties objects that type-check with no editor in scope, so they can be unit-tested and reused without booting an editor at all.

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;

What the type buys you

Options

Export the interface. A consumer who cannot see the shape of your options has to read your source to configure your plugin.

Defaults

Optional fields on the type, defaults destructured in the body. Putting defaults in the type instead makes every field required at the call site.

The editor parameter

Typed for you by Plugin<T>. Everything you register inside — blocks, component types, commands — is checked against the real manager signatures.

Registration

Blocks, component types, commands and event handlers all go in the same function. A plugin that registers nothing at call time and waits for an event is fine too.

Registering it

Passing a closure keeps your options typed at the call site. The alternative — listing the plugin in plugins and its settings in pluginsOpts — types those settings as a loose record, so a misspelled key compiles and silently does nothing.

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

A design-system section is not one component — it is a small tree with a shape your product already has a name for. Describing that shape once, as an interface, is what keeps the editor, the API and the renderer from drifting apart.

One section, four types

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

What to type, and what not to

The content interface

Yours. Headline, description, call to action — the fields a marketer fills in and your API stores.

The component type

GrapesJS's. Registered once with addType, declaring the tag, the traits and the children.

Traits

The bridge. Each trait names a field on the model, so renaming a field in your interface should break the trait list — and with the defaults spread in, it does.

Children

ComponentDefinition objects rather than an HTML string. A string compiles no matter what you put in it; a definition is checked.

Attributes

Where data-gjs-type lives, which is what isComponent matches on reload.

The payoff is not fewer bugs today — it is that six months later, adding a field to HeroContent produces a list of every place that has to change, instead of a search across the codebase for the string 'headline'.

Storage is where the two type systems meet in the most consequential way, because this is the boundary that ends up in your database. Getting it wrong is expensive later; getting it right is about twenty lines.

Two shapes, not one

ProjectData is the editor's own JSON. Its internal structure belongs to GrapesJS, changes between versions, and is not something to migrate by hand. Your ProjectRecord is a row: an id, an owner, a name, a version, timestamps — plus that opaque blob in one column. Store it, load it, and leave its insides alone.

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

What the adapter has to handle

Load

Return the ProjectData for the current project. Throwing on a failed response is what makes the editor emit storage:error instead of silently opening an empty canvas.

Store

Send the data as-is. Do not reshape it on the way out — whatever you strip, the editor expects back on load.

Autosave

autosave with stepsBeforeSave batches changes. Every keystroke is not a request, and the number is yours to tune.

Versioning

A version column on your row, incremented server-side. Version the record, never the editor's JSON.

Multi-tenancy

The project id is a closure variable in the adapter, and ownership is checked server-side. The editor has no concept of a user and should not acquire one.

There is an official React wrapper — @grapesjs/react, MIT-licensed, currently 2.0.0 — and it ships its own declaration file. It does not render React components inside the canvas; it mounts the editor and hands you the instance.

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

The grapesjs prop is required. The wrapper deliberately does not import the editor itself, so the version in your bundle stays the one in your package.json — and so you can point it at a CDN build instead.

Or without the wrapper

The wrapper is a convenience, not a requirement. A useEffect with a ref does the same job in about fifteen lines, and is worth understanding even if you use the wrapper, because it makes the two rules explicit: guard the ref, and destroy on cleanup.

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

• The container ref is null on first render. strictNullChecks makes you say what happens then.
• Return a cleanup that calls destroy(). React 18's development StrictMode mounts twice, and without it you get two editors in one div.
• The wrapper's peer range is React ^18.0.0 || ^19.0.0. On React 17 you are on the manual path.

The whole Next.js question is one boundary. grapesjs.init needs a real DOM element, plus document and window; a Server Component has none of them. So the editor goes in a Client Component, and everything above it can stay on the server.

Where the line goes

'use client' at the top of the component that creates the editor, and nowhere higher. The page above it stays a Server Component: it awaits params, checks the session, loads the project and passes down plain props. That split is worth guarding, because moving 'use client' up one file quietly turns your data loading into 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, not the module body

Importing grapesjs on the server is harmless — it is calling init() that fails. useEffect only runs in the browser, which is the entire requirement.

Dynamic import is optional

next/dynamic with ssr: false is a bundle-size decision, not a correctness one, and it is not available inside a Server Component. Reach for it if the editor is a small part of a large page; skip it on a route that is only the editor.

CSS

Import grapesjs/dist/css/grapes.min.css from the client component. Without it the canvas renders unstyled and looks broken rather than unstyled.

Cleanup

Same as React: destroy() in the effect's return. Route transitions unmount the component, and an editor that outlives its container leaks its listeners.

Both work, and both follow the same shape as the manual React version: a template ref, initialisation after the element exists, destroy on teardown. The framework-specific mechanics have their own guides rather than a condensed version here.

In both cases the types are the same ones this page has been using: Editor, Component, ProjectData. The framework changes where init() is called, not what it returns.

Everything above fits in one file. It stops fitting at about the third custom component, and the thing that decides whether the next year is pleasant is where you put the seam between your application and the editor.

A structure that holds up

One seam, declared

Application code should not import from 'grapesjs' directly. Give it a single module that re-exports the handful of editor types your product legitimately knows about, aliases the managers that are not exported, and declares the narrow interface your UI actually depends on. Then a toolbar button takes that interface, not a whole Editor — and cannot reach into editor internals even by accident.

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

Your application on top, your types in the middle, the editor underneath. Dependencies point downward and never back up.

1. 01

   Application

   Yours. Knows nothing about GrapesJS.

   • Routing
   • Authentication
   • Application state
   • Your UI
   ↓
2. 02

   Types

   The seam. The only place both worlds are named.

   • Domain model
   • Project records
   • API contracts
   ↓
3. 03

   Editor layer

   Yours. The only code that imports from the editor.

   • createEditor
   • Plugins
   • Component types
   • Storage adapter
   ↓
4. 04

   GrapesJS

   The editor. Typed by the package.

   • Canvas
   • Managers
   • Events

A page-builder product is mostly not a page builder. GrapesJS covers one box in this chain; the rest is an application you were going to write anyway, and typing the joins between them is what this guide has been building toward.

GrapesJS owns the editing surface. Authentication, storage, tenancy, billing and publishing are yours.

The editor is a component of your product, not a substitute for it.

Eleven failures that come up repeatedly, most of them specific to this pairing rather than to TypeScript in general. Each one is a symptom you can match against and the change that fixes it.

None of these are TypeScript problems. They are places where the editor's model and your product's model get confused for each other, and the type system is only what makes the confusion visible early.

Four error shapes cover almost everything. In each case the useful move is to look at the declaration file in node_modules rather than to reach for any — the answer is in there, and any only postpones the question.

For framework-specific type errors, the React and Next.js guides go deeper than this page does.

Exact versions, checked against the registry and against the installed declaration file. The TypeScript floor in particular was measured by compiling against each release, not inferred from a changelog.

Verified 2026-09-03 against registry.npmjs.org and node_modules/grapesjs/dist/index.d.ts. Every code sample on this page was compiled against these versions under strict mode before publication.

Once you understand the core API, plugins can provide additional functionality without requiring you to build every feature from scratch. These are current listings on GJS.Market, grouped by which part of the typed surface each one touches.

Storage and persistence

Where ProjectData meets your database. The layer this guide's storage section is about.

Browse category

Directus Storage

A storage adapter for a headless CMS backend — the same load/store contract you would implement by hand.

FreeView plugin

IndexedDB Storage

Browser-local persistence. Useful as a draft layer in front of a remote adapter.

FreeView plugin

Cloud Firestore

Firestore as the project store, with the document standing in for your ProjectRecord.

FreeView plugin

Grapesjs Firebase Storage

Firebase-backed storage for projects, wired through the Storage Manager.

FreeView plugin

Components and content

Component types you would otherwise register yourself with addType.

Browse category

Tabs Component

A tabbed component type, with its own traits — a worked example of addType you can read.

FreeView plugin

Grapesjs Component Icon

An icon component with a picker trait, showing how a trait drives a component field.

$50.00View plugin

Symbols

Reusable linked instances, so one edit propagates across pages.

FreeView plugin

Typed Text

A typewriter-effect component wrapping Typed.js — a third-party library exposed as a component type.

FreeView plugin

Developer tooling

Code editing, script handling and project management inside the editor.

Browse category

Grapesjs Component Code Editor

Edit a component's HTML and CSS in place, which is the fastest way to see what your component types actually produce.

FreeView plugin

Grapesjs Script Editor

Attach and edit component scripts from inside the editor.

FreeView plugin

Grapesjs Plugin Toolbox

A set of editor utilities aimed at people building on GrapesJS rather than at end users.

FreeView plugin

Grapesjs Project Manager

Multi-project handling in the editor, adjacent to the storage layer above.

FreeView plugin

React and UI

Starters and presets for React-based editor stacks.

Browse category

React UI for GrapesJS

React-based editor UI around the GrapesJS canvas.

FreeView plugin

GrapesJS React Demo — Starter Integration for React Developers

A worked React integration you can read alongside this guide's React section.

FreeView plugin

Hero React Component GrapesJS

A hero component for React-based stacks — the section this guide builds by hand.

FreeView plugin

Reactor Preset for GrapesJS

A preset aimed at React developers, bundling blocks and components.

FreeView plugin

The line is not about difficulty. It is about whether the behaviour is specific to your product — because that is what decides who has to maintain it in two years.

In practice most editors are both: a handful of plugins for the parts every editor needs, and your own typed component types for the parts that make the product yours.

Where to go next, depending on whether you are still learning the editor, wiring it into a framework, or building a product around it.

If the architecture section is where your project actually is, the remaining work is usually integration rather than editor features. That is what we do.

• TypeScript plugins
• Custom component types
• React integration
• Next.js integration
• Storage and API integration
• SaaS editors
• White-label editors
• Custom editor UI
• Migrations from older versions
• Production architecture review

Start with the typed GrapesJS API, build your own components and plugins, connect your application infrastructure, and extend the editor when your product needs more functionality.