MageForge for Magento 2

https://github.com/openforgeproject/mageforge
Admin
MageForge is a powerful CLI front-end development toolkit for Magento 2 that simplifies theme...
Tokens:33,982
Snippets:485
Trust Score:7.5
License:GPL-3.0
Update:3 months ago
Show doc for...
Tokens:
Raw
### Command Output Example

Source: https://github.com/openforgeproject/mageforge/blob/main/_autodocs/07-theme-commands.md

Typical console output when starting the watch process.

```text
Starting watch mode... (use -v for verbose output)

[13:45:00] Building assets...
[13:45:02] Assets built successfully
[13:45:05] Watching for changes...
```

--------------------------------

### Theme Not Found Error

Source: https://github.com/openforgeproject/mageforge/blob/main/_autodocs/11-exceptions-and-errors.md

Example output when a specified theme is not installed or recognized.

```text
Theme 'Magento/invalid' is not installed.
Did you mean one of these?
  - Magento/luma
  - Magento/blank
```

--------------------------------

### Install Magento 2

Source: https://github.com/openforgeproject/mageforge/blob/main/docs/development.md

Executes the installation script to set up Magento 2, MageForge, and sample data. Requires DDEV to be running first.

```bash
ddev install-magento
```

--------------------------------

### Manual Test Execution Examples

Source: https://github.com/openforgeproject/mageforge/blob/main/docs/development.md

Specific examples for testing theme detection, standard builds, Hyvä builds, and watch mode.

```bash
# Theme detection
ddev magento mageforge:theme:list

# Standard Magento build
ddev magento mageforge:theme:build Magento/luma

# Hyvä theme build (requires Hyvä to be installed)
ddev magento mageforge:theme:build Hyva/default

# Watch mode
ddev magento mageforge:theme:watch Magento/luma

# System diagnostics
ddev magento mageforge:system:check
```

--------------------------------

### ThemeSuggester Usage Examples

Source: https://github.com/openforgeproject/mageforge/blob/main/_autodocs/05-theme-suggester.md

Demonstrates how to use findSimilarThemes with various inputs to get suggestions.

```php
$suggester = new ThemeSuggester($themeList);

$suggestions = $suggester->findSimilarThemes('Magento/lumic');
// Returns: ['Magento/luma'] - exact match close in spelling

$suggestions = $suggester->findSimilarThemes('mag');
// Returns: ['Magento/luma', 'Magento/blank'] - substring matches

$suggestions = $suggester->findSimilarThemes('NonExistent');
// Returns: [] - no similar themes found
```

--------------------------------

### Installation Commands

Source: https://github.com/openforgeproject/mageforge/blob/main/_autodocs/README.md

Standard commands to install the MageForge module via Composer and enable it in Magento.

```bash
composer require openforgeproject/mageforge
bin/magento module:enable OpenForgeProject_MageForge
bin/magento setup:upgrade
```

--------------------------------

### MageForge Inspector Status Output Examples

Source: https://github.com/openforgeproject/mageforge/blob/main/_autodocs/09-inspector-feature.md

Example outputs for the status command in different application modes.

```text
MageForge Inspector Status

Mode: development
Inspector: Enabled

✓ Inspector is active and ready to use!
```

```text
MageForge Inspector Status

Mode: production
Inspector: Disabled

Warning:
Inspector requires developer mode to function.
Switch to developer mode with: bin/magento deploy:mode:set developer
```

```text
MageForge Inspector Status

Mode: development
Inspector: Disabled

Note:
Inspector is disabled. Run "bin/magento mageforge:theme:inspector enable" to activate it.
```

--------------------------------

### List Themes Command

Source: https://github.com/openforgeproject/mageforge/blob/main/_autodocs/07-theme-commands.md

Displays a table of all installed themes.

```text
mageforge:theme:list
```

```bash
bin/magento mageforge:theme:list
```

--------------------------------

### Interactive Theme Selection Example

Source: https://github.com/openforgeproject/mageforge/blob/main/_autodocs/05-theme-suggester.md

Demonstrates how to use the suggestions with a SelectPrompt for interactive user input.

```php
$invalidInput = 'Magento/lumic'; // User typo
$suggester = new ThemeSuggester($themeList);
$suggestions = $suggester->findSimilarThemes($invalidInput);

if (!empty($suggestions)) {
    // Interactive selection
    $prompt = new SelectPrompt(
        label: 'Did you mean:',
        options: $suggestions,
    );
    $selected = $prompt->prompt();
    // User selects 'Magento/luma'
} else {
    $this->io->error("Theme not found: $invalidInput");
}
```

--------------------------------

### Verify MageForge Installation

Source: https://github.com/openforgeproject/mageforge/blob/main/_autodocs/14-quick-start-guide.md

Confirm the toolkit is correctly installed by checking the version.

```bash
bin/magento mageforge:system:version
```

--------------------------------

### Execute Static Content Deployment

Source: https://github.com/openforgeproject/mageforge/blob/main/_autodocs/08-support-services.md

Example usage of the deploy method to trigger static content generation.

```php
$deployer = new StaticContentDeployer($shell, $state);
if ($deployer->deploy('Magento/luma', $io, $output, true)) {
    echo "Static content deployed\n";
}
```

--------------------------------

### Retrieve All Themes

Source: https://github.com/openforgeproject/mageforge/blob/main/_autodocs/04-theme-list-and-path.md

Fetches all installed themes indexed by their filesystem path.

```php
public function getAllThemes(): array
```

```php
$themeList = new ThemeList($magentoThemeList);
$themes = $themeList->getAllThemes();

foreach ($themes as $path => $theme) {
    echo $theme->getCode() . " at " . $path . "\n";
    // Output: Magento/luma at frontend/Magento/luma
    //         Custom/theme at frontend/Custom/theme
}
```

--------------------------------

### Start DDEV environment

Source: https://github.com/openforgeproject/mageforge/blob/main/docs/development.md

Pulls necessary Docker containers and configures the local development environment.

```bash
ddev start
```

--------------------------------

### Inspector CLI Examples

Source: https://github.com/openforgeproject/mageforge/blob/main/_autodocs/09-inspector-feature.md

Common CLI commands for managing the inspector state.

```bash
# Enable inspector
bin/magento mageforge:theme:inspector enable

# Disable inspector
bin/magento mageforge:theme:inspector disable

# Check status
bin/magento mageforge:theme:inspector status
```

--------------------------------

### Handle Theme Name Suggestions

Source: https://github.com/openforgeproject/mageforge/blob/main/_autodocs/14-quick-start-guide.md

Example of how the system provides corrections for mistyped theme names.

