Download the PHP package josbeir/cakephp-vite without Composer

CakeVite: Vite Integration for CakePHP

A Vite.js integration for CakePHP 5.0+ applications. Seamlessly switch between development and production modes with automatic asset tag generation.

[!NOTE] This project is a spiritual successor to passchn/cakephp-vite, rewritten with modern PHP and a service-oriented architecture. There is no affiliation with the original project.

Table of Contents

• Features
• Installation
  • Requirements
  • Installing the Plugin
• Quick Start
  • 1. Configure Vite
  • 2. Load the Helper
  • 3. Use in Templates
• Configuration
  • Basic Configuration
  • Advanced Configuration
  • Environment Variables
• Usage
  • Development Mode
  • Production Mode
  • Plugin Assets
  • Multiple Entry Points
  • Custom Attributes
  • Inline Output
  • Preloading Assets
  • Caching
  • Multiple Configurations
  • Check Current Mode
• How It Works
• Testing
• Contributing
• License

Features

• 🚀 Automatic Mode Detection: Seamlessly switches between development and production based on your environment
• 🎯 Zero Configuration: Works out of the box with sensible defaults
• 📦 Plugin Support: Load assets from CakePHP plugins with ease
• 🔧 Flexible Configuration: Customize dev server URLs, manifest paths, and more
• 🎨 CSS Extraction: Automatically includes CSS dependencies from JavaScript entries in production
• ⚡ HMR Support: Full Hot Module Replacement support in development mode
• 🏎️ Modulepreload Support: Automatic preloading of dependencies for faster load times in code-split applications
• ✅ Type-Safe: 100% type coverage with PHPStan level 8
• 🧪 Well Tested: 95%+ code coverage with comprehensive unit and integration tests

Installation

Requirements

• PHP 8.2 or higher
• CakePHP 5.0 or higher
• Vite 2.0 or higher (installed via npm/yarn/pnpm)

Installing the Plugin

Install via Composer:

Load the plugin:

Quick Start

1. Configure Vite

Create or update your vite.config.js:

2. Load the Helper

In your src/View/AppView.php:

3. Use in Templates

In your layout file (e.g., templates/layout/default.php):

Start Vite dev server:

Build for production:

Configuration

Basic Configuration

Create config/app_vite.php in your application for custom settings:

[!NOTE] Config entries vs. Helper files parameter:

• devServer.entries: Default files for development mode only. Used when helper is called without files option.
• files parameter: Per-call override that works in both development and production. In dev, it overrides config entries. In production, it filters manifest entries.

[!NOTE] The plugin will automatically detect and load config/app_vite.php if it exists for backwards compatibility.

Advanced Configuration

All available configuration options:

Environment Variables

You can use environment variables for configuration:

Then reference in your config:

Using with DDEV

DDEV requires some additional configuration to properly expose the Vite dev server. Here's how to set it up:

1. Configure .ddev/config.yaml to expose port 5173 (or something else):

2. Create config/app_vite.php using DDEV environment variables:

3. Update vite.config.js to use the DDEV URL:

[!TIP] DDEV automatically sets environment variables like DDEV_HOSTNAME and DDEV_PRIMARY_URL. Run ddev exec printenv | grep DDEV to see all available variables.

Usage

Basic Syntax

CakeVite supports both string shorthand and array syntax for loading assets:

String Shorthand (Simple):

Array Syntax (Full Featured):

[!TIP] Both script() and css() methods are void - they append tags to view blocks. Use <?= $this->fetch('script') ?> and <?= $this->fetch('css') ?> to render them in your layout.

Development Mode

In development, CakeVite automatically:

• Connects to your Vite dev server
• Includes the Vite client for HMR
• Loads modules as ES modules
• Provides instant hot reloading

Output in development:

Production Mode

In production, CakeVite automatically:

• Reads the build manifest
• Resolves hashed filenames
• Includes dependent CSS files
• Handles legacy browser support

Output in production:

Plugin Assets

Load assets from a CakePHP plugin:

Or configure globally:

Multiple Entry Points

Load multiple files at once:

Filter production assets by pattern:

Custom Attributes

Add custom HTML attributes to generated tags:

Output:

Custom View Blocks

Use custom view blocks for scripts and styles:

Inline Output

By default, script() and css() append tags to view blocks for rendering in layouts. Set block => false to return tags as a string for inline output:

This is useful when you need to render assets directly in elements or partials:

Vite Client Deduplication:

In development mode, the @vite/client script is automatically deduplicated. Multiple script() calls (e.g., in layout, elements, components) will only output the Vite client once:

Disable Dependent CSS Injection:

In production mode, script() automatically injects dependent CSS from JS entries. Use cssBlock => false to disable this:

Preloading Assets

CakeVite supports modulepreload to improve load times for applications with code splitting. Preloading hints to the browser which modules will be needed soon, allowing parallel downloads.

Enabled by Default:

Output in production:

Disable Preloading:

Configure Globally:

Environment Variable:

[!NOTE]

• Preloading only works in production mode (development mode uses dev server, no manifest)
• Uses rel="modulepreload" for ES modules
• Automatically deduplicates URLs to prevent redundant preloads
• link-header mode is reserved for future HTTP/2 header-based preloading
• Requires Vite's build.modulePreload to be enabled (default). If you've disabled it in your Vite config, preloading won't work as import dependencies aren't tracked in the manifest.

Performance Benefits:

• Reduces load time by downloading dependencies in parallel
• Particularly beneficial for code-split applications
• Browser can start downloading imports while parsing main script

Caching

Enable persistent caching of the manifest file in production to eliminate file I/O overhead on every request.

Enable Caching:

Environment Variable:

Cache Invalidation:

• Automatic: cache key includes manifest file mtime
• When manifest rebuilds, cache automatically invalidates

Cache in Development:

[!TIP] Enabling caching could improve manifest read performance, particularly when using memory-based solutions such as Redis that avoid file I/O operations.

Multiple Configurations

Use named configurations for different parts of your application (admin panel, marketing site, etc.).

Define Named Configs:

Use in Templates:

Configuration Inheritance:

• Named configs inherit from default config
• Override only what you need
• Useful for multi-tenant or multi-section applications

Check Current Mode

Check if running in development mode:

How It Works

Mode Detection

CakeVite automatically detects the environment based on:

1. Force Production Mode: forceProductionMode configuration
2. Production Hint: Cookie or query parameter (vprod by default)
3. Host Hints: Matches hostname against development patterns
4. Default: Falls back to production for safety

Development Mode

• Connects to Vite dev server
• Serves assets from configured dev server URL
• Includes Vite client for HMR
• No manifest file required

Production Mode

• Reads manifest.json generated by Vite
• Maps entry points to hashed output files
• Automatically includes CSS dependencies
• Supports legacy browser builds

Testing

Run the test suite:

Run with coverage:

Check code standards:

Run static analysis:

Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Write tests for your changes
4. Ensure all quality checks pass (composer cs-check && composer phpstan && composer test)
5. Submit a pull request

License

This project is licensed under the MIT License - see the LICENSE file for details.