[docs] Add multiple versions of lit resolution section (#1261)

Fixes: #455

Author: AndrewJakubowicz

packages/lit-dev-content/site/docs/v3/tools/development.md

@@ -78,6 +78,36 @@ class MyElement extends LitElement {
 
 It's best for code size if the code to control warnings is eliminated in your own production builds.
 
+#### Multiple versions of Lit warning {#multiple-lit-versions}
+
+A dev mode only warning is triggered when multiple versions, or even multiple copies of the same version, of any of the Lit core packages – `lit-html`, `lit-element`, `@lit/reactive-element` – are detected.
+
+If Lit is being used as an internal dependency of elements, elements can use different versions of Lit and are completely interoperable.
+We also take care to ensure that Lit 2 and Lit 3 are mostly compatible with each other. For example, you can pass a Lit 2 template into a Lit 3 render function and vice-versa.
+
+So, why the warning? Lit is sometimes compared to frameworks which often break if components using different framework versions are mixed together. Thus, it's easier to accidentally install multiple duplicated versions of Lit without realizing.
+
+Loading multiple compatible versions of Lit is non-optimal because extra duplicated bytes must be sent to the user.
+
+If you’re publishing a library that uses Lit, follow our [publishing best practices](https://lit.dev/docs/tools/publishing/#don't-bundle-minify-or-optimize-modules) so consumers of your library are able to de-duplicate Lit in their projects.
+
+##### Resolving multiple versions of Lit
+
+It is possible to follow the steps below, and not be able to de-duplicate Lit, e.g., a library you depend on is bundling a specific version of Lit. In these cases the warning can be ignored.
+
+If you’re seeing a `Multiple versions of Lit loaded` development mode warning, there are a couple things you can try:
+
+1. Find out which Lit libraries have multiple versions loaded by checking the following variables in your browser console: `window.litElementVersions`, `window.reactiveElementVersions`, and `window.litHtmlVersions`.
+
+2. Use `npm ls` (note, you can specify exact libraries to look for, e.g. `npm ls @lit/reactive-element`) to narrow down which dependencies are loading multiple different versions of Lit.
+
+3. Try to use `npm dedupe` to de-duplicate Lit. Use `npm ls` to verify if the duplicated Lit package was successfully de-duped.
+
+4. It is possible to nudge `npm` to hoist particular versions of the core Lit packages by installing them as direct dependencies of your project with `npm i @lit/reactive-element@latest lit-element@latest lit-html@latest`. Replace `latest` with the version you want to de-dupe to.
+
+5. If there is still duplication, you may need to delete your package lock and `node_modules`. Then install the version of `lit` you want explicitly, followed by your dependencies.
+
+
 ## Local dev servers { #devserver }
 
 Lit is packaged as JavaScript modules, and it uses bare module specifiers that are not yet natively supported in most browsers. Bare specifiers are commonly used, and you may want to use them in your own code as well. For example:

packages/lit-dev-content/site/docs/v3/tools/requirements.md

@@ -49,3 +49,4 @@ All modern browsers update automatically and users are highly likely to have a r
 ## Note on legacy browsers {#note-on-legacy-browsers}
 
 Lit 3 is not tested on legacy browsers, specifically Internet Explorer 11 and Classic Edge are not supported due to non-standard DOM behavior. If you must support legacy browsers, consider using Lit 2 with additional compilation and/or polyfills as described in [Building for legacy browsers](/docs/v2/tools/requirements#building-for-legacy-browsers).
+

packages/lit-dev-server/src/redirects.ts

@@ -10,8 +10,7 @@ export const pageRedirects = new Map([
   ['/slack-invite',                   'https://discord.com/invite/buildWithLit'],
   ['/youtube',                        'https://www.youtube.com/@buildWithLit'],
   ['/msg/dev-mode',                   '/docs/tools/development/#development-and-production-builds'],
-  // TODO(sorvell) https://github.com/lit/lit.dev/issues/455
-  ['/msg/multiple-versions',          '/docs/tools/requirements/'],
+  ['/msg/multiple-versions',          '/docs/tools/development/#multiple-lit-versions'],
   ['/msg/polyfill-support-missing',   '/docs/v2/tools/requirements/#polyfills'],
   ['/msg/class-field-shadowing',      '/docs/components/properties/#avoiding-issues-with-class-fields'],
   // TODO(aomarks) Should we add something specifically about this issue?