Adds browser support info #117

sorvell · 2021-01-22T01:53:50Z

Fixes https://github.com/Polymer/internal/issues/1198

This section has been incorporated into the Build > Requirements documentation.

* getting-started: adds a small note about loading the polyfills * browsers: adds section to Tools and workflows describing browser support, building JS (mainly links to Building section), and loading polyfills.

arthurevans · 2021-02-09T00:56:50Z

A couple of comments on this. On first glance, I think we need to deduplicate some of this material with Building for Production: specifically the Build requirements and Supporting older browsers sections. At present, neither is really complete.

For example, this section has a bunch of hands-on information about loading polyfills, but doesn't mention the Babel polyfills which need to be bundled separately and imported before the WC polyfills.

I think there are a couple of options here, including placing the conceptual information about browser support in this page, and all the hands-on information in the Building section.

arthurevans · 2021-02-09T00:59:20Z

Also not sure whether we want to add the extra details about the polyfill support module to getting started; but it definitely needs to be in the hands-on sections of Building.

Also: have you tested this with the WC polyfill bundle (as opposed to the loader)? I seem to recall that this did not work.

arthurevans

Relative URLs => absolute to cope with eleventy's odd URL scheme.

packages/lit-dev-content/site/guide/getting-started.md

packages/lit-dev-content/site/guide/tools/browsers.md

Co-authored-by: Arthur Evans <arthure@google.com>

github-actions · 2021-02-10T22:49:50Z

A live preview of this PR will be available at the URL(s) below.
The latest URL will be appended to this comment on each push.
Each build usually takes around 7 minutes, and will 404 until finished.

Co-authored-by: Arthur Evans <arthure@google.com>

packages/lit-dev-content/site/guide/tools/browsers.md

justinfagnani · 2021-02-26T01:58:35Z

packages/lit-dev-content/site/guide/tools/browsers.md

+
+| Browser  | Module Specifiers     | Modern JS      | Web Components       |
+|:---------|:---------------------:|:--------------:|:--------------------:|
+| Chrome   | 90                    | 80             | 67                   |


What is "Chrome 90"? Did you mean "80"?

I think Chrome has supported modules since 61: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Modules

This is referencing import maps.

justinfagnani · 2021-02-26T01:58:54Z

packages/lit-dev-content/site/guide/tools/browsers.md

+| Browser  | Module Specifiers     | Modern JS      | Web Components       |
+|:---------|:---------------------:|:--------------:|:--------------------:|
+| Chrome   | 90                    | 80             | 67                   |
+| Safari   | build                 | 13             | 10                   |


Safari has supported modules for a while

Modern JS here includes modules. Module specifiers refers to import maps.

AFAIU the "module specifiers" column was trying to separate "bare module specifier" support (aka import maps) into its own "it works natively except on older browsers" category.

I'm uncomfortable with this framing; import maps are very so nascent, it feels disingenuous to represent it like this. AFAIK Chrome is only shipping inline import maps, meaning you need (a) a tool to generate the import map based on your dependencies, and (b) a tool to inline this into your HTML. Do either of these exist, and do we know them to work?

Since we don't provide any guidance here, I think it would be better for now to be less obtuse and say something like "Lit is published with bare packages specifiers, which need to be translated into URLs to be loadable in the browser. The import maps [link] spec just starting to be implemented will give the browsers the ability to do this on their own, we will provide guidance and tools once this feature is more common in browsers. Until then, you will need to use a toolchain that rewrites package specifiers to URLs, see ... [cross-reference] for more details."

I see... yeah, I'd rather remove this column for now, and just note that we require resolving bare module specifiers with a tool.

justinfagnani · 2021-02-26T01:59:27Z

packages/lit-dev-content/site/guide/tools/browsers.md

+
+The following table lists browser versions that support the features on which Lit relies. For the browsers not supporting these features natively, they are supported either via polyfills or by producing a compatible build.
+
+| Browser  | Module Specifiers     | Modern JS      | Web Components       |


justinfagnani · 2021-02-26T02:00:27Z

packages/lit-dev-content/site/guide/tools/browsers.md

+| Chrome   | 90                    | 80             | 67                   |
+| Safari   | build                 | 13             | 10                   |
+| Firefox  | build                 | 72             | 63                   |
+| Edge (Chromium) | build          | 80             | 79                   |


This should be roughly the same as Chrome, yeah?

justinfagnani · 2021-02-26T02:03:10Z

packages/lit-dev-content/site/guide/tools/browsers.md

+| Edge 14-18 | build               | build          | polyfill             |
+| Internet Explorer 11 | build     | build          | polyfill             |


justinfagnani · 2021-02-26T02:08:39Z

packages/lit-dev-content/site/guide/tools/browsers.md

+
+Lit uses modern Javascript features like modules, classes, and other recent syntax additions. All of these features can be transpiled into ES5 code which runs on older browsers. See [Building](/guide/tools/building/) for more information about how to build application and Lit component code into ES5.
+
+When compiling code to ES5, browsers with native web components require a small polyfill, the`custom-elements-es5-adapter.js`. Using a single ES5 build for all browsers is useful in static serving environments. Important note: the ES5 adapter must come before the web components polyfills, if any.


