Require Js Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require ekyna/require-js-bundle
   

   Add the bundle to config/bundles.php:

   Ekyna\RequireJsBundle\EkynaRequireJsBundle::class => ['all' => true],
   

2. Basic Configuration Override the default config in config/packages/ekyna_require_js.yaml:

   ekyna_require_js:
       base_url: '%kernel.project_dir%/web/js'
       packages:
           app:
               path: 'vendor/ekyna/require-js-bundle/Resources/public/js'
               main: 'app'
   

3. First Use Case Add a script to your base template (templates/base.html.twig):

   {{ ekyna_require_js('app') }}
   

   This renders a <script> tag for RequireJS with the configured main module.

Implementation Patterns

Asset Organization

• Modular Structure: Use RequireJS’s AMD modules to split JS into:

  // src/Resources/public/js/app.js
  define(['jquery', 'underscored'], function($, _) {
      // Logic here
  });
  

• Symfony Integration: Place modules in web/js/ or src/Resources/public/js/ and reference them via:

  {{ ekyna_require_js('app', {
      'paths': {
          'text': 'vendor/requirejs-text/text'
      }
  }) }}
  

Dynamic Loading

• Lazy-Loading: Load modules conditionally:

  {% if user.isAdmin %}
      {{ ekyna_require_js('admin-panel') }}
  {% endif %}
  

• Event-Driven: Trigger RequireJS loads via Symfony events (e.g., kernel.controller).

Debugging & Builds

• Development: Use debug: true in config to enable RequireJS’s debug mode.
• Production: Integrate with Webpack Encore or r.js for optimization:

  ./vendor/bin/r.js -o name=almond baseUrl=web/js out=build.js
  

Gotchas and Tips

Configuration Quirks

• Base URL: Ensure base_url in config points to a web-accessible directory (e.g., web/js/). Relative paths (e.g., ../js/) may break in production.
• Package Naming: Avoid hyphens in package names (e.g., my-package → my_package). RequireJS uses camelCase internally.

Debugging

• 404 Errors: Verify path in config matches the filesystem. Use absolute paths if needed:

  packages:
      app:
          path: '%kernel.project_dir%/web/js'
  

• Module Not Found: Check:
  1. The module file exists (e.g., web/js/app.js).
  2. The main config points to a valid entry file.
  3. No typos in dependency names (e.g., jquery vs. jQuery).

Extension Points

• Custom Templates: Override the Twig template (EkynaRequireJsBundle:default:script.js.twig) to modify output.
• Pre/Post-Process: Use Symfony’s kernel.request event to inject dynamic configs:

  // src/EventListener/RequireJsListener.php
  public function onKernelRequest(GetResponseEvent $event) {
      $this->container->get('ekyna_require_js.config')->addConfig(['shim': ['jquery': { 'exports': 'jQuery' }]]);
  }
  

• RequireJS Plugins: Register plugins via config:

  ekyna_require_js:
      plugins:
          text: 'vendor/requirejs-text/text'