Repository files navigation

The plugin provides a Helper Class for CakePHP to facilitate the use ofVite JS.

When running the Vite dev server, the Helper provides the right script tags for hot module replacement and pagereloading.

In production mode, the Helper loads the bundled files.@vitejs/plugin-legacy is supported, which willinsertnomodule-tags for older browsers, e.g. older iOS devices, which do not support js modules.

This readme is forversion 1.x. If you are migrating from 0.x and something is unclear, read the Migration guideunder/docs. Feel free to open an issue if you run into problems.

You can install this plugin into your CakePHP application usingcomposer.

The recommended way to install the plugin is:

composer require passchn/cakephp-vite

Load the plugin in your Application.php:

bin/cake plugin load ViteHelper

Load the Helper in your AppView.php:

$this->loadHelper('ViteHelper.ViteScripts');

In your php-layout, include this in your html head:

<?=$this->fetch('css')?>

Just before the closing</body> tag, insert this line:

<?=$this->fetch('script')?>

These are the default view blocks in CakePHP.Lern more about view blocks in the Book.

In your php-template or in layout you can import javascript files with:

<?php$this->ViteScripts->script($options)?>

… or by using this shortcut for a single entrypoint:

<?php$this->ViteScripts->script('webroot_src/main.ts')?>

If you imported CSS files inside your JavaScript files, this method automaticallyappends your css tags to the css view block.

If you don't have any css-entries defined in your vite-config, you can skip the::css() method call.

In your php-template you can import css files with:

<?php$this->ViteScripts->css($options)?>

… or by using this shortcut for a single entrypoint:

<?php$this->ViteScripts->css('webroot_src/style.css')?>

The plugin comes with some default configuration. You may need to change it depending on your setup. Or you might notneed any config at all.

You can override some of these config settings through the$options of the helper methods. Or you can passyour own instance ofViteHelperConfig to a helper method as a second parameter.

'ViteHelper' => ['build' => ['outDirectory' =>false,// output directory of build assets. string (e.g. 'dist') or false.'manifest' =>WWW_ROOT .'manifest.json',// absolute path to manifest    ],'development' => ['scriptEntries' => ['someFolder/myScriptEntry.ts'],// relative to project root'styleEntries' =>  ['someFolder/myStyleEntry.scss'],// relative to project root. Unnecessary when using css-in-js.'hostNeedles' => ['.test','.local'],// to check if the app is running locally'url' =>'http://localhost:3000',// url of the vite dev server    ],'forceProductionMode' =>false,// or true to always serve build assets'plugin' =>false,// or string 'MyPlugin' to serve plugin build assets'productionHint' =>'vprod',// can be a true-ish cookie or url-param to serve build assets without changing the forceProductionMode config'viewBlocks' => ['css' =>'css',// name of the css view block'script' =>'script',// name of the script view block    ],],

You can override the defaults in yourapp.php,app_local.php, orapp_vite.php.

See the plugin'sapp_vite.php for reference.

Example:

return ['ViteHelper' => ['forceProductionMode' =>1,'development' => ['hostNeedles' => ['.dev'],// if you don't use one of the defaults'url' =>'https://192.168.0.88:3000',        ],    ],];

You can pass an$options array to override config or to completely skip the necessity to have a ViteHelper config.

The options are mostly the same for::script() and::css().

$this->ViteScripts->script([// this would append both the scripts and the css to a block named 'myCustomBlock'// don't forget to use the block through $this->fetch('myCustomBlock')'block' =>'myCustomBlock','cssBlock' =>'myCustomBlock',// for ::script() only – if you use css imports inside js.// files that are entry files during development and that should be served during production'files' => ['webroot_src/main.ts',    ],// "devEntries" is like "files". If you set "files", it will override both "devEntries" and "prodFilters"'devEntries' => ['webroot_src/main.ts']// "prodFilter" filters the entry files. Useful for code-splitting if you don't use dynamic imports'prodFilter' =>'webroot_src/main.ts'// as string if there's only one option    'prodFilter' =>'main.ts'// also works - only looks for parts of the string    'prodFilter' => ['main.ts']// as array - same as above with multiple files'prodFilter' =>function (ManifestRecord$record) {/* do something with the record and return true or false */ }]);

Note: You need to setdevEntries when running the dev server. They have to either be set in the config orthrough the helper method. In contrast, you only needfiles orprodFilter if you are interested in php-sidecode-splitting and don't use dynamic imports in js.

It depends on your project and use case how you define entries. If you don't useprodFilter orfiles, the pluginwill serve all your entry files which might just be the case you want. So don't overconfigure it ;)

You can use the helper methods with multiple configurations through the$config argument.

New in version 2.3: You can pass a config key instead of a config instance to the helper. The default config keyisViteHelper.

This might be useful when using plugin scripts or when developing plugins:

<?php$this->ViteScripts->pluginScript('MyPlugin', devMode:true, config:'MyPlugin.ViteConfig');?>

The example above uses a convenience method to load plugin scripts forMyPlugin. DevMode is enabled and the helperwill use a CakePHP config under the keyMyPlugin.ViteConfig. In this way, you can scope your App's and your plugin'sconfig.

It is assumed that themanifest.json is available directly in your plugin'swebroot. If this is not the case, youshould define the absolute path throuh thebuild.manifest config option.

Install Vite e.g. via yarn:

yarn create vite

It is recommended to add the legacy plugin:

yarn add -D @vitejs/plugin-legacy

SeeScaffolding Your First Vite Project on vitejs.devfor more information.

After installing, you will need to refactor the files a bit to make sense of it in a php project. The default config ofthis plugin assumes that you put your js, ts, scss etc. in/webroot_src.

The build files will end up in/webroot/assets by default. Yourvite.config.js or *.ts file for vite stays in theproject root.

Wanted: Examples for vite/plugin configs and directory structures. Feel free to contribute with a PR to show how yourproject uses this plugin.

See the examplevite.config.ts content here. Notethat the config changes when upgrading to vite version2.9.0 or higher.

A difference to other dev servers, e.g. webpack or gulp is that you won't access yourlocal site via the port where Vite is serving. This does not work with php.

Therefore, theserver.hmr config will enable you to use hot module replacement via the websocket protocol.

Thebuild options define where the bundled js and css will end up. These need to match plugin config.

More about configuring Vite can be found atvitejs.dev/config.

You can contribute to this plugin via pull requests. If you run into an error, you can open an issue.