```bash
bin/magento mageforge:theme:build Magento/lumic
# Suggests: "Did you mean: Magento/luma?"
```

--------------------------------

### Implement the watch() Method

Source: https://github.com/openforgeproject/mageforge/blob/main/docs/custom_theme_builders.md

Starts a process to monitor theme file changes and trigger rebuilds. Demonstrates both custom script execution and standard npm command usage.

```php
public function watch(string $themePath, SymfonyStyle $io, OutputInterface $output, bool $isVerbose): bool
{
    // Examples of watch implementations:

    // 1. Start your custom watcher
    try {
        $command = 'node ' . $themePath . '/your-watcher.js';
        if ($isVerbose) {
            $io->text('Starting watch process with: ' . $command);
        }
        exec($command);
    } catch (\Exception $e) {
        $io->error('Watch process could not be started: ' . $e->getMessage());
        return false;
    }

    // 2. Use existing tools
    try {
        exec('cd ' . $themePath . ' && npm run watch');
    } catch (\Exception $e) {
        $io->error('Watch process could not be started: ' . $e->getMessage());
        return false;
    }

    return true;
}
```

--------------------------------

### Reinstall Magento

Source: https://github.com/openforgeproject/mageforge/blob/main/docs/development.md

Perform a clean installation of Magento.

```bash
ddev restart            # Ensure the source mount is fresh first
ddev install-magento   # Handles cleanup automatically
```

--------------------------------

### Build Command Usage Examples

Source: https://github.com/openforgeproject/mageforge/blob/main/_autodocs/07-theme-commands.md

Various ways to invoke the build command, including single theme, multiple themes, wildcard vendor selection, and interactive mode.

```bash
# Build single theme
bin/magento mageforge:theme:build Magento/luma

# Build multiple themes
bin/magento mageforge:theme:build Magento/luma Custom/theme

# Build all themes from vendor
bin/magento mageforge:theme:build Magento/*

# Interactive selection (no arguments)
bin/magento mageforge:theme:build
```

--------------------------------

### Compatibility Check Output

Source: https://github.com/openforgeproject/mageforge/blob/main/_autodocs/10-system-commands.md

Example output formats for checking a single theme versus checking all themes.

```text
Hyvä Compatibility Check for Magento/luma

Scanning installed modules for Hyvä compatibility...

Module Compatibility:
  
  Magento_Catalog
    Status: ✓ Compatible
    Notes: Has Hyvä layout updates
  
  Magento_Checkout
    Status: ⚠ Needs Review
    Notes: No Hyvä-specific templates found
    Recommendation: Check custom checkout styling
  
  Custom_Module
    Status: ✗ Not Compatible
    Notes: Hardcoded Bootstrap CSS detected
    Recommendation: Update to use Hyvä components

Summary: 1 compatible, 1 needs review, 1 incompatible
```

```text
Hyvä Compatibility Check

Scanning all themes and modules...

Hyvä Themes Found: 1
  • Vendor/hyva-theme

Compatibility Summary:
  ✓ Fully Compatible: 8 modules
  ⚠ Needs Review: 3 modules
  ✗ Incompatible: 2 modules

Recommendations:
  1. Review flagged modules for Hyvä compatibility
  2. Consider Hyvä-specific versions of extensions
  3. Test thoroughly with Hyvä theme active
```

--------------------------------

### Implement autoRepair() method in PHP

Source: https://github.com/openforgeproject/mageforge/blob/main/docs/custom_theme_builders.md

Use this method to perform automated fixes, such as generating missing configuration files or installing dependencies, before the build process starts.

```php
public function autoRepair(string $themePath, SymfonyStyle $io, OutputInterface $output, bool $isVerbose): bool
{
    // Examples of repair measures:

    // 1. Create missing configuration files
    if (!file_exists($themePath . '/your-config.json')) {
        if ($isVerbose) {
            $io->warning('Configuration file missing. Creating default configuration...');
        }
        file_put_contents(
            $themePath . '/your-config.json',
            json_encode(['version' => '1.0.0', 'options' => []])
        );
    }

    // 2. Install missing dependencies
    if (!is_dir($themePath . '/node_modules')) {
        if ($isVerbose) {
            $io->warning('Node modules missing. Running npm install...');
        }
        try {
            $this->shell->execute('cd ' . $themePath . ' && npm install --quiet');
        } catch (\Exception $e) {
            $io->error('Error installing node modules: ' . $e->getMessage());
            return false;
        }
    }

    return true;
}
```

--------------------------------

### Verify installation

Source: https://github.com/openforgeproject/mageforge/blob/main/docs/development.md

Runs the MageForge system check command to ensure the environment is correctly configured.

```bash
ddev magento mageforge:system:check
```

--------------------------------

### Install MageForge via Composer

Source: https://github.com/openforgeproject/mageforge/blob/main/_autodocs/14-quick-start-guide.md

Run these commands in the Magento root directory to add the toolkit to your project.

```bash
cd /path/to/magento
composer require openforgeproject/mageforge
```

--------------------------------

### Start Watch Mode

Source: https://github.com/openforgeproject/mageforge/blob/main/_autodocs/14-quick-start-guide.md

Initiate watch mode to automatically rebuild theme files upon detection of changes.

```bash
bin/magento mageforge:theme:watch Vendor/theme
```

--------------------------------

### List Magento Themes

Source: https://github.com/openforgeproject/mageforge/blob/main/docs/commands_reference.md

Lists all available themes in the current Magento installation.

```bash
bin/magento mageforge:theme:list
# or alias
bin/magento frontend:list
```

--------------------------------

### NodePackageManager installNodeModules Method

Source: https://github.com/openforgeproject/mageforge/blob/main/_autodocs/08-support-services.md

Installs npm packages in a specified directory, automatically choosing between npm ci and npm install based on the presence of a lock file.

```php
public function installNodeModules(
    string $path,
    SymfonyStyle $io,
    bool $isVerbose,
): bool
```

```php
$manager = new NodePackageManager($shell, $fileDriver);
if ($manager->installNodeModules('/path/to/web/tailwind', $io, false)) {
    echo "Dependencies installed\n";
}
```

--------------------------------

### Integrating Suggestions in AbstractCommand

Source: https://github.com/openforgeproject/mageforge/blob/main/_autodocs/05-theme-suggester.md

Example of using the suggester within a command to handle invalid theme inputs.

```php
// In AbstractCommand.handleInvalidThemeWithSuggestions()
$suggestions = $themeSuggester->findSimilarThemes($invalidTheme);

if (empty($suggestions)) {
    $this->io->error("Theme '$invalidTheme' is not installed and no similar themes were found.");
    return null;
}

// In interactive terminal: show SelectPrompt
// In non-interactive: display suggestions as text
```

