Vite asset integration

[sixmonkey]

Vite asset integration

Summary

Add Vite manifest support to URL::asset() so that hashed filenames from production builds are resolved automatically. Also add wp_enqueue_scripts integration so assets are enqueued correctly via WordPress.

Background

URL::asset('css/app.css') already exists and points to theme/public/. However it always returns the unhashed filename — in a Vite production build the actual filename is css/app.abc123.css. Without manifest resolution, assets 404 in production.

The koalapress migration depends on this feature.

What needs to be done

1. AssetsServiceProvider

src/Assets/
├── AssetsServiceProvider.php
├── Manifest.php
└── config/
    └── assets.php

2. Manifest.php — reads public/manifest.json

class Manifest
{
    public function url(string $path): string
    {
        // In development (Vite dev server) — return direct URL
        if ($this->isDevServerRunning()) {
            return $this->devServerUrl($path);
        }

        // In production — look up hashed filename in manifest.json
        return $this->resolveFromManifest($path);
    }
}

3. Update URL::asset()

public function asset(string $path): string
{
    return app('assets.manifest')->url($path);
}

4. Vite dev server detection

Check if theme/public/hot exists (Vite writes this file when dev server is running):

private function isDevServerRunning(): bool
{
    return app('files')->exists(app()->path('public', 'theme') . '/hot');
}

5. wp_enqueue_scripts integration

// In a ServiceProvider or theme bootstrap
public function getHooks(): array
{
    return [
        'wp_enqueue_scripts' => fn() => $this->enqueueAssets(),
    ];
}

private function enqueueAssets(): void
{
    wp_enqueue_style('theme', URL::asset('css/app.css'));
    wp_enqueue_script('theme', URL::asset('js/app.js'), [], null, true);
}

6. Config file — assets.php

return [
    'manifest' => 'public/manifest.json', // relative to theme root
    'dev_server' => [
        'url'  => 'http://localhost:5173',
        'hot'  => 'public/hot',
    ],
];

Publishable via:

wp sloth vendor:publish --provider="Sloth\Assets\AssetsServiceProvider" --tag=config

7. Twig integration

{{ url().asset('css/app.css') }}
{{ asset('css/app.css') }}  {# shorthand #}

Acceptance criteria

• URL::asset() resolves hashed filenames from Vite manifest in production
• URL::asset() returns dev server URL when Vite dev server is running
• URL::asset() falls back to direct URL if no manifest exists
• AssetsServiceProvider publishable config
• asset() Twig helper/directive registered via SlothViewExtension
• Tests for manifest resolution
• views.md and routing.md updated with asset examples

Related

• koalapress migration dependency
• URL::asset() already exists in UrlGenerator.php — needs updating
• [Roadmap](https://docs.folivoro.com/roadmap)