Vite Extension #

Register the extension #

use Sugar\Core\Engine;
use Sugar\Extension\Vite\ViteExtension;

$engine = Engine::builder()
    ->withExtension(new ViteExtension(
        mode: 'auto',
        manifestPath: '/var/www/app/webroot/build/manifest.json',
        assetBaseUrl: '/build/',
        devServerUrl: 'http://localhost:5173',
        injectClient: true,
    ))
    ->build();

Using s:vite #

Use the directive where you want Vite tags emitted:

<s-template s:vite="resources/assets/js/site.js" />

You can also apply it on regular elements:

<link s:vite="resources/assets/css/app.css" />

ViteDirective also supports custom-element syntax through element claiming:

<s-vite src="resources/assets/js/site.js" />

In this form, src is used as the directive expression and produces the same output as s:vite="...".

Runtime modes #

• auto: Uses development behavior in debug mode and production behavior otherwise.
• dev: Always emits dev server tags.
• prod: Always resolves assets from manifest.json.

Namespaces #

For multi-build setups — such as a plugin or theme with its own Vite build — you can register named namespaces. Each namespace is an independent ViteConfig with its own assetBaseUrl, manifestPath, and optionally a separate devServerUrl.

Register namespaces when creating the extension:

use Sugar\Core\Engine;
use Sugar\Extension\Vite\ViteConfig;
use Sugar\Extension\Vite\ViteExtension;

$engine = Engine::builder()
    ->withExtension(new ViteExtension(
        assetBaseUrl: '/build/',
        manifestPath: ROOT . '/webroot/build/.vite/manifest.json',
        namespaces: [
            'theme' => new ViteConfig(
                assetBaseUrl: '/theme/build/',
                manifestPath: ROOT . '/plugins/Theme/webroot/build/.vite/manifest.json',
                devServerUrl: 'http://localhost:5174',
                defaultEntry: 'resources/js/theme.ts',
            ),
        ],
    ))
    ->build();

Reference a namespace entry in templates using the @name/ prefix:

<s-template s:vite="'@theme/resources/js/theme.ts'" />

When a namespace has a defaultEntry configured, you can use the bare @name shorthand to load it without specifying an explicit path:

<s-template s:vite="'@theme'" />

Multiple entries from different namespaces can be combined in one directive:

<s-template s:vite="['resources/js/app.ts', '@theme/resources/js/theme.ts']" />

Each namespace resolves its assets independently: its own manifest in production, its own dev server URL in development, and its own @vite/client injection tracking.

When devServerUrl is omitted from a ViteConfig, the namespace falls back to the root extension devServerUrl.

Configuration options #

• mode: auto, dev, or prod.
• manifestPath: Absolute filesystem path to the Vite manifest.json.
• assetBaseUrl: Public URL prefix for built assets (required).
• devServerUrl: Vite development server origin.
• injectClient: Automatically inject @vite/client in development mode.
• defaultEntry: Entry used when s:vite is used as a boolean directive.
• namespaces: Named namespace configurations as an array of ViteConfig objects, keyed by namespace name.

Production recommendation #

Set manifestPath and assetBaseUrl explicitly in production. This applies equally to each registered namespace.