# vp-wp [![build status](https://github.com/nabasa-dev/vp-wp/actions/workflows/ci.yml/badge.svg)](https://github.com/nabasa-dev/vp-wp/actions/workflows/ci.yml) [![npm version](https://img.shields.io/npm/v/%40nabasa%2Fvp-wp?logo=npm)](https://www.npmjs.com/package/@nabasa/vp-wp) [![npm downloads](https://img.shields.io/npm/dm/%40nabasa%2Fvp-wp?logo=npm)](https://www.npmjs.com/package/@nabasa/vp-wp) [![composer version](https://img.shields.io/packagist/v/nabasa/vp-wp?logo=packagist)](https://packagist.org/packages/nabasa/vp-wp) [![composer downloads](https://img.shields.io/packagist/dt/nabasa/vp-wp?logo=packagist)](https://packagist.org/packages/nabasa/vp-wp) [![pkg.pr.new](https://pkg.pr.new/badge/nabasa-dev/vp-wp)](https://pkg.pr.new/~/nabasa-dev/vp-wp) [![license](https://img.shields.io/github/license/nabasa-dev/vp-wp)](https://github.com/nabasa-dev/vp-wp/blob/main/LICENSE) `vp-wp` brings a modern Vite+ workflow to WordPress plugins and themes. Use it to build and serve frontend assets with WordPress-friendly defaults, a compact TypeScript API, and a lightweight PHP runtime. ## Install Install the JavaScript package with Vite+: ```sh vp add -D vite-plus @nabasa/vp-wp ``` If you also want the PHP runtime helpers through Composer: ```sh composer require nabasa/vp-wp ``` If you are not using Composer, copy `vp-wp.php` into your plugin or theme and require it manually. ## Migration Moving from `@kucrut/vite-for-wp`? See [`docs/migrating-from-vite-for-wp.md`](docs/migrating-from-vite-for-wp.md). ## Vite+ config A minimal Vite+ config looks like this: ```ts import { defineConfig } from "vite-plus"; import { wordpress, wordpressExternals } from "@nabasa/vp-wp"; export default defineConfig({ plugins: [ wordpress({ entry: { app: "resources/app.ts", }, outDir: "assets/dist", }), wordpressExternals(), ], }); ``` Then run the usual Vite+ commands: ```sh vp dev vp build ``` `wordpress()` applies WordPress-friendly defaults: - `base: './'` - `build.manifest: 'manifest.json'` - `build.modulePreload: false` - `css.devSourcemap: true` - a development manifest at `vite-dev-server.json` These defaults keep asset URLs, manifests, and CSS handling aligned with WordPress expectations. `wordpressExternals()` keeps common WordPress globals out of your bundle and treats React as external by default. ## PHP runtime A typical enqueue setup looks like this: ```php enqueue( 'resources/app.ts', [ 'handle' => 'my-plugin-app', 'dependencies' => [ 'react', 'react-dom' ], 'in_footer' => true, ] ); } ); ``` Exposed PHP runtime API: Supported public API: - `Nabasa\VitePlus\assets()` creates a reusable `Assets` helper. - `Nabasa\VitePlus\register_asset()` registers an entry and extracted CSS. - `Nabasa\VitePlus\enqueue_asset()` registers and enqueues an entry. - `Nabasa\VitePlus\asset_url()` resolves a public asset URL. - `Nabasa\VitePlus\Assets::__construct()` creates the helper directly. - `Nabasa\VitePlus\Assets::manifest_dir()` gets the bound manifest directory. - `Nabasa\VitePlus\Assets::scope()` gets the normalized scope. - `Nabasa\VitePlus\Assets::register()` registers an entry. - `Nabasa\VitePlus\Assets::enqueue()` registers and enqueues an entry. - `Nabasa\VitePlus\Assets::url()` resolves an asset URL. Advanced callable helpers: - `Nabasa\VitePlus\filter_value()` applies shared and scoped filters. - `Nabasa\VitePlus\normalize_scope()` sanitizes a hook scope. - `Nabasa\VitePlus\get_manifest()` loads and caches manifest data. - `Nabasa\VitePlus\parse_options()` merges options with defaults. - `Nabasa\VitePlus\default_asset_handle()` generates a default handle. - `Nabasa\VitePlus\stylesheet_handle()` generates a deterministic style handle. - `Nabasa\VitePlus\prepare_asset_url()` builds a manifest base URL. - `Nabasa\VitePlus\join_asset_url()` joins a base URL and asset path. Internal and compatibility helpers: - `Nabasa\VitePlus\load_development_asset()` - `Nabasa\VitePlus\load_production_asset()` - `Nabasa\VitePlus\register_stylesheets()` - `Nabasa\VitePlus\register_vite_client_script()` - `Nabasa\VitePlus\inject_react_refresh_preamble()` - `Nabasa\VitePlus\development_asset_src()` - `Nabasa\VitePlus\filter_script_tag()` - `Nabasa\VitePlus\set_script_type_attribute()` - `Nabasa\VitePlus\should_inject_react_refresh()` - `Nabasa\VitePlus\string_ends_with()` Core PHP filters: - `nabasa_vite_plus/manifest_data` - `nabasa_vite_plus/development_assets` - `nabasa_vite_plus/production_assets` - `nabasa_vite_plus/{scope}/manifest_data` - `nabasa_vite_plus/{scope}/development_assets` - `nabasa_vite_plus/{scope}/production_assets` Use `assets()` when you want to bind a manifest directory once and reuse it across hooks or callbacks: ```php enqueue( 'resources/app.ts', [ 'handle' => 'theme-app', ] ); } ); ``` Pass a second argument to `assets()` when you want a plugin- or theme-specific hook namespace: ```php