Sourcemap Laravel Package

Technical Evaluation

Architecture Fit

• Core Use Case Alignment: The package excels in source map manipulation—a niche but critical need for build tools, debugging, and asset optimization pipelines. It aligns perfectly with Laravel’s asset compilation (e.g., Laravel Mix, Vite integration) where source maps are essential for debugging minified/transpiled assets.
• Laravel Ecosystem Synergy:
  • Asset Pipelines: Complements Laravel Mix/Vite by enabling advanced source map operations (e.g., merging, concatenation) during build processes.
  • Debugging Tools: Integrates with Laravel’s error pages (e.g., debugbar) to map stack traces back to original source files.
  • Third-Party Tools: Supports plugins like laravel-mix-sourcemaps or vite-plugin-laravel for enhanced source map handling.
• Non-Functional Fit:
  • Zero Runtime Overhead: Source map processing is deferred to build time (no runtime impact).
  • Stateless Operations: Ideal for CI/CD pipelines where source maps are generated/merged once.

Integration Feasibility

• PHP 8.1+ Compatibility: Laravel 9+ (PHP 8.1+) is fully supported, with no breaking changes expected.
• Dependency Isolation: Lightweight (no heavy dependencies) and self-contained, reducing risk of conflicts.
• Laravel Service Provider Pattern:
  • Can be bootstrapped as a service provider to register source map utilities globally.
  • Example:

    $this->app->singleton(SourceMapManager::class, function ($app) {
        return new SourceMapManager(base_path('source-maps'));
    });
    

• Artisan Command Integration:
  • Expose CLI commands for manual source map operations (e.g., php artisan sourcemap:merge).
  • Example:

    Artisan::command('sourcemap:merge', function () {
        $map = SourceMap::loadFromFile(storage_path('app/intermediate.map'));
        $map->merge(storage_path('app/original.map'));
        $map->save(storage_path('app/merged.map'));
    });
    

Technical Risk

Key Questions for TPM

1. Build Tool Strategy:

   • Should this replace Laravel Mix/Vite’s built-in source map handling, or act as a complementary layer?
   • Example: Use axy/sourcemap for post-processing (e.g., merging vendor + app source maps).

2. Debugging Workflow:

   • How will this integrate with Laravel’s debugbar or laravel-debugbar for stack trace mapping?
   • Proposal: Add a SourceMapResolver middleware to translate errors to original source files.

3. CI/CD Pipeline:

   • Should source map merging be automated (e.g., in deploy.php) or manual (e.g., via Artisan)?
   • Example: Merge vendor/source maps in deploy:post hook.

4. User Experience:

   • Should developers interact with source maps via Artisan commands, config files, or API classes?
   • Proposal: Hybrid approach—CLI for ops, API for custom logic.

5. Testing Scope:

   • What source map formats/versions must be supported? (Prioritize V3 + V4.)
   • Should tests include edge cases (e.g., malformed maps, circular dependencies)?

Integration Approach

Stack Fit

Migration Path

1. Phase 1: Proof of Concept (2 weeks)

   • Integrate axy/sourcemap into a single Laravel project (e.g., a monorepo with Mix/Vite).
   • Test concatenation and merging workflows.
   • Benchmark performance vs. existing tools (e.g., source-map npm package).

2. Phase 2: Core Integration (3 weeks)

   • Build a Laravel package (laravel-sourcemap) wrapping axy/sourcemap.
   • Add Artisan commands, config options, and debugbar integration.
   • Publish to Packagist for community feedback.

3. Phase 3: Ecosystem Adoption (Ongoing)

   • Partner with Laravel Mix/Vite plugins to adopt the package.
   • Add CI/CD templates (e.g., GitHub Actions workflows for source map merging).
   • Document best practices (e.g., when to merge vs. concatenate).

Compatibility

Sequencing

1. Prerequisite: Ensure the project uses Laravel 9+ (PHP 8.1+) and has a build tool (Mix/Vite).
2. Step 1: Install the package:

   composer require axy/sourcemap
   

3. Step 2: Configure storage paths in .env:

   SOURCE_MAPS_PATH=storage/app/source-maps
   

4. Step 3: Register the service provider in config/app.php:

   'providers' => [
       // ...
       axy\sourcemap\Laravel\ServiceProvider::class,
   ],
   

5. Step 4: Publish config and assets:

   php artisan vendor:publish --provider="axy\sourcemap\Laravel\ServiceProvider"
   

6. Step 5: Integrate with build tools (e.g., Vite):

   // vite.config.js
   import { defineConfig } from 'vite';
   import laravel from 'laravel-vite-plugin';
   import { mergeSourceMaps } from 'laravel-sourcemap';
   
   export default defineConfig({
       plugins: [
           laravel({
               input: ['resources/js/app.js'],
               refresh: true,
           }),
       ],
       build: {
           onEnd: async () => {
               await mergeSourceMaps([
                   'dist/assets/app.js.map',
                   'dist/assets/vendor.js.map',
               ]);
           },
       },
   });
   

Operational Impact

Maintenance

• Package Updates:
  • Monitor axy/sourcemap for breaking changes (MIT license allows forks if needed).
  • Test updates against Laravel’s minor versions (e.g., Laravel 10 + PHP 8.2).
• Dependency Management:
  • Pin version in