[WIP] Integrate Vite & Rework Mix

[jaxwilko]

This PR implements support for Vite side by side with Mix. All exsiting Mix functionality has been retained, but all the commands have been abstracted to allow for re-use by Vite. This allows for full support of both compilers, at the same time.

Modified

• Commands
  • mix:compile, mix:watch, mix:install, mix:list all now rely on abstract Asset* commands and inherit 90% of the functionality to allow for Vite* commands to reuse the same code.
  • mix:run & mix:update - these were used for interacting with npm via the Winter CLI, these have been renamed to refelect their function to npm:run & npm:update. Alias have been set to refer back to their previous names incase anybody is using them in scripts.

New

• Commands
  • vite:compile - shares args with mix:compile called vite build under the hood
  • vite:watch - shares args with mix:watch called vite under the hood (defaults to "watching")
  • vite:install - shares args with mix:install allows for configuring package.json workspaces and installing required global packages
  • vite:list - shares args with mix:list
  • vite:config - new allows for setting up stub files
  • mix:config - new allows for setting up stub files
• System\Classes\PackageJson - Now provides a consistant interface for modifying package.json files rather than using json_encode/json_decode everywhere
• Twig function vite() has been added, this works similarly to Laravel's @vite() in blade, however it required the base path to also be passed.

Docs

Add a vite.config.js file to whatever package (plugin, theme, module) you want, then expect the same behaviour as you would with the mix:* commands, but with vite:* instead. This can be done for you via the vite:config command.

When using Vite, to load your assets in your markup you need to use the new vite() function. It takes 2 arguments, an array of entry points, and the package name for where the assets are loaded from.

This should end up looking like:

{{ vite(['assets/css/theme.css', 'assets/javascript/theme.js'], 'theme-example') }}

Note: The default vite port is 5173, you should ensure that port is open. If you are running multiple vite:watch commands at the same time, the port will increment with each watch, so open those ports too if required.

Vite can also be used in the backend:

<?= \System\Classes\Vite::tags(['assets/css/example-plugin.css'], 'example.plugin') ?>

TODO

• Testing
  • Fresh install
  • Fresh plugin
  • Fresh theme
  • Linux
  • Mac
  • Windows
• Vite TestCases
• *:config TestCases

[bennothommo]

Couple of initial comments:

• Perhaps we could add *:build and *:dev command aliases to *:compile and *:watch commands, respectively. Both terms are more commonly used for JS libraries.
• If we're going to be separating the run and update commands under an npm namespace, then install should probably go under there too. Perhaps we should abstract that command to be able to define which path the user wants to go down (ie. install Mix or install Vite).
• With the vite command in Twig, I would think we can determine the theme's base path automatically. Is there any specific reason why we need to define it explicitly?

[jaxwilko]

@bennothommo

• Perhaps we could add *:build and *:dev command aliases to *:compile and *:watch commands, respectively. Both terms are more commonly used for JS libraries.

100% agree, makes sense.

• If we're going to be separating the run and update commands under an npm namespace, then install should probably go under there too. Perhaps we should abstract that command to be able to define which path the user wants to go down (ie. install Mix or install Vite).

Install isn't just installing packages, it's validating the configs are set and adding packages to workspaces, then adding deps if required, I kinda like how it is atm, although maybe it should be named something different.

• With the vite command in Twig, I would think we can determine the theme's base path automatically. Is there any specific reason why we need to define it explicitly?

Yes for theme, maybe for plugins, and maybe for somebody adding assets from a plugin to a theme (idk why but they could). All these edge cases are solved by just setting the same base that we pass when executing the command. Basically the php side needs to match up with the js web socket server. We could default to a guess, but it may cause more confusion when it fails than just setting a path and being done with it.

[bennothommo]

Thanks for the feedback @jaxwilko.

Install isn't just installing packages, it's validating the configs are set and adding packages to workspaces, then adding deps if required, I kinda like how it is atm, although maybe it should be named something different.

