README

A Vite plugin and CakePHP helper that connect a Vite build to a CakePHP application. The plugin produces a single JSON manifest that the helper reads to emit the correct <script> and <link> tags in both development and production.

Requirements

Dependency	Version
PHP	≥ 8.3
CakePHP	^4.5
Vite	^6.0

Installation

composer require chialab/vite-cakephp

The Vite plugin ships inside the Composer package — no separate npm install is needed.

Setup

1. Bootstrap the plugin

// src/Application.php
public function bootstrap(): void
{
    parent::bootstrap();
    $this->addPlugin('Chialab/Vite');
}

2. Load the helper

// src/View/AppView.php
public function initialize(): void
{
    parent::initialize();
    $this->loadHelper('Chialab/Vite.Vite');
}

Pass configuration options as the second argument if the defaults do not match your project layout (see PHP helper options):

$this->loadHelper('Chialab/Vite.Vite', [
    'buildPath' => ROOT . '/webroot/dist',
    'basePath' => '/dist/',
]);

3. Configure Vite

// vite.config.js
import { defineConfig } from 'vite';
import { vitePhp } from './vendor/chialab/vite-cakephp/vite-plugin-php.js';

export default defineConfig({
    build: {
        outDir: 'webroot/dist',
    },
    plugins: [
        vitePhp([
            {
                name: 'app',
                outDir: 'webroot/dist',
                publicPath: '/dist',
                inputs: {
                    home:    'resources/pages/home.ts',
                    product: 'resources/pages/product.ts',
                    styles:  'resources/css/global.css',
                },
            },
        ]),
    ],
});

Usage

Call js() and css() independently in your layout or view templates. The logical entry name is {group.name}/{entry}:

// Layout or view
<?= $this->Vite->js('app/home') ?>
<?= $this->Vite->css('app/home') ?>

{{ Vite.js('app/home') }}
{{ Vite.css('app/home') }}

Both methods return an empty string when the manifest file is absent (no dev server running, no build present), so they are always safe to call.

CSS-only and JS+CSS entries

// Emit only the stylesheet link for a CSS-only entry
<?= $this->Vite->css('app/styles') ?>

// Emit both script and stylesheet for a JS+CSS entry
<?= $this->Vite->js('app/product') ?>
<?= $this->Vite->css('app/product') ?>

Configuration reference

Vite plugin options

vitePhp(inputs: BuildGroup[]) accepts an array of build groups.

BuildGroup

Each group maps to one Rollup build with its own output directory, public URL, and entry files.

Field	Type	Default	Description
name	string	—	Namespace prefix for logical entry names, e.g. "app".
inputs	Record<string, EntryInput>	—	Local entry name → source file mapping (see below).
outDir	string	—	Output directory for this group's assets, relative to the project root.
publicPath	string	—	Public URL base where outDir is served (baked into the manifest paths).
format	"es" | "iife"	"es"	Build format. "iife" produces a self-contained bundle suitable for file:// pages.
external	string[]	[]	External module IDs (meaningful for "iife" groups).

EntryInput

Each entry in inputs can be written in two ways:

// String shortcut: extension determines the slot
'resources/pages/home.ts'        // → { js: 'resources/pages/home.ts' }
'resources/css/global.css'       // → { css: 'resources/css/global.css' }

// Explicit slots object: JS and CSS bundled as one logical entry
{ js: 'resources/pages/home.ts', css: 'resources/pages/home.css' }

Multiple groups example

vitePhp([
    {
        // ESM group: shared vendor chunk, tree-shaken per page.
        name: 'app',
        outDir: 'webroot/dist',
        publicPath: '/dist',
        inputs: {
            home:    'resources/pages/home.ts',
            product: { js: 'resources/pages/product.ts', css: 'resources/pages/product.css' },
            styles:  'resources/css/global.css',
        },
    },
    {
        // IIFE group: self-contained, no shared chunks, works under file://.
        name: 'embed',
        format: 'iife',
        outDir: 'webroot/dist/embed',
        publicPath: '/dist/embed',
        inputs: {
            widget: 'resources/embed/widget.ts',
        },
    },
]),

Logical names for the above: app/home, app/product, app/styles, embed/widget.

PHP helper options

Option	Type	Default	Description
buildPath	string|null	WWW_ROOT . 'dist'	Absolute filesystem path to the build directory (where Vite writes outDir).
basePath	string	'/dist/'	Public URL prefix prepended to relative paths from the manifest. A leading / is resolved relative to the application base by HtmlHelper.
fileName	string	'.vite/php.json'	Path to the manifest file, relative to buildPath.

buildPath must match the outDir you configure in Vite. For example, if Vite writes to webroot/dist, set buildPath to WWW_ROOT . 'dist' (the default) or an equivalent absolute path.

Runtime behaviour

The plugin writes a single file — {outDir}/.vite/php.json — whose mode field drives the helper's behaviour.

Development

Start the Vite dev server normally:

npx vite

On server start the plugin writes:

{
    "mode": "development",
    "origin": "http://localhost:5173",
    "base": "/",
    "inputs": {
        "app/home": { "js": "resources/pages/home.ts" }
    }
}

js() emits a <script type="module"> pointing at the dev server, preceded by @vite/client (deduplicated across all calls). css() emits a <script type="module"> for CSS entries — Vite serves CSS files as ESM modules with HMR. When the dev server exits the file is removed.

Production

Build with:

npx vite build

The plugin writes:

{
    "mode": "production",
    "inputs": {
        "app/home": {
            "format": "es",
            "js": "/dist/home-BcD1eF2g.js",
            "css": ["/dist/home-BcD1eF2g.css"],
            "imports": ["/dist/vendor-HiJ3kL4m.js"]
        }
    }
}

js() emits <link rel="modulepreload"> for each import chunk (ESM) followed by <script type="module">, or a classic <script> for IIFE entries. css() emits <link rel="stylesheet"> for each CSS file.

No manifest

When the file is absent (not built, dev server not running) both js() and css() return an empty string. In debug mode an unknown mode value throws a RuntimeException.