sweelix/yii2-webpack

PHP 7.1+ Webpack integration for the Yii framework

1.4.0 2018-12-21 16:45 UTC

Requires

• php: >=7.1.0
• yiisoft/yii2: ~2.0.13

Requires (Dev)

• codeception/codeception: ~2.2

BSD-3-Clause

• Philippe Gaultier

• assets
• yii2
• webpack

README

This extension allow the developper to use Webpack 2 as the asset manager.

Webpack2 comes preconfigured with the following loaders

• javascript
• typescript
• sass
• less
• css

Installation

If you use Packagist for installing packages, then you can update your `composer.json like this :

{
    "require": {
        "sweelix/yii2-webpack": "*"
    }
}

Warning

When vendor modules use typescript, typescript code can collide. In order to avoid this, you should update your tsconfig.json to exclude vendor modules

Generic tsconfig.json

{
    "compilerOptions": {
        "sourceMap": true,
        "noImplicitAny": true,
        "module": "commonjs",
        "target": "es5",
        "jsx": "react",
        "allowJs": true
    }
}

Amended tsconfig.json

If vendor modules are in folder vendor you should update your tsconfig.json like this:

{
    "compilerOptions": {
        "sourceMap": true,
        "noImplicitAny": true,
        "module": "commonjs",
        "target": "es5",
        "jsx": "react",
        "allowJs": true
    },
    "exclude": [
        "node_modules",
        "vendor"
    ]
}

Howto use it

Add extension to your console configuration to enable CLI commands

return [
    // add webpack to console bootstrap to attach console controllers 
    'bootstrap' => ['log', 'webpack'],   
    //....
    'modules' => [
        'webpack' => [
            'class' => 'sweelix\webpack\Module',
        ],
        // ...
    ],
];

Generate everything from scratch (init webpack stuff)

php protected/yii webpack

• Generating package.json

  • Relative path to composer.json ? If you are in main directory, this is probably composer.json
  • Application name ? Application name which will be used in package.json
  • Author ? Your name
  • Description ? Description of package.json
  • License ? License of the application

• Generating webpack-yii2.json

  • Webpack assets path relative to package.json This is where you will write your front app (protected/assets/webpack for example)
  • Webpack assets source directory ? Name of the directory (inside webpack assets relative path) where you will create sources src
  • Webpack assets distribution directory ? Name of the directory (inside webpack assets relative path) where bundles will be generated dist
  • Webpack assets distribution scripts directory ? Name of the directory (inside dist) where scripts will be stored (js)
  • Webpack assets distribution styles directory ? Name of the directory (inside dist) where styles will be stored (css)
  • Webpack catalog filename ? Name of catalog file which will allow the asset manager to find the bundles

• Generating webpack.config.js

if you need to regenerate one of the files, you can use the following CLI commands :

• php protected/yii webpack/generate-config : regenerate webpack-yii2.json
• php protected/yii webpack/generate-package : regenerate package.json
• php protected/yii webpack/generate-webpack : regenerate webpack.config.js
• php protected/yii webpack/generate-generate-typescript-config : regenerate tsconfig.json

Sample application structure

If your application has the following directory structure :

• index.php
• composer.json
• protected
  • yii (console script)
  • assets
    • WebpackAsset.php
    • webpack
      • src
        • app.ts
        • css
          • app.css
  • ...

Run webpack init to prepare application

The typical answer when running php protected/yii webpack would be :

• Generating package.json

  • Relative path to composer.json ? Leave default value
  • Application name ? Leave default value
  • Author ? Leave default value
  • Description ? Leave default value
  • License ? Leave default value

• Generating webpack-yii2.json

  • Webpack assets path relative to package.json protected/assets/webpack
  • Webpack assets source directory ? Leave default value
  • Webpack assets distribution directory ? Leave default value
  • Webpack assets distribution scripts directory ? Leave default value
  • Webpack assets distribution styles directory ? Leave default value
  • Webpack catalog filename ? Leave default value

• Generating webpack.config.js

• Generating tsconfig.json

Application structure with generated files will be

• index.php
• composer.json
• package.json
• webpack-yii2.json
• webpack.config.js
• tsconfig.json
• protected
  • yii (console script)
  • assets
    • WebpackAsset.php
    • webpack
      • assets-catalog.json -> generated by webpack
      • dist -> generated by webpack
        • js
          • js bundles
        • css
          • css bundles
      • src
        • app.ts
        • css
          • app.css
  • ...

Create Webpack aware asset

namespace app\assets;

use sweelix\webpack\WebpackAssetBundle;

class WebpackAsset extends WebpackAssetBundle
{

    /**
     * @var bool enable caching system (default to false)
     */
    public $cacheEnabled = false;

    /**
     * @var \yii\caching\Cache cache name of cache to use, default to `cache`
     */
    public $cache = 'cache';

    /**
     * @var string base webpack alias (do not add /src nor /dist, they are automagically handled)
     */
    public $webpackPath = '@app/assets/webpack';

    /**
     * @var array list of webpack bundles to publish (these are the entries from webpack)
     * the bundles (except for the manifest one which should be in first position) must be defined
     * in the webpack-yii2.json configuration file
     */
    public $webpackBundles = [
        'manifest',
        'app'
    ];

}

Generate the assets

For development run

webpack

or to enable automatic build on file change

npm run watch

For production run

npm run dist-clean 

Add files to your repository

When your assets are ready, you have to make sure following files are added to your repository :

• package.json node package management

• webpack.config.js needed to run webpack

• webpack-yii2.json needed by webpack.config.js to define you app entry points and the target directories

• tsconfig.json needed by webpack.config.js to handle Typescript files

• <appdir>/assets/webpack/assets-catalog.json to let the webpack aware asset find the dist files

• <appdir>/assets/webpack/dist to keep the assets (they are not dynamically generated when asset is registered)

• <appdir>/assets/webpack/src because you want to keep your sources :-)

File webpack-yii2.json explained

{
    "sourceDir": "protected\/assets\/webpack",
    "entry": {
        "app": "./app.ts"
    },
    "commonBundles": [
        "manifest"
    ],
    "externals": {

    },
    "subDirectories": {
        "sources": "src",
        "dist": "dist"
    },
    "assets": {
        "styles": "css",
        "scripts": "js"
    },
    "sri": "sha256",
    "catalog": "assets-catalog.json"
}

Specific to yii2-webpack module

• sourceDir relative path to the directory where assets will be managed
• subDirectories subpath (in < sourceDir >) of sources and distribution files
• assets subpath (in < sourceDir >/< subDirectories.dist >) of styles and scripts assets
• catalog name of assets catalog, must be in synch with WebpackAssetBundle::$webpackAssetCatalog

Mapped to Webpack vars

• entry object syntax entry points Webpack entry documentation
• commonBundles explicit vendor chunk Webpack CommonChunkPlugin documentation
• externals object syntax externals Webpack externals documentation
• alias object syntax resolve.alias Webpack resolve.alias documentation

Allow multiple webpack-yii2.json

If your project needs multiple webpack configurations (take care of manifest.js collision), you can create the webpack-yii2.json directly in the assets directory.

Example

Instead of having webpack-yii2.json in root directory, you can put it in your assets directory.

In this case, application structure should look like this:

• index.php
• composer.json
• package.json
• webpack-yii2.json
• webpack.config.js
• tsconfig.json
• protected
  • yii (console script)
  • assets
    • WebpackAsset.php
    • webpack
      • webpack-yii2.json -> Webpack specific file
      • assets-catalog.json -> generated by webpack
      • dist -> generated by webpack
        • js
          • js bundles
        • css
          • css bundles
      • src
        • app.ts
        • css
          • app.css
  • ...

In order to run this specific configuration,

For development run

webpack --env.config=protected/assets/webpack

or to enable automatic build on file change

webpack --watch  --env.config=protected/assets/webpack

For production run

webpack -p  --env.config=protected/assets/webpack

This will take the webpack-yii2.json which is in protected/assets/webpack everything else is unchanged

Contributing

All code contributions - including those of people having commit access - must go through a pull request and approved by a core developer before being merged. This is to ensure proper review of all the code.

Fork the project, create a feature branch , and send us a pull request.