-
## Guide
+
```bash
# bootstrap/setup
yarn install
diff --git a/docs/README.md b/docs/README.md
index 2fca5390..6e21058b 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -4,14 +4,15 @@ heroImage: /hero.png
actionText: Get Started →
actionLink: /guide/
features:
-- title: Smart Defaults
- details: Enjoy the peace of mind that comes from having a well-known default solution for almost everything. From linting to testing to demos to publishing - have the full experience.
-- title: Awesome Generators
- details: Get up and running quickly with opinionated generators, or add recommended tools to existing projects. Our comprehensive fleet of generators have got you covered.
-- title: Open Source Love
- details: Open Web Components is a community-effort, independent of any framework or company. We use mostly open-source tools and services.
+ - title: Smart Defaults
+ details: Enjoy the peace of mind that comes from having a well-known default solution for almost everything. From linting to testing to demos to publishing - have the full experience.
+ - title: Awesome Generators
+ details: Get up and running quickly with opinionated generators, or add recommended tools to existing projects. Our comprehensive fleet of generators have got you covered.
+ - title: Open Source Love
+ details: Open Web Components is a community-effort, independent of any framework or company. We use mostly open-source tools and services.
footer: MIT Licensed | Copyright © 2018-2019 open-wc
---
+
I used open-wc to get testing working, it was so helpful, works like a charm!
diff --git a/docs/about/README.md b/docs/about/README.md
index 9113de76..8f0512b8 100644
--- a/docs/about/README.md
+++ b/docs/about/README.md
@@ -23,7 +23,7 @@ Many web developers have experienced the dreaded "Javascript Fatigue". With our
We want web component development to be accessible and approachable for everyone, regardless of their background. Therefore, our recommendations aim to be easy to use, be ready to use, and provide that "it just works" developer experience we all crave for the various aspects of web component development.
-Best practices/recommendations and examples may change and evolve over time.
+Best practices/recommendations and examples may change and evolve over time.
### Why Web Components
@@ -46,12 +46,15 @@ What if you could remove code, gain performance, and streamline implementation a
- Write using a streamlined component API that combines the best bits of popular libraries and frameworks!
##### Performance
+
Just like `querySelector` reduces developers' dependence on jQuery, the web components standards reduces the size and complexity of component libraries and frameworks. This ultimately benefits users by decreasing page load times and increasing app performance.
##### Future Proofing
+
Using the browser's standards-based component model will increase the longevity of your application. The web has an extremely strong tradition of backwards-compatibility. Standards bodies have consistently gone out of their way to maintain legacy APIs.
##### Flexibility
+
The web components standards are fairly low-level, letting library authors build upon them with innovative APIs. By using such libraries you can build your app in the style you want while still leveraging built-in browser features.
## Contribute
diff --git a/docs/about/blog.md b/docs/about/blog.md
index ddb75ffb..0dd0c13c 100644
--- a/docs/about/blog.md
+++ b/docs/about/blog.md
@@ -1,10 +1,10 @@
# Blog
-## [Announcing Open Web Components](https://dev.to/thepassle/announcing-open-web-components-5h7)
+## [Announcing Open Web Components](https://dev.to/thepassle/announcing-open-web-components-5h7)
by [open-wc](https://github.com/open-wc)
-## [Cross Browser Testing your Stencil Web Component like a boss](https://medium.com/vincent-ogloblinsky/cross-browser-testing-your-stencil-web-component-like-a-boss-93c1b154bfd9)
+## [Cross Browser Testing your Stencil Web Component like a boss](https://medium.com/vincent-ogloblinsky/cross-browser-testing-your-stencil-web-component-like-a-boss-93c1b154bfd9)
by [Vincent Ogloblinsky](https://github.com/vogloblinsky)
@@ -12,10 +12,10 @@ by [Vincent Ogloblinsky](https://github.com/vogloblinsky)
by [npm](npmjs.com)
-## [Not Another To Do App](https://medium.com/@westbrook/not-another-to-do-app-169c14bb7ef9)
+## [Not Another To Do App](https://medium.com/@westbrook/not-another-to-do-app-169c14bb7ef9)
by [Westbrook Johnson](https://github.com/westbrook)
-## [Web Components: spoils of the browser wars](https://www.andrewzigler.com/blog/2019/02/28/web-components-spoils-of-the-browser-wars/)
+## [Web Components: spoils of the browser wars](https://www.andrewzigler.com/blog/2019/02/28/web-components-spoils-of-the-browser-wars/)
by [Andrew Zigler](https://github.com/azigler)
diff --git a/docs/about/rationales.md b/docs/about/rationales.md
index 87389ba3..cc766f4d 100644
--- a/docs/about/rationales.md
+++ b/docs/about/rationales.md
@@ -10,7 +10,6 @@ This is such a powerful and widely-used pattern in the current JavaScript ecosys
We want to help you build your apps as easily and efficiently as possible, so for now we've adopted this practice as our only exception to the above rules.
The [import maps](https://github.com/WICG/import-maps) proposal aims to bring bare modules to the web browser. You can follow that repository to stay up to date.
-
## Workflows
We recommend implementing the following three workflows for specific tasks while developing your component or application.
@@ -26,9 +25,11 @@ We recommend our [ES Dev Server](../developing/es-dev-server.html) as it does no
:::
When would you choose this workflow:
+
- When developing new features
Why would you choose this:
+
- Simple to setup
- As fast as it gets
@@ -38,16 +39,17 @@ Chances are that the web components you're building will need to run in more tha
In these cases it's time to open your toolbox and make sure everything works in all supported browsers.
When would you choose this workflow:
+
- To verify everything works in all supported browsers
- To debug legacy browsers
We recommend our [Open Web Components Building Setup](../building).
Why would you choose it:
+
- As good as it gets when you need to work with legacy browsers
- Auto-bundling/reloading
-
### Production Workflow
Once you're happy with your web components, it's time to put them somewhere more useful.
@@ -55,11 +57,13 @@ Most likely a publicly available web server.
Before you do that let's apply all the optimizations magic we can cook up.
When would you use this:
+
- Optimize your build
- Publishing to production
We recommend our [Open Web Components Building Setup](../building).
Why would you choose it:
+
- Multiple bundles for differential serving
- Conditional auto-loader for those bundles (without a special server)
diff --git a/docs/automating/README.md b/docs/automating/README.md
index 63343ff1..9aba51ed 100644
--- a/docs/automating/README.md
+++ b/docs/automating/README.md
@@ -3,6 +3,7 @@
Having continuous integration in your project can provide valuable insights, and we consider it an essential in your projects.
## Circle ci
+
If you use the default generator you will already have CircleCi setup with a .circleci folder.
It also contains a config that takes care of linting and testing.
@@ -11,13 +12,14 @@ This is part of the default [open-wc](https://open-wc.org/) recommendation.
:::
## Setup
+
```bash
npm init @open-wc automating
```
### Manual Setup
-- copy [.circleci/config.yml](https://github.com/open-wc/open-wc/blob/master/packages/create/src/generators/tools-circleci/templates/static/.circleci/config.yml) to `.circleci/config.yml`
+- copy [.circleci/config.yml](https://github.com/open-wc/open-wc/blob/master/packages/create/src/generators/tools-circleci/templates/static/.circleci/config.yml) to `.circleci/config.yml`
## Usage
@@ -36,5 +38,5 @@ npm init @open-wc automating
- Look for "Automate", and write down the "Access Key" and "Username"
- Open your [circleci App](https://circleci.com/dashboard) or direclty via https://circleci.com/gh/{groupname}/{reponame}/edit
- Go to the project settings -> Environment Variables
-- Add Variable: BROWSER_STACK_USERNAME + ${username from url above}
-- Add Variable: BROWSER_STACK_ACCESS_KEY + ${key from url above}
+- Add Variable: BROWSER_STACK_USERNAME + \${username from url above}
+- Add Variable: BROWSER_STACK_ACCESS_KEY + \${key from url above}
diff --git a/docs/building/README.md b/docs/building/README.md
index 0aeda1d5..e80bbed8 100644
--- a/docs/building/README.md
+++ b/docs/building/README.md
@@ -1,10 +1,13 @@
# Building
## Browser standards
+
We strongly believe that staying close to browser standards will be the best long term investment for your code. It is the basis for all our recommendations, and it means that sometimes we will not recommend a popular feature or functionality. It also means we can be faster to adopt and recommend new browser standards.
## Building web apps
+
Building is a necessary optimization when shipping apps to production. Generally speaking, build tools accomplish some or all of the following:
+
1. Reduce app size (tree shaking, inlining, minification etc.)
2. Bundling and code splitting (combining many into few files)
3. Transforming/polyfilling standard code for older browsers
@@ -14,8 +17,10 @@ Building is a necessary optimization when shipping apps to production. Generally
Our recommended setups address the first four points but refrain from introducing non-standard features. We think it's best to avoid those, as they might lock your source code to a specific build setup which can be hard to get away from at a later time. Javascript is evolving fast, your code can quickly become out of sync with new developments.
## Using `index.html` as an entry point
+
Our configs for `rollup` & `webpack` are unique in that sense that they take a single html file as an entry point.
Doing so allows you to work with the same entry point no matter if you use
+
- webpack
- rollup
- es-dev-server
@@ -27,6 +32,7 @@ This allows you to easily switch between build configurations; if you want to sw
It also means you can use `es-dev-server` for your regular development, and then use either `rollup` or `webpack` to prepare your application for your production environment.
## Rollup
+
We recommend [Rollup](https://rollupjs.org/) for building front-end projects. Rollup is convenient to use and gets out of your way. It is easy to understand what's going on. Quite a relief in a world of complex javascript tooling.
Rollup is focused on statically analyzing es module based projects, significantly reducing the size of your app through tree shaking, minification and code splitting. Rollup can output es modules, making use of the native module loader available in modern browsers.
@@ -34,6 +40,7 @@ Rollup is focused on statically analyzing es module based projects, significantl
Our [default configuration](/building/building-rollup.html) gets your started with a setup for modern browsers, and optionally for supporting legacy browsers.
## Webpack
+
[Webpack](https://webpack.js.org/) is a popular and flexible build tool, with a large ecosystem of plugins. Out of the box, webpack handles different module formats, such as esm, commonjs, amd and umd. It is not able to output native es modules, relying instead on it's own module loader.
Compared to rollup it is a more complex tool, with more options for composing and managing complex projects. It also comes with a dev server with features such as auto-reload and hot module reloading.
diff --git a/docs/codelabs/README.md b/docs/codelabs/README.md
index 6c8d1138..bff06f59 100644
--- a/docs/codelabs/README.md
+++ b/docs/codelabs/README.md
@@ -1,3 +1,3 @@
# Codelabs
-TODO
\ No newline at end of file
+TODO
diff --git a/docs/developing/README.md b/docs/developing/README.md
index 1bd11c86..6acd2a8e 100644
--- a/docs/developing/README.md
+++ b/docs/developing/README.md
@@ -1,6 +1,7 @@
# Developing
## Going buildless
+
Browsers have improved a lot over the past years. It's now possible to do web development without requiring any build tools, using the native module loader of the browser. We think this is a great fit for web components, and we recommend this as a general starting point.
Build tools can quickly add a lot of complexity to your code, and make your code reliant on a specific build setup. We think it's best to avoid them during development, or only add them for light transformations if you know what you're doing.
@@ -8,9 +9,11 @@ Build tools can quickly add a lot of complexity to your code, and make your code
Read [this article](https://dev.to/open-wc/developing-without-a-build-1-introduction-26ao) to learn more about this approach.
## Development server
+
We created [es-dev-server](https://open-wc.org/developing/es-dev-server.html) to help developing without build tools.
## Web component libraries
+
You can write web components using just the basic web component APIs. This can be a great choice when you're looking to keep dependencies low. But generally, we recommend using lightweight libraries to help improve the developer experience and reduce boilerplate.
We recommend [lit-html](https://www.npmjs.com/package/lit-html) with the [lit-element](https://www.npmjs.com/package/lit-element) base class as a general-purpose library for building web components. `lit-html` is feature complete, extremely lightweight and offers a great development experience. Check out the [lit-html page](/developing/lit-html/) for code examples and more information.
@@ -18,6 +21,7 @@ We recommend [lit-html](https://www.npmjs.com/package/lit-html) with the [lit-el
In the code snippets throughout our documentation we use `lit-html` and `lit-element`, but our recommendations and tools are not specific to them. You should be able to use them with any web component library that follows browser standards. If you do run into issues, or have any questions, let us know about it!
### Alternative libraries
+
Besides `lit-html`, there are other great options available:
- [haunted](https://www.npmjs.com/package/haunted) functional-style web components, with react-like hooks
@@ -27,13 +31,17 @@ Besides `lit-html`, there are other great options available:
- [stencil](https://stenciljs.com/) web component with typescript and JSX (requires a build step)
## Code examples
+
Check out the [code examples](/developing/code-examples/) page for a collection of best practices and design patterns.
## Testing
+
Check out our [testing documentation](/testing/) for help with setting up testing.
## Building
+
When you are ready to ship your app to production, or when you need to test your app on older browsers, take a look at our [building documentation](/building/) to get you started.
## Further reading
+
See: [awesome lit-html](https://github.com/web-padawan/awesome-lit-html) for a great collection of resources.
diff --git a/docs/developing/best-practices.md b/docs/developing/best-practices.md
index 0b0a02a2..dfd76062 100644
--- a/docs/developing/best-practices.md
+++ b/docs/developing/best-practices.md
@@ -16,4 +16,4 @@ We're actively looking to extend this page with common best practices. If you ha
Every developer at some point will run into the problem of moving some data upwards to a parent element. While there are many ways to manage state in your application like Redux, or passing down a bound function to a child element to mutate state in the parent, our default recommendation for moving data upwards is simply using events. The benefits of using events are that it's close to the platform, and will always have the same expected behavior across frameworks. You can find a demo of using `CustomEvents` [here](https://stackblitz.com/edit/open-wc-lit-demos?file=01-basic%2F12-firing-events.js).
-If you find yourself moving a lot of data around, it may be time to look into some state management libraries like [Redux](https://redux.js.org/) or consider some more advanced composition techniques with [slotting](https://stackblitz.com/edit/open-wc-lit-demos?file=02-intermediate%2F09-slotting.js).
\ No newline at end of file
+If you find yourself moving a lot of data around, it may be time to look into some state management libraries like [Redux](https://redux.js.org/) or consider some more advanced composition techniques with [slotting](https://stackblitz.com/edit/open-wc-lit-demos?file=02-intermediate%2F09-slotting.js).
diff --git a/docs/developing/code-examples.md b/docs/developing/code-examples.md
index 739e36fc..544fb698 100644
--- a/docs/developing/code-examples.md
+++ b/docs/developing/code-examples.md
@@ -2,45 +2,49 @@
## lit-html and lit-element
-A simple base class for creating fast, lightweight web components.
+A simple base class for creating fast, lightweight web components.
[LitElement documentation](https://lit-element.polymer-project.org)
[lit-html documentation](https://lit-html.polymer-project.org)
Click on the links below to view live code samples:
-* [Basic](https://open-wc-lit-demos.stackblitz.io/basic)
- - [01 Basic setup](https://stackblitz.com/edit/open-wc-lit-demos?file=01-basic%2F01-basic-setup.js)
- - [02 Manage properties](https://stackblitz.com/edit/open-wc-lit-demos?file=01-basic%2F02-manage-properties.js)
- - [03 Property changes](https://stackblitz.com/edit/open-wc-lit-demos?file=01-basic%2F03-property-changes.js)
- - [04 Properties and attributes](https://stackblitz.com/edit/open-wc-lit-demos?file=01-basic%2F04-properties-and-attributes.js)
- - [05 Passing properties](https://stackblitz.com/edit/open-wc-lit-demos?file=01-basic%2F05-passing-properties.js)
- - [06 Handle events](https://stackblitz.com/edit/open-wc-lit-demos?file=01-basic%2F06-handle-events.js)
- - [07 Conditional rendering](https://stackblitz.com/edit/open-wc-lit-demos?file=01-basic%2F07-conditional-rendering.js)
- - [08 Repeated templates](https://stackblitz.com/edit/open-wc-lit-demos?file=01-basic%2F08-repeated-templates.js)
- - [09 Update arrays and objects](https://stackblitz.com/edit/open-wc-lit-demos?file=01-basic%2F09-update-arrays-and-objects.js)
- - [10 Render styles](https://stackblitz.com/edit/open-wc-lit-demos?file=01-basic%2F10-render-styles.js)
- - [11 Fetching data](https://stackblitz.com/edit/open-wc-lit-demos?file=01-basic%2F11-fetching-data.js)
- - [12 Firing events](https://stackblitz.com/edit/open-wc-lit-demos?file=01-basic%2F12-firing-events.js)
-* [Intermediate](https://open-wc-lit-demos.stackblitz.io/intermediate)
- - [01 First updated](https://stackblitz.com/edit/open-wc-lit-demos?file=01-intermediate%2F01-first-updated.js)
- - [02 Updated](https://stackblitz.com/edit/open-wc-lit-demos?file=02-intermediate%2F02-updated.js)
- - [03 Lifecycle](https://stackblitz.com/edit/open-wc-lit-demos?file=02-intermediate%2F03-lifecycle.js)
- - [04 Computed properties](https://stackblitz.com/edit/open-wc-lit-demos?file=02-intermediate%2F04-computed-properties.js)
- - [05 Querying dom](https://stackblitz.com/edit/open-wc-lit-demos?file=02-intermediate%2F05-querying-dom.js)
- - [06 Light dom](https://stackblitz.com/edit/open-wc-lit-demos?file=02-intermediate%2F06-light-dom.js)
- - [07 Reflecting attributes](https://stackblitz.com/edit/open-wc-lit-demos?file=02-intermediate%2F07-reflecting-attributes.js)
- - [08 Dynamic repeated templates](https://stackblitz.com/edit/open-wc-lit-demos?file=02-intermediate%2F08-dynamic-repeated-templates.js)
- - [09 Slotting](https://stackblitz.com/edit/open-wc-lit-demos?file=02-intermediate%2F09-slotting.js)
-* [Advanced](https://open-wc-lit-demos.stackblitz.io/advanced)
- - [01 Property setter observer](https://stackblitz.com/edit/open-wc-lit-demos?file=03-advanced%2F01-property-setter-observer.js)
- - [02 Until directive](https://stackblitz.com/edit/open-wc-lit-demos?file=03-advanced%2F02-until-directive.js)
- - [03 Template wrapping](https://stackblitz.com/edit/open-wc-lit-demos?file=03-advanced%2F03-template-wrapping.js)
- - [04 Shared templates](https://stackblitz.com/edit/open-wc-lit-demos?file=03-advanced%2F04-shared-templates.js)
- - [05 Shared styles](https://stackblitz.com/edit/open-wc-lit-demos?file=03-advanced%2F05-shared-styles.js)
- - [06 External template](https://stackblitz.com/edit/open-wc-lit-demos?file=03-advanced%2F06-external-template.js)
- - [07 Template factories](https://stackblitz.com/edit/open-wc-lit-demos?file=03-advanced%2F07-template-factories.js)
- - [08 Should update](https://stackblitz.com/edit/open-wc-lit-demos?file=03-advanced%2F08-should-update.js)
+- [Basic](https://open-wc-lit-demos.stackblitz.io/basic)
+ - [01 Basic setup](https://stackblitz.com/edit/open-wc-lit-demos?file=01-basic%2F01-basic-setup.js)
+ - [02 Manage properties](https://stackblitz.com/edit/open-wc-lit-demos?file=01-basic%2F02-manage-properties.js)
+ - [03 Property changes](https://stackblitz.com/edit/open-wc-lit-demos?file=01-basic%2F03-property-changes.js)
+ - [04 Properties and attributes](https://stackblitz.com/edit/open-wc-lit-demos?file=01-basic%2F04-properties-and-attributes.js)
+ - [05 Passing properties](https://stackblitz.com/edit/open-wc-lit-demos?file=01-basic%2F05-passing-properties.js)
+ - [06 Handle events](https://stackblitz.com/edit/open-wc-lit-demos?file=01-basic%2F06-handle-events.js)
+ - [07 Conditional rendering](https://stackblitz.com/edit/open-wc-lit-demos?file=01-basic%2F07-conditional-rendering.js)
+ - [08 Repeated templates](https://stackblitz.com/edit/open-wc-lit-demos?file=01-basic%2F08-repeated-templates.js)
+ - [09 Update arrays and objects](https://stackblitz.com/edit/open-wc-lit-demos?file=01-basic%2F09-update-arrays-and-objects.js)
+ - [10 Render styles](https://stackblitz.com/edit/open-wc-lit-demos?file=01-basic%2F10-render-styles.js)
+ - [11 Fetching data](https://stackblitz.com/edit/open-wc-lit-demos?file=01-basic%2F11-fetching-data.js)
+ - [12 Firing events](https://stackblitz.com/edit/open-wc-lit-demos?file=01-basic%2F12-firing-events.js)
+
+- [Intermediate](https://open-wc-lit-demos.stackblitz.io/intermediate)
+
+ - [01 First updated](https://stackblitz.com/edit/open-wc-lit-demos?file=01-intermediate%2F01-first-updated.js)
+ - [02 Updated](https://stackblitz.com/edit/open-wc-lit-demos?file=02-intermediate%2F02-updated.js)
+ - [03 Lifecycle](https://stackblitz.com/edit/open-wc-lit-demos?file=02-intermediate%2F03-lifecycle.js)
+ - [04 Computed properties](https://stackblitz.com/edit/open-wc-lit-demos?file=02-intermediate%2F04-computed-properties.js)
+ - [05 Querying dom](https://stackblitz.com/edit/open-wc-lit-demos?file=02-intermediate%2F05-querying-dom.js)
+ - [06 Light dom](https://stackblitz.com/edit/open-wc-lit-demos?file=02-intermediate%2F06-light-dom.js)
+ - [07 Reflecting attributes](https://stackblitz.com/edit/open-wc-lit-demos?file=02-intermediate%2F07-reflecting-attributes.js)
+ - [08 Dynamic repeated templates](https://stackblitz.com/edit/open-wc-lit-demos?file=02-intermediate%2F08-dynamic-repeated-templates.js)
+ - [09 Slotting](https://stackblitz.com/edit/open-wc-lit-demos?file=02-intermediate%2F09-slotting.js)
+
+- [Advanced](https://open-wc-lit-demos.stackblitz.io/advanced)
+
+ - [01 Property setter observer](https://stackblitz.com/edit/open-wc-lit-demos?file=03-advanced%2F01-property-setter-observer.js)
+ - [02 Until directive](https://stackblitz.com/edit/open-wc-lit-demos?file=03-advanced%2F02-until-directive.js)
+ - [03 Template wrapping](https://stackblitz.com/edit/open-wc-lit-demos?file=03-advanced%2F03-template-wrapping.js)
+ - [04 Shared templates](https://stackblitz.com/edit/open-wc-lit-demos?file=03-advanced%2F04-shared-templates.js)
+ - [05 Shared styles](https://stackblitz.com/edit/open-wc-lit-demos?file=03-advanced%2F05-shared-styles.js)
+ - [06 External template](https://stackblitz.com/edit/open-wc-lit-demos?file=03-advanced%2F06-external-template.js)
+ - [07 Template factories](https://stackblitz.com/edit/open-wc-lit-demos?file=03-advanced%2F07-template-factories.js)
+ - [08 Should update](https://stackblitz.com/edit/open-wc-lit-demos?file=03-advanced%2F08-should-update.js)
## Haunted
@@ -49,25 +53,28 @@ React's Hooks API implemented for web components 👻
Click on the links below to view live code samples:
-* [Basic](https://open-wc-haunted-demos.stackblitz.io/basic)
- - [01 Basic setup](https://stackblitz.com/edit/open-wc-haunted-demos?file=01-basic%2F01-basic-setup.js)
- - [02 Manage properties](https://stackblitz.com/edit/open-wc-haunted-demos?file=01-basic%2F02-manage-properties.js)
- - [03 Property changes](https://stackblitz.com/edit/open-wc-haunted-demos?file=01-basic%2F03-property-changes.js)
- - [04 Handling attributes](https://stackblitz.com/edit/open-wc-haunted-demos?file=01-basic%2F04-handling-attributes.js)
- - [05 Passing properties](https://stackblitz.com/edit/open-wc-haunted-demos?file=01-basic%2F05-passing-properties.js)
- - [06 Handle events](https://stackblitz.com/edit/open-wc-haunted-demos?file=01-basic%2F06-handle-events.js)
- - [07 Conditional rendering](https://stackblitz.com/edit/open-wc-haunted-demos?file=01-basic%2F07-conditional-rendering.js)
- - [08 Repeated templates](https://stackblitz.com/edit/open-wc-haunted-demos?file=01-basic%2F08-repeated-templates.js)
- - [09 Firing events](https://stackblitz.com/edit/open-wc-haunted-demos?file=01-basic%2F09-firing-events.js)
- - [10 Virtual Components](https://stackblitz.com/edit/open-wc-haunted-demos?file=01-basic%2F10-virtual-components.js)
- - [11 Using styles](https://stackblitz.com/edit/open-wc-haunted-demos?file=01-basic%2F11-using-styles.js)
-* [Intermediate](https://open-wc-haunted-demos.stackblitz.io/intermediate)
- - [01 Using state](https://stackblitz.com/edit/open-wc-haunted-demos?file=02-intermediate%2F01-using-state.js)
- - [02 Using effects](https://stackblitz.com/edit/open-wc-haunted-demos?file=02-intermediate%2F02-using-effects.js)
- - [03 Fetch data](https://stackblitz.com/edit/open-wc-haunted-demos?file=02-intermediate%2F03-fetch-data.js)
- - [04 Using reducer](https://stackblitz.com/edit/open-wc-haunted-demos?file=02-intermediate%2F04-using-reducer.js)
- - [05 Using ref](https://stackblitz.com/edit/open-wc-haunted-demos?file=02-intermediate%2F04-using-ref.js)
- - [06 Using memo](https://stackblitz.com/edit/open-wc-haunted-demos?file=02-intermediate%2F06-using-memo.js)
-* [Advanced](https://open-wc-haunted-demos.stackblitz.io/advanced)
- - [01 Using context](https://stackblitz.com/edit/open-wc-haunted-demos?file=03-advanced%2F01-using-context.js)
-
\ No newline at end of file
+- [Basic](https://open-wc-haunted-demos.stackblitz.io/basic)
+
+ - [01 Basic setup](https://stackblitz.com/edit/open-wc-haunted-demos?file=01-basic%2F01-basic-setup.js)
+ - [02 Manage properties](https://stackblitz.com/edit/open-wc-haunted-demos?file=01-basic%2F02-manage-properties.js)
+ - [03 Property changes](https://stackblitz.com/edit/open-wc-haunted-demos?file=01-basic%2F03-property-changes.js)
+ - [04 Handling attributes](https://stackblitz.com/edit/open-wc-haunted-demos?file=01-basic%2F04-handling-attributes.js)
+ - [05 Passing properties](https://stackblitz.com/edit/open-wc-haunted-demos?file=01-basic%2F05-passing-properties.js)
+ - [06 Handle events](https://stackblitz.com/edit/open-wc-haunted-demos?file=01-basic%2F06-handle-events.js)
+ - [07 Conditional rendering](https://stackblitz.com/edit/open-wc-haunted-demos?file=01-basic%2F07-conditional-rendering.js)
+ - [08 Repeated templates](https://stackblitz.com/edit/open-wc-haunted-demos?file=01-basic%2F08-repeated-templates.js)
+ - [09 Firing events](https://stackblitz.com/edit/open-wc-haunted-demos?file=01-basic%2F09-firing-events.js)
+ - [10 Virtual Components](https://stackblitz.com/edit/open-wc-haunted-demos?file=01-basic%2F10-virtual-components.js)
+ - [11 Using styles](https://stackblitz.com/edit/open-wc-haunted-demos?file=01-basic%2F11-using-styles.js)
+
+- [Intermediate](https://open-wc-haunted-demos.stackblitz.io/intermediate)
+
+ - [01 Using state](https://stackblitz.com/edit/open-wc-haunted-demos?file=02-intermediate%2F01-using-state.js)
+ - [02 Using effects](https://stackblitz.com/edit/open-wc-haunted-demos?file=02-intermediate%2F02-using-effects.js)
+ - [03 Fetch data](https://stackblitz.com/edit/open-wc-haunted-demos?file=02-intermediate%2F03-fetch-data.js)
+ - [04 Using reducer](https://stackblitz.com/edit/open-wc-haunted-demos?file=02-intermediate%2F04-using-reducer.js)
+ - [05 Using ref](https://stackblitz.com/edit/open-wc-haunted-demos?file=02-intermediate%2F04-using-ref.js)
+ - [06 Using memo](https://stackblitz.com/edit/open-wc-haunted-demos?file=02-intermediate%2F06-using-memo.js)
+
+- [Advanced](https://open-wc-haunted-demos.stackblitz.io/advanced)
+ - [01 Using context](https://stackblitz.com/edit/open-wc-haunted-demos?file=03-advanced%2F01-using-context.js)
diff --git a/docs/developing/lit-html.md b/docs/developing/lit-html.md
index 074ad5d9..e385d40d 100644
--- a/docs/developing/lit-html.md
+++ b/docs/developing/lit-html.md
@@ -5,10 +5,13 @@ We recommend [lit-html](https://www.npmjs.com/package/lit-html) with the [lit-el
Under the hood new Web Component APIs such as [Constructable Stylesheets](https://developers.google.com/web/updates/2019/02/constructable-stylesheets) are used when they are available. As browser support improves, you get performance improvements for free.
## Getting started
+
To get started, we recommend using our project scaffolding:
+
```bash
npm init @open-wc
```
## Examples
-Check out the [code examples](/developing/code-examples/) page for a collection of best practices and design patterns.
\ No newline at end of file
+
+Check out the [code examples](/developing/code-examples/) page for a collection of best practices and design patterns.
diff --git a/docs/developing/routing.md b/docs/developing/routing.md
index f6c33e13..95717f04 100644
--- a/docs/developing/routing.md
+++ b/docs/developing/routing.md
@@ -10,5 +10,5 @@ In alphabetical order:
- [lit-router](https://github.com/danevans/lit-router)
- [pwa-helpers router](https://github.com/Polymer/pwa-helpers#routerjs)
- [redux first routing](https://github.com/mksarge/redux-first-routing)
-- [simplr-router](https://github.com/Matsuuu/simplr-router)
+- [simplr-router](https://github.com/Matsuuu/simplr-router)
- [vaadin-router](https://github.com/vaadin/vaadin-router)
diff --git a/docs/developing/types.md b/docs/developing/types.md
index b189c422..f89b3149 100644
--- a/docs/developing/types.md
+++ b/docs/developing/types.md
@@ -7,6 +7,7 @@
Types provide valuable information about the nature of code, and help identify typos, enable refactoring, etc. Most editors these days provide some kind of IntelliSense based on type information gleaned from the code. My favorite is Visual Studio Code. With proper type information it can give you symbol defintions on hover, code completion, symbol renaming across files, etc.
### Benefits of Types
+
1. Early detection of type errors
2. Better code analysis
3. Improved IDE support
@@ -50,13 +51,8 @@ In order to get type linting in a JavaScript project using VS Code all you need
"alwaysStrict": true,
"esModuleInterop": true
},
- "include": [
- "**/*.js",
- "node_modules/@open-wc/**/*.js"
- ],
- "exclude": [
- "node_modules/!(@open-wc)"
- ]
+ "include": ["**/*.js", "node_modules/@open-wc/**/*.js"],
+ "exclude": ["node_modules/!(@open-wc)"]
}
```
@@ -65,17 +61,14 @@ In order to get type linting in a JavaScript project using VS Code all you need
If you wish to use our typings in TypeScript you will to do a little more.
You will need to add to this to your `tsconfig.json`.
+
```json
{
"compilerOptions": {
"allowJs": true
},
- "include": [
- "node_modules/@open-wc/**/*.js"
- ],
- "exclude": [
- "node_modules/!(@open-wc)"
- ]
+ "include": ["node_modules/@open-wc/**/*.js"],
+ "exclude": ["node_modules/!(@open-wc)"]
}
```
@@ -83,7 +76,6 @@ e.g. we need to include the js files from @open-wc and you can not have it in an
However as `allowJs` prevents you from generating definition files for your own typescript files ([issue 7546](https://github.com/Microsoft/TypeScript/issues/7546)) you probably want to have an alternative config `tsconfig.build.json` for that.
-
```json
{
"extends": "./tsconfig.json",
@@ -95,6 +87,7 @@ However as `allowJs` prevents you from generating definition files for your own
```
You can then use it like so in you `package.json`
+
```json
{
"scripts": {
@@ -105,11 +98,12 @@ You can then use it like so in you `package.json`
```
That way
+
- `tsconfig.json` will be used by the language server (in VS code)
- `tsconfig.build.json` will be used to build your typescript project (including definition files)
-
Example how a full config might look like
+
```json
{
"compilerOptions": {
@@ -125,12 +119,7 @@ Example how a full config might look like
"alwaysStrict": true,
"esModuleInterop": true
},
- "include": [
- "**/*.js",
- "node_modules/@open-wc/**/*.js"
- ],
- "exclude": [
- "node_modules/!(@open-wc)"
- ]
+ "include": ["**/*.js", "node_modules/@open-wc/**/*.js"],
+ "exclude": ["node_modules/!(@open-wc)"]
}
```
diff --git a/docs/faq/README.md b/docs/faq/README.md
index e2723bd3..4cf327fd 100644
--- a/docs/faq/README.md
+++ b/docs/faq/README.md
@@ -6,20 +6,20 @@ In this section you can find answers to frequently asked questions regarding jav
[[toc]]
**Deep dives:**
+
- [Component Libraries](./component-libraries.html)
- [Rerender not triggered](./rerender.html)
- [Unit testing custom events](./unit-testing-custom-events.html)
- [Unit testing initialization error](./unit-testing-init-error.html)
-
## Custom elements render life cycle
-
## How can I set `:host` width via a property?
The following example features 3 variations:
+
- `disabled` style differently if a property is set
- `type` style if type has a certain value
- `width` map a property to a css variable
@@ -71,15 +71,15 @@ Many elements reflect their properties as attributes, and vice versa, like for e
```
```js
-console.log(myButton.disabled) // true
-console.log(myButton.hasAttribute('disabled')) // true
+console.log(myButton.disabled); // true
+console.log(myButton.hasAttribute('disabled')); // true
```
If we set the property to false, it'll _reflect_ it to an attribute. (In this case, because it's a boolean attribute, it'll be omitted)
```js
myButton.disabled = false;
-console.log(myButton.hasAttribute('disabled')) // false
+console.log(myButton.hasAttribute('disabled')); // false
```
This concept is called attribute reflection.
@@ -91,6 +91,7 @@ However, this is not true for the `checked` attribute on an input element of typ
```
It will only set the property the first time:
+
```js
console.log(mycheck.checked); // true
```
diff --git a/docs/faq/component-libraries.md b/docs/faq/component-libraries.md
index 65a35bb9..023522db 100644
--- a/docs/faq/component-libraries.md
+++ b/docs/faq/component-libraries.md
@@ -5,51 +5,67 @@ The hardest part of any project is often getting content onto that first blank p
- [Aybolit](https://web-padawan.github.io/aybolit/)
A growing family of elements with default styling for Bootstrap, Bulma, and Material, as well as a solid white-label basis for extending the underlying functionality with your own custom designs.
+
- [Bolt](https://boltdesignsystem.com/)
A family of web components built with first-class participation in the Twig templating system for PHP in mind. This set is backed by an expansive catalog of usage variants.
+
- [Clever Components](https://github.com/CleverCloud/clever-components)
A collection of low-level (atoms) and high-level (domain specific) Web Components made by Clever Cloud for its different Web UIs (public and internal).
+
- [Elix](https://component.kitchen/elix)
The Elix project aims to create a universal library of all general-purpose user interface patterns commonly found in desktop and mobile UIs, where each pattern is implemented as a well-designed, attractive, high-quality, performant, accessible, localizable, and extensively customizable web component.
+
- [HelixUI](https://rackerlabs.github.io/helix-ui/)
The HelixUI library provides front-end developers a set of reusable CSS classes and HTML Custom Elements that adhere to Helix design standards, as outlined by Rackspace.
+
- [Ink Components](https://components.ink/)
Web components for interactive scientific writing, reactive documents and explorable explanations. The Ink Components library can bring your math and science documents to the next level by breathing life into charts, equations, and variables that can be used throughout your application or content.
+
- [Io GUI](https://io-gui.dev/#page=elements)
Io is a UI framework for web applications and custom elements. It supports virtual DOM, reactive rendering and data binding. It includes a design system composed of UI elements ranging from simple input fields, to menu systems and responsive layouts. Its unique feature is the ability to create visually complex, yet fast and GPU-optimized elements using WebGL shaders.
+
- [Ionic UI Components](https://ionicframework.com/docs/components)
Take advantage of the component system that powers Ionic applications with a large ecosystem to choose from and in-depth usage instructions, no matter the framework you use.
+
- [Lightning Web Components by SalesForce](https://developer.salesforce.com/docs/component-library/overview/components)
Lightning Web Components are now the go-to standard for developing applications in the SalesForce ecosystem, and with the power of web components, they can be the basis of applications outside of their ecosystem, too!
+
- [Lion Web Components by ING Bank](https://github.com/ing-bank/lion)
Lion web components is a set of highly performant, accessible and flexible Web Components. They provide an unopinionated, white label layer that can be extended to your own layer of components.
+
- [Material Web Components](https://material-components.github.io/material-components-web-components/demos/index.html)
Material Design Components from Material Design team themselves. Stay as close as possible to the changing specification with these components from Google's own Material Design team.
+
- [Morningstar](http://designsystem.morningstar.com/components/component-status.html)
The Morningstar Design System combines vanilla HTML/CSS with web components in just the right proportions to empower the design and development of wide reaching content and functionality.
+
- [UI5 Web Components](https://sap.github.io/ui5-webcomponents/)
Get the power and flexibility of SAP's UI5 rendering stack with the ergonomics and ease of use of web components, and bring enterprise-grade features, Fiori UX and themeability home to your application.
+
- [Smart HTML Elements](https://www.htmlelements.com)
With the goal of helping to deliver modern responsive websites and applications that work on any device and are pleasure to use, the Smart HTML Elements collection is one the most feature rich and comprehensive javascript user interface frameworks.
+
- [Vaadin](https://vaadin.com/components)
Vaadin has a comprehensive set of beautifully crafted, performant, and adaptable UI components for modern mobile-first Web apps. They are the ideal building blocks for Progressive Web Applications.
+
- [Weightless](https://weightless.dev/)
A lightweight component library featuring a wide array of design concepts. It surfaces a good amount of customizability via comprehensive component and CSS Custom Property APIs with a small footprint, [just short of 30KB](https://bundlephobia.com/result?p=weightless@0.0.34).
+
- [Wired Elements](https://wiredjs.com/)
A set of common UI elements with a hand-drawn, sketchy look. These can be used for wireframes, mockups, or just the fun hand-drawn look.
diff --git a/docs/faq/rerender.md b/docs/faq/rerender.md
index 7296d93c..9c5651cd 100644
--- a/docs/faq/rerender.md
+++ b/docs/faq/rerender.md
@@ -3,18 +3,22 @@
# Modifying an array or objects members does not trigger rerender
Imagine the following scenario: you've created a custom element that observes an `items` property:
+
```js
class MyEl extends LitElement {
- render() {/*...*/}
+ render() {
+ /*...*/
+ }
static get properties() {
return {
- items: { type: Array }
- }
+ items: { type: Array },
+ };
}
}
```
-You might think that changing *one of* the items should trigger a rerender:
+You might think that changing _one of_ the items should trigger a rerender:
+
```js
const myEl = document.querySelector('my-el');
myEl.items; // [{ name: 'foo' }, { name: 'bar' }]
@@ -24,16 +28,19 @@ myEl.items[0].name = 'baz';
But this won't cause the element to update. Why not?
### Reference Values
+
Javascript has two kinds of types: direct values and reference values. Direct values are things like `'a string'` or `1` or `true`. Their value flows directly from what they are, and there's no ambiguity - the number 1 is always and simply the number 1.
Reference values like `Object` and `Array` are like containers for multiple direct (or reference) values. An array for instance can contain multiple values at any numeric index.
-In the case of direct values, equality is determined by directly comparing the value:
+In the case of direct values, equality is determined by directly comparing the value:
+
```js
-1 === 1 // true
-'three' === 'three' // true
+1 === 1; // true
+'three' === 'three'; // true
```
-But in the case of reference types, the thing that is compared is the *reference* to the object, not its contents.
+But in the case of reference types, the thing that is compared is the _reference_ to the object, not its contents.
+
```js
const o = { foo: 'bar' }
const p === { foo: 'bar' }
@@ -41,19 +48,17 @@ o === p // false
```
### LitElement's Property System
+
LitElement's property system only observes changes to the reference. Recursively listening for changes to child properties would be prohibitively expensive, especially for large nested objects.
-Therefore, setting a child or grandchild property of `myEl.items` will *not* trigger a render.
+Therefore, setting a child or grandchild property of `myEl.items` will _not_ trigger a render.
So what can we do if we need to update a nested child? Immutable data patterns can help us.
```js
const [oldItem, ...rest] = myEl.items;
const newItem = { name: 'baz' };
-myEl.items = [
- newItem,
- ...rest,
-];
+myEl.items = [newItem, ...rest];
```
For objects, the syntax is even simpler:
@@ -62,15 +67,16 @@ For objects, the syntax is even simpler:
// example of updating the `changed` property on `myEl.objectProperty`
myEl.objectProperty = {
...myEl.objectProperty,
- changed: newVal
+ changed: newVal,
};
```
### Summary
+
Polymer slack user Dracco adds:
> Actually it's not about JS, every objective language can have a collection structure, but modifying the collection does not modify the object.
-> Comparing in JS means comparing references (it would be impossible to make a universal and fast content comparison), so pushing things to an array keeps the reference the same (as it is still the same instance of an Array class) - just the contents change.
-> Similarly in `class Person { constructor() { this.isBanned = false; } }`, if you create a new instance (`const p = new Person();`) and then modify the property (`p.isBanned = true;`), it is still the same instance it was before, just the property differs.
+> Comparing in JS means comparing references (it would be impossible to make a universal and fast content comparison), so pushing things to an array keeps the reference the same (as it is still the same instance of an Array class) - just the contents change.
+> Similarly in `class Person { constructor() { this.isBanned = false; } }`, if you create a new instance (`const p = new Person();`) and then modify the property (`p.isBanned = true;`), it is still the same instance it was before, just the property differs.
-- Dracco
diff --git a/docs/faq/unit-testing-custom-events.md b/docs/faq/unit-testing-custom-events.md
index 81ee2355..334acf8c 100644
--- a/docs/faq/unit-testing-custom-events.md
+++ b/docs/faq/unit-testing-custom-events.md
@@ -1,18 +1,20 @@
# Testing Event Listeners in lifecycle events
Let's say you have a mixin that dispatches an event on `firstUpdated` and `connectedCallback`:
-```js
-const mixin = superclass => class extends superclass {
- firstUpdated() {
- super.firstUpdated();
- this.dispatchEvent(new CustomEvent('first-updated'));
- }
- connectedCallback() {
- super.connectedCallback();
- this.dispatchEvent(new CustomEvent('connected-callback'));
- }
-};
+```js
+const mixin = superclass =>
+ class extends superclass {
+ firstUpdated() {
+ super.firstUpdated();
+ this.dispatchEvent(new CustomEvent('first-updated'));
+ }
+
+ connectedCallback() {
+ super.connectedCallback();
+ this.dispatchEvent(new CustomEvent('connected-callback'));
+ }
+ };
```
These are the suggested ways of testing these events:
@@ -32,7 +34,6 @@ it('dispatches a custom event on firstUpdated', async () => {
});
```
-
#### connectedCallback
For `connectedCallback`, since this callback is fired immediately after calling `fixture`, you can't catch it anymore. What you can do is define a new component and test its callback function in a `setTimeout`.
diff --git a/docs/faq/unit-testing-init-error.md b/docs/faq/unit-testing-init-error.md
index 2df5427a..39cacea2 100644
--- a/docs/faq/unit-testing-init-error.md
+++ b/docs/faq/unit-testing-init-error.md
@@ -27,11 +27,9 @@ This method should be called before the first render when the element gets attac
## The test case
```js
-it("should throw when missing definition property", async () => {
+it('should throw when missing definition property', async () => {
const el = new StringField();
- expect(() => el.checkProperties()).to.throw(
- 'property "definition" required'
- );
+ expect(() => el.checkProperties()).to.throw('property "definition" required');
});
```
@@ -45,7 +43,7 @@ it('checkProperties gets called', async () => {
checkProperties() {
checkCalled = true;
}
- }
+ },
);
await fixture(`<${tag}>`);
expect(checkCalled).to.be.true;
diff --git a/docs/guide/README.md b/docs/guide/README.md
index cee8fac0..897e5f37 100644
--- a/docs/guide/README.md
+++ b/docs/guide/README.md
@@ -13,6 +13,7 @@ npm init @open-wc
```
## Available Recommendations
+
- [Developing](/developing/)
- [Linting](/linting/)
- [Testing](/testing/)
@@ -26,8 +27,10 @@ npm init @open-wc
You can read all about our motivation and our philosophy [here](/about/).
## FAQ
+
- [FAQ](/faq/)
## Example
+
The [Set-Game Example](https://github.com/open-wc/example-vanilla-set-game/) uses all the above recommendations.
You can find a published storybook here: [https://example-set-game-open-wc.netlify.com/](https://example-set-game-open-wc.netlify.com/).
diff --git a/docs/linting/README.md b/docs/linting/README.md
index eaf0fc97..6f9f89cc 100644
--- a/docs/linting/README.md
+++ b/docs/linting/README.md
@@ -3,12 +3,14 @@
Linting can help you write consistent code, and easily prevent mistakes. Open-wc recommends the following tools:
We recommend
+
- [ESLint](https://eslint.org/) to lint your es6 code
- [Prettier](https://prettier.io/) to auto format your code
- [lint-staged](https://www.npmjs.com/package/lint-staged) to apply linting fixed only to changed files
- [commitlint](https://www.npmjs.com/package/@commitlint/cli) so commit messages follow a certain flow
## Setup
+
```bash
npm init @open-wc
# Upgrade > Linting
@@ -19,6 +21,7 @@ This is part of the default [open-wc](https://open-wc.org/) recommendation
:::
### Manual
+
- `yarn add --dev @open-wc/eslint-config @open-wc/prettier-config lint-staged husky @commitlint/cli @commitlint/config-conventional`
- Copy [.eslintignore](https://github.com/open-wc/open-wc/blob/master/packages/create/src/generators/linting-eslint/templates/static/.eslintignore) to `.eslintignore`
- Copy [.eslintrc.js](https://github.com/open-wc/open-wc/blob/master/packages/create/src/generators/linting-prettier/templates/static/.eslintrc.js) to `.eslintrc.js`
@@ -54,6 +57,7 @@ This is part of the default [open-wc](https://open-wc.org/) recommendation
## Usage
Run:
+
- `npm run lint` to check if any file is correctly formatted
- `npm run format` to auto format your files
diff --git a/docs/linting/linting-types.md b/docs/linting/linting-types.md
index 3d0b0671..2ddce438 100644
--- a/docs/linting/linting-types.md
+++ b/docs/linting/linting-types.md
@@ -3,6 +3,7 @@
Use [TypeScript](https://www.typescriptlang.org/) to type lint your es6 JSDoc annotated code.
## Setup
+
```bash
npm init @open-wc linting-types-js
```
@@ -12,6 +13,7 @@ This is an OPTIONAL recommendation. You will need to opt-in by running the gener
:::
## Manual
+
- `yarn add --dev typescript`
- Copy [tsconfig.json](https://github.com/open-wc/open-wc/blob/master/packages/create/src/generators/linting-types-js/templates/static/tsconfig.json) to `tsconfig.json`
- Add these scripts to your package.json
@@ -32,6 +34,7 @@ For general information about types please see [developing/types](../developing/
## Usage
Run:
+
- `npm run lint:types` to check if you have type errors
## Type linting error example
diff --git a/docs/publishing/README.md b/docs/publishing/README.md
index 7e97bac9..41580064 100644
--- a/docs/publishing/README.md
+++ b/docs/publishing/README.md
@@ -12,12 +12,14 @@ To publish your Web Component we recommend [netlify](https://www.netlify.com/).
Head over to [netlify](https://www.netlify.com/) and register.
Select your github account and repository.
If you follow these recommendations all you need to do is
+
- Build command: `npm run site:build`
- Publish directory: `_site`
And you're all set up.
## Example
+
The [Set-Game Example](https://github.com/open-wc/example-vanilla-set-game/) has the default publishing via storybook on netlify.
You can see the finished page here: [https://example-set-game-open-wc.netlify.com/](https://example-set-game-open-wc.netlify.com/).
@@ -28,6 +30,7 @@ If you're using our [build configuration](http://open-wc.org/building), the `dis
- Build command: `npm run build`
- Copy the `dist` directory to your desired location: `sudo cp -R dist /Library/WebServer/Documents/myapp`
- Add a `
##### 2. Plugin
+
It is also possible to add the webpack typescript plugin, which does typechecking and compiling for you:
```javascript
@@ -342,8 +359,7 @@ module.exports = configs.map(config =>
### Making your app installable
-Make sure your PWA meets the installable criteria, which you can find [here](https://developers.google.com/web/fundamentals/app-install-banners/). You can find a tool to generate your `manifest.json` [here](https://www.pwabuilder.com/generate). When your app has a service worker with a `fetch` handler (generated by this configuration), a `manifest.json`, and is served over HTTPS, your app is ready to be installed.
-
+Make sure your PWA meets the installable criteria, which you can find [here](https://developers.google.com/web/fundamentals/app-install-banners/). You can find a tool to generate your `manifest.json` [here](https://www.pwabuilder.com/generate). When your app has a service worker with a `fetch` handler (generated by this configuration), a `manifest.json`, and is served over HTTPS, your app is ready to be installed.
### Enabling the service worker
@@ -358,9 +374,10 @@ This configuration will by default generate a service worker for you, using [wor
}
```
+
### Overriding the workbox config
-If you want to override the default config with your own workbox configuration, you can disable the default workbox configuration by setting `options.plugins.workbox` to false in the `options` object that you pass to `createBasicConfig`, and then you can override the plugins
+If you want to override the default config with your own workbox configuration, you can disable the default workbox configuration by setting `options.plugins.workbox` to false in the `options` object that you pass to `createBasicConfig`, and then you can override the plugins
```js
const merge = require('deepmerge');
@@ -370,13 +387,12 @@ const createDefaultConfig = require('@open-wc/building-webpack');
const defaultConfig = createDefaultConfig({
plugins: {
workbox: false,
- }
+ },
});
module.exports = merge(defaultConfig, {
plugins: [new InjectManifest(/* */)],
});
-
```
You can find the options for configuring Workbox [here](https://developers.google.com/web/tools/workbox/modules/workbox-build).
@@ -387,9 +403,9 @@ To opt out of using workbox to generate a service worker, you can disabled it by
```js
module.exports = createBasicConfig({
- plugins: {
- workbox: false
- }
+ plugins: {
+ workbox: false,
+ },
});
```
@@ -397,7 +413,7 @@ module.exports = createBasicConfig({
By default, the service worker generated will _not_ call `skipWaiting`. The reason for this is that it becomes very painful very quickly if you're lazyloading code in your application.
-If you want to add a user-friendly 'Add To Home Screen' experience, you can use the [pwa-update-available](https://github.com/thepassle/pwa-helpers) web component.
+If you want to add a user-friendly 'Add To Home Screen' experience, you can use the [pwa-update-available](https://github.com/thepassle/pwa-helpers) web component.
-
-
- ```
+```json
+{
+ "presets": ["@babel/preset-typescript"]
+}
+```
- 4. Run `es-dev-server` with these flags:
- ```bash
- es-dev-server --file-extensions .ts --node-resolve --babel --open
- ```
+3. Import a typescript file from your `index.html`
- To add support for experimental features that are normally handled by the typescript compiler, you can add extra babel plugins:
+```html
+
+
- 1. Install the plugins:
- ```bash
- npm i --save-dev @babel/plugin-proposal-decorators @babel/plugin-proposal-class-properties
- ```
+
+
+
+
+```
- 2. Update your babel configuration:
- ```json
- {
- "presets": [
- "@babel/preset-typescript"
- ],
- // for libraries that support babel decorators (lit-element) use:
- "plugins": [
- ["@babel/plugin-proposal-decorators", { "decoratorsBeforeExport": true }],
- "@babel/plugin-proposal-class-properties"
- ]
- // for libraries that only support typescript:
- // "plugins": [
- // ["@babel/plugin-proposal-decorators", { "legacy": true }],
- // ["@babel/plugin-proposal-class-properties", { "loose": true }]
- // ],
- }
- ```
+4. Run `es-dev-server` with these flags:
+
+```bash
+es-dev-server --file-extensions .ts --node-resolve --babel --open
+```
+
+To add support for experimental features that are normally handled by the typescript compiler, you can add extra babel plugins:
+
+1. Install the plugins:
+
+```bash
+npm i --save-dev @babel/plugin-proposal-decorators @babel/plugin-proposal-class-properties
+```
+
+2. Update your babel configuration:
+
+```json
+{
+ "presets": ["@babel/preset-typescript"],
+ // for libraries that support babel decorators (lit-element) use:
+ "plugins": [
+ ["@babel/plugin-proposal-decorators", { "decoratorsBeforeExport": true }],
+ "@babel/plugin-proposal-class-properties"
+ ]
+ // for libraries that only support typescript:
+ // "plugins": [
+ // ["@babel/plugin-proposal-decorators", { "legacy": true }],
+ // ["@babel/plugin-proposal-class-properties", { "loose": true }]
+ // ],
+}
+```
@@ -314,37 +338,42 @@ Compatibility mode enables bundle-free development with features such as es modu
Supporting decorators
- ::: warning
- Please note that decorators will add [non standard syntax](https://open-wc.org/building/building-webpack.html#common-extensions) to your code.
- :::
+::: warning
+Please note that decorators will add [non standard syntax](https://open-wc.org/building/building-webpack.html#common-extensions) to your code.
+:::
+
+```json
+{
+ "presets": ["@babel/preset-typescript"],
+ // for libraries that support babel decorators (lit-element) use:
+ "plugins": [
+ ["@babel/plugin-proposal-decorators", { "decoratorsBeforeExport": true }],
+ "@babel/plugin-proposal-class-properties"
+ ]
+ // for libraries that only support typescript:
+ // "plugins": [
+ // ["@babel/plugin-proposal-decorators", { "legacy": true }],
+ // ["@babel/plugin-proposal-class-properties", { "loose": true }]
+ // ],
+}
+```
- ```json
- {
- "presets": [
- "@babel/preset-typescript"
- ],
- // for libraries that support babel decorators (lit-element) use:
- "plugins": [
- ["@babel/plugin-proposal-decorators", { "decoratorsBeforeExport": true }],
- "@babel/plugin-proposal-class-properties"
- ]
- // for libraries that only support typescript:
- // "plugins": [
- // ["@babel/plugin-proposal-decorators", { "legacy": true }],
- // ["@babel/plugin-proposal-class-properties", { "loose": true }]
- // ],
- }
- ```
@@ -379,7 +408,7 @@ Returns an array of koa middleware functions.
import Koa from 'koa';
import { createConfig, createMiddlewares } from 'es-dev-server';
-const config = createConfig({ });
+const config = createConfig({});
const middlewares = createMiddlewares(config);
const app = new Koa();
diff --git a/packages/eslint-config/README.md b/packages/eslint-config/README.md
index b7f5949f..96786599 100644
--- a/packages/eslint-config/README.md
+++ b/packages/eslint-config/README.md
@@ -1,10 +1,11 @@
# Linting ESLint
-[//]: # (AUTO INSERT HEADER PREPUBLISH)
+[//]: # 'AUTO INSERT HEADER PREPUBLISH'
Use [ESLint](https://eslint.org/) to lint your es6 code.
## Setup
+
```bash
npm init @open-wc
# Upgrade > Linting
@@ -15,6 +16,7 @@ This is part of the default [open-wc](https://open-wc.org/) recommendation
:::
## Manual
+
- `yarn add --dev @open-wc/eslint-config`
- Copy [.eslintignore](https://github.com/open-wc/open-wc/blob/master/packages/create/src/generators/linting-eslint/templates/static/.eslintignore) to `.eslintignore`
- Copy [.eslintrc.js](https://github.com/open-wc/open-wc/blob/master/packages/create/src/generators/linting-eslint/templates/static/.eslintrc.js) to `.eslintrc.js`
@@ -29,6 +31,7 @@ This is part of the default [open-wc](https://open-wc.org/) recommendation
## What you get
This will install [`@open-wc/eslint-config`](https://github.com/open-wc/open-wc/blob/master/packages/eslint-config/index.js), a config based on airbnb but allows for some specialities needed for Web Components.
+
- Apply linting to js and html files
- Apply linting for best practices
- Allow dynamic module imports
@@ -40,6 +43,7 @@ This will install [`@open-wc/eslint-config`](https://github.com/open-wc/open-wc/
## Usage
Run:
+
- `npm run lint:eslint` to check if any file is not correctly formatted
- `npm run format:eslint` to auto format your files
diff --git a/packages/import-maps-generate/README.md b/packages/import-maps-generate/README.md
index 6a4ef742..9e06922e 100644
--- a/packages/import-maps-generate/README.md
+++ b/packages/import-maps-generate/README.md
@@ -1,6 +1,6 @@
# Generate Import Map
-[//]: # (AUTO INSERT HEADER PREPUBLISH)
+[//]: # 'AUTO INSERT HEADER PREPUBLISH'
This will allow you to generate a flat [import-map](https://github.com/WICG/import-maps).
It allows you to fix the "nested" npm problem for front end development.
@@ -14,6 +14,7 @@ This is still in early beta (Windows paths are not supported yet)
:::
## Features
+
- Generates a flat import-map
- Prompts the user when there are version conflicts that are not automatically resolvable
- Supports resolutions, overrides, and deletions via the `importMap` property in package.json
@@ -46,6 +47,7 @@ npx @import-map/generate
You can add a `importMap` key in your `package.json` file to specify overrides, deletions or resolutions.
`package.json`:
+
```
{
"name": "my-package",
@@ -64,7 +66,7 @@ You can add a `importMap` key in your `package.json` file to specify overrides,
### Overrides
-There may be times where you'll want to override certain imports. For example, if you're using the built-in `std:kv-storage` module along with `kv-storage-polyfill` for nonsupporting browsers, then `kv-storage-polyfill` will be in your lockfile. The generated import map will look like this:
+There may be times where you'll want to override certain imports. For example, if you're using the built-in `std:kv-storage` module along with `kv-storage-polyfill` for nonsupporting browsers, then `kv-storage-polyfill` will be in your lockfile. The generated import map will look like this:
```json
{
@@ -87,10 +89,7 @@ You can achieve that via an override in your `package.json`'s `importMap` config
"importMap": {
"overrides": {
"imports": {
- "kv-storage-polyfill": [
- "std:kv-storage",
- "/node_modules/kv-storage-polyfill/index.js"
- ]
+ "kv-storage-polyfill": ["std:kv-storage", "/node_modules/kv-storage-polyfill/index.js"]
}
},
"deletions": ["kv-storage-polyfill/"]
@@ -103,18 +102,17 @@ Note that if you apply overrides, you may also need to specify deletions for the
:::
Which will result in the following import map:
+
```json
{
"imports": {
- "std:kv-storage": [
- "std:kv-storage",
- "/node_modules/kv-storage-polyfill/index.js"
- ]
+ "std:kv-storage": ["std:kv-storage", "/node_modules/kv-storage-polyfill/index.js"]
}
}
```
Overrides may be useful for:
+
- Polyfilling
- Fixing a dependency with a local fork
- Getting a dependency from a CDN instead
@@ -135,12 +133,12 @@ You can also override entire scopes:
}
```
-
### Deletions
You can apply deletions to the generated import map by adding a `deletions` property to your package.json:
`package.json`:
+
```json
{
"importMap": {
@@ -159,6 +157,7 @@ There may be times where you have conflicting versions of the same package in yo
Alternatively, you can specify your own resolutions in your package.json.
`package.json`:
+
```json
{
"importMap": {
@@ -170,11 +169,13 @@ Alternatively, you can specify your own resolutions in your package.json.
```
## Command line flags overview
+
### Development help
-| name | type | description |
-| --------------- | -------------- | ------------------------------------------------------------------------ |
-| inject-to | string | Injects the import map to the specified html file |
-
+
+| name | type | description |
+| --------- | ------ | ------------------------------------------------- |
+| inject-to | string | Injects the import map to the specified html file |
+