A set of helper functions to get the correct path to your versioned css and js files generated by Vite.
You can use kirby-vite for a single or multi-page vanilla js setup or as a basis for an SPA setup. If you plan to use Kirby together with Vue 3 also checkout Johann Schopplich's Kirby + Vue 3 Starterkit!
The easiest way to get started is using the basic starter kit or the multi-page kit.
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>If you want use the plugin without one of the starter kits, you can add it to your existing kirby setup.
composer require arnoson/kirby-vite
npm install vite vite-plugin-kirby
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
All configuration is done in the vite.config.js:
// vite.config.js
import kirby from 'vite-plugin-kirby'
export default {
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.
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>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 behaviour, 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() . '/index.js', try: true);
vite()->css('templates/' . $page->template() . '/index.css', try: true);
vite()->file('maybe.woff2', try: true);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>@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.
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.