{"id":17668,"library":"grapesjs-cli","title":"GrapesJS CLI","description":"GrapesJS CLI is a command-line interface tool designed to streamline the development of GrapesJS plugins. It handles the complexities of setting up modern JavaScript build tools such as Webpack and Babel, providing a simplified and accelerated workflow for plugin authors. The current stable version, 4.1.3, focuses on dependency updates and build enhancements like the `dts` option. Historically, the CLI has undergone significant updates, including a transition to Webpack 5 in v3.0.0 and a move away from the `esm` package for internal bundling in v4.1.0, which can impact custom configurations. Its release cadence generally aligns with major GrapesJS ecosystem changes or critical dependency updates. Key differentiators for `grapesjs-cli` include its opinionated, zero-configuration approach for common plugin development scenarios, direct integration with the GrapesJS plugin structure, and features like fast project scaffolding and a built-in development server. It aims to reduce the boilerplate and configuration overhead for developers, allowing them to focus on the core plugin logic.","status":"active","version":"4.1.3","language":"javascript","source_language":"en","source_url":"https://github.com/GrapesJS/cli","tags":["javascript","grapesjs","plugin","dev","cli"],"install":[{"cmd":"npm install grapesjs-cli","lang":"bash","label":"npm"},{"cmd":"yarn add grapesjs-cli","lang":"bash","label":"yarn"},{"cmd":"pnpm add grapesjs-cli","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"GrapesJS CLI is a command-line tool. Commands are executed via `npx` or a global installation. Programmatic `import` or `require` of its internal modules is not supported for public API.","wrong":"import { init } from 'grapesjs-cli'","symbol":"init","correct":"npx grapesjs-cli init"},{"note":"Starts a development server with live reloading, primarily for plugin development. Supports `webpack-dev-server` options via CLI arguments.","wrong":"const serve = require('grapesjs-cli').serve","symbol":"serve","correct":"npx grapesjs-cli serve"},{"note":"Compiles and bundles the GrapesJS plugin into production-ready, minified JavaScript files. Generates a `dist/index.js` output by default since v3.0.0.","wrong":"require('grapesjs-cli/dist/build')","symbol":"build","correct":"npx grapesjs-cli build"}],"quickstart":{"code":"/**\n * This quickstart demonstrates the GrapesJS plugin development workflow using grapesjs-cli.\n * The commands below are intended to be run in a shell environment.\n */\n\n// 1. Create a new directory for your plugin and initialize it\n// mkdir grapesjs-my-plugin\n// cd grapesjs-my-plugin\n// npm init -y\n// git init\n\n// 2. Install the GrapesJS CLI as a development dependency\n// npm i -D grapesjs-cli\n\n// 3. Initialize your plugin project. Use '-y' to skip interactive questions.\n// npx grapesjs-cli init -y --user=your-github-username\n\n// 4. Start the development server. Access your plugin demo at http://localhost:8080.\n// npx grapesjs-cli serve\n// You can also pass custom webpack-dev-server options:\n// npx grapesjs-cli serve --devServer='{\"https\": true}'\n\n// 5. Build your plugin for production. This generates output in the 'dist' directory.\n// npx grapesjs-cli build\n\n// Example: Custom webpack.config.js for advanced configurations (placed in your plugin's root directory)\n// This JavaScript code block is runnable as a conceptual example of the config file structure.\n/** @type {import('webpack').Configuration} */\nconst customWebpackConfig = ({ config }) => {\n    // `config` is the default webpack configuration provided by grapesjs-cli\n    const isBuild = config.mode === 'production'; // Differentiate build from serve command\n\n    return {\n        ...config,\n        // Example: Add a new rule for handling SVG files\n        module: {\n            rules: [\n                {\n                    test: /\\.svg$/,\n                    use: ['@svgr/webpack'],\n                },\n                ...config.module.rules,\n            ],\n        },\n        // Example: Customize an existing plugin or add a new one\n        plugins: [\n            ...(config.plugins || []),\n            // new MyCustomWebpackPlugin(),\n        ],\n    };\n};\n\n// In a real scenario, this would be exported from a webpack.config.js file:\n// export default customWebpackConfig;\n\nconsole.log('GrapesJS CLI workflow and custom webpack config demonstrated.');\n","lang":"typescript","description":"Demonstrates the typical GrapesJS plugin development workflow including project initialization, serving, building, and an example of customizing the Webpack configuration using TypeScript types."},"warnings":[{"fix":"Review your `webpack.config.js` against Webpack 5 documentation and update deprecated options, loaders, and plugins.","message":"GrapesJS CLI v3.0.0 upgraded to Webpack 5. Custom `webpack.config.js` files may need updates to avoid deprecated options or configurations from Webpack 4.","severity":"breaking","affected_versions":">=3.0.0"},{"fix":"Update the `main` field in your plugin's `package.json` to point to `dist/index.js`.","message":"With v3.0.0, the output filenames changed from `dist/my-plugin-name.min.js` to `dist/index.js`. This affects how your plugin is referenced.","severity":"breaking","affected_versions":">=3.0.0"},{"fix":"Upgrade your Node.js environment to version 14.15.0 or later.","message":"Node.js 14.15.0 or newer is required since v4.0.0. Older versions of Node.js are no longer supported and will cause the CLI to fail.","severity":"breaking","affected_versions":">=4.0.0"},{"fix":"No direct fix for users, but if experiencing unexpected build issues, ensure your environment and custom scripts are compatible with a self-bundled CLI.","message":"Version 4.1.0 moved away from the `esm` package for bundling the CLI internally. While this primarily affects the CLI's internal workings, custom setups that relied on the previous bundling approach might be impacted.","severity":"breaking","affected_versions":">=4.1.0"},{"fix":"Ensure your `webpack.config.js` exports a function: `export default ({ config }) => { /* ... */ return { ...config, /* ... */ }; }`.","message":"When customizing Webpack through `webpack.config.js`, you must export a function that receives the default configuration object and returns a new one.","severity":"gotcha","affected_versions":">=1.0.14"},{"fix":"Use the `--devServer` flag with a JSON string, e.g., `npx grapesjs-cli serve --devServer='{\"https\": true}'`.","message":"Passing options to `webpack-dev-server` via the `serve` command requires a specific JSON string format.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-23T00:00:00.000Z","next_check":"2026-07-22T00:00:00.000Z","problems":[{"fix":"Refer to the Webpack 5 migration guide and update your custom `webpack.config.js` to use current options and syntax.","cause":"Using an outdated `webpack.config.js` that contains Webpack 4-specific configurations after upgrading grapesjs-cli to v3.0.0 (Webpack 5).","error":"Webpack options object has an unknown property '...' (e.g., 'resolve.modules'). These options were deprecated in webpack 4 and removed in webpack 5."},{"fix":"Update your `package.json` `main` field to `dist/index.js`.","cause":"The `main` entry in your plugin's `package.json` still points to the old output path (e.g., `dist/my-plugin-name.min.js`) after the v3.0.0 breaking change.","error":"Error: Cannot find module 'your-plugin-name'"},{"fix":"Ensure you have an `index.js` or `index.ts` file located directly under the `src/` directory of your plugin project.","cause":"The required entry point file for your GrapesJS plugin is missing or incorrectly named in the `src` directory.","error":"Error: No valid `src/index.js` (or `src/index.ts`) entry file found for your plugin."},{"fix":"Upgrade your Node.js installation to version 14.15.0 or newer.","cause":"Attempting to run `grapesjs-cli` with an older Node.js version than required by the CLI (v4.0.0 and above).","error":"Node.js version 12.x.x is not supported. Minimum supported Node.js version is 14.15.0."}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}