[2.x] Add Vite Realtime Compiler integration for HMR

RELEASE_NOTES.md

@@ -33,6 +33,8 @@ This serves two purposes:
     - Added method `Asset::exists()` has to check if a media file exists.
     - Added a `Hyde::assets()` method to get all media file instances in the site.
 - Added new `npm run build` command for compiling frontend assets with Vite
+- Added a Vite HMR support for the realtime compiler in https://github.com/hydephp/develop/pull/2016
+- Added Vite facade in https://github.com/hydephp/develop/pull/2016
 
 ### Changed
 
@@ -131,6 +133,7 @@ This serves two purposes:
 #### Realtime Compiler
 
 - Simplified the asset file locator to only serve files from the media source directory in https://github.com/hydephp/develop/pull/2012
+- Added Vite HMR support in https://github.com/hydephp/develop/pull/2016
 
 ### Upgrade Guide
 

app/config.php

@@ -92,6 +92,7 @@
         'Hyde' => Hyde\Hyde::class,
         'Site' => \Hyde\Facades\Site::class,
         'Meta' => \Hyde\Facades\Meta::class,
+        'Vite' => \Hyde\Facades\Vite::class,
         'Asset' => \Hyde\Facades\Asset::class,
         'Author' => \Hyde\Facades\Author::class,
         'HydeFront' => \Hyde\Facades\HydeFront::class,

docs/extensions/realtime-compiler.md

@@ -30,6 +30,11 @@ This will start a local development server at `http://localhost:8080`
 - `--pretty-urls=`: Enable pretty URLs. (Overrides config setting)
 - `--play-cdn=`: Enable the Tailwind Play CDN. (Overrides config setting)
 - `--open=false`: Open the site preview in the browser.
+- `--vite`: Enable Vite for Hot Module Replacement (HMR).
+
+### Vite Integration
+
+By adding the `--vite` option, the serve command will initiate Vite's development server alongside the Hyde Realtime Compiler. This setup enables Hot Module Replacement (HMR), allowing for instant updates to your site as you make changes to your assets.
 
 ### Configuration
 

docs/getting-started/console-commands.md

@@ -101,7 +101,7 @@ Run the static site builder for a single file
 <a name="serve" style="display: inline-block; position: absolute; margin-top: -5rem;"></a>
 
 ```bash
-php hyde serve [--host [HOST]] [--port [PORT]]
+php hyde serve [--host [HOST]] [--port [PORT]] [--vite]
 ```
 
 Start the realtime compiler server.

packages/framework/resources/views/layouts/scripts.blade.php

@@ -1,5 +1,7 @@
 {{-- The compiled Vite scripts --}}
-@if(Asset::exists('app.js'))
+@if(Vite::running())
+    {{ Vite::assets(['resources/assets/app.js']) }}
+@elseif(Asset::exists('app.js'))
     <script defer src="{{ Asset::get('app.js') }}"></script>
 @endif
 

packages/framework/resources/views/layouts/styles.blade.php

@@ -2,17 +2,22 @@
 <style>[x-cloak] {display: none!important}</style>
 
 {{-- The compiled Tailwind/App styles --}}
-@if(config('hyde.load_app_styles_from_cdn', false))
-    <link rel="stylesheet" href="{{ HydeFront::cdnLink('app.css') }}">
-@elseif(Asset::exists('app.css'))
-    <link rel="stylesheet" href="{{ Asset::get('app.css') }}">
-@endif
+@if(Vite::running())
+    {{ Vite::assets(['resources/assets/app.css']) }}
+@else
+    @if(config('hyde.load_app_styles_from_cdn', false))
+        <link rel="stylesheet" href="{{ HydeFront::cdnLink('app.css') }}">
+    @elseif(Asset::exists('app.css'))
+        <link rel="stylesheet" href="{{ Asset::get('app.css') }}">
+    @endif
+
 
-{{-- Dynamic TailwindCSS Play CDN --}}
-@if(config('hyde.use_play_cdn', false))
-    <script src="https://cdn.tailwindcss.com?plugins=typography"></script>
-    <script>tailwind.config = { {!! HydeFront::injectTailwindConfig() !!} }</script>
-    <script>console.warn('The HydePHP TailwindCSS Play CDN is enabled. This is for development purposes only and should not be used in production.', 'See https://hydephp.com/docs/1.x/managing-assets');</script>
+    {{-- Dynamic TailwindCSS Play CDN --}}
+    @if(config('hyde.use_play_cdn', false))
+        <script src="https://cdn.tailwindcss.com?plugins=typography"></script>
+        <script>tailwind.config = { {!! HydeFront::injectTailwindConfig() !!} }</script>
+        <script>console.warn('The HydePHP TailwindCSS Play CDN is enabled. This is for development purposes only and should not be used in production.', 'See https://hydephp.com/docs/1.x/managing-assets');</script>
+    @endif
 @endif
 
 {{-- Add any extra styles to include after the others --}}

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

