Component Installer Laravel Package

Getting Started

Minimal Steps

1. Installation: Add the package via Composer:

   composer require robloach/component-installer
   

   Publish the config (optional, but recommended for customization):

   php artisan vendor:publish --provider="Robloach\ComponentInstaller\ComponentInstallerServiceProvider"
   

2. First Use Case: Install a web component (e.g., vue for Vue.js):

   php artisan component:install vue
   

   This will:

   • Download the component from a configured source (default: Packagist).
   • Place it in resources/js/components/ (configurable).
   • Update package.json with the new dependency.

3. Verify: Check resources/js/components/ for the installed component files and package.json for the new dependency entry.

Implementation Patterns

Workflows

1. Component Installation:

   • Use php artisan component:install <name> to fetch and install a component from a supported source (e.g., Packagist, GitHub, or a custom registry).
   • Example for a GitHub repo:

     php artisan component:install user/repo
     

     (Ensure the config is updated to include GitHub as a source.)

2. Bulk Installation:

   • Install multiple components at once by passing a comma-separated list:

     php artisan component:install vue,alpinejs,axios
     

3. Integration with Build Tools:

   • After installation, run your build tool (e.g., Vite, Webpack) to compile the new component:

     npm install && npm run dev
     

   • Automate this in a post-install script (e.g., post-install-cmd in composer.json).

4. Custom Component Sources:

   • Extend the package to support custom sources by implementing the Robloach\ComponentInstaller\Contracts\ComponentSource interface.
   • Example: Add a private registry or internal monorepo.

5. Version Management:

   • Specify a version during installation:

     php artisan component:install vue@3.2.45
     

   • Use ^ or ~ for flexible versioning (e.g., vue@^3.2).

6. Post-Install Hooks:

   • Use the component.installed event to run custom logic after installation:

     // In EventServiceProvider
     protected $listen = [
         'component.installed' => [
             'App\Listeners\PostComponentInstall',
         ],
     ];
     

Integration Tips

• Laravel Mix/Vite: Ensure your build tool is configured to resolve components from resources/js/components/. For Vite, update vite.config.js:

  resolve: {
      alias: {
          '@components': path.resolve(__dirname, './resources/js/components'),
      },
  },
  

• IDE Support: Add resources/js/components/ to your IDE’s include path for autocompletion.

• Testing: Test installations in a fresh environment or use Docker to avoid conflicts with existing dependencies.

Gotchas and Tips

Pitfalls

1. Dependency Conflicts:

   • Installing components manually via Composer after using component-installer may cause conflicts. Always use the installer for consistency.
   • Solution: Delete node_modules and package-lock.json before reinstalling dependencies if conflicts arise.

2. Source Configuration:

   • The package defaults to Packagist. If you rely on GitHub or other sources, ensure they are added to the sources config array in config/component-installer.php:

     'sources' => [
         'packagist' => [
             'type' => 'packagist',
             'url' => 'https://packagist.org',
         ],
         'github' => [
             'type' => 'github',
             'url' => 'https://github.com',
         ],
     ],
     

3. Permission Issues:

   • Running the installer without write permissions to resources/js/ or package.json will fail.
   • Solution: Ensure proper file permissions or run the command with elevated privileges (not recommended for production).

4. Component Overwrites:

   • Installing the same component twice may overwrite files or package.json entries.
   • Solution: Use --force cautiously or check for existing entries first.

5. Build Tool Cache:

   • After installing a component, clear your build tool’s cache (e.g., npm run dev -- --force) to avoid stale builds.

Debugging

• Verbose Output: Use -v or --verbose for detailed logs:

  php artisan component:install vue -v
  

• Dry Run: Test installations without modifying files by temporarily overriding the install method in a custom command or service provider.

• Event Listeners: Debug the component.installed event to trace installation steps:

  // In a listener
  public function handle($event) {
      \Log::info('Component installed:', $event->component);
  }
  

Extension Points

1. Custom Sources: Implement Robloach\ComponentInstaller\Contracts\ComponentSource to add support for private registries or internal tools. Example:

   namespace App\ComponentSources;
   
   use Robloach\ComponentInstaller\Contracts\ComponentSource;
   
   class PrivateRegistry implements ComponentSource {
       public function getComponent($name) {
           // Fetch from private registry
       }
   }
   

   Register it in the config:

   'sources' => [
       'private' => [
           'type' => 'custom',
           'class' => App\ComponentSources\PrivateRegistry::class,
       ],
   ],
   

2. Pre/Post-Install Hooks: Extend the Robloach\ComponentInstaller\Installers\Installer class to add custom logic before or after installation. Example:

   namespace App\Installers;
   
   use Robloach\ComponentInstaller\Installers\Installer;
   
   class CustomInstaller extends Installer {
       protected function postInstall($component) {
           // Custom logic (e.g., run tests, update docs)
       }
   }
   

   Bind it in the service provider:

   $this->app->bind(
       Robloach\ComponentInstaller\Contracts\Installer::class,
       App\Installers\CustomInstaller::class
   );
   

3. Component Naming: Override the default naming convention (e.g., kebab-case to PascalCase) by extending the Robloach\ComponentInstaller\Installers\Installer and modifying the getComponentPath method.

4. Testing: Use the package’s ComponentInstaller facade or service container to test installations in PHPUnit:

   $installer = $this->app->make(Robloach\ComponentInstaller\Contracts\Installer::class);
   $installer->install('vue');
   $this->assertFileExists(resource_path('js/components/vue/index.js'));