material-components · moog16 · Sep 28, 2018 · Jul 26, 2018 · Jul 26, 2018 · Jul 26, 2018
diff --git a/README.md b/README.md
@@ -96,10 +96,14 @@ npm install @material/ripple
 Then import the ES2015 file for @material/ripple into your application, and initialize an MDCRipple with a DOM element:
 
 ```js
-import {MDCRipple} from '@material/ripple';
+import {MDCRipple} from '@material/ripple/index';
 const ripple = new MDCRipple(document.querySelector('.foo-button'));
 ```
 
+> Note: Import `@material/ripple/index` if you wish to transpile MDC Web's ES2015 sources as part of your build process.
+> If your build toolchain is configured to only transpile your own sources, import `@material/ripple` instead, which will
+> reference the distributed UMD module instead.
+
 This will produce a Material Design ripple on the button!
 
 <img src="docs/button_with_ripple.png" alt="Button with Ripple" width="90" height="36">

diff --git a/docs/getting-started.md b/docs/getting-started.md
@@ -7,9 +7,9 @@ path: /docs/getting-started/
 
 # Getting Started
 
-## Quick Start
+## Quick Start (CDN)
 
-To try Material Components for the web with minimal setup, load the CSS and JS from unpkg:
+To try Material Components for the web with minimal setup, load the precompiled all-in-one CSS and JS bundles from unpkg:
 
 ```html
 https://unpkg.com/material-components-web@latest/dist/material-components-web.min.css
@@ -28,11 +28,27 @@ Then include MDC markup...
 mdc.ripple.MDCRipple.attachTo(document.querySelector('.foo-button'));
 ```
 
-However, it is highly recommended to install Material Components for the web via npm and consume its ES2015 modules and Sass directly. This is outlined in the steps below.
+## Installing Locally
 
-## Using MDC Web with ES2015 and Sass
+Material Components for the web can be installed locally using npm. It is available as a single all-in-one package:
 
