MageForge for Magento 2

[image: Mageforge Hero]

MageForge is a powerful CLI front-end development toolkit for Magento 2 that simplifies theme development workflows. It provides tools for many types of Magento themes and can be easily extended for custom themes.

Table of Contents

• Supported Magento Versions
• Features
  • Supported Theme-Types
  • Available Commands
• Getting Started
  • Installation
  • Quick Start Guide
  • Frontend Inspector
• Additional Documentation
• Support
• Project Information
• Credits

Supported Magento Versions

MageForge requires Magento 2.4.7 or higher with PHP 8.3 or higher.
Please ensure that your Magento installation meets this requirement before installation.

Features

Supported Theme-Types 🎨

[image: Mageforge Hero]

Available Commands

Frontend Toolbar with Inspector and Performance Metrics

[image: Mageforge Toolbar]

Getting Started

Installation

1. Install the module via Composer:

   composer require openforgeproject/mageforge
   

2. Enable the module:

   bin/magento module:enable OpenForgeProject_MageForge
   bin/magento setup:upgrade
   

Quick Start Guide

1. List available themes:

   bin/magento mageforge:theme:list
   

2. Build a theme:

   bin/magento mageforge:theme:build <theme-code>
   

   Example: bin/magento mageforge:theme:build Magento/luma

3. Start development watch mode:

   bin/magento mageforge:theme:watch <theme-code>
   

4. Generate Hyvä design tokens (for Hyvä themes):

   bin/magento mageforge:hyva:tokens <theme-code>
   

   This creates a generated/hyva-tokens.css file from your design tokens configuration.

5. Enjoy automatic CSS rebuilding as you work on your theme files!

Frontend Inspector 🕵️

The MageForge Inspector is a powerful developer tool that allows you to inspect Magento blocks, templates, and performance metrics directly in your browser.

Key Features:

• Structure Analysis: View template paths, block classes, and module names for any element.
• Performance Metrics: See PHP render times and cache status (lifetime, tags).
• Web Vitals: Monitor LCP, CLS, and INP metrics per element.
• Accessibility Checks: Inspect ARIA roles, contrast ratios, and alt text.

How to use:

1. Enable the Inspector in the CLI:

   bin/magento mageforge:theme:inspector enable
   

   (Note: Requires Magento Developer Mode)

2. Enable the Inspector in Magento Admin Settings
   You can activate the Inspector in Magento Admin under Stores > Configuration > MageForge > Frontend Inspector.

3. Usage in Browser:

   • Toggle: Press Ctrl+Shift+I (Windows/Linux) or Cmd+Option+I (macOS).
   • Inspect: Hover over elements to see details. Click to lock the inspector on a specific block.

To disable the inspector:

bin/magento mageforge:theme:inspector disable

Note: The Inspector is currently not compatible with Magewire components. Magewire blocks are automatically excluded from inspection to prevent rendering errors.

Additional Documentation

• Advanced Usage Guide - Tips, tricks and troubleshooting
• Custom Theme Builders Documentation - Extend MageForge for your custom themes
• Commands Documentation - Detailed command reference

Support

• Report Bugs/Features: GitHub Issues
• Discussions: GitHub Discussions
• Contributing: See Contributing Guidelines

Project Information

• License: LICENSE
• Changelog: CHANGELOG

Credits

MageForge uses the following third-party libraries:

Thank you for using MageForge!

Changelog for MageForge

All notable changes to this project will be documented in this file.

UNRELEASED

Changed

• Inspector CSS Migration: Migrated Inspector component from Tailwind CSS to pure Vanilla CSS for universal compatibility
  • All CSS classes now use mageforge-* prefix for namespace isolation
  • Removed Tailwind build dependency (tailwind/ directory deprecated)
  • No npm build step required - direct CSS editing
  • Compatible with all Magento 2 projects regardless of frontend stack
  • Inspector CSS location: src/view/frontend/web/css/inspector.css

Latest Release

0.22.0 (2026-06-01)

Added

