[Custom Elements] Update README.md

packages/custom-elements/README.md

@@ -4,13 +4,32 @@ A polyfill for the [custom elements](https://html.spec.whatwg.org/multipage/scri
 v1 spec.
 
 ## Using
+#### Standalone script tag
+Include a script tag at the beginning of your page, *before* any code that
+manipulates the DOM. The custom-elements.min.js can be loaded from a CDN:
+```html
+<script src="https://unpkg.com/@webcomponents/custom-elements"></script>
+```
 
-Include `custom-elements.min.js` at the beginning of your page, *before* any code that
-manipulates the DOM:
+Or you can build it yourself and then load it:
 ```html
 <script src="custom-elements.min.js"></script>
 ```
 
+#### Via npm:
+If you're using npm, webpack, or similar tools, this package can be installed and imported:
+```bash
+npm install @webcomponents/custom-elements
+```
+
+```js
+// Do this import before any code that manipulates the DOM.
+import '@webcomponents/custom-elements'
+```
+
+#### Via the webcomponents polyfill
+Alternatively, you can use this polyfill via the [webcomponentjs polyfills](https://github.com/WebComponents/webcomponentsjs).
+
 ## Developing
 
 1. Install and build
@@ -209,3 +228,23 @@ customElements.define('c-e', class extends HTMLElement {});
 // 'added first'
 // The document is walked to attempt upgrades.
 ```
+
+### Settings
+
+The polyfill provides a few settings to improve performance by tweaking behavior.
+These settings typically have correctness trade offs (noted below) and should be
+used with caution.
+
+* `customElements.noDocumentConstructionObserver`: Set this flag to true to
+prevent the polyfill from mutation observing and upgrading DOM as it is added
+to the main document. This provides a small performance improvement during
+document parsing. With this setting on, the polyfill will not upgrade elements
+created when parsing the main document's HTML. This setting should be
+used in conjunction with a `polyfillWrapFlushCallback` that defers element
+upgrades until the parser is complete.
+
+* `customElements.shadyDomFastWalk`: Set this flag to true when using the
+ShadyDOM polyfill to optimize how elements are found in the DOM. There are a
+couple of limitations: (1) Elements that are children of Shadow DOM hosts and
+are not distributed to slots may not upgrade; (2) This setting is not compatible
+with using native HTML Imports.