GrapesJS Web Builder Framework

Common errors

• TypeError: Cannot read properties of undefined (reading 'init')

  cause The `grapesjs` object was not correctly loaded or imported before `init()` was called, often due to incorrect script order or an invalid import path.
  fix Ensure `import grapesjs from 'grapesjs';` is at the top of your module, or for global scripts, that `<script src="path/to/grapes.min.js"></script>` is loaded before attempting to call `grapesjs.init()`.

• GrapesJS is not defined

  cause This error typically occurs in a browser environment when the GrapesJS script has not been loaded or has failed to execute, meaning the global `grapesjs` object is unavailable.
  fix Verify the CDN link or local script path for `grapes.min.js` is correct and accessible. Ensure the script tag is placed before any inline script that attempts to use `grapesjs`.

• BUG: Cannot read properties of null (reading 'hasFocus') in Canvas module

  cause Reported in recent GrapesJS versions (e.g., v0.22.11 or v0.22.14) in certain browser environments (Safari, Chrome) related to the Canvas module.
  fix This is an active bug. Check the GrapesJS GitHub issues for potential fixes, workarounds, or official patch releases. Temporarily, you might need to try slightly older patch versions or implement custom logic to guard against `null` references where `hasFocus` is called.

Warnings

• breaking The global `GrapesJS` variable and main `grapesjs` export changed casing from `GrapesJS` (capital 'G') to `grapesjs` (lowercase 'g') around v0.16.x. Projects upgrading from much older versions may need to update their imports/global references.
  Fix: Update `require('grapesjs')` or global script references to use `grapesjs` (lowercase 'g'). For ESM, use `import grapesjs from 'grapesjs';`.
• breaking From v0.20.x, the API for registering custom components via `typeModelOrView.extend` became deprecated. Users should switch to the modern `Components.addType('component-id', { model: {...} })` syntax.
  Fix: Refactor custom component registrations from `model: defaultModel.extend({...})` to `model: { defaults: {...} }` as per the updated documentation.
• gotcha When initializing GrapesJS, ensure that the core CSS file (`grapes.min.css`) is properly loaded. Without it, the editor UI will appear unstyled and broken, leading to a poor user experience.
  Fix: For npm installations, add `import 'grapesjs/dist/css/grapes.min.css';` to your entry file. For CDN usage, include `<link rel="stylesheet" href="//unpkg.com/grapesjs/dist/css/grapes.min.css">` before your script.
• gotcha Issues with undo/redo functionality or unexpected behavior after calling `component.replaceWith()` during lifecycle events can occur if the UndoManager is enabled. This can lead to editor crashes.
  Fix: Avoid manipulating components with `replaceWith()` directly within complex lifecycle event handlers, especially when UndoManager is active. Consider deferring the operation or temporarily disabling UndoManager around such critical operations if absolutely necessary. Review GrapesJS issue tracker for specific workarounds or fixes related to your version.

Install

• npm install grapesjs npm
• yarn add grapesjs yarn
• pnpm add grapesjs pnpm

Imports

• grapesjs
  wrong:

  const grapesjs = require('grapesjs');

  correct:

  import grapesjs from 'grapesjs';
  import 'grapesjs/dist/css/grapes.min.css';

  The primary import for GrapesJS is a default export, typically used as a factory function. Ensure you also import the default CSS stylesheet for proper styling.
• Editor

  import type { Editor } from 'grapesjs';

  For TypeScript projects, import the `Editor` interface for type hinting and auto-completion. This represents the instance returned by `grapesjs.init()`.
• GrapesJS (global)
  wrong:

  var editor = Grapesjs.init(...); // incorrect casing

  correct:

  <script src="//unpkg.com/grapesjs@0.22.15"></script>
  <link rel="stylesheet" href="//unpkg.com/grapesjs@0.22.15/dist/css/grapes.min.css">

  When using GrapesJS via CDN or a global script tag, the library exposes a global variable named `grapesjs` (lowercase 'g') as of recent versions. Older versions (pre-0.16.x) might have used `GrapesJS` (uppercase 'G').

Quickstart

This quickstart initializes a GrapesJS editor in a designated DOM element, configures local storage for persistence, and adds a few basic draggable blocks (section, text, image). It also includes basic panel configurations and logs the generated HTML and CSS on content updates.

import grapesjs from 'grapesjs';
import 'grapesjs/dist/css/grapes.min.css';

// Ensure a DOM element exists for the editor
document.body.innerHTML = '<div id="gjs"></div>';

const editor = grapesjs.init({
  container: '#gjs',
  height: '700px',
  width: 'auto',
  fromElement: true, // Loads HTML from the container element
  storageManager: {
    type: 'local', // Use local storage
    autosave: true, // Autosave content
    autoload: true, // Autoload content on editor init
    stepsBeforeSave: 1, // Number of changes before autosave
  },
  // Add some basic blocks
  blockManager: {
    blocks: [
      {
        id: 'section', // id is a unique and required property
        label: '<b>Section</b>', // You can use HTML for the label
        category: 'Basic',
        content: '<section><h1>This is a section</h1></section>',
      },
      {
        id: 'text',
        label: 'Text',
        category: 'Basic',
        content: '<div data-gjs-type="text">Insert your text here</div>',
      },
      {
        id: 'image',
        label: 'Image',
        category: 'Basic',
        activate: true,
        select: true,
        content: { type: 'image' },
      }
    ],
  },
  // Configure the panels (optional)
  panels: {
    defaults: [
      { id: 'commands', buttons: [{ id: 'undo', command: 'undo' }, { id: 'redo', command: 'redo' }] },
      { id: 'options', buttons: [{ id: 'sw-visibility', command: 'sw-visibility', context: 'sw-visibility' }] },
      { id: 'views', buttons: [{ id: 'open-blocks', command: 'open-blocks', active: true }] }
    ]
  },
});

// Log the HTML and CSS when the editor changes
editor.on('update', () => {
  console.log('HTML:', editor.getHtml());
  console.log('CSS:', editor.getCss());
});

console.log('GrapesJS Editor initialized successfully.');