[2.x] Improve the Vite integration

docs/creating-content/managing-assets.md

@@ -18,6 +18,57 @@ Some extra component styles are organized into modular files in the HydeFront pa
 To get you started quickly, all the styles are already compiled and minified into `_media/app.css`,
 which will be copied to the `_site/media/app.css` directory when you run `php hyde build`.
 
+## Vite
+
+Hyde uses [Vite](https://vitejs.dev/) to compile assets. Vite is a build tool that aims to provide a faster and more efficient development experience for modern web projects.
+
+### Why Vite?
+
+HydePHP integrates Vite to compile assets such as CSS and JavaScript files. This integration ensures that your assets are processed efficiently, enhancing the development workflow by leveraging Vite's rapid build system.
+
+#### Asset Management
+
+**Development and Production Modes**
+
+- **Development Mode**: Use `npm run dev` to start the Vite development HMR server, which provides fast live reloading and efficient compilation during development.
+- **Production Mode**: Use `npm run build` for creating optimized, minified asset bundles ready for production deployment.
+
+**Asset Compilation**:
+
+- Assets are compiled from the `resources/assets` directory. The primary CSS file, `app.css`, is processed with TailwindCSS and other specified tools like PostCSS.
+- Vite automatically processes all scripts and styles, outputting compiled files to the `_media` directory. These are copied to `_site/media` when the static site is built with `php hyde build`.
+
+>warn Note that the HydePHP Vite integration only supports CSS and JavaScript files, if you try to load other file types, they will not be processed by Vite.
+
+**Configuration**:
+- You can customize Vite's behavior and output paths by modifying the pre-configured `vite.config.js` file in the project root directory.
+
+### Hot Module Replacement (HMR)
+
+Vite's HMR feature allows for instant updates to the browser without requiring a full page reload. This **only works** through the realtime compiler when the Vite development server is also running.
+
+You can start both of these by running `npm run dev` and `php hyde serve` in separate terminals, or using the `--vite` flag with the serve command:
+
+```bash
+php hyde serve --vite
+```
+
+### Blade Integration
+
+Hyde effortlessly integrates Vite with Blade views, allowing you to include compiled assets in your templates. The Blade components `hyde::layouts.styles` and `hyde::layouts.scripts` are already set up to load the compiled CSS and JavaScript files.
+
+You can check if the Vite HMR server is running with `Vite::running()`, and you can include CSS and JavaScript resources with `Vite::asset('path')`, or `Vite::assets([])` to supply an array of paths.
+
+**Example: Using Vite if the HMR server is enabled, or loading the compiled CSS file if not:**
+
+```blade
+@if(Vite::running())
+    {{ Vite::assets(['resources/assets/app.css']) }}
+@else
+    <link rel="stylesheet" href="{{ asset('media/app.css') }}">
+@endif
+```
+
 ## Additional Information and Answers to Common Questions
 
 ### Is NodeJS/NPM Required for Using Hyde?

packages/framework/src/Console/Commands/ServeCommand.php

@@ -5,6 +5,7 @@
 namespace Hyde\Console\Commands;
 
 use Closure;
+use Hyde\Facades\Filesystem;
 use Hyde\Hyde;
 use Hyde\Facades\Config;
 use Illuminate\Contracts\Process\InvokedProcess;
@@ -112,7 +113,6 @@ protected function getEnvironmentVariables(): array
             'HYDE_SERVER_DASHBOARD' => $this->parseEnvironmentOption('dashboard'),
             'HYDE_PRETTY_URLS' => $this->parseEnvironmentOption('pretty-urls'),
             'HYDE_PLAY_CDN' => $this->parseEnvironmentOption('play-cdn'),
-            'HYDE_SERVER_VITE' => $this->option('vite') ? 'enabled' : null,
         ]);
     }
 
@@ -204,6 +204,8 @@ protected function runViteProcess(): void
             );
         }
 
+        Filesystem::touch('app/storage/framework/cache/vite.hot');
+
         $this->vite = Process::forever()->start('npm run dev');
     }
 

packages/framework/src/Facades/Vite.php

@@ -5,37 +5,75 @@
 namespace Hyde\Facades;
 
 use Illuminate\Support\HtmlString;