@@ -7,7 +7,9 @@
 use Closure;
 use Hyde\Hyde;
 use Hyde\Facades\Config;
+use Illuminate\Contracts\Process\InvokedProcess;
 use Illuminate\Support\Arr;
+use Illuminate\Support\Sleep;
 use InvalidArgumentException;
 use Hyde\Console\Concerns\Command;
 use Hyde\RealtimeCompiler\ConsoleOutput;
@@ -35,13 +37,17 @@ class ServeCommand extends Command
         {--pretty-urls= : Enable pretty URLs. (Overrides config setting)}
         {--play-cdn= : Enable the Tailwind Play CDN. (Overrides config setting)}
         {--open=false : Open the site preview in the browser.}
+        {--vite : Enable Vite for Hot Module Replacement (HMR)}
     ';
 
     /** @var string */
     protected $description = 'Start the realtime compiler server';
 
     protected ConsoleOutput $console;
 
+    protected InvokedProcess $server;
+    protected InvokedProcess $vite;
+
     public function safeHandle(): int
     {
         $this->configureOutput();
@@ -51,11 +57,29 @@ public function safeHandle(): int
             $this->openInBrowser((string) $this->option('open'));
         }
 
-        $this->runServerProcess(sprintf('php -S %s:%d %s',
+        $command = sprintf('php -S %s:%d %s',
             $this->getHostSelection(),
             $this->getPortSelection(),
             $this->getExecutablePath()
-        ));
+        );
+
+        if ($this->option('vite')) {
+            $this->runViteProcess();
+        }
+
+        $this->runServerProcess($command);
+
+        while ($this->server->running()) {
+            if (isset($this->vite) && $this->vite->running()) {
+                $output = $this->vite->latestOutput();
+
+                if ($output) {
+                    $this->output->write($output);
+                }
+            }
+
+            Sleep::usleep(100000); // 100ms
+        }
 
         return Command::SUCCESS;
     }
@@ -77,7 +101,7 @@ protected function getExecutablePath(): string
 
     protected function runServerProcess(string $command): void
     {
-        Process::forever()->env($this->getEnvironmentVariables())->run($command, $this->getOutputHandler());
+        $this->server = Process::forever()->env($this->getEnvironmentVariables())->start($command, $this->getOutputHandler());
     }
 
     protected function getEnvironmentVariables(): array
@@ -88,6 +112,7 @@ 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,
         ]);
     }
 
@@ -169,4 +194,29 @@ protected function getOpenCommand(string $osFamily): ?string
             default => null
         };
     }
+
+    protected function runViteProcess(): void
+    {
+        if (! $this->isPortAvailable(5173)) {
+            throw new InvalidArgumentException(
+                'Unable to start Vite server: Port 5173 is already in use. '.
+                'Please stop any other Vite processes and try again.'
+            );
+        }
+
+        $this->vite = Process::forever()->start('npm run dev');
+    }
+
+    /** @experimental This feature may be removed before the final release. */
+    protected function isPortAvailable(int $port): bool
+    {
+        $socket = @fsockopen('localhost', $port, $errno, $errstr, 1);
+        if ($socket !== false) {
+            fclose($socket);
+
+            return false;
+        }
+
+        return true;
+    }
 }

packages/framework/src/Facades/Vite.php

@@ -0,0 +1,52 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Hyde\Facades;
+
+use Illuminate\Support\HtmlString;
+
+/**
+ * Vite facade for handling Vite-related operations.
+ */
+class Vite
+{
+    public static function running(): bool
+    {
+        // Check if Vite was enabled via the serve command
+        if (env('HYDE_SERVER_VITE') === 'enabled') {
+            return true;
+        }
+
+        // Check if Vite dev server is running by attempting to connect to it
+        // Todo: Improve performance on Windows (takes less than 1ms on macOS, but around 100ms on Windows)
+        set_error_handler(fn () => false); // Todo: This warning surpressor does not work on Windows
+        $server = fsockopen('localhost', 5173, $errno, $errstr, 0.1);
+        restore_error_handler();
+
+        if ($server) {
+            fclose($server);
+
+            return true;
+        }
+
+        return false;
+    }
+
+    public static function assets(array $paths): HtmlString
+    {
+        $html = sprintf('<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);
+            }
+        }
+
+        return new HtmlString($html);
+    }
+}

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

@@ -7,6 +7,7 @@
 use Closure;
 use Hyde\Hyde;
 use Hyde\Testing\TestCase;
+use Illuminate\Contracts\Process\InvokedProcess;
 use Illuminate\Support\Facades\Process;
 use TypeError;
 
