@nuxt/hints 0.0.0 → 1.0.0-alpha.2

package/dist/runtime/web-vitals/plugin.client.js

@@ -0,0 +1,137 @@
+import { defineNuxtPlugin, useNuxtApp } from "#imports";
+import { onINP, onLCP, onCLS } from "web-vitals/attribution";
+import { defu } from "defu";
+import { ref } from "vue";
+function isImgElement(element) {
+  return element instanceof Element && element.tagName === "IMG";
+}
+export default defineNuxtPlugin({
+  name: "nuxt-hints:performance",
+  setup() {
+    const nuxtApp = useNuxtApp();
+    nuxtApp.__hints = defu(nuxtApp.__hints, {
+      webvitals: {
+        lcp: ref([]),
+        inp: ref([]),
+        cls: ref([])
+      }
+    });
+    nuxtApp.hook("hints:webvitals:sync", (webvitals) => {
+      webvitals.lcp.value = [...nuxtApp.__hints.webvitals.lcp.value];
+      webvitals.inp.value = [...nuxtApp.__hints.webvitals.inp.value];
+      webvitals.cls.value = [...nuxtApp.__hints.webvitals.cls.value];
+    });
+    nuxtApp.hook("app:mounted", () => {
+      onINP((metric) => {
+        if (metric.rating === "good") {
+          return;
+        }
+        console.info(
+          "[@nuxt/hints:web-vitals] INP Metric: ",
+          metric
+        );
+        nuxtApp.__hints.webvitals.inp.value.push(metric);
+        nuxtApp.callHook("hints:webvitals:inp", metric);
+      }, {
+        reportAllChanges: true
+      });
+      onLCP((metric) => {
+        if (metric.rating === "good") {
+          return;
+        }
+        console.info(
+          `[@nuxt/hints:web-vitals] LCP Metric: `,
+          metric
+        );
+        nuxtApp.__hints.webvitals.lcp.value.push(metric);
+        nuxtApp.callHook("hints:webvitals:lcp", metric);
+        for (const performanceEntry of metric.entries) {
+          if (!performanceEntry.element || !isImgElement(performanceEntry.element)) {
+            continue;
+          }
+          if (performanceEntry.element.attributes?.getNamedItem("loading")?.value === "lazy") {
+            console.warn(
+              '[@nuxt/hints:performance] LCP Element should not have `loading="lazy"` \n\n Learn more: https://web.dev/optimize-lcp/#optimize-the-priority-the-resource-is-given'
+            );
+          }
+          if (hasImageFormat(performanceEntry.element.src)) {
+            if (!performanceEntry.element.src.includes("webp") || !performanceEntry.element.src.includes("avif")) {
+              console.warn(
+                "[@nuxt/hints:performance] LCP Element can be served in a next gen format like `webp` or `avif` \n\n Learn more: https://web.dev/choose-the-right-image-format/ \n\n Use: https://image.nuxt.com/usage/nuxt-img#format"
+              );
+            }
+          }
+          if (performanceEntry.element.fetchPriority !== "high") {
+            console.warn(
+              '[@nuxt/hints:performance] LCP Element can have `fetchPriority="high"` to load as soon as possible \n\n Learn more: https://web.dev/optimize-lcp/#optimize-the-priority-the-resource-is-given'
+            );
+          }
+          if (!performanceEntry.element.attributes.getNamedItem("height") || !performanceEntry.element.attributes.getNamedItem("width")) {
+            console.warn(
+              "[@nuxt/hints:performance] Images should have `width` and `height` sizes set  \n\n Learn more: https://web.dev/optimize-cls/#images-without-dimensions \n\n Use: https://image.nuxt.com/usage/nuxt-img#width-height"
+            );
+          }
+          if (performanceEntry.startTime > 2500) {
+            console.warn(
+              `[@nuxt/hints:performance] LCP Element loaded in ${performanceEntry.startTime} miliseconds. Good result is below 2500 miliseconds 
+
+ Learn more: https://web.dev/lcp/#what-is-a-good-lcp-score`
+            );
+          }
+          if (!isElementPreloaded(performanceEntry.element.src)) {
+            console.warn(
+              "[@nuxt/hints:performance] LCP Element can be preloaded in `head` to improve load time \n\n Learn more: https://web.dev/optimize-lcp/#optimize-when-the-resource-is-discovered \n\n Use: https://image.nuxt.com/usage/nuxt-img#preload"
+            );
+          }
+        }
+      }, {
+        reportAllChanges: true
+      });
+      onCLS((metric) => {
+        if (metric.rating === "good") {
+          return;
+        }
+        console.info(
+          "[@nuxt/hints:web-vitals] CLS Metric: ",
+          metric
+        );
+        nuxtApp.callHook(
+          "hints:webvitals:cls",
+          metric
+        );
+        nuxtApp.__hints.webvitals.cls.value.push(metric);
+        for (const entry of metric.entries) {
+          const performanceEntry = entry;
+          if (!performanceEntry.sources?.[0]) return;
+          const sourceElement = performanceEntry.sources?.[0].node;
+          if (!sourceElement || sourceElement.parentElement?.className.includes("nuxt-devtools")) return;
+          console.info(
+            "[@nuxt/hints:performance] Potential CLS Element: ",
+            sourceElement
+          );
+          if ((performanceEntry.value ?? 0) > 0.1) {
+            console.warn(
+              `[@nuxt/hints:performance] CLS was ${performanceEntry.value}. Good result is below 0.1 
+
+ Learn more: https://web.dev/articles/cls#what-is-a-good-cls-score`
+            );
+          }
+          if (isImgElement(sourceElement) && (!sourceElement.attributes.getNamedItem("height") || !sourceElement.attributes.getNamedItem("width"))) {
+            console.warn(
+              "[@nuxt/hints:performance] Images should have `width` and `height` sizes set  \n\n Learn more: https://web.dev/optimize-cls/#images-without-dimensions \n\n Use: https://image.nuxt.com/usage/nuxt-img#width-height"
+            );
+          }
+        }
+      });
+    });
+  }
+});
+const hasImageFormat = (src) => {
+  const imageFormats = ["avif", "jpg", "jpeg", "png", "webp"];
+  return imageFormats.some((format) => src.includes(format));
+};
+const isElementPreloaded = (src) => {
+  return Array.from(document.head.childNodes).filter(
+    (el) => el.nodeName === "LINK" && el.attributes.href.value === src
+  ).length;
+};

