From 414d3868ca7e265d86e41df82865c6a9734d0a49 Mon Sep 17 00:00:00 2001 From: Kate Jeffreys Date: Thu, 10 Jan 2019 12:59:40 -0800 Subject: [PATCH 01/12] draft publish and use docs --- docs/_guide/deploy.md | 13 --- docs/_guide/publish.md | 63 ++++++++++++++ docs/_guide/use.md | 192 +++++++++++++++++++++++++++++++++++++++++ 3 files changed, 255 insertions(+), 13 deletions(-) delete mode 100644 docs/_guide/deploy.md create mode 100644 docs/_guide/publish.md create mode 100644 docs/_guide/use.md diff --git a/docs/_guide/deploy.md b/docs/_guide/deploy.md deleted file mode 100644 index 654e4861..00000000 --- a/docs/_guide/deploy.md +++ /dev/null @@ -1,13 +0,0 @@ ---- -layout: guide -title: Deploy -slug: deploy ---- - -{::options toc_levels="1..3" /} -* ToC -{:toc} - -## Polyfills - -## Build tools diff --git a/docs/_guide/publish.md b/docs/_guide/publish.md new file mode 100644 index 00000000..11ad7885 --- /dev/null +++ b/docs/_guide/publish.md @@ -0,0 +1,63 @@ +--- +layout: guide +title: Publish an element +slug: publish +--- + +**TODO: actual sentences** + +{::options toc_levels="1..3" /} +* ToC +{:toc} + +TODO: make sentences + +* We recommend publishing ES2017 +* We recommend not bundling elements +* If you're writing your element in standard ES2017, you don't need to transpile for publication +* If you're using decorators, class fields, or other ES2017+ features, you'll need to transpile your element for publication + +## publish to npm + +To publish to npm [see instructions on npm site](https://docs.npmjs.com/packages-and-modules/contributing-packages-to-the-registry). + +Your package.json configuration must have both `main` and `module`: + +**package.json** + +```json +{ + "main": "my-element.js", + "module": "my-element.js" +} +``` + +Also, make a README telling people how to consume your element + +### if typescript + +To transpile TypeScript, conigure tsconfig.josn. eg + +**tsconfig.json** + +```json +{ + "include": ["src/*.ts"], + "compilerOptions": { + "downlevelIteration": true, + "target": "es2017", + "module": "es2017", + "moduleResolution": "node", + "lib": ["es2017"], + "experimentalDecorators": true + } +} +``` + +Run `tsc`: + +```bash +tsc +``` + +Publish `lib` as well as `src`. Users would consume `lib`. diff --git a/docs/_guide/use.md b/docs/_guide/use.md new file mode 100644 index 00000000..047deeb6 --- /dev/null +++ b/docs/_guide/use.md @@ -0,0 +1,192 @@ +--- +layout: guide +title: Use an element +slug: use +--- + +**TODO: clean this up** + +{::options toc_levels="1..3" /} +* ToC +{:toc} + +General guide. you must also the element's README + +## import + +### Install from npm + +``` +npm install some-element-package-name +``` + +### Import the package + +``` +import 'some-element-package-name'; +``` + +or + +``` + +``` + +### Use in html + +```html + +``` + +## Build an app with a LitElement in it + +* babel +* rollup/webpack + +### Configure Babel + +* babel - transpile from es2017 to target + +e.g. 1 - serving esmodules + +**.babelrc** + +``` +{ + "presets": [ + [ + "@babel/preset-env", + { + "modules": false, + "targets": { + "esmodules": true + } + } + ] + ], + "plugins": [@babel/proposal-decorators] +} +``` + +e.g. 2 - serving es5 + +**.babelrc** + +``` +{ + "presets": [ + [ + "@babel/preset-env", + { + "modules": ??, + "targets": { + ?? + } + } + ] + ], + "plugins": [@babel/proposal-decorators] +} +``` + + +## Configure a bundler + +### Rollup example + +**rollup.config.js** + +```js +import resolve from 'rollup-plugin-node-resolve'; +import common from 'rollup-plugin-commonjs'; +import babel from 'rollup-plugin-babel'; + +export default { + input: 'index.js', + output: { + dir: 'build', + format: 'es' + }, + plugins: [ + resolve(), + common(), + babel({ + exclude: 'node_modules/**', + include: 'src/**' + }) + ] +}; +``` + +### WebPack example + +```js + +``` + + +## load Polyfills from entrypoing + +Because reasons + + * reason + * reason + + +### install polyfills + +``` +npm install @webcomponents/webcomponentsjs +``` + +### Use polyfills + +**index.html** + +```html + + + + + + + + + + + + + + +``` + +
+ +**Do not transpile or bundle the polyfills.** + +
+ +See [the Webcomponentsjs documentation](https://github.com/webcomponents/webcomponentsjs) for more information. From d2f26976d3f1888f76b3ba34d2d0a468a09ec7d5 Mon Sep 17 00:00:00 2001 From: Kate Jeffreys Date: Wed, 16 Jan 2019 18:37:44 -0800 Subject: [PATCH 02/12] Elaborate on use instructions --- docs/_data/guide.yml | 9 +- docs/_guide/use.md | 196 ++++++++++++++++++++++++------------------- 2 files changed, 115 insertions(+), 90 deletions(-) diff --git a/docs/_data/guide.yml b/docs/_data/guide.yml index 9068b089..7e5d59d7 100644 --- a/docs/_data/guide.yml +++ b/docs/_data/guide.yml @@ -8,7 +8,6 @@ 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 @@ -16,9 +15,13 @@ toc: 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 diff --git a/docs/_guide/use.md b/docs/_guide/use.md index 047deeb6..d55a02df 100644 --- a/docs/_guide/use.md +++ b/docs/_guide/use.md @@ -1,59 +1,93 @@ --- layout: guide -title: Use an element +title: Use a component slug: use --- -**TODO: clean this up** - {::options toc_levels="1..3" /} * ToC {:toc} -General guide. you must also the element's README +This page describes how to [use a LitElement component in your application](#use). It also describes how to make sure your deployed application is compatible with your target browsers by [building it for production](#build) and [loading the Web Components polyfills](#polyfills). -## import +## Use a LitElement component {#use} -### Install from npm +This is a general guide to using third-party LitElement components. Refer to a component's README or other documentation for specific details. -``` -npm install some-element-package-name -``` +To use a LitElement component in your code: + +1. Install the component from npm. + + ``` + npm install some-package-name + ``` + +2. Import the component. + + In another JavaScript module: + + ```js + import 'some-package-name'; + ``` + + In an HTML page: + + ```html + + ``` + + Or: + + ```html + + ``` + +3. Add the component to the page via markup: + + ```html + + ``` + +## Serve for local development {#serve} + +LitElement uses npm conventions to reference dependencies by name. A light transform to rewrite specifiers to URLs is required to get it to run in the browser. + +For local development, we recommend installing the [Polymer CLI](https://github.com/Polymer/polymer-cli) and using its development server via `polymer serve`. The development server automatically handles this transform. -### Import the package +To install Polymer CLI: ``` -import 'some-element-package-name'; +npm install -g polymer-cli ``` -or +From within your project folder, run the development server: ``` - +polymer serve ``` -### Use in html +You can also use tools like [WebPack](https://webpack.js.org/) or [Rollup](https://rollupjs.org/guide/en). See the section on [Rollup configuration](#rollup) for an example configuration. -```html - -``` +## Build for production {#build} + +LitElement is published on npm using JavaScript Modules. This means it can take advantage of the standard native JavaScript module loader available in all current major browsers. We distribute LitElement as a JavaScript library compiled from LitElement's TypeScript source. -## Build an app with a LitElement in it +This section describes how to build an app that uses a LitElement component for production. -* babel -* rollup/webpack +To build your app: -### Configure Babel +1. [Configure transpilation with Babel](#babel). +2. [Configure module resolution and bundling](#bundle). -* babel - transpile from es2017 to target +### Configure transpilation with Babel {#babel} -e.g. 1 - serving esmodules +To serve ES Modules: **.babelrc** -``` +```js { "presets": [ [ @@ -70,11 +104,11 @@ e.g. 1 - serving esmodules } ``` -e.g. 2 - serving es5 +To serve ES5 code: **.babelrc** -``` +```js { "presets": [ [ @@ -91,10 +125,9 @@ e.g. 2 - serving es5 } ``` +### Configure module resolution and bundling {#bundle} -## Configure a bundler - -### Rollup example +This example uses [Rollup](https://rollupjs.org/guide/en) to resolve modules and dependencies, and bundle the output. **rollup.config.js** @@ -116,76 +149,65 @@ export default { exclude: 'node_modules/**', include: 'src/**' }) - ] + ], + // If using any exports from a symlinked project, uncomment the following: + // preserveSymlinks: true, }; ``` -### WebPack example - -```js - -``` +## Load the WebComponents polyfills {#polyfills} +To load the WebCompnents polyfills: -## load Polyfills from entrypoing +1. Install the `@webcomponents/webcomponentsjs` package: -Because reasons + ``` + npm install --save @webcomponents/webcomponentsjs + ``` - * reason - * reason +2. Add the polyfills to your HTML entrypoint: + ```html + + + -### install polyfills + + -``` -npm install @webcomponents/webcomponentsjs -``` + + - - - - - - - - - - - -``` + WebComponents.waitFor(async () => { + import('./path-to/some-element.js'); + }); + + + + + + + ```
-**Do not transpile or bundle the polyfills.** +**Do not transpile the polyfills.**
From afb7e7ef94e13153393598ce4cc9520c3f325105 Mon Sep 17 00:00:00 2001 From: Kate Jeffreys Date: Wed, 16 Jan 2019 18:45:24 -0800 Subject: [PATCH 03/12] Elaborate on publish docs --- docs/_guide/publish.md | 25 ++++++++++--------------- 1 file changed, 10 insertions(+), 15 deletions(-) diff --git a/docs/_guide/publish.md b/docs/_guide/publish.md index 11ad7885..ef371162 100644 --- a/docs/_guide/publish.md +++ b/docs/_guide/publish.md @@ -4,24 +4,19 @@ title: Publish an element slug: publish --- -**TODO: actual sentences** - {::options toc_levels="1..3" /} * ToC {:toc} -TODO: make sentences +This page describes how to publish a LitElement component to npm. -* We recommend publishing ES2017 -* We recommend not bundling elements -* If you're writing your element in standard ES2017, you don't need to transpile for publication -* If you're using decorators, class fields, or other ES2017+ features, you'll need to transpile your element for publication +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 decorators, class fields, or other ES2017+ features, you will need to transpile your element for publication. -## publish to npm +## Publish to npm -To publish to npm [see instructions on npm site](https://docs.npmjs.com/packages-and-modules/contributing-packages-to-the-registry). +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 must have both `main` and `module`: +Your package.json configuration should have both the `main` and `module` fields: **package.json** @@ -32,11 +27,11 @@ Your package.json configuration must have both `main` and `module`: } ``` -Also, make a README telling people how to consume your element +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). -### if typescript +## Transpiling TypeScript -To transpile TypeScript, conigure tsconfig.josn. eg +To transpile element code from TypeScript, conigure tsconfig.json. Make sure you include the `"downlevelIteration": true` option. **tsconfig.json** @@ -54,10 +49,10 @@ To transpile TypeScript, conigure tsconfig.josn. eg } ``` -Run `tsc`: +Run the TypeScript compiler: ```bash tsc ``` -Publish `lib` as well as `src`. Users would consume `lib`. +Publish your `lib` folder as well as your component's `src` files. Users of your element would consume it from `lib`. From d434ae2c16dd51ad7f5cde05c8812d13c5b2d73d Mon Sep 17 00:00:00 2001 From: Kate Jeffreys Date: Thu, 17 Jan 2019 13:36:48 -0800 Subject: [PATCH 04/12] Some corrections --- docs/_guide/publish.md | 33 ++++++++++-- docs/_guide/use.md | 117 ++++++++--------------------------------- 2 files changed, 53 insertions(+), 97 deletions(-) diff --git a/docs/_guide/publish.md b/docs/_guide/publish.md index ef371162..24af09ad 100644 --- a/docs/_guide/publish.md +++ b/docs/_guide/publish.md @@ -29,9 +29,9 @@ Your package.json configuration should have both the `main` and `module` fields: 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 TypeScript +## Transpiling with TypeScript -To transpile element code from TypeScript, conigure tsconfig.json. Make sure you include the `"downlevelIteration": true` option. +To transpile element code from TypeScript to JavaScript, conigure tsconfig.json. Make sure you include the `"downlevelIteration": true` option. **tsconfig.json** @@ -55,4 +55,31 @@ Run the TypeScript compiler: tsc ``` -Publish your `lib` folder as well as your component's `src` files. Users of your element would consume it from `lib`. +## Transpiling with Babel + +To transpile a LitElement component that uses proposed JavaScript features like class properties and decorators, 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. + +See a [sample build configuration for LitElement with Babel and Rollup](https://github.com/PolymerLabs/lit-element-build-rollup/blob/master/src/index.html). diff --git a/docs/_guide/use.md b/docs/_guide/use.md index d55a02df..2c9597f0 100644 --- a/docs/_guide/use.md +++ b/docs/_guide/use.md @@ -8,7 +8,7 @@ slug: use * ToC {:toc} -This page describes how to [use a LitElement component in your application](#use). It also describes how to make sure your deployed application is compatible with your target browsers by [building it for production](#build) and [loading the Web Components polyfills](#polyfills). +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} @@ -19,12 +19,12 @@ To use a LitElement component in your code: 1. Install the component from npm. ``` - npm install some-package-name + npm install --save some-package-name ``` 2. Import the component. - In another JavaScript module: + In a JavaScript module: ```js import 'some-package-name'; @@ -50,119 +50,44 @@ To use a LitElement component in your code: ``` -## Serve for local development {#serve} - -LitElement uses npm conventions to reference dependencies by name. A light transform to rewrite specifiers to URLs is required to get it to run in the browser. - -For local development, we recommend installing the [Polymer CLI](https://github.com/Polymer/polymer-cli) and using its development server via `polymer serve`. The development server automatically handles this transform. - -To install Polymer CLI: - -``` -npm install -g polymer-cli -``` - -From within your project folder, run the development server: - -``` -polymer serve -``` - -You can also use tools like [WebPack](https://webpack.js.org/) or [Rollup](https://rollupjs.org/guide/en). See the section on [Rollup configuration](#rollup) for an example configuration. - ## Build for production {#build} -LitElement is published on npm using JavaScript Modules. This means it can take advantage of the standard native JavaScript module loader available in all current major browsers. We distribute LitElement as a JavaScript library compiled from LitElement's TypeScript source. - -This section describes how to build an app that uses a LitElement component for production. - -To build your app: +LitElement is published on npm using JavaScript Modules. This means it can take advantage of the standard native JavaScript module loader available in all current major browsers. -1. [Configure transpilation with Babel](#babel). -2. [Configure module resolution and bundling](#bundle). +You will need a light transform to resolve LitElement's npm dependencies. This can be done with a bundler such as WebPack or Rollup. -### Configure transpilation with Babel {#babel} - -To serve ES Modules: - -**.babelrc** - -```js -{ - "presets": [ - [ - "@babel/preset-env", - { - "modules": false, - "targets": { - "esmodules": true - } - } - ] - ], - "plugins": [@babel/proposal-decorators] -} -``` - -To serve ES5 code: - -**.babelrc** - -```js -{ - "presets": [ - [ - "@babel/preset-env", - { - "modules": ??, - "targets": { - ?? - } - } - ] - ], - "plugins": [@babel/proposal-decorators] -} -``` - -### Configure module resolution and bundling {#bundle} - -This example uses [Rollup](https://rollupjs.org/guide/en) to resolve modules and dependencies, and bundle the output. +The following example configuration for [Rollup](https://rollupjs.org/guide/en) resolves modules and dependencies, and bundles the output. **rollup.config.js** ```js import resolve from 'rollup-plugin-node-resolve'; -import common from 'rollup-plugin-commonjs'; -import babel from 'rollup-plugin-babel'; export default { - input: 'index.js', + // If using any exports from a symlinked project, uncomment the following: + // preserveSymlinks: true, + input: ['src/index.js'], output: { - dir: 'build', - format: 'es' + file: 'build/index.js', + format: 'es', + sourcemap: true }, plugins: [ - resolve(), - common(), - babel({ - exclude: 'node_modules/**', - include: 'src/**' - }) - ], - // If using any exports from a symlinked project, uncomment the following: - // preserveSymlinks: true, + 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} -To load the WebCompnents polyfills: +To load the WebComponents polyfills: 1. Install the `@webcomponents/webcomponentsjs` package: ``` - npm install --save @webcomponents/webcomponentsjs + npm install --save-dev @webcomponents/webcomponentsjs ``` 2. Add the polyfills to your HTML entrypoint: @@ -177,7 +102,9 @@ To load the WebCompnents polyfills: If you are not loading es5 code, you don't need custom-elements-es5-loader. --> + ``` -3. Add the component to the page via markup: +3. Add the component to your application or component: ```html From 44214eb0f8dcc1e7189d317338d775b75b395a5f Mon Sep 17 00:00:00 2001 From: Kate Date: Mon, 4 Feb 2019 16:40:37 -0800 Subject: [PATCH 12/12] Update use.md --- docs/_guide/use.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/_guide/use.md b/docs/_guide/use.md index 935401d1..726a1347 100644 --- a/docs/_guide/use.md +++ b/docs/_guide/use.md @@ -16,7 +16,7 @@ This is a general guide to using third-party LitElement components. Refer to a c To use a LitElement component in your code: -1. Install the component from npm. +1. From your project folder, install the component from npm. ``` npm install --save some-package-name @@ -96,7 +96,7 @@ For compatibility with older browsers and Edge, load the Web Components polyfill To load the WebComponents polyfills: -1. Install the `@webcomponents/webcomponentsjs` package: +1. From your project folder, install the `@webcomponents/webcomponentsjs` package: ``` npm install --save-dev @webcomponents/webcomponentsjs