--------------------------------

### Watch Command Examples

Source: https://github.com/openforgeproject/mageforge/blob/main/_autodocs/07-theme-commands.md

Various ways to invoke the watch command using arguments, options, or interactive mode.

```bash
# Watch theme (argument)
bin/magento mageforge:theme:watch Magento/luma

# Watch theme (option)
bin/magento mageforge:theme:watch -t Magento/luma

# Interactive selection (no arguments)
bin/magento mageforge:theme:watch
```

--------------------------------

### Check System Requirements

Source: https://github.com/openforgeproject/mageforge/blob/main/_autodocs/14-quick-start-guide.md

Verifies PHP version, Magento installation, Node.js/npm, and available builders.

```bash
bin/magento mageforge:system:check
```

--------------------------------

### Restart DDEV

Source: https://github.com/openforgeproject/mageforge/blob/main/docs/development.md

Use these commands to resolve issues where DDEV fails to start.

```bash
ddev poweroff
ddev start
```

--------------------------------

### Retrieve MageForge Version

Source: https://github.com/openforgeproject/mageforge/blob/main/_autodocs/10-system-commands.md

Displays the current version, license, and installation status of MageForge.

```text
mageforge:system:version
```

```bash
bin/magento mageforge:system:version
```

```text
MageForge Version

Version: 0.27.0
License: GPL-3.0
Status: Installed and active
```

--------------------------------

### Resolve Grunt Issues

Source: https://github.com/openforgeproject/mageforge/blob/main/_autodocs/14-quick-start-guide.md

Ensure grunt-cli is installed globally before rebuilding the theme.

```bash
# Install Grunt globally
npm install -g grunt-cli

# Rebuild theme
bin/magento mageforge:theme:build Vendor/theme -v
```

--------------------------------

### mageforge:system:version

Source: https://github.com/openforgeproject/mageforge/blob/main/_autodocs/10-system-commands.md

Displays the current version, license, and installation status of the MageForge module.

```APIDOC
## mageforge:system:version

### Description
Displays MageForge version information, including the version number, license type, and installation status.

### Signature
`bin/magento mageforge:system:version`

### Arguments
None

### Options
None
```

--------------------------------

### mageforge:system:check

Source: https://github.com/openforgeproject/mageforge/blob/main/_autodocs/10-system-commands.md

Performs system diagnostics to verify MageForge prerequisites, environment setup, and builder availability.

```APIDOC
## mageforge:system:check

### Description
Performs system diagnostics to verify MageForge prerequisites, including PHP version, Magento installation, module status, Node.js availability, and theme configuration.

### Signature
`bin/magento mageforge:system:check`

### Arguments
None

### Options
None

### Exit Codes
- 0: All checks passed
- 1: One or more checks failed
```

--------------------------------

### autoRepair(string $themePath, SymfonyStyle $io, OutputInterface $output, bool $isVerbose): bool

Source: https://github.com/openforgeproject/mageforge/blob/main/_autodocs/02-builder-interface.md

Validates and repairs missing dependencies or setup.

```APIDOC
## autoRepair

### Description
Validates and repairs missing dependencies or setup. Typically installs Node modules and verifies prerequisites.

### Parameters
- **themePath** (string) - Required - Filesystem path to theme
- **io** (SymfonyStyle) - Required - Styled console output
- **output** (OutputInterface) - Required - Raw console output
- **isVerbose** (bool) - Required - Verbose mode flag

### Returns
- **bool** - True if repair succeeded, false otherwise
```

--------------------------------

### Build and Watch Magento Standard Theme

Source: https://github.com/openforgeproject/mageforge/blob/main/_autodocs/14-quick-start-guide.md

Builds or watches a standard Magento theme using Grunt. Requires Node.js, npm, and Grunt setup.

```bash
# Build
bin/magento mageforge:theme:build Magento/luma

# Watch
bin/magento mageforge:theme:watch Magento/luma
```

--------------------------------

### Hyvä Tokens Command Usage

Source: https://github.com/openforgeproject/mageforge/blob/main/_autodocs/10-system-commands.md

Examples of common operations including exporting, importing, and resetting design tokens.

```bash
# Export current Hyvä tokens
bin/magento mageforge:hyva:tokens export

# Import tokens from file
bin/magento mageforge:hyva:tokens import token-config.json

# Reset to defaults
bin/magento mageforge:hyva:tokens reset
```

--------------------------------

### Injectable Service Constructor

Source: https://github.com/openforgeproject/mageforge/blob/main/_autodocs/13-module-structure.md

Example of injecting core MageForge services into a class constructor via dependency injection.

```php
public function __construct(
    private readonly ThemeList $themeList,
    private readonly ThemePath $themePath,
    private readonly BuilderPool $builderPool,
    private readonly ThemeSuggester $suggester,
    private readonly CacheCleaner $cache,
) {
}
```

--------------------------------

### Clone the repository

Source: https://github.com/openforgeproject/mageforge/blob/main/docs/development.md

Initializes the local project directory by cloning the repository and navigating into it.

```bash
git clone git@github.com:OpenForgeProject/mageforge.git
cd mageforge
```

--------------------------------

### Inspector Element Information Example

Source: https://github.com/openforgeproject/mageforge/blob/main/_autodocs/09-inspector-feature.md

Example of the block and template information displayed during element inspection.

```text
Magento\Catalog\Block\Product\View

Template: Magento_Catalog::product/view.phtml
Module: Magento_Catalog
Path: app/code/Magento/Catalog
```

--------------------------------

### NodePackageManager::installNodeModules

Source: https://github.com/openforgeproject/mageforge/blob/main/_autodocs/08-support-services.md

Installs npm packages in a specified directory, automatically choosing between 'npm ci' or 'npm install' based on the presence of a lock file.

```APIDOC
## NodePackageManager::installNodeModules

### Description
Installs npm packages in a directory.

### Parameters
- **path** (string) - Required - Directory containing package.json
- **io** (SymfonyStyle) - Required - Console output
- **isVerbose** (bool) - Required - Verbose mode flag

### Returns
- **bool** - True if installation succeeded

### Example
```php
$manager = new NodePackageManager($shell, $fileDriver);
if ($manager->installNodeModules('/path/to/web/tailwind', $io, false)) {
    echo "Dependencies installed\n";
}
```
```

--------------------------------

### Retrieve Builder by Path

Source: https://github.com/openforgeproject/mageforge/blob/main/_autodocs/03-builder-pool.md

Find the first compatible builder for a specific theme directory path.

```php
$builder = $builderPool->getBuilder('/var/www/app/design/frontend/Vendor/theme');

if ($builder === null) {
    echo 'No suitable builder found';
} else {
    echo 'Using builder: ' . $builder->getName();
}
```

