Add renderStylePreloads method and corresponding Twig function for CSS preload hints

- Implemented renderStylePreloads in ViteManifest to generate <link rel="preload" as="style"> tags for CSS files.
- Added vite_css_preload Twig function to utilize the new method.
- Updated README and CHANGELOG to reflect these changes.
- Added tests for style preload functionality and ensured compatibility with existing features.

Author: lcharette

CHANGELOG.md

@@ -4,6 +4,11 @@ All notable changes to this project will be documented in this file.
 
 The format is based on [Keep a Changelog](http://keepachangelog.com/en/1.0.0/) and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.html).
 
+## 1.2.0
+- Fix `getStyle()` silently dropping the standalone `.css` output file when a chunk also has a `css[]` array (assignment was overwriting instead of merging)
+- Add `renderStylePreloads()` method to `ViteManifest` and `ViteManifestInterface` to emit `<link rel="preload" as="style">` hints for CSS files
+- Add `vite_css_preload()` Twig function backed by `renderStylePreloads()`
+
 ## 1.1.0
 - Support CSS standalone file by [@imagoiq](https://github.com/imagoiq) in [#1](https://github.com/userfrosting/vite-php-twig/pull/1)
 - Add PHP 8.4 Tests

README.md

@@ -30,9 +30,10 @@ $manifest->getStyles('views/foo.js'); // Styles
 $manifest->getImports('views/foo.js'); // Preloads
 
 // Render HTML tags for `views/foo.js` entry
-$manifest->renderScripts('views/foo.js'); // Scripts
-$manifest->renderStyles('views/foo.js'); // Styles
-$manifest->renderPreloads('views/foo.js'); // Preloads
+$manifest->renderScripts('views/foo.js');      // Scripts
+$manifest->renderStyles('views/foo.js');       // Styles
+$manifest->renderPreloads('views/foo.js');     // JS module preloads
+$manifest->renderStylePreloads('views/foo.js'); // CSS preload hints
 
 // If you have multiple entry point scripts on the same page, you should pass them in a single call to avoid duplicates - for example:
 $manifest->getScripts('views/foo.js', 'views/bar.js');
@@ -68,8 +69,14 @@ Now, to render all of the `script` and `link` tags for a specific "entry" (e.g.
 {{ vite_js('views/foo.js') }}
 {{ vite_css('views/foo.js') }}
 {{ vite_preload('views/foo.js') }}
+{{ vite_css_preload('views/foo.js') }}
 ```
 
+- `vite_js` — renders `<script type="module">` tags for the entry's JS files.
+- `vite_css` — renders `<link rel="stylesheet">` tags for the entry's CSS files.
+- `vite_preload` — renders `<link rel="modulepreload">` hints for eagerly fetching imported JS chunks.
+- `vite_css_preload` — renders `<link rel="preload" as="style">` hints so the browser discovers CSS files earlier, even though `vite_css` already adds the `<link rel="stylesheet">` tags.
+
 If you have multiple entry point scripts on the same page, you should pass them in a single call to avoid duplicates - for example:
 ```twig
 {{ vite_js('views/foo.js', 'views/bar.js') }}

src/ViteManifest.php

@@ -123,6 +123,31 @@ public function renderPreloads(string ...$entries): string
         return implode('', $tags);
     }
 
+    /**
+     * Fetches the style files from the manifest for the specified entries and
+     * returns them as HTML style preload hints. If the dev server is used, no
+     * preloading tags are returned for CSS coming from JS chunks, since Vite
+     * injects those at runtime.
+     *
+     * @param string ...$entries
+     *
+     * @throws JsonException               If manifest can't be read
+     * @throws EntrypointNotFoundException If an entry point is not found in the
+     *                                     manifest.
+     *
+     * @return string The CSS preload tags
+     */
+    public function renderStylePreloads(string ...$entries): string
+    {
+        $styles = $this->getStyles(...$entries);
+
+        $tags = array_map(function (string $file) {
+            return $this->renderStylePreload($file);
+        }, $styles);
+
+        return implode('', $tags);
+    }
+
     /**
      * Fetches and returns all script files for the specified entry points, or
      * the server config if development server is activated.
@@ -273,7 +298,7 @@ protected function getStyle(string $entry): array
 
         // Add entry point chunk's css list
         if (array_key_exists('css', $chunk)) {
-            $files = $chunk['css'];
+            $files = array_merge($files, $chunk['css']);
         }
 
         // Recursively follow all chunks in the entry point's imports list
@@ -428,6 +453,21 @@ protected function renderPreload(string $fileName): string
         );
     }
 
+    /**
+     * Return style preload tag for specified filename.
+     *
+     * @param string $fileName
+     *
+     * @return string
+     */
+    protected function renderStylePreload(string $fileName): string
+    {
+        return sprintf(
+            '<link rel="preload" as="style" href="%s" />',
+            $fileName
+        );
+    }
+
     /**
      * Prefixes a file name with either the dev server URL or the base path,
      * depending on whether the dev server is used or not.

src/ViteManifestInterface.php

@@ -50,6 +50,18 @@ public function renderStyles(string ...$entries): string;
      */
     public function renderPreloads(string ...$entries): string;
 
+    /**
+     * Fetches the style files from the manifest for the specified entries and
+     * returns them as HTML style preload hints. If the dev server is used, no
+     * preloading tags are returned for CSS coming from JS chunks, since Vite
+     * injects those at runtime.
+     *
+     * @param string ...$entries
+     *
+     * @return string The CSS preload tags
+     */
+    public function renderStylePreloads(string ...$entries): string;
+
     /**
      * Fetches and returns all script files for the specified entry points, or
      * the server config if development server is activated.

src/ViteTwigExtension.php

@@ -22,6 +22,7 @@
  * - vite_js(string $entryName)
  * - vite_css(string $entryName)
  * - vite_preload(string $entryName)
+ * - vite_css_preload(string $entryName)
  *
  * @see https://vitejs.dev/guide/backend-integration
  */
@@ -44,6 +45,7 @@ public function getFunctions(): array
             new TwigFunction('vite_js', [$this->manifest, 'renderScripts'], ['is_safe' => ['html']]),
             new TwigFunction('vite_css', [$this->manifest, 'renderStyles'], ['is_safe' => ['html']]),
             new TwigFunction('vite_preload', [$this->manifest, 'renderPreloads'], ['is_safe' => ['html']]),
+            new TwigFunction('vite_css_preload', [$this->manifest, 'renderStylePreloads'], ['is_safe' => ['html']]),
         ];
     }
 }

