A little present for AngularClass. Webpack configuration documentation

webpack.config.js

@@ -28,81 +28,216 @@ const METADATA = {
 
 /**
  * Webpack configuration
+ *
+ * See: http://webpack.github.io/docs/configuration.html#cli
  */
 module.exports = {
 
-  // Static data for index.html
+  // Static metadata for index.html
+  //
+  // See: (custom attribute)
   metadata: METADATA,
 
-  devtool: 'cheap-module-eval-source-map',
-  // cache: true,
+  // Switch loaders to debug mode.
+  //
+  // See: http://webpack.github.io/docs/configuration.html#debug
   debug: true,
-  // devtool: 'eval' // for faster builds use 'eval'
 
+  // Developer tool to enhance debugging
+  //
+  // See: http://webpack.github.io/docs/configuration.html#devtool
+  // See: https://github.com/webpack/docs/wiki/build-performance#sourcemaps
+  devtool: 'cheap-module-eval-source-map',
+
+  // Cache generated modules and chunks to improve performance for multiple incremental builds.
+  // This is enabled by default in watch mode.
+  // You can pass false to disable it.
+  //
+  // See: http://webpack.github.io/docs/configuration.html#cache
+  // cache: false,
+
+  // The entry point for the bundle
   // Our Angular.js app
+  //
+  // See: http://webpack.github.io/docs/configuration.html#entry
   entry: {
+
     'polyfills': './src/polyfills.ts',
     'vendor': './src/vendor.ts',
     'main': './src/main.ts'
+
   },
 
+  // Options affecting the resolving of modules.
+  //
+  // See: http://webpack.github.io/docs/configuration.html#resolve
   resolve: {
+
+    // An array of extensions that should be used to resolve modules.
+    //
+    // See: http://webpack.github.io/docs/configuration.html#resolve-extensions
     extensions: ['', '.ts', '.js']
+
   },
 
-  // Configuration for our build files
+  // Options affecting the output of the compilation.
+  //
+  // See: http://webpack.github.io/docs/configuration.html#output
   output: {
+
+    // The output directory as absolute path (required).
+    //
+    // See: http://webpack.github.io/docs/configuration.html#output-path
     path: helpers.root('dist'),
+
+    // Specifies the name of each output file on disk.
+    // IMPORTANT: You must not specify an absolute path here!
+    //
+    // See: http://webpack.github.io/docs/configuration.html#output-filename
     filename: '[name].bundle.js',
+
+    // The filename of the SourceMaps for the JavaScript files.
+    // They are inside the output.path directory.
+    //
+    // See: http://webpack.github.io/docs/configuration.html#output-sourcemapfilename
     sourceMapFilename: '[name].map',
+
+    // The filename of non-entry chunks as relative path
+    // inside the output.path directory.
+    //
+    // See: http://webpack.github.io/docs/configuration.html#output-chunkfilename
     chunkFilename: '[id].chunk.js'
+
   },
 
+  // Options affecting the normal modules.
+  //
+  // See: http://webpack.github.io/docs/configuration.html#module
   module: {
+
+    // An array of applied pre and post loaders.
+    //
+    // See: http://webpack.github.io/docs/configuration.html#module-preloaders-module-postloaders
     preLoaders: [
+
+      // Tslint loader support for *.ts files
+      //
+      // See: https://github.com/wbuchwalter/tslint-loader
       // { test: /\.ts$/, loader: 'tslint-loader', exclude: [ helpers.root('node_modules') ] },
-      // TODO(gdi2290): `exclude: [ helpers.root('node_modules/rxjs') ]` fixed with rxjs 5 beta.3 release
-      { test: /\.js$/, loader: 'source-map-loader', exclude: [ helpers.root('node_modules/rxjs') ] }
+
+      // Source map loader support for *.js files
+      // Extracts SourceMaps for source files that as added as sourceMappingURL comment.
+      //
+      // See: https://github.com/webpack/source-map-loader
+      {test: /\.js$/, loader: 'source-map-loader', exclude: [helpers.root('node_modules/rxjs')]}
+
     ],
+
+    // An array of automatically applied loaders.
+    //
+    // IMPORTANT: The loaders here are resolved relative to the resource which they are applied to.
+    // This means they are not resolved relative to the configuration file.
+    //
+    // See: http://webpack.github.io/docs/configuration.html#module-loaders
     loaders: [
-      // Support for .ts files.
-      { test: /\.ts$/, loader: 'awesome-typescript-loader', exclude: [ /\.(spec|e2e)\.ts$/ ] },
 
-      // Support for *.json files.
-      { test: /\.json$/,  loader: 'json-loader' },
+      // Typescript loader support for .ts and Angular 2 async routes via .async.ts
+      //
+      // See: https://github.com/s-panferov/awesome-typescript-loader
+      {test: /\.ts$/, loader: 'awesome-typescript-loader', exclude: [/\.(spec|e2e)\.ts$/]},
+
+      // Json loader support for *.json files.
+      //
+      // See: https://github.com/webpack/json-loader
+      {test: /\.json$/, loader: 'json-loader'},
 
-      // Support for CSS as raw text
-      { test: /\.css$/,   loader: 'raw-loader' },
+      // Raw loader support for *.css files
+      // Returns file content as string
+      //
+      // See: https://github.com/webpack/raw-loader
+      {test: /\.css$/, loader: 'raw-loader'},
 
-      // Support for .html as raw text
-      { test: /\.html$/,  loader: 'raw-loader', exclude: [ helpers.root('src/index.html') ] }
+      // Raw loader support for *.html
+      // Returns file content as string
+      //
+      // See: https://github.com/webpack/raw-loader
+      {test: /\.html$/, loader: 'raw-loader', exclude: [helpers.root('src/index.html')]}
 
     ]
+
   },
 
+  // Add additional plugins to the compiler.
+  //
+  // See: http://webpack.github.io/docs/configuration.html#plugins
   plugins: [
+
+    // Plugin: ForkCheckerPlugin
+    // Description: Do type checking in a separate process, so webpack don't need to wait.
+    //
+    // See: https://github.com/s-panferov/awesome-typescript-loader#forkchecker-boolean-defaultfalse
     new ForkCheckerPlugin(),
+
+    // Plugin: OccurenceOrderPlugin
+    // Description: Varies the distribution of the ids to get the smallest id length
+    // for often used ids.
+    //
+    // See: https://webpack.github.io/docs/list-of-plugins.html#occurrenceorderplugin
+    // See: https://github.com/webpack/docs/wiki/optimization#minimize
     new webpack.optimize.OccurenceOrderPlugin(true),
-    new webpack.optimize.CommonsChunkPlugin({ name: ['main', 'vendor', 'polyfills'], minChunks: Infinity }),
-    // Static assets
-    new CopyWebpackPlugin([ { from: 'src/assets', to: 'assets' } ]),
-    // Generating HTML
-    new HtmlWebpackPlugin({ template: 'src/index.html', chunksSortMode: 'none' }),
-    // Environment helpers (when adding more properties make sure you include them in custom-typings.d.ts)
-    new webpack.DefinePlugin({
-      'ENV': JSON.stringify(METADATA.ENV),
-      'HMR': HMR
-    })
-  ],
 
-  // Other module loader config
+    // Plugin: CommonsChunkPlugin
+    // Description: Shares common code between the pages.
+    // It identifies common modules and put them into a commons chunk.
+    //
+    // See: https://webpack.github.io/docs/list-of-plugins.html#commonschunkplugin
+    // See: https://github.com/webpack/docs/wiki/optimization#multi-page-app
+    new webpack.optimize.CommonsChunkPlugin({name: ['main', 'vendor', 'polyfills'], minChunks: Infinity}),
 
-  // Our Webpack Development Server config
+    // Plugin: CopyWebpackPlugin
+    // Description: Copy files and directories in webpack.
+    //
+    // Copies project static assets.
+    //
+    // See: https://www.npmjs.com/package/copy-webpack-plugin
+    new CopyWebpackPlugin([{from: 'src/assets', to: 'assets'}]),
+
+    // Plugin: HtmlWebpackPlugin
+    // Description: Simplifies creation of HTML files to serve your webpack bundles.
+    // This is especially useful for webpack bundles that include a hash in the filename
+    // which changes every compilation.
+    //
+    // See: https://github.com/ampedandwired/html-webpack-plugin
+    new HtmlWebpackPlugin({template: 'src/index.html', chunksSortMode: 'none'}),
+
+    // Plugin: DefinePlugin
+    // Description: Define free variables.
+    // Useful for having development builds with debug logging or adding global constants.
+    //
+    // Environment helpers
+    //
+    // See: https://webpack.github.io/docs/list-of-plugins.html#defineplugin
+    // NOTE: when adding more properties make sure you include them in custom-typings.d.ts
+    new webpack.DefinePlugin({'ENV': JSON.stringify(METADATA.ENV), 'HMR': HMR})
+
+  ],
+
+  // Static analysis linter for TypeScript advanced options configuration
+  // Description: An extensible linter for the TypeScript language.
+  //
+  // See: https://github.com/wbuchwalter/tslint-loader
   tslint: {
     emitErrors: false,
     failOnHint: false,
-    resourcePath: 'src',
+    resourcePath: 'src'
   },
+
+  // Webpack Development Server configuration
+  // Description: The webpack-dev-server is a little node.js Express server.
+  // The server emits information about the compilation state to the client,
+  // which reacts to those events.
+  //
+  // See: https://webpack.github.io/docs/webpack-dev-server.html
   devServer: {
     port: METADATA.port,
     host: METADATA.host,
@@ -112,6 +247,11 @@ module.exports = {
       poll: 1000
     }
   },
+
+  // Include polyfills or mocks for various node stuff
+  // Description: Node configuration
+  //
+  // See: https://webpack.github.io/docs/configuration.html#node
   node: {
     global: 'window',
     process: true,