https://github.com/benignware/vite-plugin-wordpress
A vite plugin for dealing with @wordpress packages
https://github.com/benignware/vite-plugin-wordpress
Last synced: 11 months ago
JSON representation
A vite plugin for dealing with @wordpress packages
- Host: GitHub
- URL: https://github.com/benignware/vite-plugin-wordpress
- Owner: benignware
- Created: 2025-04-17T17:37:20.000Z (about 1 year ago)
- Default Branch: main
- Last Pushed: 2025-04-17T17:53:07.000Z (about 1 year ago)
- Last Synced: 2025-04-18T08:07:50.626Z (about 1 year ago)
- Language: JavaScript
- Size: 4.88 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# vite-plugin-wordpress
This Vite plugin externalizes WordPress dependencies and generates a `*.asset.php` manifest file during the build process. It is specifically designed for WordPress projects that require a separation between their build assets and WordPress environment, enabling seamless integration with the WordPress ecosystem.
## Features
- **Externalizes WordPress dependencies**: Automatically replaces imports for `@wordpress/*` packages with `wp.*` globals.
- **Generates a WordPress asset manifest**: Outputs a PHP file (`*.asset.php`) containing dependencies and version information based on your build output.
- **Customizable manifest generation**: The asset manifest can be generated optionally using the plugin options.
## Installation
To install the plugin, run the following command:
```bash
npm install vite-plugin-wordpress-externals --save-dev
```
## Configuration
In your `vite.config.js` (or `vite.config.ts`), add the plugin to your Vite configuration:
```javascript
import wordpressExternalsPlugin from 'vite-plugin-wordpress-externals';
export default {
plugins: [
wordpressExternalsPlugin(),
],
};
```
### Plugin Options
- `manifest`: (default `true`) - Set to `false` to skip generating the asset manifest file. If enabled, a PHP file (`*.asset.php`) is generated for each JavaScript entry chunk in the `dist` directory.
## How It Works
The plugin works by detecting all WordPress dependencies (`@wordpress/*`) defined in your `package.json`. It then replaces import statements for these dependencies with references to global `wp.*` variables, as they are available in the WordPress environment.
- **Imports**: The plugin replaces imports like `import { element } from '@wordpress/element'` with `const { element } = wp.element;`.
- **Globals**: It ensures that these dependencies are marked as external in the Rollup build process and maps them to the corresponding `wp.*` global variables.
- **Asset Manifest**: The plugin creates a PHP manifest for each JS entry file, listing the WordPress dependencies used and a hash of the file's content.
## Generated PHP Asset Manifest
The plugin generates a `*.asset.php` file for each JavaScript chunk that looks like this:
```php
['wp-element', 'wp-hooks'],
'version' => 'abcd1234',
];
```
- **`dependencies`**: Lists the WordPress dependencies used by the chunk (e.g., `wp-element`, `wp-hooks`).
- **`version`**: A unique version hash based on the chunk's content.
The asset manifest can be included in your WordPress theme or plugin to properly enqueue the generated JavaScript file with the correct dependencies and version.
## Example
If you have an entry file that imports WordPress packages:
```javascript
import { element } from '@wordpress/element';
import { hooks } from '@wordpress/hooks';
```
The plugin will replace those imports with:
```javascript
const { element } = wp.element;
const { hooks } = wp.hooks;
```
Additionally, it will generate a `*.asset.php` manifest with the dependencies:
```php
['wp-element', 'wp-hooks'],
'version' => 'abcd1234',
];
```