kirby-vite
kirby-vite copied to clipboard
arnoson
Use Kirby CMS together with Vite
Kirby Vite Plugin
A set of helper functions to get the correct path to your versioned css and js files generated by Vite.
Use-cases
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!
Getting started
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()->client() ?>
<?= vite()->css() ?>
</head>
<body>
<?= vite()->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
Folder structure
Make sure you use a modern public folder structure.
Development VS Production modes
In development, files are loaded from Vite dev server. In production, files are injected based on the manifest.json file generated by Vite.
Kirby-Vite use a file named .lock in the rootDir (see Options below) to dermine 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
For an example, have a look at the scripts in the package.json.
Alternatively, you can use the dev option below to alter this behavior.
Static assets
Ensure that Vite loads assets like images and fonts from its own server in development by setting server.origin to match Vite server host and port:
// vite.config.js
export default {
// ...
server: {
// ...
origin: 'http://localhost:3000',
}
}
See vite.config.js for a complete example.
Options
'arnoson.kirby-vite' => [
// The default entry that is used when calling `vite()->js()`
// Note: this has to match vite config's `build.rollupOptions.input`
'entry' => 'index.js',
// The source directory for assets served by Vite
// Note: this has to match vite config's `root`
'rootDir' => '/src',
// Wether or not to output legacy bundles automatically (see: Legacy build)
'legacy' => false,
// The output directory for the production assets (js, css, fonts, ...)
// Note: this has to match vite config's `base` and `build.outDir`
'outDir' => 'dist',
// Wether or not to use modern es modules
// Note: if you want to support older browsers you can still enabled es
// modules but enabled the `legacy` option
'module' => true,
// Should be `true` in development to inject Vite client and load assets from
// Vite server; and `false` in production to load them from the manifest.json
// This will override the behavior based on the `.lock` file described above.
'dev' => true,
]
Legacy build
Since version 2.4.0 you can easily support legacy browsers that do not support native ESM.
Therefore add the @vitejs/plugin-legacy plugin to your project and enable the legacy option in your config.php:
'arnoson.kirby-vite.legacy' => true
Now call kirby-vite's js() helper as usual and make sure to add the legacy polyfills:
<!-- your template -->
<?= vite()->js() ?>
<?= vite()->legacyPolyfills() ?>
which will render:
<script
src="http://your-website.org/dist/assets/index.[hash].js"
type="module"
></script>
<script
src="http://your-website.org/dist/assets/index-legacy.[hash].js"
nomodule=""
></script>
<script
src="http://your-website.org/dist/assets/polyfills-legacy.[hash].js"
nomodule=""
></script>
If you want to have more control over where the legacy files are rendered, disable arnoson.kirby-vite.legacy and use kirby-vite's legacy helpers manually:
<?= vite()->js() ?>
<?= vite()->legacyJs() ?>
<?= vite()->legacyPolyfills() ?>
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.
Watch php files
If you also want to live reload your site in development mode whenever you change something in kirby, install vite-plugin-live-reload. Then adjust your vite.config.js:
// vite.config.js
import liveReload from 'vite-plugin-live-reload'
export default {
// ...
plugins: [
liveReload(
'../content/**/*',
'../public/site/(templates|snippets|controllers|models)/**/*.php'
),
],
}
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