Vite Bundle Laravel Package

Technical Evaluation

Architecture Fit

• Symfony-First Fit: The package is explicitly designed for Symfony, leveraging its Twig templating system and routing infrastructure. It replaces Webpack Encore’s asset pipeline with Vite, aligning with modern frontend tooling while maintaining Symfony’s conventions (e.g., assets/ directory structure, Twig blocks).
• Modularity: The bundle decouples Vite’s asset handling from Symfony’s core, allowing teams to adopt Vite incrementally (e.g., migrate one entry point at a time).
• Legacy Support: Handles legacy browser compatibility via Vite’s polyfills and nomodule fallbacks, critical for enterprise apps with older browser requirements.
• Stimulus Integration: Deep integration with Symfony UX Stimulus, including HMR (Hot Module Replacement) and controller registration, reduces friction for teams using Symfony’s modern frontend stack.

Integration Feasibility

• Low Friction for Symfony Apps: Replaces webpack-encore-bundle with minimal config changes (e.g., vite_entry_link_tags instead of encore_entry_link_tags). The migration guide provides clear steps.
• Vite Plugin Dependency: Requires vite-plugin-symfony, which adds a small dependency but enables Symfony-specific features (e.g., asset manifest parsing, Twig integration).
• Dev/Prod Parity: Automatically switches between Vite’s dev server (HMR) and static asset serving in production, reducing environment-specific configs.
• Environment Variables: Supports .env variables via exposedEnvVars (v8.4.0+), useful for dynamic asset paths or API endpoints.

Technical Risk

• Vite Ecosystem Lock-In: Ties the project to Vite’s roadmap (e.g., recent updates for Vite 6/7). Teams using Webpack or other bundlers may face tooling divergence.
• Stimulus-Specific Quirks: Advanced Stimulus features (e.g., lazy-loaded controllers) require careful config (see changelog v8.0.0). Teams not using Stimulus may overlook optimizations.
• Legacy Browser Overhead: Polyfills and nomodule scripts add ~5–10KB to production builds, impacting performance for modern-only apps.
• Twig Dependency: Assumes Twig for templating. Teams using PHP templates (e.g., Blade) would need custom adapters.
• Debugging Complexity: Vite’s HMR and Symfony’s profiler integration (v7.0.0+) may require additional tooling (e.g., symfony-cli for HTTPS dev server).

Key Questions

1. Frontend Stack Alignment:

   • Does the team use Symfony UX (Stimulus, React, etc.)? If not, are the Stimulus-specific features (HMR, controllers) needed?
   • Are there non-Twig templates (e.g., Blade, PHP native) that would require custom integration?

2. Migration Strategy:

   • Should the team migrate all assets at once or phase by phase (e.g., start with CSS, then JS)?
   • Are there Webpack-specific plugins (e.g., custom loaders) that need replacement?

3. Performance Trade-offs:

   • Is the legacy browser support (polyfills) justified, or can the app target modern browsers only?
   • How will asset sizes compare to Webpack Encore’s output?

4. Dev Experience:

   • Will the team use Symfony’s dev server or a separate Vite dev server? (Affects HMR and proxy configs.)
   • Are there custom Vite plugins (e.g., for images, SVGs) that need compatibility checks?

5. CI/CD Impact:

   • How will the build process change? Vite’s npm run build replaces Webpack’s yarn encore production.
   • Are there Symfony-specific build steps (e.g., asset cache warming) that need updating?

Integration Approach

Stack Fit

• Primary Use Case: Ideal for Symfony 5.4+ apps using Twig, Stimulus, or modern frontend frameworks (React, Vue via Symfony UX).
• Compatibility:
  • PHP: Requires PHP 8.0+ (see changelog v6.3.5).
  • Vite: Supports Vite 4–7 (latest stable). Teams using older Vite versions may need updates.
  • Symfony Flex: Works seamlessly with Symfony’s recipe system (auto-configures routes, Twig extensions).
• Alternatives Considered:
  • Manual Vite Integration: Possible but requires handling asset manifests, Twig tags, and dev/prod switching manually.
  • Other Bundles: mtdowling/jms-serializer-bundle or api-platform/core for API-driven apps may conflict with Vite’s asset pipeline.

Migration Path

1. Pre-Migration:

   • Backup assets/, package.json, and webpack.config.js (if using Encore).
   • Audit custom Webpack plugins/loaders for Vite equivalents.
   • Update php.ini if using PHP < 8.0 (not supported).

2. Installation:

   composer require pentatrion/vite-bundle
   npm install vite vite-plugin-symfony --save-dev
   

   • Use the Symfony Flex recipe for auto-configuration.

3. Configuration:

   • Update vite.config.js to use named entry points (v1.x format):

     export default {
       plugins: [symfonyPlugin()],
       build: {
         rollupOptions: {
           input: {
             app: "./assets/app.js" // Named entry (no .js extension)
           }
         }
       }
     };
     

   • Add Vite routes in config/routes/dev/pentatrion_vite.yaml (auto-generated by recipe).

4. Template Updates: Replace Twig tags:

   {% block stylesheets %}
     {{ vite_entry_link_tags('app') }}  {# Instead of encore_entry_link_tags #}
   {% endblock %}
   

5. Post-Migration:

   • Test HMR (npm run dev) and production builds (npm run build).
   • Verify legacy browser support (if needed) via nomodule scripts.
   • Update CI/CD to run npm run build and copy assets to public/build/.

Compatibility

• Symfony Features:
  • AssetMapper: Works with Symfony’s AssetMapper for versioned URLs.
  • Debug Toolbar: Integrates with Symfony Profiler (v7.0.0+).
  • Cache: Supports Symfony’s cache system for asset manifests.
• Edge Cases:
  • Custom Asset Directories: Requires outDir config in vite.config.js if assets aren’t in public/build/.
  • Multiple Vite Configs: Supported via configs key (see changelog v6.4.3).
  • Docker/HTTPS: May need symfony-cli for HTTPS dev server (see docs).

Sequencing

1. Phase 1: CSS Migration

   • Start with CSS-only entry points to validate Twig integration.
   • Use vite_entry_link_tags for stylesheets.

2. Phase 2: JavaScript Migration

   • Migrate JS entry points, testing HMR and Stimulus controllers.
   • Replace encore_entry_script_tags with vite_entry_script_tags.

3. Phase 3: Framework-Specific

   • For Stimulus: Test HMR and controller registration.
   • For React/Vue: Ensure Symfony UX compatibility (e.g., symfony/ux-react).

4. Phase 4: Production Rollout

   • Test npm run build and asset caching.
   • Monitor performance (bundle sizes, load times).

Operational Impact

Maintenance

• Dependency Updates:
  • Vite and vite-plugin-symfony updates are frequent (e.g., Vite 6/7 support in v8.2.0). Teams should monitor the changelog.
  • Symfony Flex recipes simplify updates but may require composer update for bundle changes.
• Debugging:
  • HMR Issues: Stimulus HMR may need controllersDir config (see changelog v8.0.0).
  • Asset Loading: Use Symfony’s profiler or browser dev tools to check for 404s (common if outDir is misconfigured).
• Long-Term Support:
  • The bundle is actively maintained (MIT license,