README

安装后，您可以使用 vite() 辅助函数将 Vite 资产包含到您的 Kirby 项目中。此插件与 laravel-vite-plugin 配合最佳。

<!doctype html>
<head>
  <?= vite(['assets/css/app.css', 'assets/js/app.js']) ?>
</head>

注意
一些功能尚未得到适当文档。如果您认为缺少某些内容，请随时浏览源代码。

安装

Composer

composer require lukaskleinschmidt/kirby-laravel-vite

Git 子模块

git submodule add https://github.com/lukaskleinschmidt/kirby-laravel-vite.git site/plugins/laravel-vite

下载

下载并将此存储库复制到 /site/plugins/laravel-vite。

安装 Laravel Vite 插件

Laravel Vite 插件的文档可以在 Laravel 网站上找到。

npm install --save-dev laravel-vite-plugin

import { defineConfig } from 'vite';
import laravel from 'laravel-vite-plugin';

export default defineConfig({
  plugins: [
    laravel(['assets/css/app.css', 'assets/js/app.js']),
  ],
});

保存时刷新

当您的应用程序使用传统的服务器端渲染构建时，Vite 可以通过在您更改应用程序中的模板或片段文件时自动刷新浏览器来改进您的开发工作流程。要开始使用，您只需指定刷新选项即可。

export default defineConfig({
  laravel({
    input: [
      'assets/css/app.css',
      'assets/js/app.js',
    ],
    refresh: [
      'site/templates/**',
      'site/snippets/**',
    ],
  }),
});

自动加载特定模板的资产

如果您为资产使用了 @auto 选项，您也可以对可选资产执行相同的操作。

可选资产

当您使用 Kirby 查询语言 或在资产前加上 @ 时，这些资产被视为可选。这意味着插件将仅包含在给定源路径中实际存在的资产。

<!doctype html>
<head>
  <?= vite([
    // Using the Kirby Query Language
    'assets/css/templates/{{ page.template }}.css',
    'assets/js/templates/{{ page.template }}.js',

    // Equivalent to this
    '@assets/css/templates/' . $page->template() . '.css',
    '@assets/js/templates/' . $page->template() . '.js',
  ]) ?>
</head>

注意
请记住在 vite 中也包含可选资产，以确保它们在捆绑后真正可用。未包含在 vite 中的资产在 开发模式 下将工作，但在捆绑时不会工作。

export default defineConfig({
  laravel([
    'assets/css/app.css',
    'assets/css/templates/home.css',
    'assets/js/app.js',
    'assets/js/templates/home.js',
  ]),
});

自定义面板脚本和样式

注意自 1.1.0 版起可用

您可以使用 vite 来处理您的 panel.css 或 panel.js。由于插件需要 Kirby 实例才能工作，您需要在 ready 回调中定义资产才能使用 vite() 辅助函数。

return [
    'ready' => fn () => [
        'panel' => [
            'css' => vite('assets/css/panel.css'),
            'js'  => vite([
                'assets/js/feature.js',
                'assets/js/panel.js',
            ]),
        ],
    ]
];

注意
请记住在 vite 中也包含可选的面板资产，以确保它们在捆绑后真正可用。未包含在 vite 中的资产在 开发模式 下将工作，但在捆绑时不会工作。

export default defineConfig({
  laravel([
    'assets/css/panel.css',
    'assets/js/feature.js',
    'assets/js/panel.js',
  ]),
});

React

如果您使用 React 框架构建前端，您还需要在现有的 vite() 调用之外调用额外的 vite()->reactRefresh() 方法。

<?= vite()->reactRefresh() ?>
<?= vite('assets/js/app.jsx') ?>

vite()->reactRefresh() 方法必须在 vite() 调用之前调用。

使用 Vite 处理静态资产

当在 JavaScript 或 CSS 中引用资产时，Vite 会自动处理和版本化它们。此外，当您的应用程序使用传统的服务器端渲染构建时，Vite 还可以处理和版本化您在模板中引用的静态资产。