--------------------------------

### View Command Help

Source: https://github.com/openforgeproject/mageforge/blob/main/_autodocs/14-quick-start-guide.md

Use the --help flag to display usage information for specific MageForge commands.

```bash
bin/magento mageforge:theme:build --help
bin/magento mageforge:theme:watch --help
```

--------------------------------

### NodePackageManager isNodeModulesInSync Method

Source: https://github.com/openforgeproject/mageforge/blob/main/_autodocs/08-support-services.md

Verifies if the installed packages match the package-lock.json file.

```php
public function isNodeModulesInSync(string $path): bool
```

```php
if (!$manager->isNodeModulesInSync('/path/to/web/tailwind')) {
    // Run installNodeModules
}
```

--------------------------------

### Execute Complete Theme Build Cycle

Source: https://github.com/openforgeproject/mageforge/blob/main/_autodocs/14-quick-start-guide.md

Standard sequence for developing and deploying themes, including mode switching and cleanup.

```bash
# 1. Switch to developer mode
bin/magento deploy:mode:set developer

# 2. List themes
bin/magento mageforge:theme:list

# 3. Build theme
bin/magento mageforge:theme:build Vendor/theme

# 4. Enter watch mode for development
bin/magento mageforge:theme:watch Vendor/theme
# (leaves terminal running, edit theme files, refresh browser)

# 5. Exit watch mode (Ctrl+C)

# 6. Clean up when done
bin/magento mageforge:theme:clean Vendor/theme

# 7. Switch back to production
bin/magento deploy:mode:set production
```

--------------------------------

### Get TailwindCSS Builder Name

Source: https://github.com/openforgeproject/mageforge/blob/main/_autodocs/06-builder-implementations.md

Retrieves the identifier for the TailwindCSS builder service.

```php
public function getName(): string
// Returns: 'TailwindCSS'
```

--------------------------------

### Basic CLI Usage

Source: https://github.com/openforgeproject/mageforge/blob/main/_autodocs/README.md

Common CLI commands for listing, building, watching, and cleaning Magento themes.

```bash
# List themes
bin/magento mageforge:theme:list

# Build a theme
bin/magento mageforge:theme:build Vendor/theme

# Watch for changes
bin/magento mageforge:theme:watch Vendor/theme

# Clean static files
bin/magento mageforge:theme:clean Vendor/theme
```

--------------------------------

### Grunt Not Found Error

Source: https://github.com/openforgeproject/mageforge/blob/main/_autodocs/11-exceptions-and-errors.md

Error message indicating a failure to install the grunt-cli package.

```text
Failed to install grunt: npm install -g grunt-cli exited with code 1
```

--------------------------------

### Constructing ThemeSuggester

Source: https://github.com/openforgeproject/mageforge/blob/main/_autodocs/05-theme-suggester.md

Initialize the service with a required ThemeList instance.

```php
public function __construct(
    ThemeList $themeList,
)
```

--------------------------------

### Perform auto-repair

Source: https://github.com/openforgeproject/mageforge/blob/main/_autodocs/02-builder-interface.md

Validates and repairs theme dependencies, such as installing missing Node modules.

```php
if (!$builder->autoRepair($themePath, $io, $output, false)) {
    throw new Exception('Failed to repair theme dependencies');
}
```

--------------------------------

### MageForge Theme and System Commands

Source: https://github.com/openforgeproject/mageforge/blob/main/docs/development.md

Commands for listing, building, and watching themes, as well as running system diagnostics.

```bash
ddev magento mageforge:theme:list                # List all themes
ddev magento mageforge:theme:build <theme>       # Build a theme
ddev magento mageforge:theme:watch <theme>       # Watch mode (Ctrl+C to stop)
ddev magento mageforge:system:check              # System diagnostics
```

--------------------------------

### Node Modules Sync Error

Source: https://github.com/openforgeproject/mageforge/blob/main/_autodocs/11-exceptions-and-errors.md

Error message indicating a failure during the npm installation process.

```text
Failed to install node modules: npm install exited with code 1
```

--------------------------------

### Command Integration Pattern

Source: https://github.com/openforgeproject/mageforge/blob/main/_autodocs/04-theme-list-and-path.md

Demonstrates how to inject and use ThemeList and ThemePath within a command class.

```php
class BuildCommand extends AbstractCommand {
    public function __construct(
        private ThemeList $themeList,
        private ThemePath $themePath,
    ) {
        parent::__construct();
    }
    
    protected function executeCommand(...) {
        // Get all themes for interactive selection
        $themes = $this->themeList->getAllThemes();
        
        // Resolve user input to filesystem path
        $path = $this->themePath->getPath($userInput);
        
        // Pass to builder
        $builder = $this->builderPool->getBuilder($path);
    }
}
```

--------------------------------

### Troubleshoot Hyvä Theme Build Failures

Source: https://github.com/openforgeproject/mageforge/blob/main/_autodocs/10-system-commands.md

Sequence of commands to verify prerequisites, compatibility, and rebuild the theme.

```bash
# First: Check system prerequisites
bin/magento mageforge:system:check

# Verify Hyvä builder is available
# If not, install Node.js and npm

# Then: Check Hyvä compatibility
bin/magento mageforge:hyva:compatibility:check VendorName/hyva-theme

# Review incompatible modules
# Update or disable incompatible extensions

# Finally: Try build again
bin/magento mageforge:theme:build VendorName/hyva-theme -v
```

--------------------------------

### Perform Quick Theme Rebuild

Source: https://github.com/openforgeproject/mageforge/blob/main/_autodocs/14-quick-start-guide.md

Combines theme building and cache clearing into a single command.

```bash
# One-line rebuild
bin/magento mageforge:theme:build Vendor/theme && bin/magento cache:clean full_page
```

--------------------------------

### Install MageForge via Composer

Source: https://github.com/openforgeproject/mageforge/blob/main/README.md

Use this command to add the MageForge package to your Magento project dependencies.

```bash
composer require openforgeproject/mageforge
```

--------------------------------

### Implement multi-theme builder in PHP

Source: https://github.com/openforgeproject/mageforge/blob/main/docs/custom_theme_builders.md

Use this pattern to build parent themes before processing the current theme.

```php
public function build(string $themePath, SymfonyStyle $io, OutputInterface $output, bool $isVerbose): bool
{
    // Find all dependent themes
    $parentThemes = $this->findParentThemes($themePath);

    // Build parent themes first
    foreach ($parentThemes as $parentTheme) {
        $io->text('Building parent theme: ' . basename($parentTheme));
        // Call build logic for parent theme here
    }

    // Then build the current theme
    // ...

    return true;
}
```

