Cms Assets Laravel Package

Getting Started

Minimal Steps

1. Installation Add the package via Composer in your Laravel project (if applicable, though this is primarily a Craft CMS asset package):

   composer require craftcms/cms-assets
   

   Note: This package is designed for Craft CMS, not Laravel. If integrating with Laravel, ensure compatibility with Craft’s asset pipeline or use its compiled assets directly.

2. Locate Assets The package provides compiled assets (CSS, JS, fonts) for Craft CMS. Check the resources/assets or web/assets directory (depending on the subtree split) for:

   • css/ (e.g., craft.css, control-panel.css)
   • js/ (e.g., craft.js, util.js)
   • fonts/ (e.g., Craft’s icon fonts)

3. First Use Case

   • For Craft CMS: Include the compiled assets in your templates via:

     {{ css('assets/css/craft.css') }}
     {{ js('assets/js/craft.js') }}
     

   • For Laravel (if applicable): Link directly in Blade:

     <link href="{{ asset('vendor/craftcms/cms-assets/css/craft.css') }}" rel="stylesheet">
     <script src="{{ asset('vendor/craftcms/cms-assets/js/craft.js') }}"></script>
     

Implementation Patterns

Workflows

1. Asset Integration

   • Craft CMS: Use the package’s assets as-is in your templates or extend them via SASS/JS preprocessors.
   • Laravel: Treat as a vendor dependency. Override or extend assets by publishing them:

     php artisan vendor:publish --tag=craft-assets
     

     Then customize in resources/assets/craft/.

2. Customization

   • SASS: Extend craft.scss (if available) by importing it in your main SASS file:

     @import 'vendor/craftcms/cms-assets/scss/craft';
     

   • JavaScript: Use Craft’s global Craft object (if available) or extend its modules.

3. Build Process

   • If using Laravel Mix/Webpack, alias the package’s assets in webpack.mix.js:

     mix.sass('resources/assets/craft/custom.scss', 'public/assets')
         .js('resources/assets/craft/custom.js', 'public/assets')
         .alias({
             'craft-assets': path.resolve(__dirname, 'vendor/craftcms/cms-assets')
         });
     

4. Asset Versioning

   • Craft CMS handles versioning automatically. In Laravel, append a query string for cache busting:

     <link href="{{ asset('vendor/craftcms/cms-assets/css/craft.css?v='.filemtime(public_path('vendor/craftcms/cms-assets/css/craft.css')) }}" rel="stylesheet">
     

Integration Tips

• Craft Plugins: Bundle assets with your plugin by copying them to your-plugin/assets/ and referencing them via getBasePath().
• Laravel Packages: Use composer.json autoloading to expose assets:

  "extra": {
      "craft-assets": {
          "css": "vendor/craftcms/cms-assets/css",
          "js": "vendor/craftcms/cms-assets/js"
      }
  }
  

Gotchas and Tips

Pitfalls

1. Craft-Specific Dependencies

   • This package assumes Craft CMS’s asset pipeline (e.g., {{ asset }} Twig function). In Laravel, manually link assets or mock the function:

     // In a Laravel service provider
     Blade::directive('asset', function ($expression) {
         return "<?php echo asset($expression); ?>";
     });
     

2. Asset Paths

   • The subtree split may not include source files (e.g., SASS/JS). Only compiled assets are provided. For customization, use Craft’s original repo or override files.

3. Version Conflicts

   • If using multiple Craft packages, ensure asset versions align. Check composer.json for conflicts:

     composer why craftcms/cms-assets
     

4. Missing Files

   • Some assets (e.g., control-panel.css) may be omitted. Verify the dist/ or web/ folder in the package.

Debugging

• Broken CSS/JS: Clear Laravel’s cache and config:

  php artisan cache:clear
  php artisan config:clear
  

• 404 Errors: Ensure assets are published or symlinked:

  php artisan vendor:publish --tag=craft-assets --force
  

Extension Points

1. Custom Assets

   • Override package assets by publishing them and extending:

     php artisan vendor:publish --tag=craft-assets --force
     

     Then modify resources/assets/craft/css/craft.css.

2. Dynamic Asset Loading

   • In Laravel, conditionally load assets based on routes:

     @if (request()->is('admin*'))
         {{ asset('vendor/craftcms/cms-assets/css/control-panel.css') }}
     @endif
     

3. Webpack Integration

   • Use copy-webpack-plugin to include Craft assets in your Laravel build:

     const CopyWebpackPlugin = require('copy-webpack-plugin');
     mix.copy('vendor/craftcms/cms-assets/css', 'public/vendor/craft/css');
     

Tips

• Check for Updates: Monitor the Craft CMS repo for asset updates.
• Laravel-Craft Hybrid: If using both, isolate Craft assets to a subdirectory (e.g., /craft-assets) to avoid conflicts.
• Minification: Laravel Mix can minify Craft’s assets:

  mix.sass('resources/assets/craft/custom.scss', 'public/assets')
      .options({ processCssUrls: false });