README

Vite and Webpack asset bundles for Yii with manifest support.

👁 License
👁 Packagist Version

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 philippe@blackcube.io