Document `name` and Move Example

[skipjack]

Moving this issue from webpack/webpack.js.org#1330 (originally webpack/webpack#5144)...

See the comments in the originals but essentially the issue is that in the example on the main repo, there is a name option passed to the actual webpack config which isn't mentioned in this package's readme, the example, or in the main webpack configuration documentation:

var path = require("path");
var I18nPlugin = require("i18n-webpack-plugin");
var languages = {
	"en": null,
	"de": require("./de.json")
};
module.exports = Object.keys(languages).map(function(language) {
	return {
		name: language, // <= THIS PROPERTY
		entry: "./example",
		output: {
			path: path.join(__dirname, "js"),
			filename: language + ".output.js"
		},
		plugins: [
			new I18nPlugin(
				languages[language]
			)
		]
	};
});

I dug through the code a bit but couldn't figure out if or how that name property is used. Does this plugin actually use it in some way or does it just help identify locale-specific configs while debugging?

I would suggest two things (and I'd be happy to help with them):

1. If it is used, document how it affects the end user and why it's required.
2. I think we should move the example, maybe barring the actual output to this repository.

The second is more of an overall thing... I think those examples at the main repo lead to a bit of confusion for users. Imho they should either be located in the docs repo or the repo for the package they describe. I think I or @hovissimo would be happy to help push this forward just looking for some advice/clarification.

[michael-ciniawsky]

I give the standardisation REDAME overhaul here some priority :), if someone with more experience using the plugin (@sullenor) could help to clearify the usage of name, would be appreciated 😛

[mightyaleksey]

@skipjack as far as I know the i18n plugin doesn't use the name option in its code.

Since the example describes the two configurations (one for each language) I assume that the name is used here to identify the configs, so you may be able to execute only one from cli by its name. https://github.com/webpack/webpack/commit/3c77b07212d827184e55d5b7a0c281bdca93706a

Check this out:

webpack --config-name de
webpack --config-name en

[skipjack]

@sullenor thanks for that clarification, your description makes sense. Can you point me to an example or the source code where that --config-name flag is made available? I've never seen it used before, though I also haven't done much with i18n and webpack. I did do a quick search through the CLI repository for that flag but didn't see anything.

[mightyaleksey]

@skipjack looks like it was added in webpack version 3.4.0 (just found the release note) and implemented in that commit https://github.com/webpack/webpack/commit/3c77b07212d827184e55d5b7a0c281bdca93706a

The option can be used in case you have multi-compilation (your's webpack config expose an array of configurations). Using it you may choose particular configurations to run. I guess it was added to solve some performance issues :)

Here is another example of usage https://github.com/webpack/webpack/tree/master/examples/multi-compiler#webpackconfigjs

I'm not quite familiar with webpack-cli repo, but webpack has a cli interface build in: https://github.com/webpack/webpack/blob/master/bin/config-optimist.js