Wordpress Vite | southcoastweb

Being quite fond of working with Laravel, one of the major pain points when coming to a WordPress site is the complexity in using JS frameworks and bundlers. Vite is especially tricky since during development, it utilises Hot Module Reloading which allows you to see the fruits of your labour on the browser the second you save your work.

We’d experimented with a few other solutions, but none of them had that ‘it just works’ feels of the Laravel/Vite integration. So we figured, why not just port that to work with WordPress?

There were a few technical challenges to overcome: the need for both theme development and plugin development compatibility; cache-busting of resources; integration with WordPress dependencies. Happily though, it just works.

Installing the PHP Plugin

We’ve listed this as an NPM project, but really it requires both a PHP package (installed as a plugin) and the NPM package working together to function.

To download the WordPress plugin, head over to our Github Repository and download the ‘southcoastweb-wp-vite.zip‘ file. You can upload this file as a plugin to your WordPress site and then activate it.

Installing the JavaScript Plugin

Next, enter the directory of the plugin/theme you want to power with Vite and do your usual setup (package.json, vite.config.js etc).

Now run

// via NPM
npm i wordpress-vite-plugin

// or via Yarn
yarn add wordpress-vite-plugin

Now load up your Vite config file and include the following:

1import { defineConfig } from "vite";
2import { wordpress } from "wordpress-vite-plugin";
3
4export default defineConfig({
5    plugins: [
6        wordpress({
7            input: "src/main.js",
8            namespace: "theme-vite",
9        }),
10    ],
11});

If you’re using Vue, don’t forget to include the following when defining your vue plugin:

1...
2    vue({
3        template: {
4            transformAssetUrls: {
5                base: false,
6                includeAbsolute: false
7            }
8        }
9    })
10...

You can pass an array of inputs to the wordpress plugin if you want. Full details on configuration below.

Enqueueing Scripts / Styles

In either your plugin’s entry file, or your theme’s functions.php file, enter the following:

1<?php
2
3use Southcoastweb\WpVite\WpVite;
4
5WpVite::enqueue([
6	'input' => "src/main.js",
7	'namespace' => 'theme-vite'
8]);

Note that both input and namespace must match the values you declared in your Vite config file exactly.

PHP Parameters

The enqueue function takes a single associative array as an argument. Inside that array, you can pass the following parameters

Param	Type	Default	Description
input	string \| string[]	<none> required	The entry points of your Vite bundle. These must match exactly the ones defined in your Vite config file
namespace	string	<none> required	A unique namespace for the manifest (collection of entry points and their dependencies) being enqueued
admin	bool	false	Enqueue the inputs for WordPress admin pages instead of frontend
dependencies	string[]	[]	WordPress JS dependencies for your manifest

Vite Plugin Parameters

Both input and namespace are the same as above. You do not need to pass a dependencies array to the Vite plugin since these will be detected automatically. Speaking of…

Wordpress dependencies

You should have already included any dependencies your manifest requires in your PHP call to enqueue. These may comprise any of the scripts registered by WordPress.

Because of how WordPress delivers its dependencies to the frontend, we have to handle them slightly differently depending on whether we’re working in development mode (with Hot Module Reloading) or in production mode. For the former, we want to import them as standard NPM modules, for the latter, we want to use the versions that WordPress will put on the window object. Fortunately, the plugin handles all of that for you. So in your project, it’s as simple as:

import { __ } from "@wordpress/i18n";

console.log(__("Hello World", "southcoastweb-wp-vite"));

Don’t forget to install the @wordpress/i18n package as a devDependency with your prefered package manager.

Running your Vite project

From the root of your project directory (either the plugin folder or your theme folder) you can now run Vite. You may find it helpful to add the following scripts to your package.json file.

1"scripts": {
2    "dev": "vite",
3    "prod": "vite build"
4}

Thoughts and comments

For feedback on the PHP part of the project, head here: https://github.com/southcoastweb/wp-vite

Or for the JavaScript part: https://github.com/southcoastweb/wordpress-vite-plugin