I wouldn't call the adapter a polyfill, and I think we can describe what it does quickly enough. Also, I'm not sure about the second sentence.

Suggested change

When compiling code to ES5, browsers with native web components require a small polyfill, the`custom-elements-es5-adapter.js`. Using a single ES5 build for all browsers is useful in static serving environments. Important note: the ES5 adapter must come before the web components polyfills, if any.

When compiling code to ES5, browsers with native web components require a small adapter, the`custom-elements-es5-adapter.js` that lets ES5 extend built-in classes. Important note: the ES5 adapter must be loaded before the web components polyfills, if any.

It's useful anywhere you only want to serve one version to all of your users. That includes anyone who's using static hosting and doesn't want to mess around with feature detection on the client before loading all of the JS.

packages/lit-dev-content/site/guide/tools/browsers.md

Co-authored-by: Justin Fagnani <justinfagnani@google.com>

kevinpschaaf · 2021-03-11T20:44:28Z

packages/lit-dev-content/site/guide/tools/browsers.md

+  order: 7
+---
+
+Lit works and is supported on the last-two major versions of Chrome, Firefox, Edge, and Safari, and other browsers based on those rendering engines. Lit is also supported on IE11 and "classic" Edge. Lit uses modern JavaScript and web platform features like web components, JavaScript modules, and classes. Lit supports modern browsers natively, and older browsers like IE11 via compilers and polyfills.


I feel like "Lit works and is supported on the last-two major versions" is a little ambiguous around the meaning of "supported" ... does this mean "SLA" or "works"? It's a bit in tension with this statement and the table below:

For the browsers not supporting these features natively, they are supported either via polyfills or by producing a compatible build.

Which implies browsers not supporting these features natively are still supported.

I mainly just don't want the first sentence to be off-putting if it's misunderstood as "Lit only works on the last two major versions of modern browsers."

Can we clarify what this exactly means by saying something like:

Lit supports modern browsers natively, and older browsers like IE11 via compilers and polyfills. We run continual integration tests to ensure Lit works on the last two major versions of Chrome, Firefox, Edge, and Safari, as well as IE11 and "classic" Edge 15. Older versions of evergreen browsers will likely work just fine with proper compilation and polyfills based on the features they support, although we do not test the full back catalog of these browsers.

kevinpschaaf · 2021-03-11T20:47:19Z

Let's reconcile with the info in #211.

Note, old content is still in the Tools section but needs to be integrated into the Tools and Workflows overview.

sorvell · 2021-03-19T21:42:11Z

Let's reconcile with the info in #211.

Should be integrated now, PTAL.

kevinpschaaf

LGTM, with a few things to think about before committing.

kevinpschaaf · 2021-03-20T00:44:13Z

packages/lit-dev-content/site/guide/tools/requirements.md

+| Safari            | 10-12        | <10                           |
+| Firefox           | 63-71        | <63                           |
+| Edge              | 79           |                               |
+| Edge "classic"    |              | 15-18                         |


Is the lower bound of 15 relevant? Is it just <18 or do we not run below 15?

kevinpschaaf · 2021-03-20T00:53:08Z

packages/lit-dev-content/site/guide/tools/requirements.md