+use InvalidArgumentException;
 
 /**
  * Vite facade for handling Vite-related operations.
  */
 class Vite
 {
+    protected const CSS_EXTENSIONS = ['css', 'less', 'sass', 'scss', 'styl', 'stylus', 'pcss', 'postcss'];
+    protected const JS_EXTENSIONS = ['js', 'jsx', 'ts', 'tsx'];
+
     public static function running(): bool
     {
-        // Check if Vite was enabled via the serve command
-        if (env('HYDE_SERVER_VITE') === 'enabled') {
-            return true;
-        }
-
-        // Check for Vite hot file
         return Filesystem::exists('app/storage/framework/cache/vite.hot');
     }
 
+    public static function asset(string $path): HtmlString
+    {
+        return static::assets([$path]);
+    }
+
+    /** @param array<string> $paths */
     public static function assets(array $paths): HtmlString
     {
-        $html = sprintf('<script src="http://localhost:5173/@vite/client" type="module"></script>');
+        $html = '<script src="http://localhost:5173/@vite/client" type="module"></script>';
 
         foreach ($paths as $path) {
-            if (str_ends_with($path, '.css')) {
-                $html .= sprintf('<link rel="stylesheet" href="http://localhost:5173/%s">', $path);
-            }
-
-            if (str_ends_with($path, '.js')) {
-                $html .= sprintf('<script src="http://localhost:5173/%s" type="module"></script>', $path);
-            }
+            $html .= static::formatAssetPath($path);
         }
 
         return new HtmlString($html);
     }
+
+    /** @throws InvalidArgumentException If the asset type is not supported. */
+    protected static function formatAssetPath(string $path): string
+    {
+        if (static::isCssPath($path)) {
+            return static::formatStylesheetLink($path);
+        }
+
+        if (static::isJsPath($path)) {
+            return static::formatScriptInclude($path);
+        }
+
+        // We don't know how to handle other asset types, so we throw an exception to let the user know.
+        throw new InvalidArgumentException("Unsupported asset type for path: '$path'");
+    }
+
+    protected static function isCssPath(string $path): bool
+    {
+        return static::checkFileExtensionForPath($path, static::CSS_EXTENSIONS);
+    }
+
+    protected static function isJsPath(string $path): bool
+    {
+        return static::checkFileExtensionForPath($path, static::JS_EXTENSIONS);
+    }
+
+    protected static function checkFileExtensionForPath(string $path, array $extensions): bool
+    {
+        return preg_match('/\.('.implode('|', $extensions).')$/', $path) === 1;
+    }
+
+    protected static function formatStylesheetLink(string $path): string
+    {
+        return sprintf('<link rel="stylesheet" href="http://localhost:5173/%s">', $path);
+    }
+
+    protected static function formatScriptInclude(string $path): string
+    {
+        return sprintf('<script src="http://localhost:5173/%s" type="module"></script>', $path);
+    }
 }

packages/framework/tests/Feature/Commands/ServeCommandTest.php

@@ -182,6 +182,8 @@ public function testWithFancyOutput()
 
     public function testHydeServeCommandWithViteOption()
     {
+        $this->cleanUpWhenDone('app/storage/framework/cache/vite.hot');
+
         $mockViteProcess = mock(InvokedProcess::class);
         $mockViteProcess->shouldReceive('running')
             ->once()
@@ -202,7 +204,7 @@ public function testHydeServeCommandWithViteOption()
 
         Process::shouldReceive('env')
             ->once()
-            ->with(['HYDE_SERVER_REQUEST_OUTPUT' => false, 'HYDE_SERVER_VITE' => 'enabled'])
+            ->with(['HYDE_SERVER_REQUEST_OUTPUT' => false])
             ->andReturnSelf();
 
         Process::shouldReceive('start')
@@ -224,10 +226,14 @@ public function testHydeServeCommandWithViteOption()
             ->expectsOutput('server output')
             ->expectsOutput('vite latest output')
             ->assertExitCode(0);
+
+        $this->assertFileExists('app/storage/framework/cache/vite.hot');
     }
 
     public function testHydeServeCommandWithViteOptionButViteNotRunning()
     {
+        $this->cleanUpWhenDone('app/storage/framework/cache/vite.hot');
+
         $mockViteProcess = mock(InvokedProcess::class);
         $mockViteProcess->shouldReceive('running')
             ->once()
@@ -245,7 +251,7 @@ public function testHydeServeCommandWithViteOptionButViteNotRunning()
 
         Process::shouldReceive('env')
             ->once()
-            ->with(['HYDE_SERVER_REQUEST_OUTPUT' => false, 'HYDE_SERVER_VITE' => 'enabled'])
+            ->with(['HYDE_SERVER_REQUEST_OUTPUT' => false])
             ->andReturnSelf();
 
         Process::shouldReceive('start')
@@ -263,6 +269,8 @@ public function testHydeServeCommandWithViteOptionButViteNotRunning()
         $this->artisan('serve --no-ansi --vite')
             ->expectsOutput('Starting the HydeRC server... Use Ctrl+C to stop')
             ->assertExitCode(0);
+
+        $this->assertFileExists('app/storage/framework/cache/vite.hot');
     }
 
     public function testHydeServeCommandWithViteOptionThrowsWhenPortIsInUse()