WordPress Vite Plugin

1.6.0 verified Mon Apr 27 auth: no javascript

WordPress Vite Plugin (v1.6.0) is a Vite plugin that integrates Vite into WordPress theme/plugin development, providing hot module replacement, asset bundling, and automatic enqueuing. It supports Vite 3-8, requires Node >=16, ships TypeScript types, and offers a streamlined setup with minimal configuration compared to manual webpack or custom build setups. Release cadence is irregular; key differentiators include native HMR in WordPress admin, automatic asset manifest parsing, and compatibility with both Classic and Block themes. v1.6 introduces support for Vite 6 and 7/8 prereleases.

Common errors

error Cannot find module 'wordpress-vite-plugin' ↓

cause Package not installed or ESM-only import used in CommonJS environment.

fix

Run npm install wordpress-vite-plugin --save-dev and ensure package.json has 'type': 'module' or use .mjs extension.

error wordpressVitePlugin is not a function ↓

cause Default import missing or using named import incorrectly in CommonJS.

fix

Use import wordpressVitePlugin from 'wordpress-vite-plugin' in ESM, or const plugin = require('wordpress-vite-plugin').default in CommonJS.

error Plugin 'wordpress-vite-plugin' does not have a 'name' property ↓

cause The imported value is not a properly initialized plugin factory; likely called the factory incorrectly.

fix

Ensure you call wordpressVitePlugin() as a function with options object in the plugins array.

error ENOENT: no such file or directory, open '.../dist/.vite/manifest.json' ↓

cause Production build missing manifest file; build.manifest is not set to true in Vite config.

fix

Add build: { manifest: true } to vite.config.js.

Warnings

breaking Vite 3+ required; Vite 2 and earlier are not supported. ↓

fix Upgrade Vite to ^3.0.0 || ^4.0.0 || ^5.0.0 || ^6.0.0 || ^7.0.0 || ^8.0.0

breaking Default export changed from a function to a plugin factory in v1.0; calling wordpressVitePlugin() now returns a Vite plugin object. ↓

fix Use wordpressVitePlugin({...}) instead of wordpressVitePlugin as a direct plugin.

deprecated The 'config' option has been replaced by 'pluginOptions' for advanced configuration. ↓

fix Rename 'config' to 'pluginOptions'.

gotcha HMR dev server must be running; for WordPress admin integration, set WP_HOME constant in wp-config.php to match Vite dev server origin. ↓

fix Add define('WP_HOME', 'http://localhost:5173'); to wp-config.php during development.

gotcha Asset manifest (dist/.vite/manifest.json) is required for production builds; ensure build.manifest is true in Vite config. ↓

fix Set build.manifest: true in vite.config.js.

Install

npm install wordpress-vite-plugin

yarn add wordpress-vite-plugin

pnpm add wordpress-vite-plugin

Imports

wordpressVitePlugin

wrong

const wordpressVitePlugin = require('wordpress-vite-plugin')

correct

import wordpressVitePlugin from 'wordpress-vite-plugin'

Package is ESM-only since v1, CommonJS require() will not work.

wordpressVitePlugin

wrong

const { wordpressVitePlugin } = require('wordpress-vite-plugin')

correct

const plugin = require('wordpress-vite-plugin'); module.exports = plugin.default || plugin;

If using require() in a CommonJS context, you must access the default export via .default

WordpressVitePluginOptions

wrong

import { WordpressVitePluginOptions } from 'wordpress-vite-plugin'

correct

import type { WordpressVitePluginOptions } from 'wordpress-vite-plugin'

This is a TypeScript type, not a value, so use import type to avoid bundling runtime.

Quickstart

Minimal Vite config for WordPress plugin: sets up HMR and build with two input files and custom output structure.

// vite.config.js
import { defineConfig } from 'vite';
import wordpressVitePlugin from 'wordpress-vite-plugin';

export default defineConfig({
  plugins: [wordpressVitePlugin({
    input: ['js/main.js', 'css/style.css'],
    wordpressPluginName: 'my-plugin',
  })],
  build: {
    rollupOptions: {
      output: {
        entryFileNames: 'js/[name].js',
        chunkFileNames: 'js/[name]-[hash].js',
        assetFileNames: 'css/[name][extname]',
      },
    },
  },
});