feat: add try flag

README.md

@@ -107,6 +107,16 @@ Sometimes you might want to access the (hashed) file path of your assets, e.g. t
  <link rel="preload" href="<?= vite()->file('my-font.woff2') ?>" as="font" type="font/woff2" crossorigin>
 ```
 
+## Trying
+
+If you try to load a non-existent manifest entry, this plugin will throw an error (if Kirby's `debug` option is enabled). This is intended behaviour, since you usually know which entries exist. But sometimes, especially in a multi-page setup, you may want to try to load an entry only if it exists. You can do this with the `try` flag:
+
+```php
+vite()->js('templates/' . $page->template() . '/index.js', try: true);
+vite()->css('templates/' . $page->template() . '/index.css', try: true);
+vite()->file('maybe.woff2', try: true);
+```
+
 ## Legacy build
 
 Since version `2.4.0` you can easily support legacy browsers that do not support native ESM.

packages/kirby-vite/Vite.php

@@ -103,18 +103,22 @@ public function manifest(): array {
    *
    * @throws Exception
    */
-  protected function manifestProperty(string $entry, $key = 'file') {
+  protected function manifestProperty(
+    string $entry,
+    $key = 'file',
+    $try = false
+  ) {
     $manifestEntry = $this->manifest()[$entry] ?? null;
     if (!$manifestEntry) {
-      if (option('debug')) {
+      if (!$try && option('debug')) {
         throw new Exception("`$entry` is not a manifest entry.");
       }
       return;
     }
 
     $value = $manifestEntry[$key] ?? null;
     if (!$value) {
-      if (option('debug')) {
+      if (!$try && option('debug')) {
         throw new Exception("`$key` not found in manifest entry `$entry`");
       }
       return;
@@ -150,8 +154,12 @@ protected function client(): ?string {
   /**
    * Include the js file for the specified entry.
    */
-  public function js(string $entry, $options = []): ?string {
-    $file = $this->file($entry);
+  public function js(string $entry, $options = [], $try = false): ?string {
+    $file = $this->file($entry, $try);
+    if (!$file && $try) {
+      return null;
+    }
+
     $options = array_merge(['type' => 'module'], $options);
 
     $legacy = $this->config()['legacy'];
@@ -174,7 +182,7 @@ public function js(string $entry, $options = []): ?string {
    * `vite()->css('main.js')`, in this case the CSS imported in the JS file will
    *  be used.
    */
-  public function css(string $entry, array $options = null): ?string {
+  public function css(string $entry, $options = [], $try = false): ?string {
     if ($this->isDev()) {
       return null;
     }
@@ -183,20 +191,30 @@ public function css(string $entry, array $options = null): ?string {
     $entryIsStyle =
       $extension === 'css' || $extension === 'scss' || $extension === 'sass';
 
-    $file = $entryIsStyle
-      ? $this->manifestProperty($entry, 'file')
-      : $this->manifestProperty($entry, 'css')[0];
+    $file = null;
+    if ($entryIsStyle) {
+      $file = $this->manifestProperty($entry, 'file', $try);
+    } else {
+      $css = $this->manifestProperty($entry, 'css', $try);
+      $file = $css ? $css[0] : null;
+    }
+    if (!$file) {
+      return null;
+    }
 
     return css($this->assetProd($file), $options);
   }
 
   /**
    * Return manifest file path for entry.
    */
-  public function file(string $entry): string {
-    return $this->isDev()
-      ? $this->assetDev($entry)
-      : $this->assetProd($this->manifestProperty($entry, 'file'));
+  public function file(string $entry, $try = false): ?string {
+    if ($this->isDev()) {
+      return $this->assetDev($entry);
+    }
+
+    $property = $this->manifestProperty($entry, 'file', $try);
+    return $property ? $this->assetProd($property) : null;
   }
 
   protected function legacyPolyfills($options = []): ?string {
@@ -223,15 +241,22 @@ protected function legacyPolyfills($options = []): ?string {
     return js($entry, array_merge(['nomodule' => true], $options));
   }
 
-  protected function legacyJs(string $entry, $options = []): ?string {
+  protected function legacyJs(
+    string $entry,
+    $options = [],
+    $try = false
+  ): ?string {
     if ($this->isDev()) {
       return null;
     }
 
     $parts = explode('.', $entry);
     $parts[count($parts) - 2] .= '-legacy';
     $legacyEntry = join('.', $parts);
-    $file = $this->file($legacyEntry);
+    $file = $this->file($legacyEntry, $try);
+    if (!$file) {
+      return null;
+    }
 
     return js($file, array_merge(['nomodule' => true], $options));
   }

packages/kirby-vite/test/ViteTest.php

@@ -37,6 +37,16 @@ function setMode($mode) {
   expect($this->vite->js('main.js', $options))->toBe($result);
 });
 
+it('throws errors for missing JS entries', function () {
+  setMode('production');
+  $this->vite->js('does-not-exists.js');
+})->throws('`does-not-exists.js` is not a manifest entry.');
+
+it('it omits errors for missing JS entries when trying', function () {
+  setMode('production');
+  $this->vite->js('does-not-exists.js', try: true);
+})->throwsNoExceptions();
+
 it('omits CSS for development', function () {
   setMode('development');
   expect($this->vite->css('main.css'))->toBe(null);
@@ -58,6 +68,16 @@ function setMode($mode) {
   expect($this->vite->css('main.css', $options))->toBe($result);
 });
 
+it('throws errors for missing CSS entries', function () {
+  setMode('production');
+  $this->vite->css('does-not-exists.css');
+})->throws('`does-not-exists.css` is not a manifest entry.');
+
+it('it omits errors for missing CSS entries when trying', function () {
+  setMode('production');
+  $this->vite->css('does-not-exists.css', try: true);
+})->throwsNoExceptions();
+
 it('provides a file path for development', function () {
   setMode('development');
   expect($this->vite->file('my-font.woff2'))->toBe(
@@ -71,3 +91,13 @@ function setMode($mode) {
     '/dist/assets/my-font.1234.woff2'
   );
 });
+
+it('throws errors for missing file', function () {
+  setMode('production');
+  $this->vite->file('does-not-exist.woff2');
+})->throws('`does-not-exist.woff2` is not a manifest entry.');
+
+it('omits errors for missing file when trying', function () {
+  setMode('production');
+  $this->vite->file('does-not-exist.woff2', try: true);
+})->throwsNoExceptions();

packages/kirby-vite/test/config/config.php

@@ -0,0 +1,3 @@
+<?php return [
+  'debug' => true,
+];