{"id":10964,"library":"grapesjs","title":"GrapesJS Web Builder Framework","description":"GrapesJS is a free and open-source Web Builder Framework designed to facilitate the creation of HTML templates, websites, newsletters, and mobile applications. It's primarily intended for integration into Content Management Systems (CMS) to provide a powerful visual editing experience. The current stable version is `0.22.15`, with the project demonstrating a positive and sustainable release cadence, frequently publishing patch releases. Key differentiators include its framework-centric approach, offering core UI components like a Block Manager, Style Manager, Layer Manager, Code Viewer, and Asset Manager. It focuses on generating clean, standards-based HTML and CSS output, unlike some other tools that might rely on specific frontend frameworks.","status":"active","version":"0.22.15","language":"javascript","source_language":"en","source_url":"https://github.com/GrapesJS/grapesjs","tags":["javascript","grapes","grapesjs","wysiwyg","web","template","editor","newsletter","site","typescript"],"install":[{"cmd":"npm install grapesjs","lang":"bash","label":"npm"},{"cmd":"yarn add grapesjs","lang":"bash","label":"yarn"},{"cmd":"pnpm add grapesjs","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"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.","wrong":"const grapesjs = require('grapesjs');","symbol":"grapesjs","correct":"import grapesjs from 'grapesjs';\nimport 'grapesjs/dist/css/grapes.min.css';"},{"note":"For TypeScript projects, import the `Editor` interface for type hinting and auto-completion. This represents the instance returned by `grapesjs.init()`.","symbol":"Editor","correct":"import type { Editor } from 'grapesjs';"},{"note":"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').","wrong":"var editor = Grapesjs.init(...); // incorrect casing","symbol":"GrapesJS (global)","correct":"<script src=\"//unpkg.com/grapesjs@0.22.15\"></script>\n<link rel=\"stylesheet\" href=\"//unpkg.com/grapesjs@0.22.15/dist/css/grapes.min.css\">"}],"quickstart":{"code":"import grapesjs from 'grapesjs';\nimport 'grapesjs/dist/css/grapes.min.css';\n\n// Ensure a DOM element exists for the editor\ndocument.body.innerHTML = '<div id=\"gjs\"></div>';\n\nconst editor = grapesjs.init({\n  container: '#gjs',\n  height: '700px',\n  width: 'auto',\n  fromElement: true, // Loads HTML from the container element\n  storageManager: {\n    type: 'local', // Use local storage\n    autosave: true, // Autosave content\n    autoload: true, // Autoload content on editor init\n    stepsBeforeSave: 1, // Number of changes before autosave\n  },\n  // Add some basic blocks\n  blockManager: {\n    blocks: [\n      {\n        id: 'section', // id is a unique and required property\n        label: '<b>Section</b>', // You can use HTML for the label\n        category: 'Basic',\n        content: '<section><h1>This is a section</h1></section>',\n      },\n      {\n        id: 'text',\n        label: 'Text',\n        category: 'Basic',\n        content: '<div data-gjs-type=\"text\">Insert your text here</div>',\n      },\n      {\n        id: 'image',\n        label: 'Image',\n        category: 'Basic',\n        activate: true,\n        select: true,\n        content: { type: 'image' },\n      }\n    ],\n  },\n  // Configure the panels (optional)\n  panels: {\n    defaults: [\n      { id: 'commands', buttons: [{ id: 'undo', command: 'undo' }, { id: 'redo', command: 'redo' }] },\n      { id: 'options', buttons: [{ id: 'sw-visibility', command: 'sw-visibility', context: 'sw-visibility' }] },\n      { id: 'views', buttons: [{ id: 'open-blocks', command: 'open-blocks', active: true }] }\n    ]\n  },\n});\n\n// Log the HTML and CSS when the editor changes\neditor.on('update', () => {\n  console.log('HTML:', editor.getHtml());\n  console.log('CSS:', editor.getCss());\n});\n\nconsole.log('GrapesJS Editor initialized successfully.');","lang":"typescript","description":"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."},"warnings":[{"fix":"Update `require('grapesjs')` or global script references to use `grapesjs` (lowercase 'g'). For ESM, use `import grapesjs from 'grapesjs';`.","message":"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.","severity":"breaking","affected_versions":">=0.16.0"},{"fix":"Refactor custom component registrations from `model: defaultModel.extend({...})` to `model: { defaults: {...} }` as per the updated documentation.","message":"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.","severity":"breaking","affected_versions":">=0.20.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=0.22.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"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()`.","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.","error":"TypeError: Cannot read properties of undefined (reading 'init')"},{"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`.","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.","error":"GrapesJS is not defined"},{"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.","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.","error":"BUG: Cannot read properties of null (reading 'hasFocus') in Canvas module"}],"ecosystem":"npm"}