Yii2 Webpack integration
This extension allow the developper to use Webpack 2 as the asset manager., (*1)
Webpack2 comes preconfigured with the following loaders
* javascript
* typescript
* sass
* less
* css, (*2)
, (*3)
, (*4)
Installation
If you use Packagist for installing packages, then you can update your `composer.json like this :, (*5)
``` json
{
"require": {
"sweelix/yii2-webpack": "*"
}
}, (*6)
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`
```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:, (*7)
{
"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, (*8)
``` php
return [
// add webpack to console bootstrap to attach console controllers
'bootstrap' => ['log', 'webpack'],
//....
'modules' => [
'webpack' => [
'class' => 'sweelix\webpack\Module',
],
// ...
],
];, (*9)
### Generate everything from scratch (init webpack stuff)
php protected/yii webpack, (*10)
* **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
```php
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, (*11)
webpack
or to enable automatic build on file change, (*12)
npm run watch
For production run, (*13)
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 :, (*14)
-
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, (*15)
-
<appdir>/assets/webpack/assets-catalog.json to let the webpack aware asset find the dist files, (*16)
-
<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
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., (*17)
Example
Instead of having webpack-yii2.json in root directory, you can put it in your assets directory., (*18)
In this case, application structure should look like this:, (*19)
- 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
-
...
In order to run this specific configuration,, (*20)
For development run, (*21)
webpack --env.config=protected/assets/webpack
or to enable automatic build on file change, (*22)
webpack --watch --env.config=protected/assets/webpack
For production run, (*23)
webpack -p --env.config=protected/assets/webpack
This will take the webpack-yii2.json which is in protected/assets/webpack everything else is unchanged, (*24)
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., (*25)
Fork the project, create a feature branch , and send us a pull request., (*26)
Wallogit.com