--------------------------------

### Build All Vendor Themes

Source: https://github.com/openforgeproject/mageforge/blob/main/_autodocs/14-quick-start-guide.md

Builds all themes associated with a specific vendor using a wildcard pattern.

```bash
bin/magento mageforge:theme:build Vendor/*
```

--------------------------------

### Check MageForge Version

Source: https://github.com/openforgeproject/mageforge/blob/main/docs/commands_reference.md

Displays the currently installed version of MageForge and checks for updates via the GitHub API.

```bash
bin/magento mageforge:system:version
bin/magento system:version
```

--------------------------------

### Build Magento Themes

Source: https://github.com/openforgeproject/mageforge/blob/main/docs/commands_reference.md

Compiles assets and deploys static content for specified themes.

```bash
bin/magento mageforge:theme:build <theme-code> [<theme-code> ...]
bin/magento frontend:build Magento/luma Magento/blank
```

--------------------------------

### Build Command Verbose Mode

Source: https://github.com/openforgeproject/mageforge/blob/main/_autodocs/07-theme-commands.md

Use the -v flag to display detailed build steps, builder selection, and cache progress.

```bash
bin/magento mageforge:theme:build -v Magento/luma
```

--------------------------------

### Implement build() method in PHP

Source: https://github.com/openforgeproject/mageforge/blob/main/docs/custom_theme_builders.md

This method executes the theme build process, including asset compilation, bundling, deployment, and cache clearing.

```php
public function build(string $themeCode, string $themePath, SymfonyStyle $io, OutputInterface $output, bool $isVerbose): bool
{
    // Build process examples:

    // 1. SCSS/SASS Compilation
    $io->text('Compiling SCSS files...');
    try {
        $this->shell->execute('sass ' . $themePath . '/web/scss:' . $themePath . '/web/css --style compressed');
    } catch (\Exception $e) {
        $io->error('SCSS compilation failed: ' . $e->getMessage());
        return false;
    }

    // 2. Create JavaScript bundles
    $io->text('Creating JavaScript bundles...');
    try {
        $this->shell->execute('webpack --config ' . $themePath . '/webpack.config.js');
    } catch (\Exception $e) {
        $io->error('JavaScript bundling failed: ' . $e->getMessage());
        return false;
    }

    // 3. Deploy static content
    $themeCode = basename($themePath);
    $this->staticContentDeployer->deploy($themeCode, $io, $output, $isVerbose);

    // 4. Clear cache
    $this->cacheCleaner->clean($io, $isVerbose);

    return true;
}
```

--------------------------------

### Build Command Signature

Source: https://github.com/openforgeproject/mageforge/blob/main/_autodocs/07-theme-commands.md

The base command signature for triggering a theme build process.

```bash
bin/magento mageforge:theme:build [<themeCodes>...]
```

--------------------------------

### Implement detect() method in PHP

Source: https://github.com/openforgeproject/mageforge/blob/main/docs/custom_theme_builders.md

Use this method to define logic that identifies if a theme belongs to your builder by checking for specific files, directories, or file content.

```php
public function detect(string $themePath): bool
{
    // Examples of detection strategies:

    // 1. Check for specific configuration files
    if (file_exists($themePath . '/your-config.json')) {
        return true;
    }

    // 2. Check for specific directory structures
    if (is_dir($themePath . '/your-special-folder')) {
        return true;
    }

    // 3. Check for content in specific files
    if (file_exists($themePath . '/theme.xml')) {
        $content = file_get_contents($themePath . '/theme.xml');
        if (strpos($content, 'your-identifier') !== false) {
            return true;
        }
    }

    return false;
}
```

--------------------------------

### Create ReactJS theme builder

Source: https://github.com/openforgeproject/mageforge/blob/main/docs/custom_theme_builders.md

Detects React dependencies in package.json and executes npm build scripts.

```php
public function detect(string $themePath): bool
{
    return file_exists($themePath . '/package.json') &&
           strpos(file_get_contents($themePath . '/package.json'), '"react"') !== false;
}

public function build(string $themePath, SymfonyStyle $io, OutputInterface $output, bool $isVerbose): bool
{
    try {
        $this->shell->execute('cd ' . $themePath . ' && npm run build');
        return true;
    } catch (\Exception $e) {
        $io->error('React build failed: ' . $e->getMessage());
        return false;
    }
}
```

--------------------------------

### NodePackageManager::isNodeModulesInSync

Source: https://github.com/openforgeproject/mageforge/blob/main/_autodocs/08-support-services.md

Verifies if the installed node_modules match the package-lock.json file by checking directory existence and running npm ls.

```APIDOC
## NodePackageManager::isNodeModulesInSync

### Description
Checks if installed packages match package-lock.json.

### Parameters
- **path** (string) - Required - Directory to check

### Returns
- **bool** - True if in sync, false otherwise

### Example
```php
if (!$manager->isNodeModulesInSync('/path/to/web/tailwind')) {
    // Run installNodeModules
}
```
```

--------------------------------

### Instantiate BuilderPool

Source: https://github.com/openforgeproject/mageforge/blob/main/_autodocs/03-builder-pool.md

Initialize the pool with an array of builder instances.

```php
$pool = new BuilderPool([
    $standardBuilder,
    $hyvaBuilder,
    $tailwindBuilder,
]);
```

--------------------------------

### mageforge:hyva:compatibility:check

Source: https://github.com/openforgeproject/mageforge/blob/main/_autodocs/10-system-commands.md

Scans installed extensions for Hyvä compatibility, identifying modules with Hyvä-specific implementations or potential compatibility issues.

```APIDOC
## mageforge:hyva:compatibility:check

### Description
Scans installed extensions for Hyvä compatibility. Identifies modules that have Hyvä-specific implementations, may have compatibility issues, or are not Hyvä-optimized.

### Signature
`bin/magento mageforge:hyva:compatibility:check [<themeCode>]`

### Arguments
- **themeCode** (string) - Optional - Specific theme to check (e.g., 'Vendor/theme')

### Exit Codes
- **0** - Check completed
- **1** - Error during check
```

--------------------------------

### Enable MageForge Module

Source: https://github.com/openforgeproject/mageforge/blob/main/README.md

Execute these commands to register the module within Magento and update the database schema.

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

--------------------------------

### Define the Module Configuration

Source: https://github.com/openforgeproject/mageforge/blob/main/docs/custom_theme_builders.md

Create a module.xml file in the etc directory to define the module and its dependency on MageForge.

```xml
<?xml version="1.0"?>
<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:noNamespaceSchemaLocation="urn:magento:framework:Module/etc/module.xsd">
    <module name="YourCompany_YourModule" setup_version="1.0.0">
        <sequence>
            <module name="OpenForgeProject_MageForge"/>
        </sequence>
    </module>
</config>
```

