README

将 Kirby CMS 与 Vite 一起使用

入门指南

使用方法

请确保您有正确的设置。然后，在您的模板文件（或其他任何位置）中，您可以使用辅助函数。

<html>
  <head>
    <?= vite()->css('index.css') ?>
  </head>
  <body>
    <?= vite()->js('index.js') ?>
  </body>
</html>

设置

如果您想在不使用入门套件的情况下使用此插件，您可以将其添加到现有的 Kirby 设置中。

安装

composer require arnoson/kirby-vite

npm install vite vite-plugin-kirby

开发模式与生产模式

在开发模式下，文件从 Vite 的开发服务器加载。在生产模式下，文件基于由 Vite 生成的 manifest.json 文件注入。

kirby-vite 使用一个名为 .dev 的文件（由 vite-plugin-kirby 自动创建和删除）来决定使用哪种模式

当该文件存在时，它将运行在开发模式下
当该文件不存在时，它将运行在生产模式下

配置

所有配置都在 vite.config.js 中完成

// vite.config.js
import kirby from 'vite-plugin-kirby'

export default ({ mode }) => ({
  // During development the assets are served directly from vite's dev server
  // e.g. `localhost:5173/index.js`, but for production they are placed inside
  // the `build.outDir`, `/dist/` in this case.
  base: mode === 'development' ? '/' : '/dist/',

  build: {
    // Where your manifest an bundled assets will be placed. This example
    // assumes you use a public folder structure.
    outDir: 'public/dist',
    assetsDir: 'assets',

    // Your entry file(s).
    // Note: CSS files can either be a separate entry. In this case you use it
    // like this: `<?= vite->css('main.css') ?>`. Or you can only add the
    // `main.js` as an entry and import the CSS in your JS file. In this case
    // you would use the JS file name: `vite()->css('main.js')`.
    rollupOptions: {
      input: ['main.js', 'main.css']
    }
  },

  plugins: [kirby({
    // By default Kirby's templates, snippets, controllers, models, layouts and
    // everything inside the content folder will be watched and a full reload
    // triggered. All paths are relative to Vite's root folder.
    watch: [
      '../site/(templates|snippets|controllers|models|layouts)/**/*.php',
      '../content/**/*',
    ],
    // or disable watching
    watch: false,

    // Where the automatically generated `vite.config.php` file should be
    // placed. This has to match Kirby's config folder!
    kirbyConfigDir: 'site/config' // default
  })],
})

vite-plugin-kirby 通过动态创建一个 site/config/vite.config.php 文件，与 Kirby 共享部分配置。

资产文件路径

有时您可能需要访问资产（哈希）文件路径，例如预加载字体。您可以使用 vite()->file() 来这样做

 <link rel="preload" href="<?= vite()->file('my-font.woff2') ?>" as="font" type="font/woff2" crossorigin>

尝试

如果您尝试加载一个不存在的清单条目，此插件将抛出错误（如果启用 Kirby 的 debug 选项）。这是预期行为，因为您通常知道哪些条目存在。但有时，尤其是在多页面设置中，您可能只想在条目存在时尝试加载条目。您可以使用 try 标志来完成此操作

vite()->js('templates/' . $page->template() . '.js', try: true);
vite()->css('templates/' . $page->template() . '.css', try: true);
vite()->file('maybe.woff2', try: true);

查询语言

从版本 v5.3.0 开始，您可以在条目名称中使用 Kirby 的查询语言

vite()->js('templates/{{ page.template }}.js');
vite()->css('templates/{{ page.template }}.css');

注意：如果在调试模式下资产不存在，这将抛出错误。因此，您可能想使用尝试使资产可选。

遗留构建

从版本 2.4.0 开始，您可以轻松支持不支持原生 ESM 的遗留浏览器。只需将 @vitejs/plugin-legacy 插件添加到您的 vite.config.js。

import legacy from '@vitejs/plugin-legacy'

// vite.config.js
export default {
  // ...
  plugins: [
    // ...
    legacy(),
  ],
}

现在像往常一样调用 kirby-vite 的 js() 辅助函数。

<!-- your template -->
<?= vite()->js('index.js') ?>

这将渲染

<script
  src="https://your-website.org/dist/assets/polyfills-legacy.[hash].js"
  nomodule=""
></script>
<script
  src="https://your-website.org/dist/assets/index-legacy.[hash].js"
  nomodule=""
></script>
<script
  src="https://your-website.org/dist/assets/index.[hash].js"
  type="module"
></script>

面板 CSS/JS

从版本 5.1.0 和 Kirby 4 开始，您可以使用 Vite 将面板资产与其他资产一起打包。如果您需要在 Kirby 3 中使用此功能，请考虑 kirby-laravel-vite。

将面板资产添加到 Vite

// vite.config.js

export {
  // ...
  build: {
    rollupOptions: { input: ['src/your-other-assets.js', 'src/panel.js'] },
  },
}

并配置 Kirby。请确保使用 ready 回调，否则您将无法调用 vite() 辅助函数。

<?php return [
  'ready' => fn() => [
    'panel' => [
      // If you have a `panel.js` file, that imports the `panel.css` file:
      'css' => vite()->panelCss('panel.js'),
      'js' => vite()->panelJs('panel.js'),

      // If you only have a `panel.css` without a js file you must still use
      // `vite()->panelJs()`, as this injects the vite client in development.
      'css' => vite()->panelCss('panel.css'),
      'js' => vite()->panelJs(),
    ],
  ],
];

查看示例，其中包含面板 js/css 设置。

已知问题

@vitejs/plugin-legacy 将在旧版 JavaScript 入口中内联 CSS。因此，使用旧版浏览器的用户将下载 CSS 两次。查看此问题。

贡献

欢迎提交改进请求！如果你在贡献，以下建议将非常好：

使用常规提交，这样发布信息可以自动生成（并且你也会被包括在内！）
格式化你的代码（如果你使用的是 vscode，保存时应该会自动格式化，否则请使用 npm run format）

为了快速手动测试，请检查 /example，它使用了本地的 vite 和 kirby 插件。在添加新功能时，考虑在 /packages/kirby-vite/test 中添加/改进测试（目前我们只测试 kirby 插件）。

谢谢 :~)

致谢

此插件深受 Diverently 的 Laravel Mix Helper for Kirby 和 André Felipe 的 vite-php-setup 的启发。许多微调都归功于 Johann Schopplich 和他的 Kirby + Vue 3 Starterkit。

arnoson / kirby-vite

维护者

详情