tests/ViteManifestTest.php

@@ -284,4 +284,51 @@ public function testPreloadTags(): void
         $result = $manifest->renderPreloads('views/bar.js');
         $this->assertSame(implode('', $expected), $result);
     }
+
+    // Bug 1 — getStyle() must not drop the standalone .css file when css[] is also present
+    public function testGetStylesWithStandaloneAndCssArray(): void
+    {
+        $manifest = new ViteManifest($this->manifestFile);
+
+        $this->assertSame(
+            ['assets/mixed-standalone.css', 'assets/mixed-extra.css'],
+            $manifest->getStyles('views/mixed.js')
+        );
+    }
+
+    // Bug 2 — renderStylePreloads() must emit <link rel="preload" as="style"> tags
+    public function testStylePreloadTags(): void
+    {
+        $manifest = new ViteManifest($this->manifestFile);
+
+        // views/foo.js has css[] and an import that also has css[]
+        $expected = implode('', [
+            '<link rel="preload" as="style" href="assets/foo-5UjPuW-k.css" />',
+            '<link rel="preload" as="style" href="assets/shared-ChJ_j-JJ.css" />',
+        ]);
+        $this->assertSame($expected, $manifest->renderStylePreloads('views/foo.js'));
+
+        // views/bar.js inherits css only via its import
+        $expected = '<link rel="preload" as="style" href="assets/shared-ChJ_j-JJ.css" />';
+        $this->assertSame($expected, $manifest->renderStylePreloads('views/bar.js'));
+
+        // Entry with both standalone .css file and css[] must include both
+        $expected = implode('', [
+            '<link rel="preload" as="style" href="assets/mixed-standalone.css" />',
+            '<link rel="preload" as="style" href="assets/mixed-extra.css" />',
+        ]);
+        $this->assertSame($expected, $manifest->renderStylePreloads('views/mixed.js'));
+    }
+
+    public function testStylePreloadTagsDevServer(): void
+    {
+        $manifest = new ViteManifest(
+            manifestPath: $this->manifestFile,
+            devEnabled: true,
+        );
+
+        // In dev mode getStyles() returns no CSS for JS entries, so no preload tags
+        $this->assertSame('', $manifest->renderStylePreloads('views/foo.js'));
+        $this->assertSame('', $manifest->renderStylePreloads('views/bar.js'));
+    }
 }

tests/ViteTwigExtensionTest.php

@@ -113,6 +113,27 @@ public function testPreloadTags(): void
         $this->assertSame(implode('', $expected), $result);
     }
 
+    public function testCssPreloadTags(): void
+    {
+        // views/foo.js
+        $expected = implode('', [
+            '<link rel="preload" as="style" href="assets/foo-5UjPuW-k.css" />',
+            '<link rel="preload" as="style" href="assets/shared-ChJ_j-JJ.css" />',
+        ]);
+        $this->assertSame($expected, $this->twig->createTemplate("{{ vite_css_preload('views/foo.js') }}")->render());
+
+        // views/bar.js
+        $expected = '<link rel="preload" as="style" href="assets/shared-ChJ_j-JJ.css" />';
+        $this->assertSame($expected, $this->twig->createTemplate("{{ vite_css_preload('views/bar.js') }}")->render());
+
+        // Entry with both standalone .css file and css[] must include both
+        $expected = implode('', [
+            '<link rel="preload" as="style" href="assets/mixed-standalone.css" />',
+            '<link rel="preload" as="style" href="assets/mixed-extra.css" />',
+        ]);
+        $this->assertSame($expected, $this->twig->createTemplate("{{ vite_css_preload('views/mixed.js') }}")->render());
+    }
+
     public function testDevServer(): void
     {
         $manifest = new ViteManifest(
@@ -142,5 +163,6 @@ public function testDevServer(): void
         // No styles or imports
         $this->assertSame('', $twig->createTemplate("{{ vite_css('views/foo.js') }}")->render());
         $this->assertSame('', $twig->createTemplate("{{ vite_preload('views/bar.js') }}")->render());
+        $this->assertSame('', $twig->createTemplate("{{ vite_css_preload('views/foo.js') }}")->render());
     }
 }

tests/manifests/manifest.json

@@ -49,5 +49,11 @@
         "file": "standalone-DEF.css",
         "src": "standalone.less",
         "isEntry": true
+    },
+    "views/mixed.js": {
+        "file": "assets/mixed-standalone.css",
+        "src": "views/mixed.js",
+        "isEntry": true,
+        "css": ["assets/mixed-extra.css"]
     }
 }