Documentation improvements

[webpack-bot]

Hello guys,

I am just beginner with webpack and I fall in love to that. I would like to use edge version(v4). After many days I finally composed config file. I already worked with other bundlers(grunt, gulp, browserify) and now I can say that it was quite confusing intro into webpack. Most of time spent by googling.

In compare with other bundlers, configuration is more complex and require some node experiences and javascript skills from developer. So please be patient if you are one of them. It is possible that information that beginner find is already contained in doc, but then maybe it is not clear enough.

I found most of usefull informations in closed github issues and on stackoverflow. This tells something about current state of documentation.

There are already four major versions of webpacks and all beginner issues turn around it:

1. Proper migration doc v3 -> v4 is missing. In your doc, there is one page about migration and until now I really dont know which versions it solves. Most usefull migration info I found on medium.com.
2. Doc versioning. For example ag-grid doc has 4.0.1 mark but doc corresponds with v2 or v3. Each part of config doc could contain well-listed versions with corresponding code. It applies also to plugins and loaders. Versions are now mixed and not well marked in most of docs.
3. Better explained behaviour of each part.

For example I tried to configure webpack-dev-server and information that dev-server can not write files into folders on disc came to me after one day of googling "what is wrong with my config". I expected that it serves files in memory aswell as writing into disc when production mode is set and ExtractTextPlugin is provided.

---

This issue was moved from webpack/webpack#6662 by @sokra. Original issue was by @mysuf.

[montogeek]

Hi @mysuf

Regarding your webpack-dev-server experience, in its repo readme it says:

It uses webpack-dev-middleware under the hood, which provides fast in-memory access to the webpack assets.

If you follow webpack-dev-middleware link you will find its readme says:

No files are written to disk, rather it handles files in memory

I advice trying to click and read readmes thoughtfully.

About our webpack documentation:

1. We are working on creating this guide, meanwhile you can check official Medium webpack publication on: https://medium.com/webpack
2. We have been talking about it on https://github.com/webpack/webpack.js.org/issues/1854
3. I don't understand what are you talking about

[mysuf]

Regarding dev-server, it was quite bad example. The point is that as begginer, I thought that dev-server is extension of webpack (like plugins, loaders - it can share webpack config and you can start it by npm webpack command right?). So I thought that webpack will serve everything as usual and as bonus it runs dev-server. But later I found out that webpack forward it to different binary (npm webpack-dev-server command revealed).

Now I have everything tunned up so I only report issues I faced during my tutorial to webpack. I will share my final config file and later today, I will comment each problematic part. You can make step by step tutorial that compose config like this and it will cover 90% of newbies. The only variable is folder structure.

Asterisk comments are related to this issue:

const package = require('./package.json');
const webpack = require('webpack');

/*
* same as dev-server
* there is probability of mixing command webpack-dashboard
* with plugin inside - it could cause issues
* any benefits running binary command against using plugin?
*/
const Dashboard = require('webpack-dashboard');
const dashboard = new Dashboard();
const DashboardPlugin = require('webpack-dashboard/plugin');

/* 
* extractTextPlugin has not proper version dependency
* "*" or any wild flag does not work
*  package.json special case dependency: "extract-text-webpack-plugin": "next"
* found inside github issue 
*/
const ExtractTextPlugin = require("extract-text-webpack-plugin");

const HtmlWebpackPlugin = require("html-webpack-plugin");
const CleanWebpackPlugin = require('clean-webpack-plugin');
const path = require("path");

const port = 9000;

const htmlMinifyOptions = {
  removeAttributeQuotes: true,
  collapseWhitespace: true,
  html5: true,
  minifyCSS: true,
  removeComments: true,
  removeEmptyAttributes: true
};

module.exports = function(env, argv) {
  return {
    /* 
   *  importing external sources from entryfiles has big downside: url() paths
   *  it mixes paths relative to file where it is called with external url path
   *  loading directly to wp is not so clear, but far easier than importing
   *  bunch of plugins and doubledoting paths to fit relative right one
   */
    entry: [
      "./src/js/main.js",
      'ubuntu-fontface/_ubuntu-base.scss',
      './src/scss/styles.scss',
      "owl.carousel/dist/assets/owl.carousel.css"
    ], 
    /*
    * until now I dont fully understand hash and chunk usage
    * it would be nice to better describe
    * what is webpack chunk and what is hashed file
    * also plus/cons
    */
    output: {
      pathinfo: true,
      path: path.join(__dirname, "public"),
      filename: "assets/[name].js",
      sourceMapFilename: 'js/[name].map',
      chunkFilename: 'js/[id].js'
    },
    /*
    * what is necessarily to use hmr in each version?
    * does hot: true any role in wp4?
    * avoid present flag --hot and HotReloadPlugin inside scenario
    * provide single page/multipage example
    * /
    devServer: {
      contentBase: path.join(__dirname, "public"),
      compress: true,
      port: port,
      historyApiFallback: true,
      port: port,
      host: '127.0.0.1',
      inline: true,
      open: true,
      quiet: true,
      //hot: true
    },
    watch:true,
    resolve: { extensions: [".js"] },
    plugins: [
      new CleanWebpackPlugin(['public/*.html', 'public/dist']),
      new ExtractTextPlugin('assets/styles.css'),
      new HtmlWebpackPlugin({
        template: './src/index.html',
        filename: 'index.html',
        inject: false,
        minify: (argv.mode === 'production' ? htmlMinifyOptions : false)
      }),
      new HtmlWebpackPlugin({
        template: './src/list.html',
        filename: 'list.html',
        inject: false,
        minify: (argv.mode === 'production' ? htmlMinifyOptions : false)
      }),
      new HtmlWebpackPlugin({
        template: './src/detail.html',
        filename: 'detail.html',
        inject: false,
        minify: (argv.mode === 'production' ? htmlMinifyOptions : false)
      }),
      new DashboardPlugin({
        port: port,
        handler: dashboard.setData
      })
    ],
    module: {
      /*
      *  explanation of apply loader watterfall, what order it uses
      *  can be, for example, output of test/use forwarded to next test/use? 
      */  
      rules: [
        {
          test: /\.js$/,
          exclude: /node_modules/,
          use: {
            loader: "babel-loader",
            options: {presets: ['env']}
          }
        },
        {
          test: /\.(scss)$/,
          use: ExtractTextPlugin.extract({
            fallback: 'style-loader',
            use: [
              {
                loader: 'css-loader',
                options: (argv.mode === 'production' ? {
                  minimize: { discardComments: {removeAll: true} }
                } : {})
              },
              {
                loader: 'postcss-loader', // Run post css actions
                options: {
                  // post css plugins, can be exported to postcss.config.js
                  plugins: function () {
                    return [
                      require('precss'),
                      require('autoprefixer')
                    ];
                  }
                }
              },
              {loader: 'sass-loader'}
            ]
          })
        },
        { test: /\.css$/, use: ['style-loader', 'css-loader'] },
        {
          test: /\.(woff2?|ttf|otf|eot|svg)$/,
          loader: 'file-loader',
          options: {
            publicPath: "./",
            outputPath: "assets",
            name: 'fonts/[name].[ext]'
          }
        },
        {
          test: /\.(jpg|jpeg|png|gif)$/,
          loader: 'file-loader',
          options: {
            publicPath: "./",
            outputPath: "static",
            name: 'images/[name].[ext]'
          }
        }
      ]
    }
  }
}