https://github.com/roots/vite-plugin
A Vite plugin for working with WordPress
https://github.com/roots/vite-plugin
Last synced: 5 months ago
JSON representation
A Vite plugin for working with WordPress
- Host: GitHub
- URL: https://github.com/roots/vite-plugin
- Owner: roots
- License: mit
- Created: 2025-02-21T04:46:51.000Z (11 months ago)
- Default Branch: main
- Last Pushed: 2025-06-16T11:58:12.000Z (7 months ago)
- Last Synced: 2025-06-29T20:41:51.341Z (7 months ago)
- Language: TypeScript
- Homepage:
- Size: 53.7 KB
- Stars: 36
- Watchers: 3
- Forks: 4
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- License: LICENSE.md
Awesome Lists containing this project
README
# Vite Plugin for WordPress
Here lives a Vite plugin for WordPress development.
## Features
- 🔄 Transforms `@wordpress/*` imports into global `wp.*` references
- 📦 Generates dependency manifest for WordPress enqueuing
- 🎨 Generates theme.json from Tailwind CSS configuration
- 🔥 Hot Module Replacement (HMR) support for the WordPress editor
## Installation
```bash
npm install @roots/vite-plugin --save-dev
```
## Usage
Start by adding the base plugin to your Vite config:
```js
// vite.config.js
import { defineConfig } from 'vite';
import { wordpressPlugin } from '@roots/vite-plugin';
export default defineConfig({
plugins: [wordpressPlugin()],
});
```
Once you've added the plugin, WordPress dependencies referenced in your code will be transformed into global `wp.*` references.
When WordPress dependencies are transformed, a manifest containing the required dependencies will be generated called `editor.deps.json`.
### Editor HMR Support
The plugin automatically enables CSS Hot Module Replacement (HMR) for the WordPress editor.
> [!NOTE]
> JavaScript HMR is not supported at this time. JS changes will trigger a full page reload.
You can customize the HMR behavior in your Vite config:
```js
// vite.config.js
import { defineConfig } from 'vite';
import { wordpressPlugin } from '@roots/vite-plugin';
export default defineConfig({
plugins: [
wordpressPlugin({
hmr: {
// Enable/disable HMR (default: true)
enabled: true,
// Pattern to match editor entry points (default: /editor/)
editorPattern: /editor/,
// Name of the editor iframe element (default: 'editor-canvas')
iframeName: 'editor-canvas',
},
}),
],
});
```
### Theme.json Generation
When using this plugin for theme development, you have the option of generating a `theme.json` file from your Tailwind CSS configuration.
To enable this feature, add the `wordpressThemeJson` plugin to your Vite config:
```js
// vite.config.js
import { defineConfig } from 'vite';
import { wordpressThemeJson } from '@roots/vite-plugin';
export default defineConfig({
plugins: [
wordpressThemeJson({
// Optional: Configure shade labels
shadeLabels: {
100: 'Lightest',
900: 'Darkest',
},
// Optional: Configure font family labels
fontLabels: {
sans: 'Sans Serif',
mono: 'Monospace',
inter: 'Inter Font',
},
// Optional: Configure font size labels
fontSizeLabels: {
sm: 'Small',
base: 'Default',
lg: 'Large',
},
// Optional: Disable specific transformations
disableTailwindColors: false,
disableTailwindFonts: false,
disableTailwindFontSizes: false,
// Optional: Configure paths
baseThemeJsonPath: './theme.json',
outputPath: 'assets/theme.json',
cssFile: 'app.css',
// Optional: Legacy Tailwind v3 config path
tailwindConfig: './tailwind.config.js',
}),
],
});
```
By default, Tailwind v4 will only [generate CSS variables](https://tailwindcss.com/docs/theme#generating-all-css-variables) that are discovered in your source files.
To generate the full default Tailwind color palette into your `theme.json`, you can use the `static` theme option when importing Tailwind:
```css
@import 'tailwindcss' theme(static);
```
The same applies for customized colors in the `@theme` directive. To ensure your colors get generated, you can use another form of the `static` theme option:
```css
@theme static {
--color-white: #fff;
--color-purple: #3f3cbb;
--color-midnight: #121063;
--color-tahiti: #3ab7bf;
--color-bermuda: #78dcca;
}
```