[docs] Document the /es folder

[oliviertassinari]

Document and make the /es folder official as requested by @dantman.

Closes #10857, I believe the root of the problem is to find in webpack side. Ideally, I would have tried with Rollup to see if that works.

[dantman]

Note that #10857 is being closed not because /es fixes the tree shaking problem. But because whether we use index.es.js or the raw /es code WebPack does not tree shake the modules and we cannot figure out why.

/es makes unrelated optimizations in babel available, not tree shaking optimizations.

[dantman]

I actually use the /es folder via a WebPack alias. Perhaps I should add some documentation for that later.

[oliviertassinari]

@dantman webpack is popular, why not.

[dantman]

Actually I'm not great at writing documentation. Writing can be difficult for me.

I just wanted to note that I use the following in my WebPack config:

	resolve: {
		alias: {
			// Load ECMAScript 6+/module variants of packages
			lodash: 'lodash-es',
			'material-ui': 'material-ui/es',
			'material-ui/styles': 'material-ui/es/styles',
			'material-ui-icons': 'material-ui-icons/es',
		},
	},

You can see the aliases for material-ui and material-ui-icons. I also alias material-ui/styles because I import it for now until #10858 is handled.

Doing it this way makes it so you don't need to explicitly write /es over an over when this is really a technical difference (import {TextField} from 'material-ui'; and import {TextField} from 'material-ui/es'; have the same API, the only difference is the behind the scenes syntax). And it also avoids the issue of 3rd party dependencies importing material-ui directly resulting in duplicates, since WebPack will rewrite material-ui to material-ui/es in those as well.

Although I suppose there is a chance that a 3rd party library could still try and import TextField from 'material-ui/TextField/TextField'; which would create duplicates.

[oliviertassinari]

Although I suppose there is a chance that a 3rd party library could still try and import TextField from 'material-ui/TextField/TextField'; which would create duplicates.

@dantman Most third party libraries do import TextField from 'material-ui/TextField'; over import { TextField } from 'material-ui';. It's what I think we should encourage for now. For instance:

• material-ui-pickers cc @dmtrKovalenko
• dx-react-grid-material-ui cc @kvet
• react-admin cc @fzaninotto

It's also the approach we document in all the demos. The react-router approach is interesting, but I what does it provide that the current approach doesn't?

[dantman]

@dantman Most third party libraries do import TextField from 'material-ui/TextField'; over import { TextField } from 'material-ui';.

Ok, then if I start using them I'm going to have to come up with an alternative configuration that rewrites the whole path based on a pattern instead of just aliasing individual modules.

[dantman]

I'm trying out this plugin config in WebPack instead of using resolve.alias:

// Force imports of packages like material-ui and material-ui-icons to use the /es versions
new webpack.NormalModuleReplacementPlugin(
	/^(material-ui|material-ui-icons)(\/|$)/,
	resource => {
		resource.request = resource.request.replace(
			/^([^/+]+)(?:\/es)?(\/.*)?$/,
			'$1/es$2'
		);
	}
),