That's cool by me. I just would like a rational and natural way for someone to "update" their dependencies - especially with the frequency of JS libraries and their dependencies being affected by security vulnerabilities. I suppose that npm:update would work - perhaps allowing us to reserve vite:upgrade for doing more thorough upgrades to Vite if, say, down the track we need to make configuration changes as part of an upgrade process (ie. allowing the command to do major upgrades to Vite).

Yes for theme, maybe for plugins, and maybe for somebody adding assets from a plugin to a theme (idk why but they could). All these edge cases are solved by just setting the same base that we pass when executing the command. Basically the php side needs to match up with the js web socket server. We could default to a guess, but it may cause more confusion when it fails than just setting a path and being done with it.

I've been thinking about this exact scenario for some time - pretty much since we introduced Mix. I think the easiest way we can move forward on this is that we have to consider that each plugin and theme is responsible for its own build and assets and that's it. The fact is, not everyone is going to write plugins and components that work nicely with every type of build used by themes, especially when our goal with the CMS side is that "people can use whatever front-end framework they want".

As you said too, people can have the plugins (or at the very least, the components) inject assets into the theme when used. I still would argue that it would be most likely that the "entrypoint" to these assets would still reside in the theme if they built the plugins themselves. For third-party plugins, it's fair game for them to have their own build process and you simply use the compiled assets (or perhaps the build process in the theme could concatenate/minify these assets into the theme build). Either way, I think they're both out of scope for the vite filter you would be introducing.

So I wonder if we can just simplify the vite filter to assume all paths are relative to the theme, and make it so that the entrypoints always exist within the theme (these entrypoints can however import plugin assets however they wish).

Thoughts on this?

[jaxwilko]

I don't think vite will play ball, unless we only enable vite for themes and not plugins (which was my first thought before I was able to get plugins working too).

By all means have a play with it, but I think currently just adding the base covers all possible situations with the most flexibility.

[jaxwilko]

@LukeTowers @bennothommo the param ordering for getPackages() has been swapped. I've also added some extra helpers to CompilableAssets & PackageJson to simplify logic in some commands.

[LukeTowers]

@mjauvin do you feel like having a play around with this to help test it?

[mjauvin]

You all know the love I have for npm... why do you even ask? 😂

[jaxwilko]

@bennothommo had a thought, what if we swap the "base path thing" for the package name, i.e. theme-example or winter.test, then resolve the base via CompilableAssets.

That way it makes a lot more sense as you're "loading entry files from this package".

Any thoughts?

[bennothommo]

That sounds a lot better. I still think it can default to the theme base path, but yeah having it allow the theme and plugin codes that Mix uses would give that extra flexibility in a simple way. 👍

[LukeTowers]

You all know the love I have for npm... why do you even ask? 😂

That's why I ask 😂

[jaxwilko]

I've put together a simple testing guide to try out vite + the new config command.

Set up a testing plugin, configure it and add stubs:

./artisan create:plugin Example.Test
./artisan create:component Example.Test Testing
./artisan vite:config Example.Test --tailwind --stubs
./artisan vite:install

echo  -e "<p class=\"text-red-900\">hello world</p>\n{{ vite(['assets/css/example-test.css'], 'example.test') }}" > plugins/example/test/components/testing/default.htm

Enable the component in the plugin:

return [
    \Example\Test\Components\Testing::class => 'testing',
];

Add the component to one of your pages:

...
[testing]
...
==
...
{% component testing %}
...

Run vite:

./artisan vite:watch example.test

[bennothommo]

No need to double-up @return doc with return type definition, unless you want to specify some additional content for the return doc.

Suggested change

* @return \Illuminate\Support\HtmlString

[jaxwilko]

I'll go through and remove all of them where relevant :)

[jaxwilko]

I've added a helper so you can run vite in the backend too.

<?= \System\Classes\Vite::tags(['assets/css/example-plugin.css'], 'example.plugin') ?>