How to set up GrapesJS with Vite (complete guide 2026)

Why Vite for GrapesJS

Vite gives GrapesJS a fast dev server and an optimized production bundle with almost no configuration. GrapesJS ships an ESM build, so Vite handles it out of the box. This guide installs GrapesJS, imports the CSS and core, and initialises the editor.

1. Install

npm create vite@latest my-editor
cd my-editor
npm install grapesjs

2. Initialise in the entry file

In src/main.js:

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

const editor = grapesjs.init({
  container: '#gjs',
  height: '100vh',
  fromElement: true,
  storageManager: false,
  components: '<h1>Hello from GrapesJS</h1>',
});

export default editor;

Add the container to index.html:

<div id="gjs"></div>
<script type="module" src="/src/main.js"></script>

3. Run and build

npm run dev     # fast HMR dev server
npm run build   # optimized production bundle

If you ever see a pre-bundling warning, pin GrapesJS in vite.config.js:

export default {
  optimizeDeps: { include: ['grapesjs'] },
};

4. Add a plugin

import grapesjs from 'grapesjs';
import preset from 'grapesjs-preset-webpage';

grapesjs.init({
  container: '#gjs',
  plugins: [preset],
  pluginsOpts: { 'grapesjs-preset-webpage': {} },
});

Troubleshooting

If the editor loads but looks unstyled, you forgot to import 'grapesjs/dist/css/grapes.min.css' in your entry file. If Vite logs a dependency pre-bundling warning, add grapesjs to optimizeDeps.include in vite.config.js. Using Vite in SSR mode (SvelteKit, Nuxt, Astro)? Initialise GrapesJS only on the client — the dev server renders on the server too, and the editor needs the DOM. For production, nothing special is required: vite build tree-shakes and bundles GrapesJS like any ESM dependency.

Prerequisites

You'll need Node.js 18+ and a Vite project (npm create vite@latest). GrapesJS ships an ES module, so Vite handles it with essentially no configuration — this guide covers the few cases where you need to nudge it.

Add custom blocks to the editor

Register draggable blocks with the Block Manager after grapesjs.init:

editor.BlockManager.add('hero', {
  label: 'Hero section',
  category: 'Sections',
  content: '<section class="hero"><h1>Headline</h1><p>Copy</p></section>',
});

Pull ready-made block libraries and presets from GJS.Market for a richer set.

Using GrapesJS inside a framework on Vite

If your Vite app uses React or Vue, mount GrapesJS in a client-only effect so it never runs during any SSR pass and the container exists first:

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

export default function Editor() {
  const ref = useRef(null);
  useEffect(() => {
    let editor;
    import('grapesjs').then(({ default: grapesjs }) => {
      editor = grapesjs.init({ container: ref.current, height: '100vh' });
    });
    return () => editor?.destroy();
  }, []);
  return <div ref={ref} />;
}

Performance tips

Import GrapesJS dynamically (import('grapesjs')) so Vite splits it into its own chunk and the rest of your app stays light. vite build tree-shakes and minifies it for production with no extra work. If only part of your app uses the editor, load it behind the route that needs it.

Troubleshooting common errors

The editor loads unstyled means you forgot import 'grapesjs/dist/css/grapes.min.css' in your entry. A pre-bundling warning is fixed by adding grapesjs to optimizeDeps.include in vite.config.js. An SSR “document is not defined” (SvelteKit/Nuxt/Astro on Vite) means you must initialise the editor only on the client.

Vite vs Webpack for GrapesJS

Vite is the lower-config choice — it handles the ESM build and CSS import out of the box and gives you a fast dev server. Reach for Webpack only when an existing project already standardises on it; the GrapesJS setup itself is equally simple on either.

Next steps

See the related GrapesJS + Svelte and GrapesJS + React guides, browse the GrapesJS marketplace, or start from the GJS.Market home page.

FAQ

How do I import GrapesJS styles in Vite?

Import 'grapesjs/dist/css/grapes.min.css' in your entry file — Vite injects it in dev and bundles it for production.

Does GrapesJS need special Vite config?

Usually no. If you hit a pre-bundling issue, add grapesjs to optimizeDeps.include.

Can I use plugins with Vite?

Yes — install via npm, import, and pass it in the plugins array of grapesjs.init.