@@ -138,6 +139,11 @@ public function testHydeServeCommandWithInvalidConfigValue()
 
     public function testHydeServeCommandPassesThroughProcessOutput()
     {
+        $mockProcess = mock(InvokedProcess::class);
+        $mockProcess->shouldReceive('running')
+            ->once()
+            ->andReturn(false);
+
         Process::shouldReceive('forever')
             ->once()
             ->withNoArgs()
@@ -148,14 +154,14 @@ public function testHydeServeCommandPassesThroughProcessOutput()
             ->with(['HYDE_SERVER_REQUEST_OUTPUT' => false])
             ->andReturnSelf();
 
-        Process::shouldReceive('run')
+        Process::shouldReceive('start')
             ->once()
             ->withArgs(function (string $command, Closure $handle) {
                 $handle('type', 'foo');
 
                 return $command === "php -S localhost:8080 {$this->binaryPath()}";
             })
-            ->andReturnSelf();
+            ->andReturn($mockProcess);
 
         $this->artisan('serve --no-ansi')
             ->expectsOutput('Starting the HydeRC server... Use Ctrl+C to stop')
@@ -174,6 +180,102 @@ public function testWithFancyOutput()
         Process::assertRan("php -S localhost:8080 {$this->binaryPath()}");
     }
 
+    public function testHydeServeCommandWithViteOption()
+    {
+        $mockViteProcess = mock(InvokedProcess::class);
+        $mockViteProcess->shouldReceive('running')
+            ->once()
+            ->andReturn(true);
+        $mockViteProcess->shouldReceive('latestOutput')
+            ->once()
+            ->andReturn('vite latest output');
+
+        $mockServerProcess = mock(InvokedProcess::class);
+        $mockServerProcess->shouldReceive('running')
+            ->times(2)
+            ->andReturn(true, false);
+
+        Process::shouldReceive('forever')
+            ->twice()
+            ->withNoArgs()
+            ->andReturnSelf();
+
+        Process::shouldReceive('env')
+            ->once()
+            ->with(['HYDE_SERVER_REQUEST_OUTPUT' => false, 'HYDE_SERVER_VITE' => 'enabled'])
+            ->andReturnSelf();
+
+        Process::shouldReceive('start')
+            ->once()
+            ->with('npm run dev')
+            ->andReturn($mockViteProcess);
+
+        Process::shouldReceive('start')
+            ->once()
+            ->withArgs(function (string $command, Closure $output) {
+                $output('stdout', 'server output');
+
+                return $command === "php -S localhost:8080 {$this->binaryPath()}";
+            })
+            ->andReturn($mockServerProcess);
+
+        $this->artisan('serve --no-ansi --vite')
+            ->expectsOutput('Starting the HydeRC server... Use Ctrl+C to stop')
+            ->expectsOutput('server output')
+            ->expectsOutput('vite latest output')
+            ->assertExitCode(0);
+    }
+
+    public function testHydeServeCommandWithViteOptionButViteNotRunning()
+    {
+        $mockViteProcess = mock(InvokedProcess::class);
+        $mockViteProcess->shouldReceive('running')
+            ->once()
+            ->andReturn(false);
+
+        $mockServerProcess = mock(InvokedProcess::class);
+        $mockServerProcess->shouldReceive('running')
+            ->times(2)
+            ->andReturn(true, false);
+
+        Process::shouldReceive('forever')
+            ->twice()
+            ->withNoArgs()
+            ->andReturnSelf();
+
+        Process::shouldReceive('env')
+            ->once()
+            ->with(['HYDE_SERVER_REQUEST_OUTPUT' => false, 'HYDE_SERVER_VITE' => 'enabled'])
+            ->andReturnSelf();
+
+        Process::shouldReceive('start')
+            ->once()
+            ->with('npm run dev')
+            ->andReturn($mockViteProcess);
+
+        Process::shouldReceive('start')
+            ->once()
+            ->withArgs(function (string $command, Closure $handle) {
+                return $command === "php -S localhost:8080 {$this->binaryPath()}";
+            })
+            ->andReturn($mockServerProcess);
+
+        $this->artisan('serve --no-ansi --vite')
+            ->expectsOutput('Starting the HydeRC server... Use Ctrl+C to stop')
+            ->assertExitCode(0);
+    }
+
+    public function testHydeServeCommandWithViteOptionThrowsWhenPortIsInUse()
+    {
+        $socket = stream_socket_server('tcp://127.0.0.1:5173');
+
+        $this->artisan('serve --vite')
+            ->expectsOutputToContain('Unable to start Vite server: Port 5173 is already in use')
+            ->assertExitCode(1);
+
+        stream_socket_shutdown($socket, STREAM_SHUT_RDWR);
+    }
+
     protected function binaryPath(): string
     {
         return Hyde::path('vendor/hyde/realtime-compiler/bin/server.php');