• add CMS block identifier support in InspectorHints and tabs (dcce46d)
• add Escaper dependency and improve JSON escaping in InspectorHints (adaa5db)
• add magewire support for Inspector Hints (f47d497)
• add new color group styles to toolbar (#188) (fc4b7ee)
• add new color group styles to toolbar (#188) (3cf6803)
• data-mageforge attribute handling (35975ac)
• enable phpcs annotations for method arguments in InspectorHintsFactory (e8c2ee3)
• enhance block detection for PageBuilder elements in inspector (0121ec8)
• enhance InspectorHints to inject data attributes into root HTML elements (0a9cf42)
• implement InspectorHintsFactory for creating InspectorHints instances (3a27262)
• improve accessibility and functionality of inspector and toolbar components (2873970)
• improve accessibility and styling for inspector and toolbar buttons (68b6bea)
• update CompatibilityCheckCommand to handle summary directly (57a0263)

Fixed

• simplify warning display logic in CompatibilityChecker (41a895f)

0.21.1 (2026-05-15)

Fixed

• cast render result to string in InspectorHints (#187) (c857129)
• update shas and update to node24 workflows (36bd346)

0.21.0 (2026-05-11)

Added

• add toolbar position configuration and implement in UI (3f331bf)
• health scoring (#182) (89bba7c)

Fixed

• exclude toolbar elements from tab-order & mark overflow-clipped focusables as unreachable (1484347)

Changed

• centralize inspector configuration constants in Inspector class (b7c9027)

Documentation

• add frontend toolbar section and image to README (1a2fb75)
• update toolbar image from PNG to JPEG format (1e1bafd)

0.20.0 (2026-04-26)

Added

• add additional audits for accessibility and usability checks (2dfea0d)
• add additional audits for accessibility and usability checks (ad30fe9)
• add additional check for elements within the toolbar (877edcd)
• add warning styles and enhance audit checks for toolbar elements (cfab08a)
• clarify description for unsafe target="_blank" audit (2df5ff2)
• enhance audits for duplicate IDs and interactive elements (002d30f)
• exclude toolbar elements from highlight application (bfdcc29)
• update minimum size for small touch targets audit (d492c1e)
• update touch target size description for accessibility audit (81ae5e4)

Fixed

• add aria-expanded attribute for burger button accessibility (363403b)
• cast show labels to integer for consistent data attribute (37658fb)
• disable inspector in config and update layout reference (#175) (99c71a9)
• enhance constructor PHPDoc for Inspector and ThemeSuggester classes (ad2eb35)
• ensure audits are deactivated on toolbar destruction (b1a16fd)
• improve type safety and clean up PHPDoc in Inspector block (0c63ac3)
• normalise opacity visibility check across all toolbar audits (0fb1642)
• refine theme path matching and enhance theme suggestion logic (3484f34)
• refine theme path matching and enhance theme suggestion logic (fc1747b)
• streamline toolbar destruction process and clean up references (65221fe)
• toolbar fixes (#177) (f4382b5)
• update aria-expanded attribute for collapsible menu groups (96ac5e1)

Styling

• adjust toolbar dimensions for better usability on small devices (d41c6e2)
• update toolbar CSS for improved visibility (84f80de)
• update toolbar for improved design (4871193)

0.19.1 (2026-04-22)

Fixed

• remove cacheable attribute from inspector block (#174) (e12e44e)

Documentation

• Fix commands.md numbering, missing sections, and flag inconsistencies (#172) (ba5498f)

0.19.0 (2026-04-13)

Added

• defer page timing caching until load event and add global metrics (6721e60)

Fixed

• clamp badge dragging within viewport boundaries (03aee99)
• ensure drag end handler is removed on draggable removal (8957129)

Changed

• enhance toolbar menu display logic with CSS transitions (e150700)
• simplify connector management in draggable methods (c995694)
• update audit overlay styles and improve highlight logic (27f1588)

0.18.0 (2026-04-13)

Added

• toolbar audit highlighting (4fcfc7d)

0.17.0 (2026-04-12)

Added

• add MageForge Toolbar with basic audits (#167) (2a8a8ba)

Fixed

• adjust initial badge position and add scroll handler for connector (#162) (84baaf0)
• enhance role determination for input elements in accessibility analysis (adb7996)
• enhance structure rendering with additional properties (109418b)
• handle click outside inspector overlay correctly when pinned (c885f81)
• improve badge update logic to prevent flickering (5526e15)
• improve CSS resource matching in element resource categorization (a1dba6a)
• remove INP metric tracking from performance and vitals modules (#165) (6c78a39)
• remove unused badge offset in position calculation for info badge (686387b)
• update cursor check for interactive elements in accessibility analysis (c430f99)
• update pull request header for clarity on changes (ccd5a47)
• update pull request title and header formatting in config (0dbab2e)

Changed

• remove feature views and new badge logic from inspector (#164) (3bf7143)
• use WeakMap for block data storage in inspector (#166) (5c383fd)

0.16.0 (2026-04-10)

Added

• add CSP whitelist and update Alpine.js to version 3.15.11 with hash security (#159) (fa811bd)
• update PHP and Magento framework requirements in composer.json #155 (#156) (9a3f92d)

Fixed

• add keydownHandler and impove performance observers to inspector (#160) (5639b87)
• Refactor inspector.js into ES modules (#161) (f3fb74d)
• updated advanced_usage.md for better understanding (#158) (956efe4)

0.15.1 (2026-03-18)

Fixed

• update phpstan to level 9 (#152) (c57f6c7)

0.15.0 (2026-03-18)

Added

• add wildcard theme resolution to build and clean commands (#150) (ec4316d)

0.14.1 (2026-03-12)

Fixed

• ensure theme codes are indexed correctly in commands (#149) (f9175a7)
• update Magento requirement to 2.4.7 with PHP 8.3 in README (3b4cfca)
• update Magento version to 2.4.7-p9 in compatibility workflow (79eb0b2)
• update PHP version and Magento version in compatibility matrix (8d662f6)

0.14.0 (2026-03-06)

Added

• replace MultiSelectPrompt with MultiSearchPrompt for theme selection (bc89442)

0.13.0 (2026-03-03)

Added

• add NodeSetupValidator for validating Magento default setup files (#142) (3f36d43)

Fixed

• resolve phpcs errors (#145) (cb90564)
• run mago format (#146) (fa34cd8)

0.12.0 (2026-02-14)

Added

• actions: replace elasticsearch with opensearch (#137) (cc8c534)

Fixed

• correct font size and border radius in inspector CSS (7bb3348)
• phpcs errors (#138) (625c6da)
• phpcs: refactor environment variable handling in commands (#135) (9c01ce5)
• update font settings and sizes in inspector CSS (986ded6)

Documentation

• update README with custom theme details and add inspector section (084b528)

0.11.0 (2026-02-10)

Added

• add cache and webvitals tabs to inspector and improve ux with dragable overlay (#127) (eea755d)
• implement dark/light mode theme selection and admin configuration section (#131) (0a95280)

Fixed

• remove metric icons and rename metric titles for better ux (#129) (11d3c45)

0.10.3 (2026-02-05)

Fixed

• update phpcs errors (#124) (a19e23d)

0.10.2 (2026-02-02)

Fixed

• return theme parts as array in parseThemeName (#122) (94aef44)

0.10.1 (2026-01-30)

Fixed

• correct spacing and formatting in multiple files (#120) (3f9048a)
• update phpstan level to 8 and improve commands (#119) (e24e138)

0.10.0 (2026-01-30)

Added

• update phpstan level and add type hints (#116) (0a4a5fa)

Fixed

• update phpstan level to 7 and improve error handling (#118) (7c84ae7)

0.9.0 (2026-01-30)

Added

• Node.js/Grunt setup detection for improved build process (#114) (5330e17)

Fixed

• phpstan level 5 errors #84 (#100) (154d15e)

0.8.1 (2026-01-27)

Fixed

• improve node module installation fallback logic (#107) (c400732)

0.8.0 (2026-01-23)

Added

• add functional-tests badge to readme.md (#95) (7108ef0)
• add npm sync validation to NodePackageManager and theme builders (#93) (5fcbdaf)
• add phpstan & phpcs (#96) (06bcfdc)
• add pinning functionality for inspector badge (#104) (69f7328)
• enhance inspector with JSON metadata and comment parsing (#105) (a2f9ebf)
• separate functional tests from compatibility tests (effac26)
• update feature request link to direct to new issue template (7e0b57e)

Fixed

• correct head-branch regex and add new changed-files sections (53777ea)
• labeler.yml to simplify Documentation labels (2d96502)
• labeler.yml to update label rules (79c3fc0)
• remove deprecated environment retrieval method (#98) (3e11ae7)
• remove unnecessary blank lines in functional tests workflow (f1e9bb7)
• update head-branch patterns and file globbing in labeler.yml (#103) (bd48b7c)
• update validateHyvaTheme to include output parameter (#99) (9b53f8d)
• Workflow permissions (#101) (c0c4c3d)

0.7.0 (2026-01-20)

Added

• add context7 configuration file with URL and public key (977bee0)
• add NodePackageManager service for npm dependency management (#91) (1ab623f)
• implement SymlinkCleaner service and integrate into theme builders #88 (#89) (3f40ef6)

0.6.0 (2026-01-19)

Added

• dev Inspector Overlay (Frontend) (#85) (806d04a)

0.5.0 (2026-01-17)

⚠ BREAKING CHANGES

• create theme:clean command for cleaning theme static files and cache, remove old mageforge:static:clean command (#80)

Added

• implement StaticContentCleaner and update theme build commands (#83) (80a6abf)

Fixed

• create theme:clean command for cleaning theme static files and cache, remove old mageforge:static:clean command (#80) (ffd5ec8)
• update command aliases for consistency and clarity (#82) (34640fa)

0.4.0 (2026-01-17)

Added

• add theme suggestion service and integrate with commands #75 (#76) (1347782)
• implement Release Please workflow and update configuration (d814853)

Fixed

• adjust command argument order and clean up whitespace (9c4fb73)
• enhance interactive mode for compatibility checks and prompts (#79) (428a133)
• improve theme selection and validation in TokensCommand (#77) (9167e95)

Documentation

• update community support links to GitHub Discussions (c67380e)
• update dependencies and naming conventions in Copilot instructions (cf98266)
• update README for command list and support section (f4fb886)

[0.3.1] - 2026-01-12

Fixed

• fix: add missing static property $cachedEnv in CleanCommand to resolve undeclared property error

[0.3.0] - 2026-01-12

Added

• feat: add verbose output support for watch task with -v flag
  • Shows informative messages during watch mode based on verbosity level
  • Captures and reports exit codes from npm/grunt watch commands
  • Displays clear error messages when watch mode exits with errors
  • Provides hint to use -v flag for verbose output in non-verbose mode
• feat: add mageforge:theme:tokens command to generate Hyvä design tokens from design.tokens.json or hyva.config.json
• feat: add mageforge:hyva:compatibility:check command to add a Hyvä compatibility checker
  • Scans Magento modules for Hyvä theme compatibility issues
  • Detects RequireJS, Knockout.js, jQuery, and UI Components usage
  • Interactive menu with Laravel Prompts for scan options
  • Options: --show-all, --third-party-only, --include-vendor, --detailed
  • Color-coded output (✓ Compatible, ⚠ Warnings, ✗ Incompatible)
  • Detailed file-level issues with line numbers
  • Exit code 1 for critical issues, 0 for success
  • Command aliases: m:h:c:c, hyva:check
• feat: add mageforge:theme:clean command for comprehensive cache and generated files cleanup
  • feat: add interactive multi-theme selection for theme:clean command using Laravel Prompts
  • feat: add --all option to clean all themes at once
  • feat: add --dry-run option to preview what would be cleaned without deleting
  • feat: add command alias frontend:clean for quick access
  • feat: add CI/CD tests for theme:clean command in compatibility workflow

Fixed

• fix: remove duplicate --verbose option from WatchCommand that conflicted with Symfony Console's built-in verbose option

Changed

• refactor: improve build commands to show full output in verbose mode
  • Remove --quiet flag from npm/grunt build commands when using verbose mode
  • Allow better debugging of build issues during theme compilation
• refactor: split complex executeCommand method into smaller, focused methods to reduce cyclomatic complexity
• docs: update copilot-instructions.md with CI/CD integration guidelines for new commands

[0.2.2] - 2025-06-05

• feat: enhance theme command arguments for better clarity and compatibility

[0.2.1] - 2025-06-04

• feat: reduce cyclomatic complexity
• fix: normalize theme name check to be case-insensitive for Hyva themes

[0.2.0] - 2025-05-30

• docs: clean up CHANGELOG.md
• feat: add PHP 8.4 and Magento 2.4.8 compatibilty check with opensearch support
• feat: enhance MySQL and Search Engine checks for mageforge:system:check command
• removed: removed Github Action to watch for Changelog edits
• fix: fixed issue where missing node_modules were not being installed
• fix: fixed issue where watch output was not displayed correctly

[0.1.0] - 2025-05-23

• docs: add cli-chooser image to README.md
• docs: simplify installation instructions in README.md
• feat: add comprehensive documentation for MageForge commands and custom ThemeBuilders
• feat: add Magento compatibility tests workflow (#35)
• feat: add spinner for theme building process in BuildThemeCommand
• feat: add system check commands for Node.js, MySQL, and environment status
• feat: enhance npm installation process with package-lock.json check
• feat: enhance system check command to display additional environment information
• feat: implement abstract command structure for improved command handling
• fix: improve theme builder to reduce cyclomatic complexity
• fix: restore TTY after prompting for theme selection in BuildThemeCommand and ThemeWatchCommand 🎨
• fix: update MageForge version command in compatibility test workflow
• refactor system and theme commands
• refactor: remove redundant docblocks and improve table headers in SystemCheckCommand
• refactor: simplify theme options retrieval in ThemeWatchCommand
• Update ListCommand.php
• Update custom_theme_builders.md
• Update magento-compatibility.yml