+Load the `custom-elements-es5-adapter.js` after any Babel polyfills and before web components, like this:
+
+```html
+<script src="nomodule/src/babel-polyfills-nomodule.js"></script>


nomodule/src/babel-polyfills-nomodule.js referred to a custom polyfill bundle that we showed how to make on the old lit docs.

Above, I'm just listing you need core-js, regenerator-runtime, maybe systemjs, and then on the concrete page the plugin just does all that for you, so we don't show exactly what to load for those now.

So it's probably confusing to reference that URL because it's not mentioned anywhere. Should maybe just make this some sort of generic URL that implies its the polyfills you need? aka path/to/polyfills/you/need.js or something?

kevinpschaaf · 2021-03-20T01:01:09Z

packages/lit-dev-content/site/guide/tools/requirements.md

+
+#### Setting web components polyfill options
+
+By default, the individual polyfill for a given feature is disabled on browsers that natively support that feature. For testing purposes, you can force the polyfills on for browsers that have native support. You can force the polyfills on by adding a JavaScript snippet before you import the polyfills:


Is it worth showing this?

I think for most polyfills, users don't think of testing with them on/off because they should be transparent. So I think this assumes the user understands that they (particularly ShadyCSS) is imperfect, which is probably not apparent to a new reader.

While it's a benefit to us to test on Chrome, that's mostly for debugging; users should still test on the browsers they intend to support. So maybe this is too much detail? Or else I think it needs a little more context, i.e.

While the web compoents polyfills strive to match the spec in a performant way, there are some infidelities particularly around styling. We recommend ensuring you test with polyfills both on and off, either on the browsers that need them, or by forcing them on.

But that sounds a little scary, and my next question would be, where exactly are the infidelities...

Maybe also link to https://github.com/webcomponents/polyfills/tree/master/packages/shadycss#limitations?

Included that paragraph with a link to the limitations.

Adds browser support to tools and getting started

74259b1

* getting-started: adds a small note about loading the polyfills * browsers: adds section to Tools and workflows describing browser support, building JS (mainly links to Building section), and loading polyfills.

sorvell requested a review from arthurevans January 22, 2021 01:53

arthurevans reviewed Feb 9, 2021

View reviewed changes

packages/lit-dev-content/site/guide/getting-started.md Outdated Show resolved Hide resolved

packages/lit-dev-content/site/guide/getting-started.md Outdated Show resolved Hide resolved

packages/lit-dev-content/site/guide/tools/browsers.md Outdated Show resolved Hide resolved

nicolejadeyee added this to the Website complete milestone Feb 10, 2021

Steve Orvell and others added 2 commits February 10, 2021 14:49

Update packages/lit-dev-content/site/guide/getting-started.md

f5a7c19

Co-authored-by: Arthur Evans <arthure@google.com>

Update packages/lit-dev-content/site/guide/tools/browsers.md

c1bf4dd

Co-authored-by: Arthur Evans <arthure@google.com>

Steve Orvell and others added 2 commits February 10, 2021 14:50

Update packages/lit-dev-content/site/guide/getting-started.md

a4eb96c

Co-authored-by: Arthur Evans <arthure@google.com>

Merge branch 'master' into browser-support

5e4b35f

kevinpschaaf mentioned this pull request Feb 12, 2021

Tools and Workflows-- Building #90

Closed

justinfagnani reviewed Feb 26, 2021

View reviewed changes

Steven Orvell and others added 5 commits February 26, 2021 16:39

Merge branch 'master' into browser-support

f88810c

Update packages/lit-dev-content/site/guide/tools/browsers.md

7ca7b1c

Co-authored-by: Justin Fagnani <justinfagnani@google.com>

Merge branch 'master' into browser-support

a1da9d6

Address review feedback

607033e

Update packages/lit-dev-content/site/guide/tools/browsers.md

56a1bbf

Co-authored-by: Justin Fagnani <justinfagnani@google.com>

kevinpschaaf requested changes Mar 11, 2021

View reviewed changes

Steven Orvell added 4 commits March 14, 2021 10:39

Merge branch 'master' into browser-support

284c32d

Moves intro browser support to main introduction

2df9a33

Note, old content is still in the Tools section but needs to be integrated into the Tools and Workflows overview.

Merge branch 'master' into browser-support

e0e9d34

Incorporate browser support into Build|Requirements

034aad7

sorvell requested review from kevinpschaaf, arthurevans and justinfagnani March 19, 2021 21:41

kevinpschaaf approved these changes Mar 20, 2021

View reviewed changes

Address review feedback.

28457bb

Merge branch 'master' into browser-support

815918f

sorvell changed the title ~~Adds browser support to tools and getting started~~ Adds browser support info Mar 22, 2021

sorvell merged commit ca7f30d into master Mar 22, 2021

sorvell deleted the browser-support branch March 22, 2021 14:45

arthurevans mentioned this pull request Jun 8, 2022

Update decorators doc to stage 3, update babel config. #856

Merged


		The following table lists browser versions that support the features on which Lit relies. For the browsers not supporting these features natively, they are supported either via polyfills or by producing a compatible build.

		\| Browser \| Module Specifiers \| Modern JS \| Web Components \|

	\| Browser \| Module Specifiers \| Modern JS \| Web Components \|
	\| Browser \| JS Modules \| ES2020 \| Web Components \|

		\| Edge 14-18 \| build \| build \| polyfill \|
		\| Internet Explorer 11 \| build \| build \| polyfill \|


		Lit uses modern Javascript features like modules, classes, and other recent syntax additions. All of these features can be transpiled into ES5 code which runs on older browsers. See [Building](/guide/tools/building/) for more information about how to build application and Lit component code into ES5.

		When compiling code to ES5, browsers with native web components require a small polyfill, the`custom-elements-es5-adapter.js`. Using a single ES5 build for all browsers is useful in static serving environments. Important note: the ES5 adapter must come before the web components polyfills, if any.


		#### Setting web components polyfill options

		By default, the individual polyfill for a given feature is disabled on browsers that natively support that feature. For testing purposes, you can force the polyfills on for browsers that have native support. You can force the polyfills on by adding a JavaScript snippet before you import the polyfills:

Adds browser support info #117

Adds browser support info #117

Uh oh!

Conversation

sorvell commented Jan 22, 2021 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

arthurevans commented Feb 9, 2021

Uh oh!

arthurevans commented Feb 9, 2021

Uh oh!

arthurevans left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

github-actions bot commented Feb 10, 2021 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

kevinpschaaf Mar 1, 2021 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

kevinpschaaf commented Mar 11, 2021

Uh oh!

sorvell commented Mar 19, 2021

Uh oh!

kevinpschaaf left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

sorvell commented Jan 22, 2021 •

edited

Loading

github-actions bot commented Feb 10, 2021 •

edited

Loading

kevinpschaaf Mar 1, 2021 •

edited

Loading