README

A CraftCMS 插件，允许使用 Laravel Mix 来管理资源构建。

要求

PHP 7+
Node.js 6+
CraftCMS 2.5+

安装

手动

下载并安装此插件到您的 CRAFT_PLUGINS_PATH。将目录重命名为 mix 以与插件处理程序相对应。例如，如果您的 CRAFT_PLUGINS_PATH 是 craft/plugins，您可以从项目的根目录运行以下命令

cd craft/plugins
curl -Lo mix.zip https://api.github.com/repos/dnunez24/craft-laravel-mix/zipball
unzip mix.zip

然后从 CraftCMS 管理面板安装插件。

Composer

如果您使用 Composer 管理依赖项，您可以通过从您的 composer.json 文件中要求它来安装此插件。此插件的 composer 包类型为 craft-plugin，因此 Composer 可以将其直接安装到您的 Craft 插件目录。然而，在安装依赖项之前，您必须添加一个额外的配置选项来重命名插件的目标目录。例如，如果您的 CRAFT_PLUGINS_PATH 是 craft/plugins，那么您将需要在您的 composer.json 中添加以下配置

...
    "extra": {
        "installer-paths": {
            "craft/plugins/mix/": [
                "dnunez24/craft-laravel-mix"
            ]
        }
    }
...

有关配置安装期间包的目标的更多信息，请参阅 Composer Installers。

然后只需在 composer.json 文件中添加包并将其安装

composer require dnunez24/craft-laravel-mix

创建一个包含以下内容的 package.json 文件，以安装 Laravel Mix 依赖项并配置资源构建任务。

{
    "private": "true",
    "scripts": {
      "dev": "npm run development",
      "development": "cross-env NODE_ENV=development node_modules/webpack/bin/webpack.js --progress --hide-modules --config=node_modules/laravel-mix/setup/webpack.config.js",
      "watch": "cross-env NODE_ENV=development node_modules/webpack/bin/webpack.js --watch --progress --hide-modules --config=node_modules/laravel-mix/setup/webpack.config.js",
      "watch-poll": "npm run watch -- --watch-poll",
      "hot": "cross-env NODE_ENV=development node_modules/webpack-dev-server/bin/webpack-dev-server.js --inline --hot --config=node_modules/laravel-mix/setup/webpack.config.js",
      "prod": "npm run production",
      "production": "cross-env NODE_ENV=production node_modules/webpack/bin/webpack.js --progress --hide-modules --config=node_modules/laravel-mix/setup/webpack.config.js"
    },
    "devDependencies": {
        "cross-env": "^5.0.0",
        "laravel-mix": "^1.0.0"
    }
}

使用 npm 或 yarn 安装 Node.js 依赖项。

npm install # OR yarn install

配置

为了演示插件的使用，让我们设想一个具有以下目录结构的项目。

...
src/
  assets/
    js/
      main.js
    css/
      main.scss
public/
  js/
  css/
...

在项目的根目录中创建一个 webpack.mix.js 文件来配置 Laravel Mix 以构建您的资源。有关配置细节和更多选项，请参阅 Laravel Mix 文档。务必配置 publicPath 选项以指向您将从中提供静态资源（图像、字体、javascript 和 CSS）的目录。以下是一个示例配置，作为起点，它将适用于之前描述的项目结构

const { mix } = require('laravel-mix');

// this must be the relative path from the webpack.mix.js
// file to your public web directory
mix.setPublicPath('public')
  // outputs built SCSS files to the public/css directory
  .sass('src/assets/css/main.scss', 'public/css')
  // outputs built JS files to the public/js directory
  .js('src/assets/js/main.js', 'public/js');

if (mix.inProduction()) {
  mix.version();
}

此插件还提供 CraftCMS 配置值来设置它使用的公共目录，以便定位和读取 Mix 清单文件。如果您的方法与默认值（CRAFT_BASE_PATH/public）不同，则可能需要覆盖此设置。您可以通过在 CRAFT_CONFIG_PATH/mix.php 中创建一个包含以下内容的文件来完成此操作

<?php

return [
    // set "build" to the name of your public web directory
    'publicDir' => 'build'
];

使用方法

此插件的主要目的是提供模板辅助程序，它们在构建后的资源已知路径和实际路径之间进行转换（这取决于构建模式）。您可以从 CraftCMS 中的 Twig 模板以三种主要方式使用 Mix

{# Twig Filter #}
<script type="text/javascript" src="{{ 'js/main.js' | mix }}"></script>

{# Twig Function #}
<script type="text/javascript" src="{{ mix('js/main.js') }}"></script>

{# CraftCMS Variable #}
<script type="text/javascript" src="{{ craft.mix.getAssetPath('js/main.js') }}"></script>

Mix 有几种不同的运行模式，插件在每个模式下的工作方式不同，如下文所述。

开发模式

开发模式将构建您的资源以针对开发环境。根据您如何配置 Mix，这可能会绕过仅针对生产环境设计的某些构建指令。在示例 webpack.mix.js 文件中，我们仅在生产模式下对资源进行版本控制，用于缓存失效或类似用途。您可以通过在 package.json 文件中添加的 npm 脚本来构建开发模式的资源

npm run dev

这将在我们的示例项目结构中生成以下文件

public/
  mix.js
  mix-manifest.json
  css/
    main.css
  js/
    main.js

然后您可以在模板中使用此插件的 Twig 辅助函数来从 mix-manifest.json 文件加载资源

<link rel="stylesheet" href="{{ mix('css/app.css') }}">
...
<script type="text/javascript" src="{{ mix('js/main.js') }}"></script>

输出

<link rel="stylesheet" href="/css/main.css">
...
<script type="text/javascript" src="/js/main.js"></script>

监控模式

功能与开发模式类似，但 Mix 将作为 NodeJS 的前台进程继续运行，并在检测到源文件更改时构建资源。

npm run watch

热模块替换模式

构建您的资源并运行 Webpack 开发服务器，以允许热模块替换。它与 Laravel Mix 文档中描述的类似。要运行 HMR 模式，请运行以下命令

npm run hot

然后您可以在模板中使用此插件的 Twig 辅助函数来从 Webpack 开发服务器（运行在 //:8080）加载资源

<link rel="stylesheet" href="{{ mix('css/main.css') }}">
...
<script type="text/javascript" src="{{ mix('js/main.js') }}"></script>

输出

<link rel="stylesheet" href="//:8080/css/main.css">
...
<script type="text/javascript" src="//:8080/js/main.js"></script>

生产模式

或为生产打包资源

npm run production

这将在我们的示例项目结构中生成以下文件

public/
  mix-manifest.json
  css/
    main.css
  js/
    main.js

然后您可以在模板中使用此插件的 Twig 辅助函数来从 mix-manifest.json 文件加载资源

<link rel="stylesheet" href="{{ mix('css/main.css') }}">
...
<script type="text/javascript" src="{{ mix('js/main.js') }}"></script>

输出

<link rel="stylesheet" href="/css/main.css?id=3b3bff1760a5005737de">
...
<script type="text/javascript" src="/js/main.js?id=5f474c7493fb1b375dca"></script>

致谢

待办事项

许可证

Craft Laravel Mix 是开源软件，许可协议为 MIT 许可证。

dnunez24 / craft-laravel-mix

维护者

详细信息