Initial commit xmarticaims

This commit is contained in:
2026-11-02 10:26:32 -06:00
commit e74236f5c1
9764 changed files with 2880647 additions and 0 deletions
@@ -0,0 +1,240 @@
# 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
<?php
use function Nabasa\VitePlus\assets;
$vite = assets( __DIR__ . '/assets/dist' );
add_action( 'wp_enqueue_scripts', function () use ( $vite ): void {
$vite->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
<?php
use function Nabasa\VitePlus\assets;
$vite = assets( __DIR__ . '/assets/dist' );
add_action( 'wp_enqueue_scripts', function () use ( $vite ): void {
$vite->enqueue( 'resources/app.ts', [
'handle' => 'theme-app',
] );
} );
```
Pass a second argument to `assets()` when you want a plugin- or theme-specific hook namespace:
```php
<?php
use function Nabasa\VitePlus\assets;
$vite = assets( __DIR__ . '/assets/dist', 'windpress' );
add_filter( 'nabasa_vite_plus/windpress/production_assets', function ( array $assets ) {
return $assets;
} );
```
Scoped helpers still trigger the shared `nabasa_vite_plus/*` hooks as well as the scoped `nabasa_vite_plus/{scope}/*` hooks. The scope is normalized with `sanitize_key()`.
If you prefer standalone functions, `register_asset()` and `enqueue_asset()` accept the same scope as a fourth argument.
Supported PHP options include:
- `handle`
- `dependencies`
- `css_dependencies`
- `css_media`
- `css_only`
- `in_footer`
During `vp dev`, `vp-wp` reads `vite-dev-server.json` and serves assets from the active dev server. During `vp build`, it reads `manifest.json` and registers the compiled JavaScript and extracted CSS assets.
Use `asset_url()` when you need the public URL for a file in the built assets directory without looking it up in the manifest:
```php
<?php
use function Nabasa\VitePlus\asset_url;
$logo_url = asset_url( __DIR__ . '/assets/dist', 'images/logo.svg' );
```
## Externals presets
Pick a preset when you want tighter control over which globals stay external:
```ts
wordpressExternals({ preset: "wordpress" });
```
Built-in presets:
- `wordpress`
- `wordpress+react`
You can also extend or trim the externals map to fit your project:
```ts
wordpressExternals({
include: {
"@acme/ui": "AcmeUI",
},
exclude: ["lodash"],
});
```
## Development
```sh
vp install
vp check
vp test
vp pack
```
## Credits
`vp-wp` is a fork and rewrite inspired by [`@kucrut/vite-for-wp`](https://github.com/kucrut/vite-for-wp).
## Examples
Need a working reference? See [`examples/README.md`](examples/README.md) for React, Vue, Svelte, SolidJS, and vanilla JavaScript. Each example includes the full plugin structure, Vite config, PHP bootstrap, and frontend entry for its framework.