Merge pull request #62 from inpsyde/feature/wp-modules-and-webpack-autoloader

Chrico · web-flow · commit a8a8ba88ebc1 · 2025-10-30T15:02:36.000+01:00
WebPack Loader Script Modules Support
diff --git a/docs/loaders.md b/docs/loaders.md
@@ -24,6 +24,9 @@ The [webpack-manifest-plugin](https://www.npmjs.com/package/webpack-manifest-plu
 ```json
 {
     "script.js": "/public/path/script.23dafsf2138d.js",
+    "module.mjs": "/public/path/module.12aafrf5675d.mjs",
+    "custom.module.js": "/public/path/custom.12aafrf5675d.module.js",
+    "@vendor/module.js" "/public/path/@vendor/module.js",
     "style.css": "style.23dafsf2138d.css",
     "sub-folder/style.css": ""
 }
@@ -52,6 +55,14 @@ $loader->withDirectoryUrl('www.example.com/path/to/assets/');
 $assets = $loader->load('manifest.json');
 ```
 
+The loader does support scripts modules, files with the `.mjs` extension. 
+
+However, due to the limitations imposed on those files in regard to the MIME, we added a support to those files ending with `.module.js`.
+This permits us to load those files as script modules too even if we do not have control over the server configuration.
+
+Moreover, if your file ends with `.module.js` or `.mjs`, the loader will automatically resolve these files as a `Inpsyde/Assets/ScriptModule`.
+Additionally, we support `@vendor/` in the handle name when parsing from `manifest.json`. Before, the `@vendor/` was detected as part of the filepath and being stripped away.
+
 ### `EncoreEntrypointsLoader`
 
 [Symfony Webpack Encore](https://symfony.com/doc/current/frontend.html) provides a custom implementation of the [assets-webpack-plugin](https://www.npmjs.com/package/assets-webpack-plugin) which groups asset chunks into a single array for a given handle.
diff --git a/src/Loader/AbstractWebpackLoader.php b/src/Loader/AbstractWebpackLoader.php
@@ -10,6 +10,7 @@
 use Inpsyde\Assets\Exception\FileNotFoundException;
 use Inpsyde\Assets\Exception\InvalidResourceException;
 use Inpsyde\Assets\Script;
+use Inpsyde\Assets\ScriptModule;
 use Inpsyde\Assets\Style;
 
 abstract class AbstractWebpackLoader implements LoaderInterface
@@ -110,20 +111,27 @@ protected function buildAsset(string $handle, string $fileUrl, string $filePath)
         $extensionsToClass = [
             'css' => Style::class,
             'js' => Script::class,
+            'mjs' => ScriptModule::class,
+            'module.js' => ScriptModule::class,
         ];
 
         /** @var array{filename?:string, extension?:string} $pathInfo */
         $pathInfo = pathinfo($filePath);
+        $baseName = $pathInfo['basename'] ?? '';
         $filename = $pathInfo['filename'] ?? '';
         $extension = $pathInfo['extension'] ?? '';
 
+        if (self::isModule($baseName)) {
+            $extension = 'module.js';
+        }
+
         if (!in_array($extension, array_keys($extensionsToClass), true)) {
             return null;
         }
 
         $class = $extensionsToClass[$extension];
 
-        /** @var Style|Script $asset */
+        /** @var Style|Script|ScriptModule $asset */
         $asset = new $class($handle, $fileUrl, $this->resolveLocation($filename));
         $asset->withFilePath($filePath);
         $asset->canEnqueue(true);
@@ -137,6 +145,15 @@ protected function buildAsset(string $handle, string $fileUrl, string $filePath)
         return $asset;
     }
 
+    protected static function isModule(string $fileName): bool
+    {
+        // TODO replace it with `str_ends_with` once dropping support for php 7.4
+        $strEndsWith = static function (string $haystack, string $needle): bool {
+            return substr_compare($haystack, $needle, -strlen($needle)) === 0;
+        };
+        return $strEndsWith($fileName, '.module.js') || $strEndsWith($fileName, '.mjs');
+    }
+
     /**
      * The "file"-value can contain:
      *  - URL
@@ -159,6 +176,34 @@ protected function sanitizeFileName(string $file): string
         return ltrim($parsedUrl['path'] ?? $file, './');
     }
 
+    /**
+     * Internal function to sanitize the handle based on the file
+     * by taking into consideration that @vendor can be present.
+     *
+     * @param string $file
+     *
+     * @return string
+     * @example /path/to/@vendor/script.module.js   -> @vendor/script.module
+     *
+     * @example /path/to/script.js                  -> script
+     * @example @vendor/script.module.js            -> @vendor/script.module
+     */
+    protected function sanitizeHandle(string $file): string
+    {
+        $pathInfo = pathinfo($file);
+
+        $dirName = $pathInfo['dirname'] ?? '';
+        $parts = explode('@', $dirName);
+        $vendor = $parts[1] ?? null;
+
+        $handle = $pathInfo['filename'];
+        if ($vendor !== null) {
+            $handle = "@{$vendor}/{$handle}";
+        }
+
+        return $handle;
+    }
+
     /**
      * Internal function to resolve a location for a given file name.
      *
diff --git a/src/Loader/WebpackManifestLoader.php b/src/Loader/WebpackManifestLoader.php
@@ -18,9 +18,7 @@ protected function parseData(array $data, string $resource): array
         $directory = trailingslashit(dirname($resource));
         $assets = [];
         foreach ($data as $handle => $file) {
-            // It can be possible, that the "handle"-key is a filepath.
-            $handle = pathinfo($handle, PATHINFO_FILENAME);
-
+            $handle = $this->sanitizeHandle($handle);
             $sanitizedFile = $this->sanitizeFileName($file);
 
             $fileUrl = (!$this->directoryUrl)
diff --git a/tests/phpunit/Unit/Loader/AbstractWebpackLoaderTest.php b/tests/phpunit/Unit/Loader/AbstractWebpackLoaderTest.php
@@ -9,6 +9,7 @@
 use Inpsyde\Assets\Exception\InvalidResourceException;
 use Inpsyde\Assets\Loader\AbstractWebpackLoader;
 use Inpsyde\Assets\Script;
+use Inpsyde\Assets\ScriptModule;
 use Inpsyde\Assets\Style;
 use Inpsyde\Assets\Tests\Unit\AbstractTestCase;
 use org\bovigo\vfs\vfsStream;
@@ -104,6 +105,64 @@ public function resolveLocation(string $fileName): int
         static::assertSame($expectedLocation, $loader->resolveLocation($inputFile));
     }
 
+    public function testBuildModulesAssets(): void
+    {
+        vfsStream::newFile('assets/my.mjs')
+            ->withContent('console.log("Hello, World!");')
+            ->at($this->root);
+
+        $handle = 'asset-handle';
+        $fileUrl = 'https://example.com/assets/my.mjs';
+        $filePath = vfsStream::url('tmp/assets/my.module.mjs');
+
+        $loader = new class extends AbstractWebpackLoader {
+            protected function parseData(array $data, string $resource): array
+            {
+                return [];
+            }
+
+            public function buildAsset(string $handle, string $fileUrl, string $filePath): ?Asset
+            {
+                return parent::buildAsset($handle, $fileUrl, $filePath);
+            }
+        };
+
+        $asset = $loader->buildAsset($handle, $fileUrl, $filePath);
+
+        $this->assertInstanceOf(ScriptModule::class, $asset);
+        $this->assertSame($handle, $asset->handle());
+        $this->assertSame($fileUrl, $asset->url());
+    }
+
+    public function testBuildCustomModulesAssets(): void
+    {
+        vfsStream::newFile('assets/my.module.js')
+            ->withContent('console.log("Hello, World!");')
+            ->at($this->root);
+
+        $handle = 'asset-handle';
+        $fileUrl = 'https://example.com/assets/my.module.js';
+        $filePath = vfsStream::url('tmp/assets/my.module.js');
+
+        $loader = new class extends AbstractWebpackLoader {
+            protected function parseData(array $data, string $resource): array
+            {
+                return [];
+            }
+
+            public function buildAsset(string $handle, string $fileUrl, string $filePath): ?Asset
+            {
+                return parent::buildAsset($handle, $fileUrl, $filePath);
+            }
+        };
+
+        $asset = $loader->buildAsset($handle, $fileUrl, $filePath);
+
+        $this->assertInstanceOf(ScriptModule::class, $asset);
+        $this->assertSame($handle, $asset->handle());
+        $this->assertSame($fileUrl, $asset->url());
+    }
+
     /**
      * @return \Generator
      */
diff --git a/tests/phpunit/Unit/Loader/WebpackManifestLoaderTest.php b/tests/phpunit/Unit/Loader/WebpackManifestLoaderTest.php
@@ -7,6 +7,7 @@
 use Inpsyde\Assets\Asset;
 use Inpsyde\Assets\Loader\WebpackManifestLoader;
 use Inpsyde\Assets\Script;
+use Inpsyde\Assets\ScriptModule;
 use Inpsyde\Assets\Style;
 use Inpsyde\Assets\Tests\Unit\AbstractTestCase;
 use org\bovigo\vfs\vfsStream;
@@ -37,10 +38,10 @@ public function testLoadFromManifest(
         string $expectedHandle,
         string $expectedFileName,
         string $expectedClass
-    ): void {
-
+    ): void
+    {
         $expectedDirUrl = 'http://localhost.com/assets/';
-        $expectedFileUrl = $expectedDirUrl . $expectedFileName;
+        $expectedFileUrl = $expectedDirUrl . ltrim($expectedFileName, '/');
 
         $loader = new WebpackManifestLoader();
         $loader->withDirectoryUrl($expectedDirUrl);
@@ -64,14 +65,20 @@ public function testLoadFromManifestMultipleAssets(): void
             [
                 'script' => 'script.js',
                 'style' => 'style.css',
+                'module' => 'module.mjs',
+                'custom-module' => 'custom.module.js',
+                '@vendor/module' => 'vendor.module.js',
             ]
         );
 
         $loader = new WebpackManifestLoader();
         $assets = $loader->load($this->mockManifestJson($json));
 
-        static::assertCount(2, $assets);
+        static::assertCount(5, $assets);
 
+        static::assertInstanceOf(ScriptModule::class, $assets[4]);
+        static::assertInstanceOf(ScriptModule::class, $assets[3]);
+        static::assertInstanceOf(ScriptModule::class, $assets[2]);
         static::assertInstanceOf(Script::class, $assets[0]);
         static::assertInstanceOf(Style::class, $assets[1]);
     }
