[2.x] Replace Laravel Mix with Vite

[caendesilva]

Abstract

• Fixes Replace Laravel Mix with Vite #1129
• Targets HydePHP v2.x Development #1565 via [2.x] New asset system #2006
• Supersedes Use Vite as the default frontend asset bundler for new HydePHP projects #1130

Important: You must now use npm run build instead of npm run prod

Motivation

Key changes from Laravel Mix to Vite:

• Simpler configuration with Vite
• Faster development builds with HMR support
• Better production optimization
• Modern ESM-based development
• Match new Laravel syntax of npm run build.
• And we can use HMR as a BrowserSync replacement.

Community support

Vite is also winning by a landslide by a community vote

Laravel Mix vs Vite Benchmark

All cases have had the NPM command been run before the benchmark to warmup any caches. Note that the benchmarks did not run enough iterations to get an accurate average. Tests were run on Windows.

Laravel Mix:

• First build: 9694 ms
• Rebuild: 8907 ms
• Average: 9300 ms

Vite:

• First build: 4628 ms
• Rebuild: 4518 ms
• Average: 4575 ms

Analysis

Vite is approximately 52% faster than Laravel Mix, in other words it's about twice as fast.

[codecov]

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 100.00%. Comparing base (3d48284) to head (56d7c06).
Report is 19 commits behind head on new-asset-system.

Additional details and impacted files

@@                 Coverage Diff                  @@
##             new-asset-system     #2010   +/-   ##
====================================================
  Coverage              100.00%   100.00%           
  Complexity               1891      1891           
====================================================
  Files                     194       194           
  Lines                    5044      5044           
====================================================
  Hits                     5044      5044           

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

[caendesilva]

Since run dev has a changed scope, we may want to remove this: (a merged --vite option may work better)

if ($this->option('run-dev')) {
    $this->runNodeCommand('npm run dev', 'Building frontend assets for development!');
}

And update this:

Then run npm run dev to compile the assets in development mode. For production builds, run npm run build.

[caendesilva]

Clause response to renamed build flag

Based on the provided code and context, I'll analyze the situation and provide some suggestions for renaming the flags.

Current situation:

    protected $signature = 'build
        {--run-dev : Run the NPM dev script after build}
        {--run-prod : Run the NPM prod script after build}
        {--run-prettier : Format the output using NPM Prettier}
        {--pretty-urls : Should links in output use pretty URLs?}
        {--no-api : Disable API calls, for example, Torchlight}';

The current flags --run-dev and --run-prod are misleading now that we've switched to Vite, since:

1. npm run dev with Vite starts a development server
2. npm run build with Vite builds for production
3. There's no direct equivalent to Laravel Mix's unminified build

Here are my suggestions, ordered by preference:

1. --compile-assets

Motivation:

• Generic and future-proof name that describes what it does
• Doesn't tie to specific build tool terminology
• Single flag simplifies the API
• Clear that it's about asset compilation
• Matches Hyde's existing terminology (e.g. "compile static pages")

2. --build-assets

Motivation:

• Aligns with Vite's npm run build command
• Simple and clear purpose
• Common terminology in frontend tooling
• Matches documentation that talks about "building assets"

3. --vite-build

Motivation:

• Explicitly mentions the tool being used
• Clear that it's using Vite's build command
• Matches the actual npm script name
• But: Could be limiting if we switch tools again

I recommend going with --compile-assets because:

1. It's the most tool-agnostic option
2. Simplifies the API by consolidating two flags into one
3. Matches Hyde's existing terminology
4. Clearly communicates purpose to users
5. Won't need changing if build tools change again

The implementation would then just run npm run build since we no longer need separate dev/prod modes with Vite.

---

Regarding potential confusion: Let's explore more specific options that clearly indicate we're building/bundling assets with Vite:

1. --run-vite-build

   • Pros: Very explicit, combines tool and action
   • Cons: Slightly longer

2. --run-bundle

   • Pros: Describes the action without tool specificity
   • Cons: Might be too generic

3. --run-assets-build

   • Pros: Clear purpose without implementation details
   • Cons: Similar to the ambiguity with "build"

I would now recommend --run-vite-build because:

1. It's completely unambiguous - clearly different from the site build
2. Explicitly indicates it's using Vite
3. The "build" part makes it clear we're compiling/bundling, not running the dev server
4. While longer, the clarity is worth it

The longer flag name trades brevity for clarity, which seems appropriate for a command that isn't likely to be typed frequently (and can be abbreviated in scripts when needed).

[caendesilva]

Think I will go with --run-vite to match --run-prettier. I think it's clear enough that we mean it runs the Vite compiler/bundler, not the server, given the context of a final site build.