--------------------------------

### Utilize Injected Magento Services

Source: https://github.com/openforgeproject/mageforge/blob/main/_autodocs/12-extension-points.md

Examples of common operations using the injected services for file management, shell commands, and configuration access.

```php
// File operations
$fileDriver->isExists($path);
$fileDriver->isDirectory($path);
$fileDriver->fileGetContents($path);

// Shell execution
$shell->execute('command %s', ['argument']);

// State checking
$state->getMode(); // Returns 'development', 'production', etc.

// Configuration
$config->getValue('path/to/config');

// Cache management
$cacheManager->clean(['cache_type']);
```

--------------------------------

### Install Mageforge Module via Composer

Source: https://github.com/openforgeproject/mageforge/wiki/Development

Use these Composer commands to add the Mageforge repository, require the module, and enable it in your Magento 2 project.

```bash
# add repository
composer config repositories.mageforge vcs https://github.com/OpenForgeProject/mageforge.git

# require module
composer require openforgeproject/mageforge:dev-main --prefer-source

# enable module
bin/magento setup:upgrade
```

--------------------------------

### Debug Frontend Display Issues

Source: https://github.com/openforgeproject/mageforge/blob/main/_autodocs/10-system-commands.md

Commands to verify builder detection and check for extension conflicts when the frontend appears broken.

```bash
# Check theme builder detection
bin/magento mageforge:system:check

# Verify correct builder used
bin/magento mageforge:theme:build -v YourVendor/theme

# Check for extension conflicts
bin/magento mageforge:hyva:compatibility:check YourVendor/theme
```

--------------------------------

### CLI Commands

Source: https://github.com/openforgeproject/mageforge/blob/main/_autodocs/00-index.md

List of available CLI commands for managing themes, system status, and Hyvä compatibility.

```APIDOC
## CLI Commands

### Theme Operations
- `bin/magento mageforge:theme:list` - List all themes
- `bin/magento mageforge:theme:build [themes...]` - Build specified themes
- `bin/magento mageforge:theme:watch <theme>` - Watch a theme for changes
- `bin/magento mageforge:theme:clean [themes...] [--all] [--dry-run]` - Clean theme artifacts

### System
- `bin/magento mageforge:system:version` - Display system version
- `bin/magento mageforge:system:check` - Run system checks

### Inspector
- `bin/magento mageforge:theme:inspector <enable|disable|status>` - Manage theme inspector

### Hyvä
- `bin/magento mageforge:hyva:compatibility:check [theme]` - Check Hyvä compatibility
- `bin/magento mageforge:hyva:tokens <export|import|reset>` - Manage Hyvä tokens
```

--------------------------------

### Access and save configuration values

Source: https://github.com/openforgeproject/mageforge/blob/main/_autodocs/13-module-structure.md

Demonstrates reading configuration via ScopeConfig and writing via WriterInterface.

```php
// Read inspector config
$isEnabled = $scopeConfig->isSetFlag(Inspector::XML_PATH_ENABLED);
$theme = $scopeConfig->getValue(Inspector::XML_PATH_THEME);
$position = $scopeConfig->getValue(Inspector::XML_PATH_POSITION);

// Save config (requires WriterInterface)
$configWriter->save(Inspector::XML_PATH_ENABLED, '1');
```

--------------------------------

### Theme Selection Prompt Interface

Source: https://github.com/openforgeproject/mageforge/blob/main/_autodocs/07-theme-commands.md

The interactive prompt for selecting themes during build or clean operations, supporting multi-select via space and navigation via arrow keys.

```text
Select themes to build

Type to search theme... [Type to search, arrow keys to navigate, Space to toggle, Enter to confirm]
```

--------------------------------

### MageForge Theme Management Commands

Source: https://github.com/openforgeproject/mageforge/blob/main/README.md

Basic CLI commands for listing, building, and watching Magento themes during development.

```bash
# 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
```

--------------------------------

### Build theme assets

Source: https://github.com/openforgeproject/mageforge/blob/main/_autodocs/02-builder-interface.md

Executes the main build process, including asset compilation and cache cleaning.

```php
$success = $builder->build(
    'Magento/luma',
    '/var/www/app/design/frontend/Magento/luma',
    $io,
    $output,
    true
);
```

--------------------------------

### Switch to Production Mode

Source: https://github.com/openforgeproject/mageforge/blob/main/_autodocs/14-quick-start-guide.md

Set the Magento application to production mode to trigger automatic static content deployment.

```bash
bin/magento deploy:mode:set production
```

--------------------------------

### Build a Theme Programmatically in PHP

Source: https://github.com/openforgeproject/mageforge/blob/main/_autodocs/00-index.md

Uses ThemePath and BuilderPool to locate and execute a theme build process.

```php
public function __construct(
    private readonly ThemePath $themePath,
    private readonly BuilderPool $builderPool,
) {}

public function buildTheme(string $themeCode): bool
{
    // Get theme path
    $themePath = $this->themePath->getPath($themeCode);
    if ($themePath === null) {
        echo "Theme not found: $themeCode\n";
        return false;
    }
    
    // Get appropriate builder
    $builder = $this->builderPool->getBuilder($themePath);
    if ($builder === null) {
        echo "No builder found for: $themeCode\n";
        return false;
    }
    
    // Build theme
    $io = new SymfonyStyle($input, $output);
    return $builder->build($themeCode, $themePath, $io, $output, true);
}
```

--------------------------------

### Deploy Static Content

Source: https://github.com/openforgeproject/mageforge/blob/main/_autodocs/08-support-services.md

Method signature for deploying theme-specific static files.

```php
public function deploy(
    string $themeCode,
    SymfonyStyle $io,
    OutputInterface $output,
    bool $isVerbose,
): bool
```

--------------------------------

### build(string $themeCode, string $themePath, SymfonyStyle $io, OutputInterface $output, bool $isVerbose): bool

Source: https://github.com/openforgeproject/mageforge/blob/main/_autodocs/02-builder-interface.md

Builds theme assets by compiling SASS/Tailwind, deploying static content, and cleaning caches.

```APIDOC
## build

### Description
Builds theme assets. This is the main operation: compiles SASS/Tailwind, deploys static content, and cleans caches.

### Parameters
- **themeCode** (string) - Required - Magento theme code
- **themePath** (string) - Required - Filesystem path to theme
- **io** (SymfonyStyle) - Required - Styled console output
- **output** (OutputInterface) - Required - Raw console output
- **isVerbose** (bool) - Required - Verbose mode flag

### Returns
- **bool** - True if build succeeded, false otherwise
```

