MageForge for Magento 2

[image: Mageforge Hero]

MageForge is a powerful CLI toolkit for Magento 2 front-end development. It simplifies theme building workflows, supports multiple theme types (Magento Standard, Hyvä, TailwindCSS, custom), and includes developer tools like the Frontend Inspector.

Table of Contents

• Requirements
• Supported Theme Types
• Installation
• Quick Start
• Frontend Inspector
• Commands Reference
• Documentation
• Get your Merch
• Credits

Contributor? Jump to the Development Guide.

Requirements

• Magento 2.4.7+ (tested on 2.4.7-p10, 2.4.8-p5, 2.4.9)
• PHP 8.3+
• Node.js (LTS recommended)
• Composer

Supported Theme Types

[image: Mageforge Hero]

Installation

1. Install via Composer:

   composer require openforgeproject/mageforge
   

2. Enable the module:

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

Quick Start

# 1. List available themes
bin/magento mageforge:theme:list

# 2. Build a theme
bin/magento mageforge:theme:build Magento/luma

# 3. Watch for changes (development mode)
bin/magento mageforge:theme:watch Magento/luma

See Commands Reference for the full command list with options and examples.

Frontend Inspector

The MageForge Inspector lets you inspect Magento blocks, templates, and performance metrics directly in your browser.

Features:

• Template paths, block classes, and module names
• PHP render times and cache status (lifetime, tags)
• Web Vitals: LCP, CLS, INP per element
• Accessibility checks: ARIA roles, contrast ratios, alt text

Screenshot

[image: Mageforge Toolbar]

Enable:

bin/magento mageforge:theme:inspector enable

(Requires Developer Mode. Can also be enabled in Admin: Stores > Configuration > MageForge > Frontend Inspector)

Use in Browser:

• Toggle: Ctrl+Shift+I (Windows/Linux) or Cmd+Option+I (macOS)
• Hover over elements to inspect; click to lock on a specific block

Note: Not compatible with Magewire components (automatically excluded).

Commands Reference

See the dedicated Commands Reference for complete documentation of all MageForge commands, including:

• Theme commands (list, build, watch, clean, inspector)
• Hyvä commands (tokens, compatibility:check)
• System commands (version, check)
• Options, arguments, and usage examples

Documentation

• Commands Reference — Full command documentation
• Custom Theme Builders — Extend MageForge for custom themes
• Development Guide — Local dev setup, workflow, and contribution guide

Get your Merch

[image: Mageforge Hero]

Support

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

Credits

MageForge uses the following third-party libraries:

Special Thanks

A big thank you to e3n-team for their continuous support and collaboration in the further development of MageForge.

Your contributions have been invaluable!

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.23.0 (2026-06-24)

⚠ BREAKING CHANGES

• install module via Composer path repository instead of app/code bind-mount
• add MageForge bind-mount setup and dependency management (#198)
• improve PHPStan target path and config detection
• add ddev pre-start hook to mount MageForge source files for local development

Added

• add ddev pre-start hook to mount MageForge source files for local development (5682455)
• add dev env (#192) (2e4b5fb)
• add hyva theme install for local dev environment (#196) (3392557)
• add MageForge bind-mount setup and dependency management (#198) (2e0e168)
• add MageForge Logo to admin menu (#197) (a7c2c8a)
• add merchandise section to README with promotional image (8dbcb9a)
• add SVG logo and enhance toolbar styles and functionality (#201) (724c607)
• require Hyvä theme and enable MageForge module during Magento installation (79a6e00)
• Toolbar redesign (#202) (fd5854a)
• update qa tools (#200) (e8bbdcd)
• update README and commands documentation (#194) (526c456)

Fixed

• audit toggle functionality (d4bbb3c)
• enhance cache cleaning in InspectorCommand to include layout and… (#195) (f8de418)
• image names for CLI chooser, toolbar, and merch in README (b535622)
• improve install-magento script to clean up leftover files from failed installations (124180a)
• improve PHPStan target path and config detection (e398fc0)
• install module via Composer path repository instead of app/code bind-mount (1305ee6)
• update symlink option in composer path repository configuration (3ef1c43)

Documentation

• enhance development documentation with automated release and changelog generation details (652f984)
• update contributing guidelines for clarity and best practices (c108a86)
• update development documentation to clarify bind-mount setup and module dependency management (0f279cc)

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