Jimport Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require davidjegat/jimport-bundle
   

   Add the bundle to config/bundles.php:

   return [
       // ...
       DavidJegat\JImportBundle\DavidJegatJImportBundle::class => ['all' => true],
   ];
   

2. Configure Assetic: In config/packages/assetic.yaml:

   assetic:
       bundles: ['AppBundle']  # Replace with your bundle name
   

3. First Use Case: Create a main.js file in assets/js/ with:

   @import('js/foo.js');
   @import('js/rep/bar.js');
   

   Use it in Twig:

   {% javascripts 'assets/js/main.js' filter='jimport' %}
       <script src="{{ asset_url }}"></script>
   {% endjavascripts %}
   

Implementation Patterns

Workflow Integration

1. Bundle-Aware Imports:

   • Register bundles in assetic.bundles to prioritize imports from Resources/public.
   • Example: @import('bundles/AppBundle/js/lib.js') will first check AppBundle/Resources/public/js/lib.js.

2. Dynamic Asset Loading:

   • Use @import in entrypoint files (e.g., main.js) to modularize JS dependencies.
   • Example:

     // assets/js/main.js
     @import('js/vendor/jquery.js');
     @import('js/app/features/*.js');  // Wildcard support
     

3. Twig Integration:

   • Always use {% javascripts ... filter='jimport' %} to parse imports.
   • Combine with other Assetic filters (e.g., uglifyjs2):

     {% javascripts 'assets/js/main.js' filter=['jimport', 'uglifyjs2'] %}
     

4. CSS Support:

   • Works identically for CSS files (replace javascripts with stylesheets in Twig).

Extension Patterns

1. Custom Functions:

   • Create a service tagged davidjegat_jimport.function (see README for interface).
   • Example: Add a generateRoute function to resolve Symfony routes in JS:

     # config/services.yaml
     services:
         App\JImport\RouteFunction:
             arguments: ['@router']
             tags: ['davidjegat_jimport.function']
     

2. Conditional Imports:

   • Use custom functions to conditionally load assets:

     if (@isMobile()) {
         @import('js/mobile.js');
     }
     

Gotchas and Tips

Pitfalls

1. Dev vs. Prod Parsing:

   • Imports are only parsed during Assetic dump in production. Avoid dynamic logic (e.g., DB queries) in @import replacements.
   • Fix: Use AJAX or server-side logic for dynamic asset loading.

2. Bundle Priority:

   • If a file isn’t found in the first registered bundle, it checks subsequent bundles. No fallback to filesystem—missing files become empty strings.
   • Fix: Verify bundle registration order in assetic.bundles.

3. Wildcard Limitations:

   • Wildcards (*.js) are parsed but not recursively resolved (e.g., @import('js/**/*.js') won’t work).
   • Fix: Manually list files or use a build tool (e.g., Webpack) for complex dependencies.

4. Twig Syntax Conflicts:

   • Avoid @import in Twig templates (e.g., {{ asset('js/foo.js') }}). Use only in JS/CSS files.

Debugging Tips

1. Check Parsed Output:

   • Enable Assetic debug mode (debug: true in assetic.yaml) to see resolved imports.
   • Look for warnings like File not found: js/foo.js.

2. Custom Function Debugging:

   • Add var_dump() in execute() to inspect $arguments and $parser state.
   • Example:

     public function execute(array $args, Parser $parser) {
         error_log(print_r($args, true));
         return '// Debug: ' . json_encode($args);
     }
     

3. Cache Issues:

   • Clear Assetic cache after changes:

     php bin/console assetic:dump --watch --env=prod
     

Extension Points

1. Parser Hooks:

   • Extend DavidJegat\JImportBundle\Parser\Parser to modify import resolution logic.
   • Example: Add a preProcess() method to normalize paths.

2. Filter Chaining:

   • Combine with other Assetic filters (e.g., yui_compressor) for minification:

     {% javascripts 'assets/js/main.js' filter=['jimport', 'yui_compressor'] %}
     

3. Environment-Specific Imports:

   • Use custom functions to load environment-specific assets:

     @import('@env('APP_ENV') === "dev" ? "js/dev.js" : "js/prod.js"');
     

     (Requires a custom function to evaluate JS expressions.)