@@ -102,8 +109,8 @@ public function testLoadFromManifestWithAlternativeUrl(
         string $json,
         string $alternativeUrl,
         string $expectedUrl
-    ): void {
-
+    ): void
+    {
         $loader = new WebpackManifestLoader();
         $loader->withDirectoryUrl($alternativeUrl);
         $assets = $loader->load($this->mockManifestJson($json));
@@ -197,10 +204,32 @@ public function provideManifest(): \Generator
             'sub-folder/script.js',
             Script::class,
         ];
+
+        yield 'with @vendor in handle for modules' => [
+            '{"@vendor/script.module.js": "script.module.js"}',
+            '@vendor/script.module',
+            'script.module.js',
+            ScriptModule::class,
+        ];
+
+        yield 'with @vendor in handle for modules and file path' => [
+            '{"@vendor/script.module.js": "/path/to/script.module.js"}',
+            '@vendor/script.module',
+            '/path/to/script.module.js',
+            ScriptModule::class,
+        ];
+
+        yield 'with complex @vendor in handle for modules and file path' => [
+            '{"path/to/@vendor/script.module.js": "/path/to/script.module.js"}',
+            '@vendor/script.module',
+            '/path/to/script.module.js',
+            ScriptModule::class,
+        ];
     }
 
     /**
      * @param string $json
+     *
      * @return string
      */
     private function mockManifestJson(string $json): string
