README

Vite and Webpack asset bundles for Yii with manifest support.

Installation

composer require blackcube/yii-assets

Configuration

Aliases

In config/web/aliases.php, ensure these aliases are defined:

<?php

declare(strict_types=1);

return [
    '@assets' => '@root/www/assets',
    '@assetsUrl' => '@baseUrl/assets',
    '@assetsSource' => '@root/assets',
    '@baseUrl' => '/',
    '@public' => '@root/www',
];

DI Container

Create config/web/di/assets.php:

<?php

declare(strict_types=1);

use Blackcube\Assets\ManifestAssetLoader;
use Yiisoft\Aliases\Aliases;
use Yiisoft\Assets\AssetLoader;
use Yiisoft\Assets\AssetLoaderInterface;
use Yiisoft\Definitions\Reference;

return [
    AssetLoaderInterface::class => [
        'class' => ManifestAssetLoader::class,
        '__construct()' => [
            'innerLoader' => Reference::to(AssetLoader::class),
            'aliases' => Reference::to(Aliases::class),
        ],
    ],
];

Quick Start

1. Initialize build tools (once)

./yii blackcube:assets/init

Interactive prompts:

• Builder(s): vite, webpack, or both
• Source directory (default: assets/src)
• Output base directory (default: assets)

Generated files:

project/
├── assets-blackcube.json
├── package.json
├── tsconfig.json
├── vite.config.mts          # if Vite selected
├── vite-manifest-plugin.mts # if Vite selected
├── webpack.config.mts       # if Webpack selected
└── assets/
    └── src/
        └── tsconfig.json

2. Build

npm install
npm run dist-clean

Output structure:

assets/
├── dist-vite/
│   ├── js/
│   ├── css/
│   └── assets-catalog.json
└── dist-webpack/
    ├── js/
    ├── css/
    └── assets-catalog.json

3. Create your asset bundle(s)

Create one or more bundles pointing to the build output:

Vite:

<?php

declare(strict_types=1);

namespace App\Asset;

use Blackcube\Assets\ViteAssetBundle;

final class AppAsset extends ViteAssetBundle
{
    public ?string $basePath = '@assets';
    public ?string $baseUrl = '@assetsUrl';
    public ?string $sourcePath = '@assetsSource/dist-vite';
}

Webpack:

<?php

declare(strict_types=1);

namespace App\Asset;

use Blackcube\Assets\WebpackAssetBundle;

final class AppAsset extends WebpackAssetBundle
{
    public ?string $basePath = '@assets';
    public ?string $baseUrl = '@assetsUrl';
    public ?string $sourcePath = '@assetsSource/dist-webpack';
}

4. Register in view

$assetManager->register(AppAsset::class);

npm Scripts

Advanced Options

WebpackAssetBundle

final class AppAsset extends WebpackAssetBundle
{
    public ?string $basePath = '@assets';
    public ?string $baseUrl = '@assetsUrl';
    public ?string $sourcePath = '@assetsSource/dist-webpack';

    // Explicit bundle order (default: auto-detect from catalog)
    public array $bundles = ['manifest', 'vendors', 'app'];

    // Load only CSS from these bundles (skip JS)
    public array $cssOnly = [];

    // Load only JS from these bundles (skip CSS)
    public array $jsOnly = ['manifest'];
}

By default, WebpackAssetBundle auto-loads all bundles from the catalog with ordering: manifest → vendors → rest.

License

BSD-3-Clause. See LICENSE.md.

Author

Philippe Gaultier philippe@blackcube.io