Add lit.dev short links to dev mode warnings (#2119)

aomarks · web-flow · commit 24feb4306ec3 · 2021-09-01T10:53:53.000-07:00
Adds a See https://lit.dev/msg/<code> for more information. string to all warnings logged by Lit's dev mode. Half of #2078. Other half is at lit/lit.dev#465.
diff --git a/.changeset/light-feet-tickle.md b/.changeset/light-feet-tickle.md
@@ -0,0 +1,7 @@
+---
+'lit-element': patch
+'lit-html': patch
+'@lit/reactive-element': patch
+---
+
+Added lit.dev/msg links to dev mode warnings.
diff --git a/packages/lit-element/src/index.ts b/packages/lit-element/src/index.ts
@@ -12,5 +12,6 @@ export * from './decorators.js';
 console.warn(
   "The main 'lit-element' module entrypoint is deprecated. Please update " +
     "your imports to use the 'lit' package: 'lit' and 'lit/decorators.ts' " +
-    "or import from 'lit-element/lit-element.ts'. See https://lit.dev/docs/releases/upgrade/#update-packages-and-import-paths for more information."
+    "or import from 'lit-element/lit-element.ts'. See " +
+    'https://lit.dev/msg/deprecated-import-path for more information.'
 );
diff --git a/packages/lit-element/src/lit-element.ts b/packages/lit-element/src/lit-element.ts
@@ -57,7 +57,7 @@ export const UpdatingElement = ReactiveElement;
 
 const DEV_MODE = true;
 
-let issueWarning: (warning: string) => void;
+let issueWarning: (code: string, warning: string) => void;
 
 if (DEV_MODE) {
   // Ensure warnings are issued only 1x, even if multiple versions of Lit
@@ -66,7 +66,8 @@ if (DEV_MODE) {
     (globalThis.litIssuedWarnings ??= new Set());
 
   // Issue a warning, if we haven't already.
-  issueWarning = (warning: string) => {
+  issueWarning = (code: string, warning: string) => {
+    warning += ` See https://lit.dev/msg/${code} for more information.`;
     if (!issuedWarnings.has(warning)) {
       console.warn(warning);
       issuedWarnings.add(warning);
@@ -171,38 +172,32 @@ globalThis.litElementPlatformSupport?.({LitElement});
 
 // DEV mode warnings
 if (DEV_MODE) {
+  /* eslint-disable @typescript-eslint/no-explicit-any */
   // Note, for compatibility with closure compilation, this access
   // needs to be as a string property index.
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
   (LitElement as any)['finalize'] = function (this: typeof LitElement) {
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any
     const finalized = (ReactiveElement as any).finalize.call(this);
     if (!finalized) {
       return false;
     }
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any
-    const warnRemoved = (obj: any, name: string) => {
+    const warnRemovedOrRenamed = (obj: any, name: string, renamed = false) => {
       if (obj.hasOwnProperty(name)) {
         const ctorName = (typeof obj === 'function' ? obj : obj.constructor)
           .name;
         issueWarning(
+          renamed ? 'renamed-api' : 'removed-api',
           `\`${name}\` is implemented on class ${ctorName}. It ` +
-            `has been removed from this version of LitElement. See ` +
-            `https://lit.dev/docs/releases/upgrade/#litelement ` +
-            `for more information.`
+            `has been ${renamed ? 'renamed' : 'removed'} ` +
+            `in this version of LitElement.`
         );
       }
     };
-    [`render`, `getStyles`].forEach((name: string) =>
-      // eslint-disable-next-line @typescript-eslint/no-explicit-any
-      warnRemoved(this as any, name)
-    );
-    [`adoptStyles`].forEach((name: string) =>
-      // eslint-disable-next-line @typescript-eslint/no-explicit-any
-      warnRemoved(this.prototype as any, name)
-    );
+    warnRemovedOrRenamed(this, 'render');
+    warnRemovedOrRenamed(this, 'getStyles', true);
+    warnRemovedOrRenamed(this.prototype, 'adoptStyles');
     return true;
   };
+  /* eslint-enable @typescript-eslint/no-explicit-any */
 }
 
 /**
@@ -242,8 +237,8 @@ export const _$LE = {
 (globalThis.litElementVersions ??= []).push('3.0.0-rc.3');
 if (DEV_MODE && globalThis.litElementVersions.length > 1) {
   issueWarning!(
+    'multiple-versions',
     `Multiple versions of Lit loaded. Loading multiple versions ` +
-      `is not recommended. See https://lit.dev/docs/tools/requirements/ ` +
-      `for more information.`
+      `is not recommended.`
   );
 }
diff --git a/packages/lit-html/src/lit-html.ts b/packages/lit-html/src/lit-html.ts
@@ -18,24 +18,24 @@ const ENABLE_SHADYDOM_NOPATCH = true;
  */
 export const INTERNAL = true;
 
-let issueWarning: (warning: string) => void;
+let issueWarning: (code: string, warning: string) => void;
 
 if (DEV_MODE) {
   const issuedWarnings: Set<string | undefined> =
     (globalThis.litIssuedWarnings ??= new Set());
 
   // Issue a warning, if we haven't already.
-  issueWarning = (warning: string) => {
+  issueWarning = (code: string, warning: string) => {
+    warning += ` See https://lit.dev/msg/${code} for more information.`;
     if (!issuedWarnings.has(warning)) {
       console.warn(warning);
       issuedWarnings.add(warning);
     }
   };
 
   issueWarning(
-    `Lit is in dev mode. Not recommended for production! See ` +
-      `https://lit.dev/docs/tools/development/` +
-      `#development-and-production-builds for more information.`
+    'dev-mode',
+    `Lit is in dev mode. Not recommended for production!`
   );
 }
 
@@ -1728,8 +1728,8 @@ globalThis.litHtmlPlatformSupport?.(Template, ChildPart);
 (globalThis.litHtmlVersions ??= []).push('2.0.0-rc.4');
 if (DEV_MODE && globalThis.litHtmlVersions.length > 1) {
   issueWarning!(
-    `Multiple versions of Lit loaded. Loading multiple versions ` +
-      `is not recommended. See https://lit.dev/docs/tools/requirements/ ` +
-      `for more information.`
+    'multiple-versions',
+    `Multiple versions of Lit loaded. ` +
+      `Loading multiple versions is not recommended.`
   );
 }
diff --git a/packages/reactive-element/src/reactive-element.ts b/packages/reactive-element/src/reactive-element.ts
@@ -36,7 +36,7 @@ let requestUpdateThenable: (name: string) => {
   ) => void;
 };
 
-let issueWarning: (warning: string) => void;
+let issueWarning: (code: string, warning: string) => void;
 
 if (DEV_MODE) {
   // Ensure warnings are issued only 1x, even if multiple versions of Lit
@@ -45,17 +45,17 @@ if (DEV_MODE) {
     (globalThis.litIssuedWarnings ??= new Set());
 
   // Issue a warning, if we haven't already.
-  issueWarning = (warning: string) => {
+  issueWarning = (code: string, warning: string) => {
+    warning += ` See https://lit.dev/msg/${code} for more information.`;
     if (!issuedWarnings.has(warning)) {
       console.warn(warning);
       issuedWarnings.add(warning);
     }
   };
 
   issueWarning(
-    `Lit is in dev mode. Not recommended for production! See ` +
-      `https://lit.dev/docs/tools/development/` +
-      `#development-and-production-builds for more information.`
+    'dev-mode',
+    `Lit is in dev mode. Not recommended for production!`
   );
 
   // Issue platform support warning.
@@ -64,10 +64,9 @@ if (DEV_MODE) {
     globalThis.reactiveElementPlatformSupport === undefined
   ) {
     issueWarning(
+      'polyfill-support-missing',
       `Shadow DOM is being polyfilled via \`ShadyDOM\` but ` +
-        `the \`polyfill-support\` module has not been loaded. See ` +
-        `https://lit.dev/docs/tools/requirements/#polyfills ` +
-        `for more information.`
+        `the \`polyfill-support\` module has not been loaded.`
     );
   }
 
@@ -77,6 +76,7 @@ if (DEV_MODE) {
       _onrejected?: () => void
     ) => {
       issueWarning(
+        'request-update-promise',
         `The \`requestUpdate\` method should no longer return a Promise but ` +
           `does so on \`${name}\`. Use \`updateComplete\` instead.`
       );
@@ -615,17 +615,19 @@ export abstract class ReactiveElement
     this.elementStyles = this.finalizeStyles(this.styles);
     // DEV mode warnings
     if (DEV_MODE) {
-      [`initialize`, `requestUpdateInternal`, `_getUpdateComplete`].forEach(
-        (name: string) => {
-          if (this.prototype.hasOwnProperty(name)) {
-            issueWarning(
-              `\`${name}\` is implemented on class ${this.name}. It ` +
-                `has been removed from this version of \`ReactiveElement\`.` +
-                ` See the changelog at https://github.com/lit/lit/blob/main/packages/reactive-element/CHANGELOG.md`
-            );
-          }
+      const warnRemovedOrRenamed = (name: string, renamed = false) => {
+        if (this.prototype.hasOwnProperty(name)) {
+          issueWarning(
+            renamed ? 'renamed-api' : 'removed-api',
+            `\`${name}\` is implemented on class ${this.name}. It ` +
+              `has been ${renamed ? 'renamed' : 'removed'} ` +
+              `in this version of LitElement.`
+          );
         }
-      );
+      };
+      warnRemovedOrRenamed('initialize');
+      warnRemovedOrRenamed('requestUpdateInternal');
+      warnRemovedOrRenamed('_getUpdateComplete', true);
     }
     return true;
   }
@@ -902,6 +904,7 @@ export abstract class ReactiveElement
         attrValue === undefined
       ) {
         issueWarning(
+          'undefined-attribute-value',
           `The attribute value for the ${name as string} property is ` +
             `undefined on element ${this.localName}. The attribute will be ` +
             `removed, but in the previous version of \`ReactiveElement\`, ` +
@@ -1093,17 +1096,15 @@ export abstract class ReactiveElement
         );
         if (shadowedProperties.length) {
           issueWarning(
+            'class-field-shadowing',
             `The following properties on element ${this.localName} will not ` +
               `trigger updates as expected because they are set using class ` +
               `fields: ${shadowedProperties.join(', ')}. ` +
               `Native class fields and some compiled output will overwrite ` +
               `accessors used for detecting changes. To fix this issue, ` +
               `either initialize properties in the constructor or adjust ` +
               `your compiler settings; for example, for TypeScript set ` +
-              `\`useDefineForClassFields: false\` in your \`tsconfig.json\`.` +
-              `See https://lit.dev/docs/components/properties/#declare and ` +
-              `https://lit.dev/docs/components/decorators/` +
-              `#avoiding-issues-with-class-fields for more information.`
+              `\`useDefineForClassFields: false\` in your \`tsconfig.json\`.`
           );
         }
       }
@@ -1163,6 +1164,7 @@ export abstract class ReactiveElement
       ) >= 0
     ) {
       issueWarning(
+        'change-in-update',
         `Element ${this.localName} scheduled an update ` +
           `(generally because a property was set) ` +
           `after an update completed, causing a new update to be scheduled. ` +
@@ -1323,8 +1325,8 @@ if (DEV_MODE) {
 (globalThis.reactiveElementVersions ??= []).push('1.0.0-rc.3');
 if (DEV_MODE && globalThis.reactiveElementVersions.length > 1) {
   issueWarning!(
+    'multiple-versions',
     `Multiple versions of Lit loaded. Loading multiple versions ` +
-      `is not recommended. See https://lit.dev/docs/tools/requirements/ ` +
-      `for more information.`
+      `is not recommended.`
   );
 }
