Cli Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer require sheaf/cli
   

   Add the package to your composer.json and run composer update.

2. First Command:

   php artisan sheaf:init
   

   Run this in your Laravel project root. Follow the interactive prompts or use flags for non-interactive setup (e.g., --with-dark-mode).

3. First Use Case: Install a component (e.g., a button) to test integration:

   php artisan sheaf:install button
   

   Verify the component appears in your resources/views/components directory and is usable in Blade templates.

4. Verify Setup: Check resources/css/sheaf.css and resources/js/sheaf.js for generated files. Test dark mode (if enabled) by toggling the theme switcher.

Implementation Patterns

Workflow Integration

1. Component-Driven Development:

   • Use sheaf:list to discover components before coding:

     php artisan sheaf:list --filter="form"
     

   • Install components incrementally (e.g., sheaf:install card → sheaf:install modal).

2. Theme Management:

   • Override default themes by publishing config:

     php artisan vendor:publish --provider="Sheaf\Cli\SheafServiceProvider" --tag="config"
     

   • Edit config/sheaf.php to customize theme.colors or theme.transitions.

3. Dependency Resolution:

   • Let Sheaf auto-resolve dependencies (e.g., Alpine.js for interactivity). Avoid manual npm install for Sheaf-managed assets.

4. Blade Integration:

   • Use components directly in Blade:

     <x-button type="primary">Click Me</x-button>
     

   • Access component props via @props in resources/views/components/button.blade.php.

5. Asset Compilation:

   • Sheaf auto-generates sheaf.css and sheaf.js. Rebuild after changes:

     npm run dev  # or `npm run build` for production
     

Advanced Patterns

• Custom Components: Create a component in resources/views/components/custom/ and register it via sheaf:register (if supported in future versions).
• Global Configuration: Use sheaf:config to toggle features globally (e.g., disable dark mode):

  php artisan sheaf:config set dark-mode false
  

• CI/CD Pipelines: Cache Sheaf dependencies in Docker/Laravel Forge by running sheaf:init --no-interaction in build steps.

Gotchas and Tips

Pitfalls

1. PHP/Node Version Mismatches:

   • Ensure PHP 8.1+ and Node.js 16+ are used. Sheaf CLI may fail silently with older versions.
   • Debug with:

     php -v && node -v
     

2. Tailwindcss Conflicts:

   • If tailwind.config.js exists, Sheaf may skip CSS setup. Merge configs manually or delete tailwind.config.js before sheaf:init.
   • Fix: Backup tailwind.config.js, then run sheaf:init --force.

3. Component Overwrites:

   • Manual edits to resources/views/components/ may be lost during sheaf:install. Use --keep-existing to preserve files (if supported).

4. Dark Mode Flicker:

   • Alpine.js theme switching may cause layout shifts. Add transition-colors duration-300 to root elements in your CSS.

5. Missing Dependencies:

   • Sheaf auto-installs Alpine.js, but custom builds may fail. Verify package.json includes:

     "alpinejs": "^3.12.0"
     

Debugging

• Verbose Output: Use -v flag for detailed logs:

  php artisan sheaf:init -v
  

• Clear Cache: If components fail to load, clear Laravel and Sheaf caches:

  php artisan cache:clear
  php artisan sheaf:cache:clear
  

• Check Logs: Errors are logged to storage/logs/sheaf.log.

Tips

1. Component Aliases: Use sheaf:install button --alias="primary-button" to create custom aliases for components.

2. Partial Updates: Update only specific components (if supported in future):

   php artisan sheaf:update button
   

3. Local Development: Symlink Sheaf assets for faster iteration:

   npm run dev -- --watch
   

   Then link the compiled CSS/JS in your Blade layout:

   <link href="{{ mix('css/sheaf.css') }}" rel="stylesheet">
   

4. Extending Themes: Override Sheaf’s CSS variables in your resources/css/app.css:

   @layer sheaf {
     --sheaf-primary: #3b82f6; /* Override default */
   }
   

5. Testing: Use Sheaf’s built-in test helpers (if available) in tests/Feature/SheafTest.php:

   use Sheaf\Cli\Testing\Sheaf;
   public function test_button_component() {
       Sheaf::assertComponentRendered('button');
   }
   

6. Performance: Exclude unused components from builds by configuring sheaf.php:

   'components' => [
       'button' => true,
       'modal' => false, // Exclude modal
   ],