[docs] Publish and Use an Element docs

docs/_data/guide.yml

@@ -8,17 +8,20 @@ toc:
     url: /guide/start
   templates: 
     title: Templates
-    desc: Create and render LitElement templates. Use JavaScript expressions to add properties and logic.      
     url: /guide/templates
   styles:
     title: Styles
     desc: Style your elements with CSS.
     url: /guide/styles
   properties: 
     title: Properties
-    desc: Declare and configure a component's properties and attributes.
     url: /guide/properties
   lifecycle: 
     title: Lifecycle
-    desc: Specify when an element should update. Respond to updates, or wait for an update to complete.
     url: /guide/lifecycle
+  publish: 
+    title: Publish a component
+    url: /guide/publish
+  use: 
+    title: Use a component
+    url: /guide/use

docs/_guide/publish.md

@@ -0,0 +1,75 @@
+---
+layout: guide
+title: Publish an element
+slug: publish
+---
+
+{::options toc_levels="1..3" /}
+* ToC
+{:toc}
+
+This page describes how to publish a LitElement component to npm.
+
+We recommend publishing JavaScript modules in standard ES2017. If you're writing your element in standard ES2017, you don't need to transpile for publication. If you're using TypeScript, or ES2017+ features such as decorators or class fields, you will need to transpile your element for publication.
+
+## Publishing to npm
+
+To publish your component to npm, [see the instructions on contributing npm packages](https://docs.npmjs.com/packages-and-modules/contributing-packages-to-the-registry).
+
+Your package.json configuration should have both the `main` and `module` fields:
+
+**package.json**
+
+```json
+{
+  "main": "my-element.js",
+  "module": "my-element.js"
+}
+```
+
+You should also create a README describing how to consume your component. A basic guide to consuming LitElement components is documented at [Use a component](use).
+
+## Transpiling with TypeScript
+
+When compiling your code from TypeScript to JavaScript, we recommend targeting ES2017 with Node.js module resolution. 
+
+The following JSON sample is a partial tsconfig.json that uses recommended options for targeting ES2017:
+
+```json
+  "compilerOptions": {
+    "target": "ES2017",
+    "module": "ES2017",
+    "moduleResolution": "node",
+    "lib": ["ES2017", "DOM"],
+    "experimentalDecorators": true
+  }
+```
+
+See the [tsconfig.json documentation](https://www.typescriptlang.org/docs/handbook/tsconfig-json.html) for more information.
+
+## Transpiling with Babel
+
+To transpile a LitElement component that uses proposed JavaScript features, use Babel. 
+
+Install Babel and the Babel plugins you need. For example:
+
+```
+npm install --save-dev @babel/core
+npm install --save-dev @babel/plugin-proposal-class-properties
+npm install --save-dev @babel/proposal-decorators
+```
+
+Configure Babel. For example:
+
+**babel.config.js**
+
+```js
+const plugins = [
+  '@babel/plugin-proposal-class-properties',
+  ['@babel/proposal-decorators', { decoratorsBeforeExport: true } ],
+];
+
+module.exports = { plugins };
+```
+
+You can run Babel via a bundler plugin such as [rollup-plugin-babel](https://www.npmjs.com/package/rollup-plugin-babel), or from the command line. See the [Babel documentation](https://babeljs.io/docs/en/) for more information.

docs/_guide/use.md

@@ -0,0 +1,155 @@
+---
+layout: guide
+title: Use a component
+slug: use
+---
+
+{::options toc_levels="1..3" /}
+* ToC
+{:toc}
+
+This page describes how to [use a LitElement component in your application](#use). It also describes how to make sure your deployed code is browser-ready by [building it for production](#build) and [loading the Web Components polyfills](#polyfills).
+
+## Use a LitElement component {#use}
+
+This is a general guide to using third-party LitElement components. Refer to a component's README or other documentation for specific details.
+
+To use a LitElement component in your code:
+
+1.  From your project folder, install the component from npm.
+
+    ```
+    npm install --save some-package-name
+    ```
+
+2.  Import the component.
+
+    In a JavaScript module: 
+
+    ```js
+    import 'some-package-name';
+    ```
+
+    In an HTML page:
+
+    ```html
+    <script type="module">
+    import './path-to/some-package-name/some-component.js';
+    </script>
+    ```
+
+    Or:
+
+    ```html
+    <script type="module" src="./path-to/some-package-name/some-component.js"></script>
+    ```
+
+3.  Add the component to your application or component:
+
+    ```html
+    <some-component></some-component>
+    ```
+
+## Develop {#develop}
+
+Elements built with LitElement are published to npm as standard JavaScript modules, which all major browsers can now load. 
+
+However, LitElement and elements built with it import their dependencies using bare module specifiers (for example, `import { ... } from 'module-name'`) instead of full paths (`import {...} from '../path/to/module-name'`). 
+
+At the time of writing, browsers must still be provided with the full path to a standard JavaScript module in order to load it. To convert bare module specifiers to full paths, a light transform is required.
+
+For a local server that does this automatically, try the [Open Web Components development server](https://open-wc.org/developing/owc-dev-server.html). 
+
+## Build for production {#build}
+
+To build for production, you can use a bundler such as WebPack or Rollup.
+
+The following example configuration for [Rollup](https://rollupjs.org/guide/en) resolves dependencies, converts bare module specifers to paths, and bundles the output.
+
+**rollup.config.js**
+
+```js
+import resolve from 'rollup-plugin-node-resolve';
+
+export default {
+  // If using any exports from a symlinked project, uncomment the following:
+  // preserveSymlinks: true,
+	input: ['src/index.js'],
+	output: {
+		file: 'build/index.js',
+    format: 'es',
+		sourcemap: true
+	},
+	plugins: [
+    resolve()
+  ]
+};
+```
+
+See a [sample build configuration for LitElement with Babel and Rollup](https://github.com/PolymerLabs/lit-element-build-rollup/blob/master/src/index.html).
+
+## Load the WebComponents polyfills {#polyfills}
+
+Elements built with LitElement use the Web Components set of standards, which are currently supported by all major browsers with the exception of Edge. 
+
+For compatibility with older browsers and Edge, load the Web Components polyfills.
+
+To load the WebComponents polyfills:
+
+1.  From your project folder, install the `@webcomponents/webcomponentsjs` package:
+
+    ```
+    npm install --save-dev @webcomponents/webcomponentsjs
+    ```
+
+2.  Add the polyfills to your HTML entrypoint:
+
+    ```html
+    <head>
+      <!-- 
+        If you are loading es5 code you will need 
+        custom-elements-es5-loader to make the element work in 
+        es6-capable browsers. 
+
+        If you are not loading es5 code, you don't need 
+        custom-elements-es5-loader. 
+      --> 
+      <!-- 
+      <script src="./path-to/custom-elements-es5-loader.js"></script>
+      -->
+
+      <!-- Load polyfills -->
+      <script 
+        src="path-to/webcomponents-loader.js"
+        defer>
+      </script> 
+
+      <!-- Load component when polyfills are definitely ready -->
+      <script type="module">
+        // Take care of cases in which the browser runs this
+        // script before it has finished running 
+        // webcomponents-loader.js (e.g. Firefox script execution order)
+        window.WebComponents = window.WebComponents || { 
+          waitFor(cb){ addEventListener('WebComponentsReady', cb) }
+        }
+
+        WebComponents.waitFor(async () => { 
+          import('./path-to/some-element.js');
+        });
+      </script>
+    </head>
+    <body>
+      <!-- Add the element to the page -->
+      <some-element></some-element>
+    </body>
+    ```
+
+3.  Ensure that `node_modules/@webcomponents/webcomponentsjs/webcomponents-loader.js` and `node_modules/@webcomponents/webcomponentsjs/bundles/**.*` are included in your build.
+
+<div class="alert"> 
+
+**Do not transpile the polyfills.** Bundling them is okay.
+
+</div>
+
+See [the Webcomponentsjs documentation](https://github.com/webcomponents/webcomponentsjs) for more information.