Support Laravel Mix

[LukeTowers]

This directly relates to #401 and is being broken out to be it's own item on the 2022 Roadmap:

Support for Laravel Mix in Winter CMS:

The bare minimum in order to start using Laravel Mix in Winter CMS should be the presence of a winter.mix.js file.

This file can be autodetected under the following locations:

• modules/*/winter.mix.js
• plugins/*/*/winter.mix.js
• themes/*/winter.mix.js

When winter.mix.js files are detected they will be automatically registered as a mix package in the form of $packageName => $pathToWinterMixJs.

The package name for automatically generated packages should follow the below structure:

• Module: module-$name
• Plugin: $Author.$Name
• Theme: theme-$themeCode

Packages should also be able to be registered manually via the currently present options (i.e. registerCallback() -> registerPackage(), Plugin.php -> registerMixAssets(), and the mix property in the theme definition YAML file).

Registration should require the $packageName as the first argument and the $pathToWinterMixJsFile as the second.

QUESTION: If winter.mix.js does not exist at the target location for a given package (only applicable to manually registered packages of course) should one be automatically generated? I lean towards yes, and also think that it would be a good idea if mix:install would accept an additional argument for the package code and if it matches an autogenerated code format and doesn't already exist then it should be created automatically so that the next runs will pick it up in the auto scan.

mix:install --template=$template

NOTE: The template option (naming totally open for suggestions) should allow a preset template to be used to bootstrap a given environment for the package. Ex. --template=tailwind[,vue] would add the necessary dependencies to that package's package.json as well as the winter.mix.js file and any other files that should be created as a part of that template (i.e. tailwind.config.js. Examples below for the Tailwind template:

tailwind.config.js

const defaultTheme = require('tailwindcss/defaultTheme')

module.exports = {
    content: [
        './theme.yaml',
        './layouts/*.htm',
        './layouts/**/*.htm',
        './pages/*.htm',
        './pages/**/*.htm',
        './partials/*.htm',
        './partials/**/*.htm',
        './content/static-pages/*.htm',
        './content/static-pages/**/*.htm',
    ],
}

winter.mix.js:

let mix = require('laravel-mix');
mix.setPublicPath(__dirname);

mix.postCss('assets/css/src/base.css', 'assets/css/dist/theme.css', [
    require('tailwindcss'),
]);

package.json

{
    "private": true,
    "devDependencies": {
        "autoprefixer": "^10.4.0",
        "laravel-mix": "^6.0.6",
        "lodash": "^4.17.19",
        "postcss": "^8.4.5",
        "tailwindcss": "^3.0.7"
    },
}

Running this command will collect all of the Mix package registrations, automatically detected and manually registered; and then populate the root package.json's workspaces.packages property with the paths to the directories that contain the registered winter.mix.js files.

QUESTION: Should providing custom names for winter.mix.js even be supported / should we support registering multiple mix packages in the same directory? I'm leaning towards no to both questions personally.

If the root package.json does not define any dependencies (or if the required laravel-mix dependency isn't present) then the necessary dependencies for laravel-mix to function should be injected as well.

QUESTION: How can we protect ourselves against future major changes to Laravel Mix in terms of upgrading to newer versions of Laravel Mix when running the command to setup new packages vs supporting older versions present in packages created using older versions of Laravel Mix?

Once the package.json file has been updated with the workspaces (and optionally the dependencies) then npm install should be run within the root.

mix:compile --packages=comma,separated,package,names --production -- $webpackArgs

Running this command will collect all of the mix package registrations (or just the provided packages), double check that they are each present in the root package.json's workspaces.packages property (throw helpful error if not to run mix:install first), and execute the mix compile on each package in turn (generate webpack file, execute webpack, remove webpack file)

mix:watch $package --production -- $webpackArgs

NOTE: -- $webpackArgs is specifically needed for -- --watch-options-poll=1000 on virtualized filesystems with no support for the regular watch methods (typically Homestead running on Windows), see https://laravel-mix.com/docs/6.0/upgrade

The same as `mix:compile but watches for changes to the asset files and carries on from there.

@jaxwilko @bennothommo Eager to here your feedback on this revised specification for the mix commands; It's a pretty complicated set of tools that we're aiming to make extremely simple and easy to use for our end users so I appreciate the patience as we figure out the ideal way to structure it for the future of the project.

[LukeTowers]

Implemented in #444 and #401