--------------------------------

### Implement BuilderInterface in PHP

Source: https://github.com/openforgeproject/mageforge/blob/main/_autodocs/12-extension-points.md

Create a class implementing BuilderInterface to define custom theme detection, building, repair, and watch logic.

```php
namespace YourVendor\YourModule\ThemeBuilder;

use OpenForgeProject\MageForge\Service\ThemeBuilder\BuilderInterface;
use Symfony\Component\Console\Output\OutputInterface;
use Symfony\Component\Console\Style\SymfonyStyle;

class CustomBuilder implements BuilderInterface
{
    private const THEME_NAME = 'CustomTheme';
    
    public function __construct(
        private readonly Shell $shell,
        private readonly File $fileDriver,
        // ... other dependencies
    ) {
    }

    public function detect(string $themePath): bool
    {
        // Detect if theme is custom type
        // Return true if builder handles this theme
        return $this->fileDriver->isExists($themePath . '/custom-marker.txt');
    }

    public function getName(): string
    {
        return self::THEME_NAME;
    }

    public function build(
        string $themeCode,
        string $themePath,
        SymfonyStyle $io,
        OutputInterface $output,
        bool $isVerbose,
    ): bool {
        try {
            if ($isVerbose) {
                $io->text('Building custom theme...');
            }
            
            // Your build logic here
            $this->runCustomBuild($themePath, $io, $isVerbose);
            
            if ($isVerbose) {
                $io->success('Custom theme built successfully.');
            }
            return true;
        } catch (\Exception $e) {
            $io->error('Build failed: ' . $e->getMessage());
            return false;
        }
    }

    public function autoRepair(
        string $themePath,
        SymfonyStyle $io,
        OutputInterface $output,
        bool $isVerbose,
    ): bool {
        // Validate and repair dependencies
        // Return false if repair fails
        return true;
    }

    public function watch(
        string $themeCode,
        string $themePath,
        SymfonyStyle $io,
        OutputInterface $output,
        bool $isVerbose,
    ): bool {
        // Start watch mode
        // Block until user exits (Ctrl+C)
        return true;
    }

    private function runCustomBuild(string $themePath, SymfonyStyle $io, bool $isVerbose): void
    {
        // Your custom build implementation
    }
}
```

--------------------------------

### Initialize StaticContentDeployer

Source: https://github.com/openforgeproject/mageforge/blob/main/_autodocs/08-support-services.md

Constructor definition for the StaticContentDeployer service.

```php
public function __construct(
    Shell $shell,
    State $state,
)
```

--------------------------------

### Manage Inspector via CLI

Source: https://github.com/openforgeproject/mageforge/blob/main/_autodocs/09-inspector-feature.md

Commands for switching Magento modes and enabling the inspector.

```bash
# Switch to developer mode
bin/magento deploy:mode:set developer

# Enable inspector
bin/magento mageforge:theme:inspector enable

# Switch back to production when done
bin/magento deploy:mode:set production
```

--------------------------------

### Handle Invalid Theme with Suggestions

Source: https://github.com/openforgeproject/mageforge/blob/main/_autodocs/11-exceptions-and-errors.md

Commands check for null return values from path lookups to trigger suggestion logic or return failure codes.

```php
// In command
$themePath = $this->themePath->getPath($userInput);
if ($themePath === null) {
    // Theme invalid, suggest corrections
    $corrected = $this->handleInvalidThemeWithSuggestions(...);
    if ($corrected === null) {
        return Cli::RETURN_FAILURE; // User declined suggestion
    }
}
```

--------------------------------

### Define Optional Development Dependencies

Source: https://github.com/openforgeproject/mageforge/blob/main/_autodocs/13-module-structure.md

Lists development-specific packages required for testing and coding standards.

```json
{
    "carthage-software/mago": "^1.30",
    "infection/infection": "^0.34.0",
    "magento/magento-coding-standard": "^40",
    "phpunit/phpunit": "^11.0"
}
```

--------------------------------

### Troubleshoot Build Failures

Source: https://github.com/openforgeproject/mageforge/blob/main/_autodocs/14-quick-start-guide.md

Use system checks, verbose output, and compatibility checks to diagnose build issues.

```bash
# Check system requirements
bin/magento mageforge:system:check

# Run with verbose output to see details
bin/magento mageforge:theme:build -v Vendor/theme

# Check Hyvä compatibility (if Hyvä theme)
bin/magento mageforge:hyva:compatibility:check Vendor/theme
```

--------------------------------

### Enable Inspector via CLI

Source: https://github.com/openforgeproject/mageforge/blob/main/_autodocs/09-inspector-feature.md

Sets the application to developer mode and enables the inspector feature.

```bash
bin/magento deploy:mode:set developer
bin/magento mageforge:theme:inspector enable
```

--------------------------------

### NodePackageManager Constructor

Source: https://github.com/openforgeproject/mageforge/blob/main/_autodocs/08-support-services.md

Initializes the NodePackageManager with Shell and File driver dependencies.

```php
public function __construct(
    Shell $shell,
    File $fileDriver,
)
```

--------------------------------

### Integrate BuilderPool in Commands

Source: https://github.com/openforgeproject/mageforge/blob/main/_autodocs/03-builder-pool.md

Use the pool within a command to select a builder and execute the build process.

```php
// In BuildCommand
$builder = $this->builderPool->getBuilder($themePath);
if ($builder === null) {
    $this->io->error("No suitable builder found for theme $themeCode.");
    return false;
}

$success = $builder->build($themeCode, $themePath, $this->io, $output, $isVerbose);
```

--------------------------------

### watch(string $themeCode, string $themePath, SymfonyStyle $io, OutputInterface $output, bool $isVerbose): bool

Source: https://github.com/openforgeproject/mageforge/blob/main/_autodocs/02-builder-interface.md

Runs watch mode: monitors theme files and rebuilds on changes.

```APIDOC
## watch

### Description
Runs watch mode: monitors theme files and rebuilds on changes. Blocks until process exits (Ctrl+C).

### Parameters
- **themeCode** (string) - Required - Magento theme code
- **themePath** (string) - Required - Filesystem path to theme
- **io** (SymfonyStyle) - Required - Styled console output
- **output** (OutputInterface) - Required - Raw console output
- **isVerbose** (bool) - Required - Verbose mode flag

### Returns
- **bool** - True if watch completed successfully, false on error
```

--------------------------------

### Integrate Webpack with theme builder

Source: https://github.com/openforgeproject/mageforge/blob/main/docs/custom_theme_builders.md

Dynamically adjust configuration and execute shell commands to run Webpack builds.

