blackcube/yii-assets

Vite and Webpack asset bundles for Yii3 with scaffolding command

1.0.0 2026-01-24 11:49 UTC

Requires

• php: >=8.3
• ext-json: *
• yiisoft/aliases: ^3.1
• yiisoft/assets: ^4.0
• yiisoft/view: ^12.2
• yiisoft/yii-console: ^2.4

Requires (Dev)

• codeception/codeception: ^5.3
• codeception/module-asserts: ^3.3

BSD-3-Clause

• Philippe Gaultier

• assets
• manifest
• webpack
• yii3
• vite

README

PHP 8.3+ Vite and Webpack asset bundles for Yii3 framework 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',
];

Alias	Used by	Purpose
@assets	$basePath	Where Yii publishes assets (copy/symlink)
@assetsUrl	$baseUrl	Public URL to access published assets
@assetsSource	$sourcePath	Path to build output (optional shortcut)

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

Script	Description
npm run dist-clean	Build all (Vite + Webpack)
npm run dist-clean-vite	Build Vite only
npm run dist-clean-webpack	Build Webpack only
npm run watch	Webpack dev mode with watch

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 [e-mail]