package/dist/runtime/web-vitals/utils.d.ts

@@ -0,0 +1,35 @@
+export declare enum ImagePerformanceIssueType {
+    LazyAttrOnLCPElement = 0,
+    ImgFormat = 1,
+    FetchPriorityMissingOnLCPElement = 2,
+    HeightWidthMissingOnLCPElement = 3,
+    LoadingTooLong = 4,
+    PreloadMissingOnLCPElement = 5
+}
+type LazyAttrOnLCPElementDetails = {
+    type: ImagePerformanceIssueType.LazyAttrOnLCPElement;
+};
+type ImgFormatDetails = {
+    type: ImagePerformanceIssueType.ImgFormat;
+};
+type FetchPriorityMissingOnLCPElementDetails = {
+    type: ImagePerformanceIssueType.FetchPriorityMissingOnLCPElement;
+};
+type HeightWidthMissingOnLCPElementDetails = {
+    type: ImagePerformanceIssueType.HeightWidthMissingOnLCPElement;
+};
+type LoadingTooLongDetails = {
+    type: ImagePerformanceIssueType.LoadingTooLong;
+};
+type PreloadMissingOnLCPElementDetails = {
+    type: ImagePerformanceIssueType.PreloadMissingOnLCPElement;
+};
+export type ImagePerformanceIssueDetails = LazyAttrOnLCPElementDetails | ImgFormatDetails | FetchPriorityMissingOnLCPElementDetails | HeightWidthMissingOnLCPElementDetails | LoadingTooLongDetails | PreloadMissingOnLCPElementDetails;
+export declare enum CLSIssueType {
+    LayoutShiftTooBig = 0
+}
+type LayoutShiftTooBigDetails = {
+    type: CLSIssueType.LayoutShiftTooBig;
+};
+export type CLSIssueDetails = LayoutShiftTooBigDetails;
+export {};

package/dist/runtime/web-vitals/utils.js