```php
public function build(string $themePath, SymfonyStyle $io, OutputInterface $output, bool $isVerbose): bool
{
    // Dynamically adjust Webpack configuration
    $webpackConfig = $themePath . '/webpack.config.js';
    if (file_exists($webpackConfig)) {
        // Adjust configuration if necessary
        // ...
    }

    // Run Webpack
    try {
        $this->shell->execute('cd ' . $themePath . ' && npx webpack --mode production');
    } catch (\Exception $e) {
        $io->error('Webpack build failed: ' . $e->getMessage());
        return false;
    }

    return true;
}
```

--------------------------------

### CacheCleaner Constructor

Source: https://github.com/openforgeproject/mageforge/blob/main/_autodocs/08-support-services.md

Initializes the CacheCleaner service with the required Shell dependency.

```php
public function __construct(
    Shell $shell,
)
```

--------------------------------

### Implement a Webpack-based detection strategy

Source: https://github.com/openforgeproject/mageforge/blob/main/_autodocs/12-extension-points.md

The detect method verifies the presence of specific configuration files and dependencies to determine if the builder should handle the theme.

```php
public function detect(string $themePath): bool
{
    $themePath = rtrim($themePath, '/');
    
    // Check for webpack config AND webpack in package.json
    if (!$this->fileDriver->isExists($themePath . '/webpack.config.js')) {
        return false;
    }
    
    if ($this->fileDriver->isExists($themePath . '/package.json')) {
        $json = $this->fileDriver->fileGetContents($themePath . '/package.json');
        $data = json_decode($json, true);
        
        // Only match if webpack is explicitly a dependency
        $deps = array_merge(
            $data['dependencies'] ?? [],
            $data['devDependencies'] ?? [],
        );
        
        return isset($deps['webpack']);
    }
    
    return false;
}
```

--------------------------------

### Vendor Wildcard Resolution

Source: https://github.com/openforgeproject/mageforge/blob/main/_autodocs/07-theme-commands.md

Demonstrates how vendor wildcards are expanded into specific theme lists.

```bash
# These are equivalent:
bin/magento mageforge:theme:build Magento/*
bin/magento mageforge:theme:build Magento

# Resolves to:
# Magento/luma, Magento/blank, Magento/custom (all themes starting with Magento/)
```

```text
Resolved vendor 'Magento' to 3 theme(s): Magento/luma, Magento/blank, Magento/custom
```

--------------------------------

### Create SCSS theme builder

Source: https://github.com/openforgeproject/mageforge/blob/main/docs/custom_theme_builders.md

Detects SCSS files and compiles them using the Sass CLI.

```php
public function detect(string $themePath): bool
{
    return file_exists($themePath . '/web/scss/styles.scss');
}

public function build(string $themePath, SymfonyStyle $io, OutputInterface $output, bool $isVerbose): bool
{
    try {
        $this->shell->execute('sass ' . $themePath . '/web/scss:' . $themePath . '/web/css --style compressed');
        return true;
    } catch (\Exception $e) {
        $io->error('SCSS compilation failed: ' . $e->getMessage());
        return false;
    }
}
```

--------------------------------

### Implement Command Exception Handling

Source: https://github.com/openforgeproject/mageforge/blob/main/_autodocs/11-exceptions-and-errors.md

Wraps command execution in a try/catch block to catch exceptions and return a failure status code.

```php
// In AbstractCommand::execute()
protected function execute(InputInterface $input, OutputInterface $output): int
{
    $this->io = new SymfonyStyle($input, $output);

    try {
        return $this->executeCommand($input, $output);
    } catch (\Exception $e) {
        $this->io->error($e->getMessage());
        return Cli::RETURN_FAILURE;
    }
}
```

--------------------------------

### ThemeList Constructor

Source: https://github.com/openforgeproject/mageforge/blob/main/_autodocs/04-theme-list-and-path.md

Initializes the ThemeList service with the Magento framework theme list dependency.

```php
public function __construct(
    MagentoThemeList $magentoThemeList,
)
```

--------------------------------

### Register the Magento Module

Source: https://github.com/openforgeproject/mageforge/blob/main/docs/custom_theme_builders.md

Create a registration.php file in the module root to register the component with Magento.

```php
<?php
use Magento\Framework\Component\ComponentRegistrar;

ComponentRegistrar::register(
    ComponentRegistrar::MODULE,
    'YourCompany_YourModule',
    __DIR__
);
```

--------------------------------

### Build Magento Themes

Source: https://github.com/openforgeproject/mageforge/blob/main/_autodocs/14-quick-start-guide.md

Compile theme assets using various selection methods or verbose flags.

```bash
# Build single theme
bin/magento mageforge:theme:build Magento/luma

# Build with verbose output
bin/magento mageforge:theme:build -v Magento/luma

# Build multiple themes
bin/magento mageforge:theme:build Magento/luma Custom/mytheme

# Build all themes from vendor
bin/magento mageforge:theme:build Magento/*

# Interactive selection (no arguments)
bin/magento mageforge:theme:build
```

--------------------------------

### mageforge:theme:build

Source: https://github.com/openforgeproject/mageforge/blob/main/_autodocs/07-theme-commands.md

Builds specified themes or all themes from a vendor, supporting interactive selection and wildcard patterns.

```APIDOC
## mageforge:theme:build

### Description
Builds one or more themes. If no arguments are provided, it triggers an interactive multi-select prompt. Supports vendor wildcards and provides detailed output in verbose mode.

### Signature
`bin/magento mageforge:theme:build [<themeCodes>...]`

### Arguments
- **themeCodes** (array<string>) - Optional - Theme codes to build. Supports specific names (Vendor/theme) or vendor wildcards (Vendor/*).

### Examples
```bash
# Build single theme
bin/magento mageforge:theme:build Magento/luma

# Build multiple themes
bin/magento mageforge:theme:build Magento/luma Custom/theme

# Build all themes from vendor
bin/magento mageforge:theme:build Magento/*

# Interactive selection
bin/magento mageforge:theme:build
```

### Verbose Mode
Use the `-v` flag to display detailed builder selection, build steps, and cache cleaning progress.
```

--------------------------------

### Implement Automatic Fallback

Source: https://github.com/openforgeproject/mageforge/blob/main/_autodocs/11-exceptions-and-errors.md

Wraps interactive prompts in try-catch blocks to reset the environment and fallback to text-based displays upon failure.

```php
// In BuildCommand
try {
    $themeCodes = $themeCodesPrompt->prompt();
} catch (\Exception $e) {
    $this->resetPromptEnvironment();
    // Fallback to text display
    $this->displayAvailableThemes($this->io);
    return Command::SUCCESS;
}
```
Tokens:
Raw