{"id":13251,"library":"grapesjs-parser-postcss","title":"GrapesJS PostCSS Parser","description":"The `grapesjs-parser-postcss` plugin provides a custom CSS parser for the GrapesJS web page builder, leveraging PostCSS to handle CSS parsing. This is crucial for avoiding inconsistencies that can arise when importing HTML/CSS templates or embedding custom code directly, as the default browser's CSS Object Model (CSSOM) can be unreliable. The current stable version is `1.0.3`. This plugin primarily focuses on compatibility and fixes, with recent updates ensuring it works seamlessly with the latest GrapesJS versions and PostCSS v8. Its key differentiator is providing a robust and consistent CSS parsing mechanism within GrapesJS, addressing potential styling issues that default browser parsing might introduce, making it an essential tool for advanced GrapesJS usage involving custom CSS structures.","status":"active","version":"1.0.3","language":"javascript","source_language":"en","source_url":"https://github.com/GrapesJS/parser-postcss","tags":["javascript","grapesjs","plugin","parser","css","postcss","wysiwyg"],"install":[{"cmd":"npm install grapesjs-parser-postcss","lang":"bash","label":"npm"},{"cmd":"yarn add grapesjs-parser-postcss","lang":"bash","label":"yarn"},{"cmd":"pnpm add grapesjs-parser-postcss","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Peer dependency; the plugin extends GrapesJS functionality and requires it to be present in the application.","package":"grapesjs","optional":false},{"reason":"Core runtime dependency; the plugin relies on PostCSS for its parsing capabilities.","package":"postcss","optional":false}],"imports":[{"note":"The plugin is exported as a default export for modern JavaScript environments (ESM).","wrong":"import { parserPostCSS } from 'grapesjs-parser-postcss';","symbol":"parserPostCSS","correct":"import parserPostCSS from 'grapesjs-parser-postcss';"},{"note":"While the plugin exports a default function, for TypeScript type safety when assigning to a GrapesJS plugin type, you would typically import the default and assign it. The package itself was refactored to TypeScript in v1.0.1, ensuring type declarations are available.","symbol":"GrapesJSPostCSSParserPlugin","correct":"import type { Plugin } from 'grapesjs'; // Assuming Plugin type for GrapesJS plugins\nimport parserPostCSS from 'grapesjs-parser-postcss'; // The plugin itself\nconst GrapesJSPostCSSParserPlugin: Plugin = parserPostCSS;"},{"note":"For CommonJS environments, the plugin is typically consumed via `require()` as a default export.","wrong":"const { parserPostCSS } = require('grapesjs-parser-postcss');","symbol":"grapesjs-parser-postcss","correct":"const parserPostCSS = require('grapesjs-parser-postcss');"}],"quickstart":{"code":"import grapesjs from 'grapesjs';\nimport parserPostCSS from 'grapesjs-parser-postcss';\n\n// Initialize GrapesJS editor with the PostCSS parser plugin\nconst editor = grapesjs.init({\n  container : '#gjs',\n  height: '700px',\n  width: '100%',\n  fromElement: true, // Optional: Load content from #gjs element\n  storageManager: {\n    id: 'gjs-',\n    type: 'local',\n    autosave: true,\n    autoload: true,\n    stepsBeforeSave: 1,\n  },\n  // Include the PostCSS parser plugin\n  plugins: [parserPostCSS],\n  // ... other GrapesJS configurations\n});\n\n// You can further interact with the editor, e.g., load HTML or CSS\neditor.setComponents(`\n  <style>\n    .my-class {\n      color: red;\n      font-size: 16px;\n    }\n  </style>\n  <div class=\"my-class\">Hello GrapesJS with PostCSS!</div>\n`);\n\ndocument.addEventListener('DOMContentLoaded', () => {\n  // Ensure the GrapesJS editor is rendered within the DOM\n  const app = document.getElementById('gjs');\n  if (!app) {\n    const div = document.createElement('div');\n    div.id = 'gjs';\n    document.body.appendChild(div);\n  }\n});","lang":"typescript","description":"This quickstart demonstrates how to initialize a GrapesJS editor and integrate the `grapesjs-parser-postcss` plugin using modern JavaScript (ESM) and TypeScript types. It shows the basic setup and how to pass the plugin to the editor's configuration."},"warnings":[{"fix":"Ensure your project's `postcss` dependency is compatible with PostCSS 8. Review module import paths and plugin registration in your GrapesJS setup to align with the new TypeScript-based structure.","message":"Version `1.0.1` introduced significant breaking changes by upgrading to PostCSS 8 and refactoring the plugin to TypeScript. This may require updating your `postcss` dependencies and adjusting import statements if migrating from `0.x` versions.","severity":"breaking","affected_versions":">=1.0.1"},{"fix":"Update your GrapesJS dependency to `v0.14.33` or a newer version to ensure full compatibility.","message":"This plugin requires GrapesJS `v0.14.33` or higher. Using it with older versions of GrapesJS may lead to unexpected behavior or errors due to API incompatibilities.","severity":"gotcha","affected_versions":"<1.0.0"},{"fix":"Always use `grapesjs-parser-postcss` if you're working with custom CSS or importing external templates into GrapesJS to ensure consistent style application.","message":"The primary reason to use this plugin is to address inconsistencies in CSS parsing when importing HTML/CSS or using custom code components in GrapesJS. Without it, the browser's native CSSOM might produce different results than expected, especially with complex or non-standard CSS.","severity":"gotcha","affected_versions":">=0.1.1"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Verify that `grapesjs` is imported correctly as a module (`import grapesjs from 'grapesjs';`) or loaded via a script tag before the plugin. Also, check that `grapesjs-parser-postcss` is installed and imported/loaded correctly.","cause":"GrapesJS or the plugin is not correctly loaded or accessible in the global scope/module context.","error":"TypeError: grapesjs.init is not a function"},{"fix":"Upgrade your PostCSS installation and any related PostCSS plugins to versions compatible with PostCSS 8. `npm install postcss@^8` or `yarn add postcss@^8`.","cause":"Your project is using an older version of PostCSS (e.g., v7) while `grapesjs-parser-postcss` v1.0.1+ expects PostCSS 8.","error":"Error: PostCSS plugin <plugin-name> requires PostCSS 8."},{"fix":"For browser usage without a bundler, use the UMD/IIFE version via CDN `<script src=\"https://unpkg.com/grapesjs-parser-postcss.min.js\"></script>`. For Node.js, ensure your `package.json` has `\"type\": \"module\"` or use CommonJS `require()` syntax (`const parserPostCSS = require('grapesjs-parser-postcss');`).","cause":"Attempting to use ES module `import` syntax in a browser or Node.js environment that does not support it, typically without a module bundler or proper configuration.","error":"Uncaught SyntaxError: Cannot use import statement outside a module"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":"","cli_version":null}