Stars: 124
Forks: 16
Pull Requests: 39
Issues: 8
Watchers: 5
Last Updated: 2023-09-08 15:52:29
Vite integration for WordPress plugins and themes development.
License: GNU General Public License v2.0
Languages: PHP, JavaScript
Vite integration for WordPress plugins and themes development.
Let's assume we have this plugin files structure:
my-plugin/
├ js/
| └ src/
| └ main.ts
├ package.json
├ plugin.php
└ vite.config.js
Add JS dependencies:
npm add -D vite @kucrut/vite-for-wp
Create vite.config.js
:
import create_config from '@kucrut/vite-for-wp';
export default create_config( 'js/src/main.ts', 'js/dist' );
If you have multiple entrypoints to build, pass an object as the first parameter:
// vite.config.js
import create_config from '@kucrut/vite-for-wp';
export default create_config(
{
main: 'js/src/main.ts',
extra: 'js/src/extra.ts',
},
'js/dist',
);
Pass a configuration object as the third parameter if you need to add plugins, use https, etc:
// vite.config.js
import { readFileSync } from 'node:fs';
import { resolve } from 'node:path';
import create_config from '@kucrut/vite-for-wp';
import react from '@vitejs/plugin-react';
export default create_config( 'js/src/main.ts', 'js/dist', {
plugins: [ react() ],
server: {
host: 'mydomain.com',
https: {
cert: readFileSync( 'path/to/cert.pem' ),
key: readFileSync( 'path/to/key.pem' ),
},
},
} );
Lastly, add dev
and build
scripts to your package.json
:
{
"scripts": {
"build": "vite build",
"dev": "vite"
}
}
Add the composer dependency:
composer require kucrut/vite-for-wp
If your plugin/theme doesn't use composer, feel free to copy the main file and require it.
Enqueue the script:
<?php
use Kucrut\Vite;
add_action( 'wp_enqueue_scripts', function (): void {
Vite\enqueue_asset(
__DIR__ . '/js/dist',
'js/src/main.ts',
[
'handle' => 'my-script-handle',
'dependencies' => [ 'wp-components', 'some-registered-script-handle' ], // Optional script dependencies. Defaults to empty array.
'css-dependencies' => [ 'wp-components', 'some-registered-style-handle' ], // Optional style dependencies. Defaults to empty array.
'css-media' => 'all', // Optional.
'css-only' => false, // Optional. Set to true to only load style assets in production mode.
'in-footer' => true, // Optional. Defaults to false.
]
);
} );
Note that each entrypoint needs to be enqueued separately, ie. if you have multiple entrypoints, you'll need to call Vite\enqueue_asset()
for each and every one of them.
To only register the asset, use Vite\register_asset()
. It accepts same parameters as Vite\enqueue_asset()
and returns an array of scripts and styles handles that you can enqueue later using wp_enqueue_script()
and wp_enqueue_style()
. Please note that style assets are only registered in production mode because in development mode, they will be automatically loaded by Vite.
You can now run npm run dev
when developing your plugin/theme and run npm run build
to build the production assets.
If your JS package depends on one or more WordPress modules (eg. @wordpress/i18n
), you can define them as externals with the help of rollup-plugin-external-globals
.
npm add -D rollup-plugin-external-globals
For example, to externalise react
and react-dom
packages:
// vite.config.js
import { defineConfig } from 'vite';
import { wp_globals } from '@kucrut/vite-for-wp/utils';
import create_config from '@kucrut/vite-for-wp';
import external_globals from 'rollup-plugin-external-globals';
import react from '@vitejs/plugin-react';
export default defineConfig( ( { command } ) => {
if ( command === 'serve' ) {
return create_config( 'js/src/main.jsx', 'js/dist', {
plugins: [ react() ],
} );
}
return create_config( 'js/src/main.jsx', 'js/dist', {
plugins: [
react(),
external_globals( {
...wp_globals(),
} ),
],
build: {
rollupOptions: {
external: [ 'react', 'react-dom' ],
output: {
globals: wp_globals(),
},
},
},
} );
} );
Note that react
and react-dom
packages still need to be installed as dev dependencies and added to the dependencies
array when enqueueing the script (see example above).
Currently, this package doesn't provide HMR support for building editor blocks yet.