From 94e4f15ff4ef95672dc534fec117364fe062a77b Mon Sep 17 00:00:00 2001
From: mscherer <dereuromark@web.de>
Date: Sun, 8 Mar 2026 08:44:44 +0100
Subject: [PATCH 1/4] Add support for inline output with block => false

When passing `block => false` option to script() or css() methods,
the helper now outputs tags directly instead of buffering to view blocks.

This is consistent with CakePHP's Html helper behavior and allows
for inline asset rendering in templates without using view blocks.

Changes:
- script(): Echo output when block is false, handle preload tags inline
- css(): Echo output when block is false
- addDependentCss(): Support inline parameter for dependent CSS

Fixes TypeError when passing block => false (previously crashed with
"Argument #1 ($name) must be of type string, false given").
---
 src/View/Helper/ViteHelper.php                |  38 ++++-
 tests/TestCase/View/Helper/ViteHelperTest.php | 143 ++++++++++++++++++
 2 files changed, 174 insertions(+), 7 deletions(-)

diff --git a/src/View/Helper/ViteHelper.php b/src/View/Helper/ViteHelper.php
index 52932ec..410fcc9 100644
--- a/src/View/Helper/ViteHelper.php
+++ b/src/View/Helper/ViteHelper.php
@@ -76,6 +76,9 @@ public function isDev(array|ViteConfig|null $config = null): bool
      *
      * Backwards compatible with ViteScriptsHelper::script()
      *
+     * When `block` option is `false`, outputs tags directly (inline).
+     * Otherwise appends to the specified view block.
+     *
      * @param array<string, mixed>|string $options Options or file shorthand
      * @param \CakeVite\ValueObject\ViteConfig|array<string, mixed>|null $config Configuration
      */
@@ -94,6 +97,7 @@ public function script(array|string $options = [], array|ViteConfig|null $config
 
         $block = $options['block'] ?? $config->scriptBlock;
         $cssBlock = $options['cssBlock'] ?? $config->cssBlock;
+        $inline = $block === false;
 
         $tags = $this->getAssetService()->generateScriptTags($config, $options);
 
@@ -103,16 +107,24 @@ public function script(array|string $options = [], array|ViteConfig|null $config
                 // Render preload tags as <link rel="modulepreload" href="...">
                 $preloadType = $tag->preloadType ?? 'modulepreload';
                 $linkTag = $this->buildPreloadLinkTag($preloadType, $tag->url, $tag->attributes);
-                $this->getView()->append($block, $linkTag);
+                if ($inline) {
+                    echo $linkTag;
+                } else {
+                    $this->getView()->append($block, $linkTag);
+                }
             } else {
                 // Render regular script tags
-                $this->Html->script($tag->url, array_merge(['block' => $block], $tag->attributes));
+                // When block is false, Html::script() returns the tag string
+                $scriptTag = $this->Html->script($tag->url, array_merge(['block' => $block], $tag->attributes));
+                if ($inline && $scriptTag !== null) {
+                    echo $scriptTag;
+                }
             }
         }
 
         // Add dependent CSS if in production
         if (!$this->isDev($config)) {
-            $this->addDependentCss($config, $options, $cssBlock);
+            $this->addDependentCss($config, $options, $cssBlock, $inline);
         }
     }
 
