README

A framework-agnostic PHP library to integrate Vite with your PHP applications. It manages manifest parsing, tag generation, and asset preloading/prefetching.

Requirements

• PHP 8.2+

Installation

composer require millancore/vite-manifest

Basic Usage

Setup

use Millancore\Vite\Vite;

$vite = new Vite();

// Configure build directory (default: 'build')
$vite->useBuildDirectory('dist');

// Configure manifest filename (default: 'manifest.json')
$vite->useManifestFilename('.vite/manifest.json');

Generating Tags

Use __invoke or toHtml() to generate <script> and <link> tags:

<!-- Single entry point -->
<?= $vite('resources/js/app.js') ?>

<!-- Multiple entry points -->
<?= $vite(['resources/js/app.js', 'resources/css/app.css']) ?>

<!-- Using withEntryPoints + toHtml -->
<?= $vite->withEntryPoints(['resources/js/app.js', 'resources/css/app.css'])->toHtml() ?>

Getting Asset URLs

// Get the URL for a specific asset
$url = $vite->asset('resources/js/app.js');

// Get the file contents of an asset
$content = $vite->content('resources/js/app.js');

Configuration

Hot Module Replacement (HMR)

The library automatically detects if Vite's HMR server is running by checking for a "hot" file.

// Set the path to the hot file (default: public_path('/hot'))
$vite->useHotFile(__DIR__ . '/public/hot');

// Check if HMR is active
if ($vite->isRunningHot()) {
    // ...
}

Content Security Policy (CSP) Nonce

Inject a nonce into all generated tags:

// Set a specific nonce
$vite->useCspNonce('your-random-nonce');

// Or generate a random one
$nonce = $vite->useCspNonce();

// Retrieve the current nonce
$vite->cspNonce();

Custom Asset Paths

If your assets are hosted on a CDN or a different path, define a custom resolver:

$vite->createAssetPathsUsing(function ($path, $secure) {
    return 'https://cdn.example.com/' . $path;
});

Subresource Integrity

By default the library looks for an integrity key in manifest chunks. You can change the key or disable it:

// Use a custom key
$vite->useIntegrityKey('sri-hash');

// Disable integrity checking
$vite->useIntegrityKey(false);

Entry Points

// Set entry points
$vite->withEntryPoints(['resources/js/app.js']);

// Merge additional entry points (deduplicates)
$vite->mergeEntryPoints(['resources/css/app.css']);

Manifest Hash

Get a unique hash of the current manifest, useful for cache busting:

$hash = $vite->manifestHash(); // returns null when hot or no manifest

Prefetching

Enable prefetching for dynamic imports to improve navigation performance.

Aggressive Strategy

Loads all prefetchable assets immediately:

$vite->useAggressivePrefetching();

Waterfall Strategy

Loads assets sequentially with a concurrency limit to avoid network congestion:

// Default concurrency of 3
$vite->useWaterfallPrefetching();

// Custom concurrency
$vite->useWaterfallPrefetching(concurrency: 5);

Shorthand

// Aggressive (no concurrency specified)
$vite->prefetch();

// Waterfall with concurrency
$vite->prefetch(concurrency: 3);

// Custom event trigger (default: 'load')
$vite->prefetch(event: 'DOMContentLoaded');

Tag Attributes

Add custom attributes to generated tags using arrays or callbacks:

// Script tags
$vite->useScriptTagAttributes(['defer' => true]);
$vite->useScriptTagAttributes(function ($src, $url, $chunk, $manifest) {
    return ['data-module' => 'true'];
});

// Style tags
$vite->useStyleTagAttributes(['data-theme' => 'dark']);

// Preload tags
$vite->usePreloadTagAttributes(['crossorigin' => 'anonymous']);

// Disable preloading for specific assets
$vite->usePreloadTagAttributes(function ($src, $url, $chunk, $manifest) {
    return str_contains($src, 'legacy') ? false : [];
});

React Refresh

Include the React Refresh runtime when using React with HMR:

<?= $vite->reactRefresh() ?>
<?= $vite('resources/js/app.jsx') ?>

Returns null when not in HMR mode.

License

MIT