Vite Plugin PHP

2.0.4 verified Mon Apr 27 auth: no javascript

A Vite plugin that enables processing PHP files within Vite's build pipeline, leveraging Vite's fast dev server, HMR, and build tooling for PHP-heavy projects. Currently at v2.0.4, actively maintained with regular bug fixes and performance improvements. Key differentiators: integrates PHP directly into Vite's module graph, supports multiple PHP entry points, provides browser auto-refresh on PHP changes, and works alongside traditional frontend assets. Unlike other solutions, it does not require a separate PHP server during development for asset handling.

Common errors

error Error: The PHP executable could not be found. Please install PHP or set the 'phpBinary' option. ↓

cause PHP not installed or not in system PATH, and phpBinary option is not set.

fix

Install PHP or set phpBinary in plugin config: php({ phpBinary: '/usr/bin/php' })

error [plugin:vite-plugin-php] ParseError: syntax error, unexpected '}' in ... ↓

cause Syntax error in PHP file that the plugin tries to process.

fix

Fix the PHP syntax error. The plugin expects valid PHP code in entry files and files included via vite() helper.

error TypeError: php is not a function ↓

cause Incorrect import: used named import instead of default import.

fix

Change import to: import php from 'vite-plugin-php'

error Module parse failed: Unexpected token (1:0) You may need an appropriate loader to handle this file type. ↓

cause Vite tried to process a PHP file without the plugin configured correctly, or the file is not included in the plugin's entry.

fix

Ensure the PHP file is in the plugin's entry list and the plugin is added to vite.config.

Warnings

breaking v2.0.0 changed the plugin API: options object restructured, phpBinary option renamed from 'phpPath'. ↓

fix Update your config: rename phpPath to phpBinary, and adjust nested options per documentation.

breaking Plugin no longer supports CommonJS requires; only ESM imports are valid. ↓

fix Use import syntax instead of require.

gotcha PHP binary must be available on the system PATH or specified via phpBinary option; otherwise the plugin fails silently. ↓

fix Set phpBinary explicitly or ensure PHP is in PATH.

gotcha The vite() function in PHP files requires the plugin to output the correct asset URLs; does not work with absolute or relative paths manually. ↓

fix Always use the <?= vite('entry.js') ?> pattern.

Install

npm install vite-plugin-php

yarn add vite-plugin-php

pnpm add vite-plugin-php

Imports

vitePluginPhp

wrong

import { vitePluginPhp } from 'vite-plugin-php'

correct

import vitePluginPhp from 'vite-plugin-php'

Default import only, not named export.

VitePluginPhpOptions
```
import type { VitePluginPhpOptions } from 'vite-plugin-php'
```
Type import for TypeScript users, available since v2.

php

wrong

const php = require('vite-plugin-php')

correct

import php from 'vite-plugin-php'

ESM-only; CJS require is not supported.

Quickstart

Minimal Vite config with PHP plugin and a PHP entry point showing vite() helper integration.

// vite.config.ts
import { defineConfig } from 'vite';
import php from 'vite-plugin-php';

export default defineConfig({
  plugins: [
    php({
      entry: './src/index.php',
      phpBinary: process.env.PHP_BINARY ?? 'php',
      server: {
        port: 3000,
        strictPort: false
      }
    })
  ]
});

// index.php - Basic PHP entry point
<!DOCTYPE html>
<html>
<head>
  <?= vite('src/main.js') ?>
</head>
<body>
  <h1><?= 'Hello from PHP!' ?></h1>
  <?php
    $data = ['name' => 'Vite', 'version' => '5'];
    echo '<p>Data: ' . json_encode($data) . '</p>';
  ?>
</body>
</html>