@@ -0,0 +1,13 @@
+export var ImagePerformanceIssueType = /* @__PURE__ */ ((ImagePerformanceIssueType2) => {
+  ImagePerformanceIssueType2[ImagePerformanceIssueType2["LazyAttrOnLCPElement"] = 0] = "LazyAttrOnLCPElement";
+  ImagePerformanceIssueType2[ImagePerformanceIssueType2["ImgFormat"] = 1] = "ImgFormat";
+  ImagePerformanceIssueType2[ImagePerformanceIssueType2["FetchPriorityMissingOnLCPElement"] = 2] = "FetchPriorityMissingOnLCPElement";
+  ImagePerformanceIssueType2[ImagePerformanceIssueType2["HeightWidthMissingOnLCPElement"] = 3] = "HeightWidthMissingOnLCPElement";
+  ImagePerformanceIssueType2[ImagePerformanceIssueType2["LoadingTooLong"] = 4] = "LoadingTooLong";
+  ImagePerformanceIssueType2[ImagePerformanceIssueType2["PreloadMissingOnLCPElement"] = 5] = "PreloadMissingOnLCPElement";
+  return ImagePerformanceIssueType2;
+})(ImagePerformanceIssueType || {});
+export var CLSIssueType = /* @__PURE__ */ ((CLSIssueType2) => {
+  CLSIssueType2[CLSIssueType2["LayoutShiftTooBig"] = 0] = "LayoutShiftTooBig";
+  return CLSIssueType2;
+})(CLSIssueType || {});

package/dist/types.d.mts

@@ -0,0 +1,3 @@
+export { default } from './module.mjs'
+
+export { type ModuleOptions } from './module.mjs'

package/package.json

@@ -1,8 +1,67 @@
 {
   "name": "@nuxt/hints",
-  "version": "0.0.0",
+  "version": "1.0.0-alpha.2",
+  "description": "Nuxt module that shows hints for aspects of your application such as Performance, Security, and more!",
+  "repository": "https://github.com/nuxt/hints",
+  "homepage": "https://github.com/nuxt/hints",
+  "license": "MIT",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/types.d.mts",
+      "import": "./dist/module.mjs"
+    },
+    "./runtime/*": {
+      "types": "./dist/runtime/*",
+      "import": "./dist/runtime/*"
+    }
+  },
+  "main": "./dist/module.mjs",
   "files": [
     "dist"
   ],
-  "author": "Daniel Roe <daniel@roe.dev>"
+  "dependencies": {
+    "@nuxt/devtools-kit": "^3.0.0",
+    "@nuxt/kit": "^4.1.2",
+    "h3": "^1.15.4",
+    "magic-string": "^0.30.19",
+    "nitropack": "^2.12.6",
+    "shiki": "^3.13.0",
+    "sirv": "^3.0.2",
+    "unplugin": "^2.3.10",
+    "vite-plugin-vue-tracer": "^1.0.1",
+    "web-vitals": "^5.1.0"
+  },
+  "devDependencies": {
+    "@nuxt/devtools": "^3.0.0",
+    "@nuxt/devtools-ui-kit": "^3.0.0",
+    "@nuxt/eslint": "^1.9.0",
+    "@nuxt/icon": "^2.0.0",
+    "@nuxt/module-builder": "^1.0.0",
+    "@nuxt/schema": "^4.1.2",
+    "@nuxt/test-utils": "^3.19.2",
+    "@shikijs/transformers": "^3.15.0",
+    "@types/node": "^24.0.0",
+    "changelogen": "^0.6.0",
+    "diff": "^8.0.2",
+    "eslint": "^9.36.0",
+    "happy-dom": "^20.0.10",
+    "pkg-pr-new": "0.0.60",
+    "rimraf": "^6.0.1",
+    "sass-embedded": "^1.93.3",
+    "vitest": "^4.0.0"
+  },
+  "scripts": {
+    "client:build": "nuxi generate client",
+    "client:dev": "nuxi dev client --port 3300",
+    "dev": "nuxi dev playground",
+    "dev:build": "nuxi build playground",
+    "dev:prepare": "nuxt-module-build build --stub && nuxi prepare && nuxi prepare playground",
+    "release": "npm run lint && npm run test && npm run prepack && changelogen --release && npm publish && git push --follow-tags",
+    "lint": "eslint .",
+    "test": "vitest run",
+    "test:types": "tsc --noEmit",
+    "test:watch": "vitest watch",
+    "cleanup": "rimraf **/node_modules **/dist **/.output **/.nuxt --glob"
+  }
 }