-This section walks you through how to [install MDC Web Node modules](https://www.npmjs.com/org/material), and bundle the Sass and JavaScript from those Node modules in your [webpack](https://webpack.js.org/) configuration.
+```
+npm i material-components-web
+```
+
+...or as individual components:
+
+```
+npm i @material/button @material/ripple
+```
+
+Each package provides precompiled CSS and JS under its `dist` folder. The precompiled JS is converted to UMD format and is consumable directly by browsers or within any workflow that expects to consume ES5. Referencing `@material/foo` within a Node.js context will automatically reference the precompiled JS under `dist`.
+
+However, for optimal results, we recommend consuming MDC Web's ES2015 modules and Sass directly. This is outlined in the steps below.
+
+## Using MDC Web with Sass and ES2015
+
+This section walks through how to [install MDC Web Node modules](https://www.npmjs.com/org/material), and bundle the Sass and JavaScript from those Node modules in your [webpack](https://webpack.js.org/) configuration.
 
 > Note: This guide assumes you have Node.js and npm installed locally.
 
@@ -325,10 +341,14 @@ npm install --save-dev @material/ripple
 We need to tell our `app.js` to import the ES2015 file for `@material/ripple`. We also need to initialize an `MDCRipple` with a DOM element. Replace your “hello world” version of `app.js` with this code:
 
 ```js
-import {MDCRipple} from '@material/ripple';
+import {MDCRipple} from '@material/ripple/index';
 const ripple = new MDCRipple(document.querySelector('.foo-button'));
 ```
 
+> Note: We explicitly reference `index` within each MDC Web package in order to import the ES2015 source directly.
+> This allows for tree-shaking and avoiding duplicate code for common dependencies (e.g. Ripple).
+> However, it requires transpiling the MDC Web modules using the tools installed in Step 3.
+
 Now run `npm start` again and open http://localhost:8080. You should see a Material Design ripple on the button!
 
 <img src="button_with_ripple.png" alt="Button with Ripple" width="90" height="36">

diff --git a/docs/importing-js.md b/docs/importing-js.md
@@ -12,21 +12,37 @@ Most components ship with Component / Foundation classes which are used to provi
 
 ## ES2015
 
-```javascript
+```js
 import {MDCFoo, MDCFooFoundation} from '@material/foo';
 ```
 
+Note that MDC Web's packages point `main` to pre-compiled UMD modules under `dist` to maximize compatibility.
+Build toolchains often assume that dependencies under `node_modules` are already ES5, and thus skip transpiling them.
+
+However, if you want to take advantage of tree-shaking and dependency sharing within MDC Web's code to reduce the size
+of your built assets, you will want to explicitly reference the package's `index.js`, which contains the ES2015+ source:
+
+```js
+import {MDCFoo, MDCFooFoundation} from '@material/foo/index';
+```
+
+Note that in this case, you must ensure your build toolchain is configured to process and transpile MDC Web's modules
+as well as your own. You will also need to include babel's
+[`transform-object-assign`](https://www.npmjs.com/package/babel-plugin-transform-object-assign) plugin for IE 11 support.
+
+See the [Getting Started guide](getting-started.md) for more details on setting up an environment.
+
 ## CommonJS
 
-```javascript
+```js
 const mdcFoo = require('mdc-foo');
 const MDCFoo = mdcFoo.MDCFoo;
 const MDCFooFoundation = mdcFoo.MDCFooFoundation;
 ```
 
 ## AMD
 
-```javascript
+```js
 require(['path/to/mdc-foo'], mdcFoo => {
   const MDCFoo = mdcFoo.MDCFoo;
   const MDCFooFoundation = mdcFoo.MDCFooFoundation;
@@ -35,21 +51,7 @@ require(['path/to/mdc-foo'], mdcFoo => {
 
 ## Global
 
-```javascript
+```js
 const MDCFoo = mdc.foo.MDCFoo;
 const MDCFooFoundation = mdc.foo.MDCFooFoundation;
 ```
-
-## Automatic Instantiation
-
-```javascript
-mdc.foo.MDCFoo.attachTo(document.querySelector('.mdc-foo'));
-```
-
-## Manual Instantiation
-
-```javascript
-import {MDCFoo} from '@material/foo';
-
-const foo = new MDCFoo(document.querySelector('.mdc-foo'));
-```
diff --git a/packages/material-components-web/package.json b/packages/material-components-web/package.json
@@ -7,7 +7,7 @@
     "material components",
     "material design"
   ],
-  "main": "index.js",
+  "main": "dist/material-components-web.js",
   "repository": {
     "type": "git",
     "url": "https://github.com/material-components/material-components-web"

diff --git a/packages/mdc-animation/package.json b/packages/mdc-animation/package.json
@@ -8,7 +8,7 @@
     "material design",
     "animation"
   ],
-  "main": "index.js",
+  "main": "dist/mdc.animation.js",
   "repository": {
     "type": "git",
     "url": "https://github.com/material-components/material-components-web.git"

diff --git a/packages/mdc-auto-init/package.json b/packages/mdc-auto-init/package.json
@@ -2,7 +2,7 @@
   "name": "@material/auto-init",
   "description": "Declarative, easy-to-use auto-initialization for Material Components for the web",
   "version": "0.39.0",
-  "main": "index.js",
+  "main": "dist/mdc.autoInit.js",
   "license": "MIT",
   "repository": {
     "type": "git",

diff --git a/packages/mdc-base/package.json b/packages/mdc-base/package.json
@@ -3,7 +3,7 @@
   "description": "The set of base classes for Material Components for the web",
   "version": "0.39.0",
   "license": "MIT",
-  "main": "index.js",
+  "main": "dist/mdc.base.js",
   "repository": {
     "type": "git",
     "url": "https://github.com/material-components/material-components-web.git"

diff --git a/packages/mdc-checkbox/package.json b/packages/mdc-checkbox/package.json
@@ -8,7 +8,7 @@
     "material design",
     "checkbox"
   ],
-  "main": "index.js",
+  "main": "dist/mdc.checkbox.js",
   "repository": {
     "type": "git",
     "url": "https://github.com/material-components/material-components-web.git"

diff --git a/packages/mdc-chips/package.json b/packages/mdc-chips/package.json
@@ -3,6 +3,7 @@
   "description": "The Material Components for the Web chips component",
   "version": "0.40.0",
   "license": "MIT",
+  "main": "dist/mdc.chips.js",
   "keywords": [
     "material components",
     "material design",

diff --git a/packages/mdc-dialog/package.json b/packages/mdc-dialog/package.json
@@ -9,7 +9,7 @@
     "dialog",
     "modal"
   ],
-  "main": "index.js",
+  "main": "dist/mdc.dialog.js",
   "repository": {
     "type": "git",
     "url": "https://github.com/material-components/material-components-web.git"

diff --git a/packages/mdc-dom/package.json b/packages/mdc-dom/package.json
@@ -3,7 +3,7 @@
   "description": "DOM manipulation utilities for Material Components for the web",
   "version": "0.40.0",
   "license": "MIT",
-  "main": "index.js",
+  "main": "dist/mdc.dom.js",
   "repository": {
     "type": "git",
     "url": "https://github.com/material-components/material-components-web.git"

diff --git a/packages/mdc-drawer/package.json b/packages/mdc-drawer/package.json
@@ -9,7 +9,7 @@
     "navigation",
     "drawer"
   ],
-  "main": "index.js",
+  "main": "dist/mdc.drawer.js",
   "repository": {
     "type": "git",
     "url": "https://github.com/material-components/material-components-web.git"

diff --git a/packages/mdc-floating-label/package.json b/packages/mdc-floating-label/package.json
@@ -9,7 +9,7 @@
     "floatinglabel",
     "floating label"
   ],
-  "main": "index.js",
+  "main": "dist/mdc.floatingLabel.js",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/material-components/material-components-web.git"

diff --git a/packages/mdc-form-field/package.json b/packages/mdc-form-field/package.json
@@ -8,7 +8,7 @@
     "material design",
     "form"
   ],
-  "main": "index.js",
+  "main": "dist/mdc.formField.js",
   "repository": {
     "type": "git",
     "url": "https://github.com/material-components/material-components-web.git"

diff --git a/packages/mdc-grid-list/package.json b/packages/mdc-grid-list/package.json
@@ -3,6 +3,7 @@
   "version": "0.40.0",
   "description": "The Material Components for the web grid list component",
   "license": "MIT",
+  "main": "dist/mdc.gridList.js",
   "repository": {
     "type": "git",
     "url": "https://github.com/material-components/material-components-web.git"

diff --git a/packages/mdc-icon-button/package.json b/packages/mdc-icon-button/package.json
@@ -3,6 +3,7 @@
   "description": "The Material Components for the web icon button component",
   "version": "0.40.0",
   "license": "MIT",
+  "main": "dist/mdc.iconButton.js",
   "keywords": [
     "material components",
     "material design",

diff --git a/packages/mdc-icon-toggle/package.json b/packages/mdc-icon-toggle/package.json
@@ -8,7 +8,7 @@
     "material design",
     "icon toggle"
   ],
-  "main": "index.js",
+  "main": "dist/mdc.iconToggle.js",
   "repository": {
     "type": "git",
     "url": "https://github.com/material-components/material-components-web.git"

diff --git a/packages/mdc-line-ripple/package.json b/packages/mdc-line-ripple/package.json
@@ -9,7 +9,7 @@
     "lineripple",
     "line-ripple"
   ],
-  "main": "index.js",
+  "main": "dist/mdc.lineRipple.js",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/material-components/material-components-web.git"

diff --git a/packages/mdc-linear-progress/package.json b/packages/mdc-linear-progress/package.json
@@ -3,6 +3,7 @@
   "description": "The Material Components for the web linear progress indicator component",
   "version": "0.40.0",
   "license": "MIT",
+  "main": "dist/mdc.linearProgress.js",
   "keywords": [
     "material components",
     "material design",

diff --git a/packages/mdc-list/package.json b/packages/mdc-list/package.json
@@ -3,6 +3,7 @@
   "description": "The Material Components for the web list component",
   "version": "0.40.0",
   "license": "MIT",
+  "main": "dist/mdc.list.js",
   "keywords": [
     "material components",
     "material design",

diff --git a/packages/mdc-menu-surface/package.json b/packages/mdc-menu-surface/package.json
@@ -8,7 +8,7 @@
     "material design",
     "menu surface"
   ],
-  "main": "index.js",
+  "main": "dist/mdc.menuSurface.js",
   "repository": {
     "type": "git",
     "url": "https://github.com/material-components/material-components-web.git"

diff --git a/packages/mdc-menu/package.json b/packages/mdc-menu/package.json
@@ -8,7 +8,7 @@
     "material design",
     "menu"
   ],
-  "main": "index.js",
+  "main": "dist/mdc.menu.js",
   "repository": {
     "type": "git",
     "url": "https://github.com/material-components/material-components-web.git"

diff --git a/packages/mdc-notched-outline/package.json b/packages/mdc-notched-outline/package.json
@@ -9,7 +9,7 @@
     "notchedoutline",
     "notched outline"
   ],
-  "main": "index.js",
+  "main": "dist/mdc.notchedOutline.js",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/material-components/material-components-web.git"

diff --git a/packages/mdc-radio/package.json b/packages/mdc-radio/package.json
@@ -8,7 +8,7 @@
     "material design",
     "radio"
   ],
-  "main": "index.js",
+  "main": "dist/mdc.radio.js",
   "repository": {
     "type": "git",
     "url": "https://github.com/material-components/material-components-web.git"

diff --git a/packages/mdc-ripple/package.json b/packages/mdc-ripple/package.json
@@ -8,7 +8,7 @@
     "material design",
     "ripple"
   ],
-  "main": "index.js",
+  "main": "dist/mdc.ripple.js",
   "repository": {
     "type": "git",
     "url": "https://github.com/material-components/material-components-web.git"

diff --git a/packages/mdc-select/package.json b/packages/mdc-select/package.json
@@ -9,7 +9,7 @@
     "select",
     "multi select"
   ],
-  "main": "index.js",
+  "main": "dist/mdc.select.js",
   "repository": {
     "type": "git",
     "url": "https://github.com/material-components/material-components-web.git"

diff --git a/packages/mdc-selection-control/package.json b/packages/mdc-selection-control/package.json
@@ -3,7 +3,7 @@
   "description": "The set of base classes for Material selection controls",
   "version": "0.40.0",
   "license": "MIT",
-  "main": "index.js",
+  "main": "dist/mdc.selectionControl.js",
   "repository": {
     "type": "git",
     "url": "https://github.com/material-components/material-components-web.git"

diff --git a/packages/mdc-slider/package.json b/packages/mdc-slider/package.json
@@ -2,7 +2,7 @@
   "name": "@material/slider",
   "version": "0.40.0",
   "description": "The Material Components for the web slider component",
-  "main": "index.js",
+  "main": "dist/mdc.slider.js",
   "license": "MIT",
   "repository": {
     "type": "git",

diff --git a/packages/mdc-snackbar/package.json b/packages/mdc-snackbar/package.json
@@ -8,7 +8,7 @@
     "material design",
     "snackbar"
   ],
-  "main": "index.js",
+  "main": "dist/mdc.snackbar.js",
   "repository": {
     "type": "git",
     "url": "https://github.com/material-components/material-components-web.git"

diff --git a/packages/mdc-switch/package.json b/packages/mdc-switch/package.json
@@ -8,7 +8,7 @@
     "material design",
     "switch"
   ],
-  "main": "index.js",
+  "main": "dist/mdc.switch.js",
   "repository": {
     "type": "git",
     "url": "https://github.com/material-components/material-components-web.git"

diff --git a/packages/mdc-tab-bar/package.json b/packages/mdc-tab-bar/package.json
@@ -9,7 +9,7 @@
     "tab",
     "bar"
   ],
-  "main": "index.js",
+  "main": "dist/mdc.tabBar.js",
   "repository": {
     "type": "git",
     "url": "https://github.com/material-components/material-components-web.git"

diff --git a/packages/mdc-tab-indicator/package.json b/packages/mdc-tab-indicator/package.json
@@ -9,7 +9,7 @@
     "tab",
     "indicator"
   ],
-  "main": "index.js",
+  "main": "dist/mdc.tabIndicator.js",
   "repository": {
     "type": "git",
     "url": "https://github.com/material-components/material-components-web.git"