@@ -121,6 +133,9 @@ public function script(array|string $options = [], array|ViteConfig|null $config
      *
      * Backwards compatible with ViteScriptsHelper::css()
      *
+     * When `block` option is `false`, outputs tags directly (inline).
+     * Otherwise appends to the specified view block.
+     *
      * @param array<string, mixed>|string $options Options or file shorthand
      * @param \CakeVite\ValueObject\ViteConfig|array<string, mixed>|null $config Configuration
      */
@@ -132,11 +147,16 @@ public function css(array|string $options = [], array|ViteConfig|null $config =
         $config = $this->resolveConfig($config);
 
         $block = $options['block'] ?? $config->cssBlock;
+        $inline = $block === false;
 
         $tags = $this->getAssetService()->generateStyleTags($config, $options);
 
         foreach ($tags as $tag) {
-            $this->Html->css($tag->url, array_merge(['block' => $block], $tag->attributes));
+            // When block is false, Html::css() returns the tag string
+            $cssTag = $this->Html->css($tag->url, array_merge(['block' => $block], $tag->attributes));
+            if ($inline && $cssTag !== null) {
+                echo $cssTag;
+            }
         }
     }
 
@@ -271,9 +291,10 @@ private function extractConfigFromOptions(
      *
      * @param \CakeVite\ValueObject\ViteConfig $config Configuration
      * @param array<string, mixed> $options Options
-     * @param string $cssBlock CSS block name
+     * @param string|false $cssBlock CSS block name or false for inline output
+     * @param bool $inline Whether to output inline (when block is false)
      */
-    private function addDependentCss(ViteConfig $config, array $options, string $cssBlock): void
+    private function addDependentCss(ViteConfig $config, array $options, string|false $cssBlock, bool $inline = false): void
     {
         $manifestService = new ManifestService();
         $manifest = $manifestService->load($config);
@@ -288,7 +309,10 @@ private function addDependentCss(ViteConfig $config, array $options, string $css
 
         foreach ($entries as $entry) {
             foreach ($entry->getDependentCssUrls() as $cssUrl) {
-                $this->Html->css($pluginPrefix . $cssUrl, ['block' => $cssBlock]);
+                $cssTag = $this->Html->css($pluginPrefix . $cssUrl, ['block' => $cssBlock]);
+                if ($inline && $cssTag !== null) {
+                    echo $cssTag;
+                }
             }
         }
     }
diff --git a/tests/TestCase/View/Helper/ViteHelperTest.php b/tests/TestCase/View/Helper/ViteHelperTest.php
index f9c806e..4669ab7 100644
--- a/tests/TestCase/View/Helper/ViteHelperTest.php
+++ b/tests/TestCase/View/Helper/ViteHelperTest.php
@@ -727,4 +727,147 @@ public function testBuildPreloadLinkTagEscapesSpecialCharacters(): void
         $this->assertStringNotContainsString('<script>', $result);
         $this->assertStringContainsString('&lt;script&gt;', $result);
     }
+
+    /**
+     * Test script method with block => false outputs inline
+     */
+    public function testScriptWithBlockFalseOutputsInline(): void
+    {
+        $config = [
+            'devServer' => [
+                'url' => 'http://localhost:3000',
+                'hostHints' => ['localhost'],
+                'entries' => ['script' => ['src/app.ts']],
+            ],
+        ];
+
+        ob_start();
+        $this->Vite->script(['files' => ['src/app.ts'], 'block' => false], $config);
+        $output = ob_get_clean();
+
+        // Should output directly instead of buffering to view block
+        $this->assertStringContainsString('http://localhost:3000/@vite/client', $output);
+        $this->assertStringContainsString('http://localhost:3000/src/app.ts', $output);
+        $this->assertStringContainsString('type="module"', $output);
+
+        // View block should be empty
+        $this->assertEmpty($this->View->fetch('script'));
+    }
+
+    /**
+     * Test script method with block => false in production mode
+     */
+    public function testScriptWithBlockFalseInProductionMode(): void
+    {
+        $config = [
+            'forceProductionMode' => true,
+            'build' => [
+                'manifestPath' => TESTS . 'Fixture' . DS . 'manifest.json',
+            ],
+        ];
+
+        ob_start();
+        $this->Vite->script(['files' => ['src/app.ts'], 'block' => false], $config);
+        $output = ob_get_clean();
+
+        // Should output directly
+        $this->assertStringContainsString('assets/app-abc123.js', $output);
+        $this->assertStringNotContainsString('localhost', $output);
+
+        // View block should be empty
+        $this->assertEmpty($this->View->fetch('script'));
+    }
+
+    /**
+     * Test css method with block => false outputs inline
+     */
+    public function testCssWithBlockFalseOutputsInline(): void
+    {
+        $config = [
+            'devServer' => [
+                'url' => 'http://localhost:3000',
+                'hostHints' => ['localhost'],
+                'entries' => ['style' => ['src/style.css']],
+            ],
+        ];
+
+        ob_start();
+        $this->Vite->css(['files' => ['src/style.css'], 'block' => false], $config);
+        $output = ob_get_clean();
+
+        // Should output directly
+        $this->assertStringContainsString('http://localhost:3000/src/style.css', $output);
+
+        // View block should be empty
+        $this->assertEmpty($this->View->fetch('css'));
+    }
+
+    /**
+     * Test css method with block => false in production mode
+     */
+    public function testCssWithBlockFalseInProductionMode(): void
+    {
+        $config = [
+            'forceProductionMode' => true,
+            'build' => [
+                'manifestPath' => TESTS . 'Fixture' . DS . 'manifest.json',
+            ],
+        ];
+
+        ob_start();
+        $this->Vite->css(['files' => ['src/style.css'], 'block' => false], $config);
+        $output = ob_get_clean();
+
+        // Should output directly
+        $this->assertStringContainsString('assets/style-jkl012.css', $output);
+
+        // View block should be empty
+        $this->assertEmpty($this->View->fetch('css'));
+    }
+
+    /**
+     * Test script method with block => false outputs preload tags inline
+     */
+    public function testScriptWithBlockFalseOutputsPreloadTagsInline(): void
+    {
+        $config = [
+            'build' => ['manifestPath' => TESTS . 'Fixture' . DS . 'manifest-with-imports.json'],
+            'preload' => 'link-tag',
+            'forceProductionMode' => true,
+        ];
+
+        ob_start();
+        $this->Vite->script(['files' => ['src/app.ts'], 'block' => false], $config);
+        $output = ob_get_clean();
+
+        // Preload tags should be output directly
+        $this->assertStringContainsString('modulepreload', $output);
+        $this->assertStringContainsString('<link rel="modulepreload"', $output);
+
+        // View block should be empty
+        $this->assertEmpty($this->View->fetch('script'));
+    }
+
+    /**
+     * Test script method with block => false outputs dependent CSS inline
+     */
+    public function testScriptWithBlockFalseOutputsDependentCssInline(): void
+    {
+        $config = [
+            'forceProductionMode' => true,
+            'build' => [
+                'manifestPath' => TESTS . 'Fixture' . DS . 'manifest.json',
+            ],
+        ];
+
+        ob_start();
+        $this->Vite->script(['files' => ['src/app.ts'], 'block' => false], $config);
+        $output = ob_get_clean();
+
+        // Dependent CSS should be output directly
+        $this->assertStringContainsString('assets/app-xyz789.css', $output);
+
+        // CSS view block should be empty
+        $this->assertEmpty($this->View->fetch('css'));
+    }
 }

From 675a3e02ec75d02454c8fcafb003cb5ae6c30fc0 Mon Sep 17 00:00:00 2001
From: mscherer <dereuromark@web.de>
Date: Sun, 8 Mar 2026 15:58:09 +0100
Subject: [PATCH 2/4] refactor: return ?string from script()/css() instead of
 echo

Change script() and css() methods to return the tag string when
block => false, instead of echoing directly. This is more consistent
with CakePHP's HtmlHelper conventions and makes the code easier to test.
---
 src/View/Helper/ViteHelper.php                | 51 +++++++++++++------
 tests/TestCase/View/Helper/ViteHelperTest.php | 42 +++++++--------
 2 files changed, 54 insertions(+), 39 deletions(-)

diff --git a/src/View/Helper/ViteHelper.php b/src/View/Helper/ViteHelper.php
index 03df3c2..eb2da78 100644
--- a/src/View/Helper/ViteHelper.php
+++ b/src/View/Helper/ViteHelper.php
@@ -77,13 +77,14 @@ public function isDev(array|ViteConfig|null $config = null): bool
      *
      * Backwards compatible with ViteScriptsHelper::script()
      *
-     * When `block` option is `false`, outputs tags directly (inline).
-     * Otherwise appends to the specified view block.
+     * When `block` option is `false`, returns the tags as a string for inline output.
+     * Otherwise appends to the specified view block and returns null.
      *
      * @param array<string, mixed>|string $options Options or file shorthand
      * @param \CakeVite\ValueObject\ViteConfig|array<string, mixed>|null $config Configuration
+     * @return string|null Returns tag string when block is false, null otherwise
      */
-    public function script(array|string $options = [], array|ViteConfig|null $config = null): void
+    public function script(array|string $options = [], array|ViteConfig|null $config = null): ?string
     {
         $options = $this->normalizeOptions($options);
         $config = $this->extractConfigFromOptions($options, $config);
@@ -102,6 +103,8 @@ public function script(array|string $options = [], array|ViteConfig|null $config
 
         $tags = $this->getAssetService()->generateScriptTags($config, $options);
 
+        $output = '';
+
         // Render tags (preload tags as link elements, script tags as script elements)
         foreach ($tags as $tag) {
             if ($tag->isPreload) {
@@ -109,7 +112,7 @@ public function script(array|string $options = [], array|ViteConfig|null $config
                 $preloadType = $tag->preloadType ?? 'modulepreload';
                 $linkTag = $this->buildPreloadLinkTag($preloadType, $tag->url, $tag->attributes);
                 if ($inline) {
-                    echo $linkTag;
+                    $output .= $linkTag;
                 } else {
                     $this->getView()->append($block, $linkTag);
                 }
@@ -118,15 +121,17 @@ public function script(array|string $options = [], array|ViteConfig|null $config
                 // When block is false, Html::script() returns the tag string
                 $scriptTag = $this->Html->script($tag->url, array_merge(['block' => $block], $tag->attributes));
                 if ($inline && $scriptTag !== null) {
-                    echo $scriptTag;
+                    $output .= $scriptTag;
                 }
             }
         }
 
         // Add dependent CSS if in production
         if (!$this->isDev($config)) {
-            $this->addDependentCss($config, $options, $cssBlock, $inline);
+            $output .= $this->addDependentCss($config, $options, $cssBlock, $inline);
         }
+
+        return $inline ? $output : null;
     }
 
     /**
@@ -134,13 +139,14 @@ public function script(array|string $options = [], array|ViteConfig|null $config
      *
      * Backwards compatible with ViteScriptsHelper::css()
      *
-     * When `block` option is `false`, outputs tags directly (inline).
-     * Otherwise appends to the specified view block.
+     * When `block` option is `false`, returns the tags as a string for inline output.
+     * Otherwise appends to the specified view block and returns null.
      *
      * @param array<string, mixed>|string $options Options or file shorthand
      * @param \CakeVite\ValueObject\ViteConfig|array<string, mixed>|null $config Configuration
+     * @return string|null Returns tag string when block is false, null otherwise
      */
-    public function css(array|string $options = [], array|ViteConfig|null $config = null): void
+    public function css(array|string $options = [], array|ViteConfig|null $config = null): ?string
     {
         $options = $this->normalizeOptions($options);
         $config = $this->extractConfigFromOptions($options, $config);
@@ -152,13 +158,17 @@ public function css(array|string $options = [], array|ViteConfig|null $config =
 
         $tags = $this->getAssetService()->generateStyleTags($config, $options);
 
+        $output = '';
+
         foreach ($tags as $tag) {
             // When block is false, Html::css() returns the tag string
             $cssTag = $this->Html->css($tag->url, array_merge(['block' => $block], $tag->attributes));
             if ($inline && $cssTag !== null) {
-                echo $cssTag;
+                $output .= $cssTag;
             }
         }
+
+        return $inline ? $output : null;
     }
 
     /**
@@ -293,10 +303,15 @@ private function extractConfigFromOptions(
      * @param \CakeVite\ValueObject\ViteConfig $config Configuration
      * @param array<string, mixed> $options Options
      * @param string|false $cssBlock CSS block name or false for inline output
-     * @param bool $inline Whether to output inline (when block is false)
+     * @param bool $inline Whether to return inline (when block is false)
+     * @return string Returns CSS tags when inline is true, empty string otherwise
      */
-    private function addDependentCss(ViteConfig $config, array $options, string|false $cssBlock, bool $inline = false): void
-    {
+    private function addDependentCss(
+        ViteConfig $config,
+        array $options,
+        string|false $cssBlock,
+        bool $inline = false,
+    ): string {
         $manifestService = new ManifestService();
         $manifest = $manifestService->load($config);
 
@@ -308,14 +323,20 @@ private function addDependentCss(ViteConfig $config, array $options, string|fals
         $entries = $manifest->filterEntries();
         $pluginPrefix = $config->pluginName ? $config->pluginName . '.' : '';
 
+        $output = '';
+
         foreach ($entries as $entry) {
             foreach ($entry->getDependentCssUrls() as $cssUrl) {
-                $cssTag = $this->Html->css($pluginPrefix . $cssUrl, ['block' => $cssBlock]);
+                // When inline, pass block => false to get the tag string; otherwise use the block name
+                $blockOption = $inline ? false : $cssBlock;
+                $cssTag = $this->Html->css($pluginPrefix . $cssUrl, ['block' => $blockOption]);
                 if ($inline && $cssTag !== null) {
-                    echo $cssTag;
+                    $output .= $cssTag;
                 }
             }
         }
+
+        return $output;
     }
 
     /**
diff --git a/tests/TestCase/View/Helper/ViteHelperTest.php b/tests/TestCase/View/Helper/ViteHelperTest.php
index 4669ab7..ff6c0a1 100644
--- a/tests/TestCase/View/Helper/ViteHelperTest.php
+++ b/tests/TestCase/View/Helper/ViteHelperTest.php
@@ -741,11 +741,10 @@ public function testScriptWithBlockFalseOutputsInline(): void
             ],
         ];
 
-        ob_start();
-        $this->Vite->script(['files' => ['src/app.ts'], 'block' => false], $config);
-        $output = ob_get_clean();
+        $output = $this->Vite->script(['files' => ['src/app.ts'], 'block' => false], $config);
 
-        // Should output directly instead of buffering to view block
+        // Should return tags directly instead of buffering to view block
+        $this->assertNotNull($output);
         $this->assertStringContainsString('http://localhost:3000/@vite/client', $output);
         $this->assertStringContainsString('http://localhost:3000/src/app.ts', $output);
         $this->assertStringContainsString('type="module"', $output);
@@ -766,11 +765,10 @@ public function testScriptWithBlockFalseInProductionMode(): void
             ],
         ];
 
-        ob_start();
-        $this->Vite->script(['files' => ['src/app.ts'], 'block' => false], $config);
-        $output = ob_get_clean();
+        $output = $this->Vite->script(['files' => ['src/app.ts'], 'block' => false], $config);
 
-        // Should output directly
+        // Should return tags directly
+        $this->assertNotNull($output);
         $this->assertStringContainsString('assets/app-abc123.js', $output);
         $this->assertStringNotContainsString('localhost', $output);
 
@@ -791,11 +789,10 @@ public function testCssWithBlockFalseOutputsInline(): void
             ],
         ];
 
-        ob_start();
-        $this->Vite->css(['files' => ['src/style.css'], 'block' => false], $config);
-        $output = ob_get_clean();
+        $output = $this->Vite->css(['files' => ['src/style.css'], 'block' => false], $config);
 
-        // Should output directly
+        // Should return tags directly
+        $this->assertNotNull($output);
         $this->assertStringContainsString('http://localhost:3000/src/style.css', $output);
 
         // View block should be empty
@@ -814,11 +811,10 @@ public function testCssWithBlockFalseInProductionMode(): void
             ],
         ];
 
-        ob_start();
-        $this->Vite->css(['files' => ['src/style.css'], 'block' => false], $config);
-        $output = ob_get_clean();
+        $output = $this->Vite->css(['files' => ['src/style.css'], 'block' => false], $config);
 
-        // Should output directly
+        // Should return tags directly
+        $this->assertNotNull($output);
         $this->assertStringContainsString('assets/style-jkl012.css', $output);
 
         // View block should be empty
@@ -836,11 +832,10 @@ public function testScriptWithBlockFalseOutputsPreloadTagsInline(): void
             'forceProductionMode' => true,
         ];
 
-        ob_start();
-        $this->Vite->script(['files' => ['src/app.ts'], 'block' => false], $config);
-        $output = ob_get_clean();
+        $output = $this->Vite->script(['files' => ['src/app.ts'], 'block' => false], $config);
 
-        // Preload tags should be output directly
+        // Preload tags should be returned directly
+        $this->assertNotNull($output);
         $this->assertStringContainsString('modulepreload', $output);
         $this->assertStringContainsString('<link rel="modulepreload"', $output);
 
@@ -860,11 +855,10 @@ public function testScriptWithBlockFalseOutputsDependentCssInline(): void
             ],
         ];
 
-        ob_start();
-        $this->Vite->script(['files' => ['src/app.ts'], 'block' => false], $config);
-        $output = ob_get_clean();
+        $output = $this->Vite->script(['files' => ['src/app.ts'], 'block' => false], $config);
 
-        // Dependent CSS should be output directly
+        // Dependent CSS should be returned directly
+        $this->assertNotNull($output);
         $this->assertStringContainsString('assets/app-xyz789.css', $output);
 
         // CSS view block should be empty

From 0003205ede874ab4c63991e4bd1273cdb376534a Mon Sep 17 00:00:00 2001
From: mscherer <dereuromark@web.de>
Date: Sun, 8 Mar 2026 16:39:35 +0100
Subject: [PATCH 3/4] docs: add inline output section for block => false

---
 README.md | 24 ++++++++++++++++++++++++
 1 file changed, 24 insertions(+)

diff --git a/README.md b/README.md
index 98c8f21..631f8a6 100644
--- a/README.md
+++ b/README.md
@@ -34,6 +34,7 @@ A [Vite.js](https://vitejs.dev/) integration for CakePHP 5.0+ applications. Seam
   - [Plugin Assets](#plugin-assets)
   - [Multiple Entry Points](#multiple-entry-points)
   - [Custom Attributes](#custom-attributes)
+  - [Inline Output](#inline-output)
   - [Preloading Assets](#preloading-assets)
   - [Caching](#caching)
   - [Multiple Configurations](#multiple-configurations)
@@ -487,6 +488,29 @@ $this->Vite->script([
 <?= $this->fetch('custom_scripts') ?>
 ```
 
+### Inline Output
+
+By default, `script()` and `css()` append tags to view blocks for rendering in layouts.
+Set `block => false` to return tags as a string for inline output:
+
+```php
+<?php
+// Output directly instead of buffering to view blocks
+echo $this->Vite->script(['files' => ['src/main.js'], 'block' => false]);
+echo $this->Vite->css(['files' => ['src/style.css'], 'block' => false]);
+?>
+```
+
+This is useful when you need to render assets directly in elements or partials:
+
+```php
+<!-- In an element file -->
+<?= $this->Vite->css(['files' => ['src/component.css'], 'block' => false]) ?>
+<div class="component">
+    <!-- Component content -->
+</div>
+```
+
 ### Preloading Assets
 
 CakeVite supports `modulepreload` to improve load times for applications with code splitting. Preloading hints to the browser which modules will be needed soon, allowing parallel downloads.

From 1608fc6d0b6aea529a383e6e0ec31c1d09119f2e Mon Sep 17 00:00:00 2001
From: mscherer <dereuromark@web.de>
Date: Sun, 8 Mar 2026 17:24:21 +0100
Subject: [PATCH 4/4] Deduplicate @vite/client in development mode and fix
 inline output edge cases

- Add viteClientRendered tracking to ViteHelper to prevent duplicate @vite/client output
- Update AssetService to support skipViteClient option
- Fix pluginScript/pluginCss to return ?string for inline mode (block => false)
- Fix addDependentCss to skip CSS when cssBlock is false and not in inline mode
- Add tests for deduplication and plugin inline output
- Document deduplication and cssBlock behavior in README
---
 README.md                                     |  23 +++
 src/Service/AssetService.php                  |  14 +-
 src/View/Helper/ViteHelper.php                |  40 +++-
 tests/TestCase/View/Helper/ViteHelperTest.php | 180 ++++++++++++++++++
 4 files changed, 245 insertions(+), 12 deletions(-)

diff --git a/README.md b/README.md
index 631f8a6..6e9cc63 100644
--- a/README.md
+++ b/README.md
@@ -511,6 +511,29 @@ This is useful when you need to render assets directly in elements or partials:
 </div>
 ```
 
+**Vite Client Deduplication:**
+
+In development mode, the `@vite/client` script is automatically deduplicated. Multiple `script()` calls (e.g., in layout, elements, components) will only output the Vite client once:
+
+```php
+// Layout
+<?php $this->Vite->script(['files' => ['src/app.js']]); ?>  <!-- Includes @vite/client -->
+
+// Element
+<?php $this->Vite->script(['files' => ['src/element.js']]); ?>  <!-- No duplicate client -->
+```
+
+**Disable Dependent CSS Injection:**
+
+In production mode, `script()` automatically injects dependent CSS from JS entries. Use `cssBlock => false` to disable this:
+
+```php
+<?php
+// Only output scripts, skip dependent CSS injection
+$this->Vite->script(['files' => ['src/main.js'], 'cssBlock' => false]);
+?>
+```
+
 ### Preloading Assets
 
 CakeVite supports `modulepreload` to improve load times for applications with code splitting. Preloading hints to the browser which modules will be needed soon, allowing parallel downloads.
diff --git a/src/Service/AssetService.php b/src/Service/AssetService.php
index 1523262..27ba1a4 100644
--- a/src/Service/AssetService.php
+++ b/src/Service/AssetService.php
@@ -74,12 +74,14 @@ private function generateDevelopmentScriptTags(ViteConfig $config, array $option
     {
         $tags = [];
 
-        // Add Vite client
-        $tags[] = new AssetTag(
-            url: $config->devServerUrl . '/@vite/client',
-            type: AssetType::Script,
-            attributes: ['type' => 'module'],
-        );
+        // Add Vite client (skip if already rendered to avoid duplicates)
+        if (empty($options['skipViteClient'])) {
+            $tags[] = new AssetTag(
+                url: $config->devServerUrl . '/@vite/client',
+                type: AssetType::Script,
+                attributes: ['type' => 'module'],
+            );
+        }
 
         // Add script entries
         $entries = $options['files'] ?? $options['devEntries'] ?? $config->scriptEntries;
diff --git a/src/View/Helper/ViteHelper.php b/src/View/Helper/ViteHelper.php
index eb2da78..2eae3ac 100644
--- a/src/View/Helper/ViteHelper.php
+++ b/src/View/Helper/ViteHelper.php
@@ -44,6 +44,11 @@ class ViteHelper extends Helper
      */
     private ?Environment $cachedEnvironment = null;
 
+    /**
+     * Track if @vite/client has been rendered (optimization #3: deduplicate vite client)
+     */
+    private bool $viteClientRendered = false;
+
     /**
      * Check if currently in development mode
      *
@@ -101,8 +106,15 @@ public function script(array|string $options = [], array|ViteConfig|null $config
         $cssBlock = $options['cssBlock'] ?? $config->cssBlock;
         $inline = $block === false;
 
+        // Pass flag to skip vite client if already rendered (deduplication)
+        $options['skipViteClient'] = $this->viteClientRendered;
         $tags = $this->getAssetService()->generateScriptTags($config, $options);
 
+        // Mark vite client as rendered after first dev mode script() call
+        if ($this->isDev($config) && !$this->viteClientRendered) {
+            $this->viteClientRendered = true;
+        }
+
         $output = '';
 
         // Render tags (preload tags as link elements, script tags as script elements)
@@ -176,24 +188,28 @@ public function css(array|string $options = [], array|ViteConfig|null $config =
      *
      * Backwards compatible with ViteScriptsHelper::pluginScript()
      *
+     * When `block` option is `false`, returns the tags as a string for inline output.
+     * Otherwise appends to the specified view block and returns null.
+     *
      * @param string $pluginName Plugin name
      * @param bool $devMode Development mode flag
      * @param array<string, mixed> $options Options
      * @param \CakeVite\ValueObject\ViteConfig|array<string, mixed>|null $config Configuration
+     * @return string|null Returns tag string when block is false, null otherwise
      */
     public function pluginScript(
         string $pluginName,
         bool $devMode = false,
         array $options = [],
         array|ViteConfig|null $config = null,
-    ): void {
+    ): ?string {
         $config = $this->resolveConfig($config);
         $config = $config->merge([
             'plugin' => $pluginName,
             'forceProductionMode' => !$devMode,
         ]);
 
-        $this->script($options, $config);
+        return $this->script($options, $config);
     }
 
     /**
@@ -201,24 +217,28 @@ public function pluginScript(
      *
      * Backwards compatible with ViteScriptsHelper::pluginCss()
      *
+     * When `block` option is `false`, returns the tags as a string for inline output.
+     * Otherwise appends to the specified view block and returns null.
+     *
      * @param string $pluginName Plugin name
      * @param bool $devMode Development mode flag
      * @param array<string, mixed> $options Options
      * @param \CakeVite\ValueObject\ViteConfig|array<string, mixed>|null $config Configuration
+     * @return string|null Returns tag string when block is false, null otherwise
      */
     public function pluginCss(
         string $pluginName,
         bool $devMode = false,
         array $options = [],
         array|ViteConfig|null $config = null,
-    ): void {
+    ): ?string {
         $config = $this->resolveConfig($config);
         $config = $config->merge([
             'plugin' => $pluginName,
             'forceProductionMode' => !$devMode,
         ]);
 
-        $this->css($options, $config);
+        return $this->css($options, $config);
     }
 
     /**
@@ -300,10 +320,13 @@ private function extractConfigFromOptions(
     /**
      * Add dependent CSS from JS entries
      *
+     * When cssBlock is false and inline mode is disabled, dependent CSS injection is skipped.
+     * This allows users to explicitly disable automatic CSS injection.
+     *
      * @param \CakeVite\ValueObject\ViteConfig $config Configuration
      * @param array<string, mixed> $options Options
-     * @param string|false $cssBlock CSS block name or false for inline output
-     * @param bool $inline Whether to return inline (when block is false)
+     * @param string|false $cssBlock CSS block name or false to disable/inline
+     * @param bool $inline Whether to return inline (when script block is false)
      * @return string Returns CSS tags when inline is true, empty string otherwise
      */
     private function addDependentCss(
@@ -312,6 +335,11 @@ private function addDependentCss(
         string|false $cssBlock,
         bool $inline = false,
     ): string {
+        // Skip dependent CSS injection if cssBlock is false and not in inline mode
+        if ($cssBlock === false && !$inline) {
+            return '';
+        }
+
         $manifestService = new ManifestService();
         $manifest = $manifestService->load($config);
 
diff --git a/tests/TestCase/View/Helper/ViteHelperTest.php b/tests/TestCase/View/Helper/ViteHelperTest.php
index ff6c0a1..199018a 100644
--- a/tests/TestCase/View/Helper/ViteHelperTest.php
+++ b/tests/TestCase/View/Helper/ViteHelperTest.php
@@ -864,4 +864,184 @@ public function testScriptWithBlockFalseOutputsDependentCssInline(): void
         // CSS view block should be empty
         $this->assertEmpty($this->View->fetch('css'));
     }
+
+    /**
+     * Test @vite/client is only output once when script() is called multiple times
+     */
+    public function testViteClientIsDeduplicatedInDevelopmentMode(): void
+    {
+        $config = [
+            'devServer' => [
+                'url' => 'http://localhost:3000',
+                'hostHints' => ['localhost'],
+                'entries' => ['script' => ['src/app.ts']],
+            ],
+        ];
+
+        // Call script() multiple times (simulating layout + element + component)
+        $this->Vite->script(['files' => ['src/app.ts']], $config);
+        $this->Vite->script(['files' => ['src/component.ts']], $config);
+        $this->Vite->script(['files' => ['src/element.ts']], $config);
+
+        $result = $this->View->fetch('script');
+
+        // @vite/client should only appear once
+        $this->assertSame(1, substr_count($result, '/@vite/client'));
+
+        // But all three script entries should be present
+        $this->assertStringContainsString('src/app.ts', $result);
+        $this->assertStringContainsString('src/component.ts', $result);
+        $this->assertStringContainsString('src/element.ts', $result);
+    }
+
+    /**
+     * Test @vite/client deduplication works with inline mode
+     */
+    public function testViteClientIsDeduplicatedWithInlineMode(): void
+    {
+        $config = [
+            'devServer' => [
+                'url' => 'http://localhost:3000',
+                'hostHints' => ['localhost'],
+                'entries' => ['script' => ['src/app.ts']],
+            ],
+        ];
+
+        // First call outputs vite client
+        $output1 = $this->Vite->script(['files' => ['src/app.ts'], 'block' => false], $config);
+
+        // Second call should NOT include vite client again
+        $output2 = $this->Vite->script(['files' => ['src/component.ts'], 'block' => false], $config);
+
+        // First output should have the client
+        $this->assertNotNull($output1);
+        $this->assertStringContainsString('/@vite/client', $output1);
+
+        // Second output should NOT have the client
+        $this->assertNotNull($output2);
+        $this->assertStringNotContainsString('/@vite/client', $output2);
+
+        // But both should have their respective entry points
+        $this->assertStringContainsString('src/app.ts', $output1);
+        $this->assertStringContainsString('src/component.ts', $output2);
+    }
+
+    /**
+     * Test @vite/client deduplication state is tracked in helper property
+     */
+    public function testViteClientRenderedStateIsTracked(): void
+    {
+        $reflection = new ReflectionClass($this->Vite);
+        $property = $reflection->getProperty('viteClientRendered');
+
+        // Initially false
+        $this->assertFalse($property->getValue($this->Vite));
+
+        $config = [
+            'devServer' => [
+                'url' => 'http://localhost:3000',
+                'hostHints' => ['localhost'],
+                'entries' => ['script' => ['src/app.ts']],
+            ],
+        ];
+
+        // Call script() in development mode
+        $this->Vite->script(['files' => ['src/app.ts']], $config);
+
+        // Should now be true
+        $this->assertTrue($property->getValue($this->Vite));
+    }
+
+    /**
+     * Test @vite/client deduplication does not affect production mode
+     */
+    public function testViteClientDeduplicationDoesNotAffectProductionMode(): void
+    {
+        $config = [
+            'forceProductionMode' => true,
+            'build' => [
+                'manifestPath' => TESTS . 'Fixture' . DS . 'manifest.json',
+            ],
+        ];
+
+        // Multiple calls in production mode
+        $this->Vite->script(['files' => ['src/app.ts']], $config);
+        $this->Vite->script(['files' => ['src/app.ts']], $config);
+
+        $result = $this->View->fetch('script');
+
+        // Production mode doesn't use @vite/client at all
+        $this->assertStringNotContainsString('@vite/client', $result);
+
+        // But the manifest scripts should be there (potentially duplicated, that's fine)
+        $this->assertStringContainsString('assets/app-abc123.js', $result);
+    }
+
+    /**
+     * Test pluginScript returns inline output with block => false
+     */
+    public function testPluginScriptReturnsInlineOutput(): void
+    {
+        $config = [
+            'forceProductionMode' => true,
+            'build' => [
+                'manifestPath' => TESTS . 'Fixture' . DS . 'manifest.json',
+            ],
+        ];
+
+        $output = $this->Vite->pluginScript('TestPlugin', false, ['files' => ['src/app.ts'], 'block' => false], $config);
+
+        // Should return tags directly
+        $this->assertNotNull($output);
+        $this->assertStringContainsString('assets/app-abc123.js', $output);
+
+        // View block should be empty
+        $this->assertEmpty($this->View->fetch('script'));
+    }
+
+    /**
+     * Test pluginCss returns inline output with block => false
+     */
+    public function testPluginCssReturnsInlineOutput(): void
+    {
+        $config = [
+            'forceProductionMode' => true,
+            'build' => [
+                'manifestPath' => TESTS . 'Fixture' . DS . 'manifest.json',
+            ],
+        ];
+
+        $output = $this->Vite->pluginCss('TestPlugin', false, ['files' => ['src/style.css'], 'block' => false], $config);
+
+        // Should return tags directly
+        $this->assertNotNull($output);
+        $this->assertStringContainsString('assets/style-jkl012.css', $output);
+
+        // View block should be empty
+        $this->assertEmpty($this->View->fetch('css'));
+    }
+
+    /**
+     * Test cssBlock => false skips dependent CSS when not in inline mode
+     */
+    public function testCssBlockFalseSkipsDependentCssWhenNotInline(): void
+    {
+        $config = [
+            'forceProductionMode' => true,
+            'build' => [
+                'manifestPath' => TESTS . 'Fixture' . DS . 'manifest.json',
+            ],
+        ];
+
+        // script block is 'script' (not inline), but cssBlock is false
+        $this->Vite->script(['files' => ['src/app.ts'], 'cssBlock' => false], $config);
+
+        // Scripts should be in the block
+        $scriptResult = $this->View->fetch('script');
+        $this->assertStringContainsString('assets/app-abc123.js', $scriptResult);
+
+        // CSS should be empty (cssBlock false means skip dependent CSS)
+        $cssResult = $this->View->fetch('css');
+        $this->assertEmpty($cssResult);
+    }
 }