包简介

Vite helper for Kirby CMS

README 文档

README

Kirby Vite

Bundle your Kirby frontend assets with Vite. The easiest way to get started is using the basic starter kit or the multi-page kit.

Usage

Make sure you have the right setup. Then inside your template files (or anywhere else) you can use the helper functions.

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

Setup

If you want use the plugin without one of the starter kits, you can add it to your existing kirby setup.

Installation

composer require arnoson/kirby-vite

npm install vite vite-plugin-kirby

Development VS Production modes

In development, files are loaded from Vite's dev server. In production, files are injected based on the manifest.json file generated by Vite.

kirby-vite uses a file named .dev (created and removed automatically by vite-plugin-kirby) to determine which mode to use:

when the file exists, it will run in development mode
when the file doesn’t exists, it will run in production mode

Config

All configuration is done in the 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 shares part of this config with Kirby, by dynamically creating a site/config/vite.config.php file.

Asset file paths

Sometimes you might want to access the (hashed) file path of your assets, e.g. to preload fonts. You can do so with vite()->file():

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

Trying

If you try to load a non-existent manifest entry, this plugin will throw an error (if Kirby's debug option is enabled). This is intended behavior, since you usually know which entries exist. But sometimes, especially in a multi-page setup, you may want to try to load an entry only if it exists. You can do this with the try flag:

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

Query Language

Since version v5.3.0 you can use Kirby's query language in your entry names:

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

Note: this will throw errors in debug mode if the assets don't exist. So you might want to use Trying to make the assets optional.

Legacy build

Since version 2.4.0 you can easily support legacy browsers that do not support native ESM. Just add the @vitejs/plugin-legacy plugin to your vite.config.js:

import legacy from '@vitejs/plugin-legacy'

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

Now call kirby-vite's js() helper as usual.

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

which will render:

<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>

Panel CSS/JS

Since version 5.1.0 and Kirby 4 you can bundle your panel assets alongside your other assets with vite. If you need this feature in Kirby 3, consider kirby-laravel-vite.

Add your panel assets to vite:

// vite.config.js

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

And configure Kirby. Make sure to use the ready callback, otherwise you won't be able to call the vite() helpers.

<?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(),
    ],
  ],
];

Checkout the example which includes a panel js/css setup.

Known issue

@vitejs/plugin-legacy will inline the css in the legacy js entry. So users with a legacy browser will download the css twice. See this issue.

Contribution

PRs are welcome! If you are contributing it'd be great if you

use conventional commits, so the release message can be auto-generated (and you are included in it!)
format your code (if you are using vscode, this should happen automatically on save, otherwise use npm run format)

For quick manual testing, checkout the /example which uses the local vite and kirby plugin. When adding new features consider adding/improving tests in /packages/kirby-vite/test (right now we're only testing the kirby plugin).

Thanks :~)

Credits

This plugin is highly inspired by Diverently's Laravel Mix Helper for Kirby and André Felipe's vite-php-setup. Many of the fine tunings I owe to Johann Schopplich and his Kirby + Vue 3 Starterkit.

arnoson/kirby-vite 适用场景与选型建议

arnoson/kirby-vite 是一款基于 PHP 开发的 Composer 扩展包，目前已累计 64.24k 次下载、GitHub Stars 达 97，最近一次更新时间为 2020 年 12 月 15 日，在 PHP 生态内属于活跃度较高的组件。

它主要适用于以下技术方向：「kirby3」「vite」「kirby4」「kirby5」等业务场景。在实际项目中，围绕这些方向常见需要落地的问题包括：接口对接、性能调优、并发安全、与既有框架（Laravel / ThinkPHP / Yii / Webman 等）的兼容适配，以及生产环境的日志埋点与稳定性保障。

我们在过去多个企业项目中使用过 arnoson/kirby-vite 或与其功能相近的方案，如果你在选型或落地过程中遇到问题，例如 版本兼容、二次改造、私有化封装、与内部系统对接、生产 BUG 排查，欢迎联系我们协助评估。

围绕 arnoson/kirby-vite 我们能提供哪些服务？

定制开发 / 二次开发

基于 arnoson/kirby-vite 在你已有业务上做功能扩展、字段裁剪、UI 适配、与内部账号 / 权限 / 日志系统的深度对接。

BUG 修复 & 性能优化

线上偶发问题、内存泄漏、慢查询、并发异常等排查修复；针对高流量场景做缓存、队列、索引层面的调优。

项目外包 & 长期维护

承接完整的项目从需求 → 设计 → 开发 → 上线 → 长期运维；也可按月提供技术保姆服务。

yvsm@zunyunkeji.com QQ：316430983 微信：yvsm316 西安尊云信息科技 · 专注 PHP / Go / 分布式系统研发

与 arnoson/kirby-vite 相关的其它包

同方向 / 同关键字的高下载量 PHP Composer 包推荐，方便对比选型：

idleberg/wordpress-vite-assets 149

Injects assets from a Vite manifest to the Wordpress head, supports themes and plugins

bvdputte/kirby-autopublish 35

Kirby plugin to schedule the automatic publishing of pages on a certain date+time. It is built to work with enabled cache.

beebmx/kirby-courier 40

Courier offers a convenient and painless solution for creating emails tailored for your Kirby website.

beebmx/blade 5

The standalone version of Laravel's Blade templating engine for use outside of Laravel.

carbdrox/pimcore-vite-bundle 2

Pimcore Vite integration

steirico/kirby-plugin-image-crop-field 15

A image cropping field for kirby.

arnoson/kirby-vite

包简介

关键字：