@nuxt/hints 0.0.0 → 1.0.0-alpha.10

package/dist/runtime/web-vitals/plugin.client.d.ts

@@ -0,0 +1,13 @@
+declare global {
+    interface PerformanceEntry {
+        element?: HTMLElement;
+        sources?: {
+            node: HTMLElement;
+            currentRect: DOMRect;
+            previousRect: DOMRect;
+        }[];
+        value?: number;
+    }
+}
+declare const _default: any;
+export default _default;

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

@@ -0,0 +1,138 @@
+import { defineNuxtPlugin, useNuxtApp } from "#imports";
+import { onINP, onLCP, onCLS } from "web-vitals/attribution";
+import { defu } from "defu";
+import { ref } from "vue";
+import { logger } from "./utils.js";
+function isImgElement(element) {
+  return element instanceof Element && element.tagName === "IMG";
+}
+export default defineNuxtPlugin({
+  name: "nuxt-hints:performance",
+  setup() {
+    const nuxtApp = useNuxtApp();
+    nuxtApp.payload.__hints = defu(nuxtApp.payload.__hints, {
+      webvitals: {
+        lcp: ref([]),
+        inp: ref([]),
+        cls: ref([])
+      }
+    });
+    nuxtApp.hook("hints:webvitals:sync", (webvitals) => {
+      webvitals.lcp.value = [...nuxtApp.payload.__hints.webvitals.lcp.value];
+      webvitals.inp.value = [...nuxtApp.payload.__hints.webvitals.inp.value];
+      webvitals.cls.value = [...nuxtApp.payload.__hints.webvitals.cls.value];
+    });
+    nuxtApp.hook("app:mounted", () => {
+      onINP((metric) => {
+        if (metric.rating === "good") {
+          return;
+        }
+        logger.info(
+          "[web-vitals] INP Metric: ",
+          metric
+        );
+        nuxtApp.payload.__hints.webvitals.inp.value.push(metric);
+        nuxtApp.callHook("hints:webvitals:inp", metric);
+      }, {
+        reportAllChanges: true
+      });
+      onLCP((metric) => {
+        if (metric.rating === "good") {
+          return;
+        }
+        logger.info(
+          `[web-vitals] LCP Metric: `,
+          metric
+        );
+        nuxtApp.payload.__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") {
+            logger.warn(
+              '[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")) {
+              logger.warn(
+                "[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") {
+            logger.warn(
+              '[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")) {
+            logger.warn(
+              "[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) {
+            logger.warn(
+              `[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)) {
+            logger.warn(
+              "[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;
+        }
+        logger.info(
+          "[web-vitals] CLS Metric: ",
+          metric
+        );
+        nuxtApp.callHook(
+          "hints:webvitals:cls",
+          metric
+        );
+        nuxtApp.payload.__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;
+          logger.info(
+            "[performance] Potential CLS Element: ",
+            sourceElement
+          );
+          if ((performanceEntry.value ?? 0) > 0.1) {
+            logger.warn(
+              `[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"))) {
+            logger.warn(
+              "[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,36 @@
+export declare const logger: import("consola").ConsolaInstance;
+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,15 @@
+import { createHintsLogger } from "../logger.js";
+export const logger = createHintsLogger("webVitals");
+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,76 @@
 {
   "name": "@nuxt/hints",
-  "version": "0.0.0",
+  "version": "1.0.0-alpha.10",
+  "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.2.1",
+    "@nuxt/kit": "^4.3.1",
+    "consola": "^3.4.2",
+    "h3": "^1.15.5",
+    "knitwork": "^1.3.0",
+    "magic-string": "^0.30.21",
+    "nitropack": "^2.13.1",
+    "oxc-parser": "^0.115.0",
+    "sirv": "^3.0.2",
+    "unplugin": "^3.0.0",
+    "unstorage": "^1.17.4",
+    "valibot": "^1.2.0",
+    "vite-plugin-vue-tracer": "^1.2.0",
+    "web-vitals": "^5.1.0"
+  },
+  "devDependencies": {
+    "@nuxt/devtools": "^3.2.1",
+    "@nuxt/devtools-ui-kit": "^3.2.1",
+    "@nuxt/eslint": "^1.15.1",
+    "@nuxt/icon": "^2.2.1",
+    "@nuxt/module-builder": "^1.0.2",
+    "@nuxt/schema": "^4.3.1",
+    "@nuxt/test-utils": "^4.0.0",
+    "@shikijs/transformers": "^3.22.0",
+    "@types/node": "^24.10.13",
+    "@vue/test-utils": "^2.4.6",
+    "changelogen": "^0.6.2",
+    "diff": "^8.0.3",
+    "eslint": "^10.0.1",
+    "get-port-please": "^3.2.0",
+    "happy-dom": "^20.7.0",
+    "pkg-pr-new": "0.0.63",
+    "rimraf": "^6.1.3",
+    "sass-embedded": "^1.97.3",
+    "shiki": "^3.22.0",
+    "shiki-transformer-fold": "^0.2.0",
+    "vitest": "^4.0.18",
+    "@nuxt/hints": "^1.0.0-alpha.10"
+  },
+  "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": "pnpm run lint && pnpm run test && pnpm run prepack && changelogen --release && pnpm 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"
+  }
 }