但是，为了实现这一点，您需要通过将静态资产导入应用程序的入口点来让 Vite 了解您的资产。例如，如果您想处理和版本化存储在 assets/images 中的所有图像和存储在 assets/fonts 中的所有字体，您应该在应用程序的 assets/js/app.js 入口点中添加以下内容

import.meta.glob([
  '../images/**',
  '../fonts/**',
]);

这些资产现在将在运行 npm run build 时由 Vite 处理。您可以使用 vite()->asset() 方法在模板中引用这些资产，该方法将返回给定资产的版本化 URL。

<img src="<?= vite()->asset('assets/images/logo.png') ?>">

任意属性

如果您需要在脚本和样式标签上包含额外的属性，例如 data-turbo-track 属性，您可以通过插件选项指定它们。

return [
    'lukaskleinschmidt.laravel-vite' => [
        'scriptTagAttributes' => [
            'data-turbo-track' => 'reload', // Specify a value for the attribute...
            'async'            => true,     // Specify an attribute without a value...
            'integrity'        => false,    // Exclude an attribute that would otherwise be included...
        ],
        'styleTagAttributes' => [
            'data-turbo-track' => 'reload',
        ],
    ],
];

如果您需要条件性地添加属性，您可以通过一个回调函数传递，该回调函数将接收资产源路径、其 URL、其清单块和整个清单。

return [
    'lukaskleinschmidt.laravel-vite' => [
        'scriptTagAttributes' => fn (string $src, string $url, array $chunk, array $manifest) => [
            'data-turbo-track' => $src === 'assets/js/app.js' ? 'reload' : false,
        ],
        'styleTagAttributes' => fn (string $src, string $url, array $chunk, array $manifest) => [
            'data-turbo-track' => $chunk && $chunk['isEntry'] ? 'reload' : false,
        ],
    ],
];

注意
在 Vite 开发服务器运行时，$chunk 和 $manifest 参数将为空。

高级自定义

默认情况下，Laravel 的 Vite 插件使用合理的约定，应该适用于大多数应用程序。但是，有时您可能需要自定义 Vite 的行为。要启用额外的自定义选项，您可以使用以下选项

return [
    'lukaskleinschmidt.laravel-vite' => [
        'hotFile'        => fn () => kirby()->root('storage') . '/vite.hot',
        'buildDirectory' => 'bundle',
        'manifest'       => 'assets.json',
    ],
];

注意如果您需要访问 Kirby 实例，可以使用回调函数来定义选项。或者，您可以在 Kirby 的 ready 回调或直接在模板中配置 Vite。

use LukasKleinschmidt\Vite;

return [
    'ready' => function () {
        Vite::instance()
            ->useHotFile(kirby()->root('storage') . '/vite.hot')
            ->useBuildDirectory('bundle')
            ->useManifest('assets.json');
    },
];

<!doctype html>
<head>
  <?=
    vite()->useHotFile($kirby->root('storage') . '/vite.hot')
          ->useBuildDirectory('bundle')
          ->useManifest('assets.json')
          ->withEntries(['assets/js/app.js'])
  ?>
</head>

然后，在 vite.config.js 文件中，您应该指定相同的配置

import { defineConfig } from 'vite';
import laravel from 'laravel-vite-plugin';

export default defineConfig({
    plugins: [
        laravel({
            hotFile: 'storage/vite.hot',
            buildDirectory: 'bundle',
            input: [
              'assets/js/app.js',
            ],
        }),
    ],
    build: {
      manifest: 'assets.json',
    },
});

商业用途

此插件免费，但如果您在商业项目中使用它，请考虑进行捐赠。

许可证

MIT

致谢

大部分文档已从 Laravel 网站复制并适配到 Kirby 实现。

lukaskleinschmidt / kirby-laravel-vite

维护者

详细信息