@nuxt/hints 0.0.0 → 1.0.0-alpha.2

package/dist/module.mjs

@@ -0,0 +1,115 @@
+import { addDevServerHandler, defineNuxtModule, createResolver, addPlugin, addBuildPlugin, addComponent, addServerPlugin } from '@nuxt/kit';
+import { existsSync } from 'node:fs';
+import { eventHandler, proxyRequest } from 'h3';
+import MagicString from 'magic-string';
+import { createUnplugin } from 'unplugin';
+
+const DEVTOOLS_UI_ROUTE = "/__nuxt-hints";
+const DEVTOOLS_UI_LOCAL_PORT = 3300;
+function setupDevToolsUI(nuxt, resolver) {
+  const clientPath = resolver.resolve("./client");
+  const isProductionBuild = existsSync(clientPath);
+  if (isProductionBuild) {
+    nuxt.hook("vite:serverCreated", async (server) => {
+      const sirv = await import('sirv').then((r) => r.default || r);
+      server.middlewares.use(
+        DEVTOOLS_UI_ROUTE,
+        sirv(clientPath, { dev: true, single: true })
+      );
+    });
+  } else {
+    addDevServerHandler({
+      route: DEVTOOLS_UI_ROUTE,
+      handler: eventHandler((e) => {
+        return proxyRequest(e, "http://localhost:" + DEVTOOLS_UI_LOCAL_PORT + DEVTOOLS_UI_ROUTE + e.path);
+      })
+    });
+  }
+  nuxt.hook("devtools:customTabs", (tabs) => {
+    tabs.push({
+      name: "hints",
+      title: "Hints",
+      icon: "carbon:idea",
+      category: "analyze",
+      view: {
+        type: "iframe",
+        src: DEVTOOLS_UI_ROUTE
+      }
+    });
+  });
+}
+
+const ID_INCLUDE = /\.vue$/;
+const ID_EXCLUDE = /node_modules/;
+const InjectHydrationPlugin = createUnplugin(() => {
+  return {
+    name: "@nuxt/hints:inject-hydration-check",
+    enforce: "pre",
+    transformInclude(id) {
+      return id.endsWith(".vue") && !id.includes("node_modules");
+    },
+    transform: {
+      filter: {
+        id: {
+          include: ID_INCLUDE,
+          exclude: ID_EXCLUDE
+        }
+      },
+      handler(code) {
+        const m = new MagicString(code);
+        const re = /<script\s+setup[^>]*>/g;
+        const match = re.exec(code);
+        if (!match) {
+          return code;
+        }
+        m.appendRight(
+          match.index + match[0].length,
+          `
+import { useHydrationCheck } from '@nuxt/hints/runtime/hydration/composables'
+useHydrationCheck();`
+        );
+        return {
+          code: m.toString(),
+          map: m.generateMap({ hires: true })
+        };
+      }
+    }
+  };
+});
+
+const module$1 = defineNuxtModule({
+  meta: {
+    name: "@nuxt/hints",
+    configKey: "hints"
+  },
+  defaults: {
+    devtools: true
+  },
+  setup(options, nuxt) {
+    if (!nuxt.options.dev) {
+      return;
+    }
+    const resolver = createResolver(import.meta.url);
+    addPlugin(resolver.resolve("./runtime/web-vitals/plugin.client"));
+    addPlugin(resolver.resolve("./runtime/hydration/plugin.client"));
+    addBuildPlugin(InjectHydrationPlugin);
+    addComponent({
+      name: "NuxtIsland",
+      filePath: resolver.resolve("./runtime/core/components/nuxt-island"),
+      priority: 1e3
+    });
+    addPlugin(resolver.resolve("./runtime/third-party-scripts/plugin.client"));
+    addServerPlugin(resolver.resolve("./runtime/third-party-scripts/nitro.plugin"));
+    nuxt.hook("prepare:types", ({ references }) => {
+      references.push({
+        types: resolver.resolve("./runtime/types.d.ts")
+      });
+    });
+    if (options.devtools) {
+      setupDevToolsUI(nuxt, resolver);
+      addPlugin(resolver.resolve("./runtime/core/plugins/vue-tracer-state.client"));
+    }
+  }
+});
+
+export { module$1 as default };

package/dist/runtime/core/components/nuxt-island.d.ts

@@ -0,0 +1,137 @@
+declare const HintsNuxtIsland: {
+    new (...args: any[]): import("vue").CreateComponentPublicInstanceWithMixins<Readonly<import("vue").ExtractPropTypes<{
+        name: {
+            type: StringConstructor;
+            required: true;
+        };
+        lazy: BooleanConstructor;
+        props: {
+            type: ObjectConstructor;
+            default: () => undefined;
+        };
+        context: {
+            type: ObjectConstructor;
+            default: () => {};
+        };
+        scopeId: {
+            type: import("vue").PropType<string | undefined | null>;
+            default: () => undefined;
+        };
+        source: {
+            type: StringConstructor;
+            default: () => undefined;
+        };
+        dangerouslyLoadClientComponents: {
+            type: BooleanConstructor;
+            default: boolean;
+        };
+    }>> & Readonly<{
+        onError?: ((...args: any[]) => any) | undefined;
+    }>, (_ctx: any, _cache: any) => (import("vue").VNode<import("vue").RendererNode, import("vue").RendererElement, {
+        [key: string]: any;
+    }> | import("vue").VNode<import("vue").RendererNode, import("vue").RendererElement, {
+        [key: string]: any;
+    }>[])[] | import("vue").VNode<any, any, {
+        [key: string]: any;
+    }>[], {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, "error"[], import("vue").PublicProps, {
+        props: Record<string, any>;
+        source: string;
+        scopeId: string | null | undefined;
+        lazy: boolean;
+        context: Record<string, any>;
+        dangerouslyLoadClientComponents: boolean;
+    }, true, {}, {}, import("vue").GlobalComponents, import("vue").GlobalDirectives, string, {}, any, import("vue").ComponentProvideOptions, {
+        P: {};
+        B: {};
+        D: {};
+        C: {};
+        M: {};
+        Defaults: {};
+    }, Readonly<import("vue").ExtractPropTypes<{
+        name: {
+            type: StringConstructor;
+            required: true;
+        };
+        lazy: BooleanConstructor;
+        props: {
+            type: ObjectConstructor;
+            default: () => undefined;
+        };
+        context: {
+            type: ObjectConstructor;
+            default: () => {};
+        };
+        scopeId: {
+            type: import("vue").PropType<string | undefined | null>;
+            default: () => undefined;
+        };
+        source: {
+            type: StringConstructor;
+            default: () => undefined;
+        };
+        dangerouslyLoadClientComponents: {
+            type: BooleanConstructor;
+            default: boolean;
+        };
+    }>> & Readonly<{
+        onError?: ((...args: any[]) => any) | undefined;
+    }>, (_ctx: any, _cache: any) => (import("vue").VNode<import("vue").RendererNode, import("vue").RendererElement, {
+        [key: string]: any;
+    }> | import("vue").VNode<import("vue").RendererNode, import("vue").RendererElement, {
+        [key: string]: any;
+    }>[])[] | import("vue").VNode<any, any, {
+        [key: string]: any;
+    }>[], {}, {}, {}, {
+        props: Record<string, any>;
+        source: string;
+        scopeId: string | null | undefined;
+        lazy: boolean;
+        context: Record<string, any>;
+        dangerouslyLoadClientComponents: boolean;
+    }>;
+    __isFragment?: never;
+    __isTeleport?: never;
+    __isSuspense?: never;
+} & import("vue").ComponentOptionsBase<Readonly<import("vue").ExtractPropTypes<{
+    name: {
+        type: StringConstructor;
+        required: true;
+    };
+    lazy: BooleanConstructor;
+    props: {
+        type: ObjectConstructor;
+        default: () => undefined;
+    };
+    context: {
+        type: ObjectConstructor;
+        default: () => {};
+    };
+    scopeId: {
+        type: import("vue").PropType<string | undefined | null>;
+        default: () => undefined;
+    };
+    source: {
+        type: StringConstructor;
+        default: () => undefined;
+    };
+    dangerouslyLoadClientComponents: {
+        type: BooleanConstructor;
+        default: boolean;
+    };
+}>> & Readonly<{
+    onError?: ((...args: any[]) => any) | undefined;
+}>, (_ctx: any, _cache: any) => (import("vue").VNode<import("vue").RendererNode, import("vue").RendererElement, {
+    [key: string]: any;
+}> | import("vue").VNode<import("vue").RendererNode, import("vue").RendererElement, {
+    [key: string]: any;
+}>[])[] | import("vue").VNode<any, any, {
+    [key: string]: any;
+}>[], {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, "error"[], "error", {
+    props: Record<string, any>;
+    source: string;
+    scopeId: string | null | undefined;
+    lazy: boolean;
+    context: Record<string, any>;
+    dangerouslyLoadClientComponents: boolean;
+}, {}, string, {}, import("vue").GlobalComponents, import("vue").GlobalDirectives, string, import("vue").ComponentProvideOptions> & import("vue").VNodeProps & import("vue").AllowedComponentProps & import("vue").ComponentCustomProps;
+export default HintsNuxtIsland;

package/dist/runtime/core/components/nuxt-island.js

@@ -0,0 +1,14 @@
+import NuxtIsland from "#app/components/nuxt-island";
+import { useNuxtApp } from "#imports";
+const originalSetup = NuxtIsland.setup;
+const HintsNuxtIsland = Object.assign({}, NuxtIsland, {
+  setup(props, ctx) {
+    if (useNuxtApp().ssrContext?.islandContext) {
+      console.warn(
+        `[@nuxt/hints] Nesting islands within islands is not recommanded for performance reasons. This leads to waterfall calls.`
+      );
+    }
+    return originalSetup(props, ctx);
+  }
+});
+export default HintsNuxtIsland;

package/dist/runtime/core/plugins/vue-tracer-state.client.d.ts

@@ -0,0 +1,2 @@
+declare const _default: import("nuxt/app").Plugin<Record<string, unknown>> & import("nuxt/app").ObjectPlugin<Record<string, unknown>>;
+export default _default;

package/dist/runtime/core/plugins/vue-tracer-state.client.js

@@ -0,0 +1,7 @@
+import * as tracerOverlay from "vite-plugin-vue-tracer/client/overlay";
+import * as tracerRecord from "vite-plugin-vue-tracer/client/record";
+import { defineNuxtPlugin } from "#imports";
+export default defineNuxtPlugin((nuxtApp) => {
+  nuxtApp.__tracerOverlay = tracerOverlay;
+  nuxtApp.__tracerRecord = tracerRecord;
+});

package/dist/runtime/hydration/composables.d.ts

@@ -0,0 +1,5 @@
+/**
+ * prefer implementing onMismatch hook after vue 3.6
+ * compare element
+ */
+export declare function useHydrationCheck(): void;

package/dist/runtime/hydration/composables.js

@@ -0,0 +1,46 @@
+import { getCurrentInstance, onMounted } from "vue";
+import { useNuxtApp } from "#imports";
+function formatHTML(html) {
+  if (!html) return "";
+  let formatted = "";
+  let indent = 0;
+  const tags = html.split(/(<\/?[^>]+>)/g);
+  for (const tag of tags) {
+    if (!tag.trim()) continue;
+    if (tag.startsWith("</")) {
+      indent--;
+      formatted += "\n" + "  ".repeat(Math.max(0, indent)) + tag;
+    } else if (tag.startsWith("<") && !tag.endsWith("/>") && !tag.includes("<!")) {
+      formatted += "\n" + "  ".repeat(indent) + tag;
+      indent++;
+    } else if (tag.startsWith("<")) {
+      formatted += "\n" + "  ".repeat(indent) + tag;
+    } else {
+      formatted += "\n" + "  ".repeat(indent) + tag.trim();
+    }
+  }
+  return formatted.trim();
+}
+export function useHydrationCheck() {
+  if (import.meta.server) return;
+  const nuxtApp = useNuxtApp();
+  if (!nuxtApp.isHydrating) {
+    return;
+  }
+  const instance = getCurrentInstance();
+  if (!instance) return;
+  const htmlPrehydration = formatHTML(instance.vnode.el?.outerHTML);
+  const vnodePrehydration = instance.vnode;
+  onMounted(() => {
+    const htmlPostHydration = formatHTML(instance.vnode.el?.outerHTML);
+    if (htmlPrehydration !== htmlPostHydration) {
+      nuxtApp.__hints.hydration.push({
+        instance,
+        vnode: vnodePrehydration,
+        htmlPreHydration: htmlPrehydration,
+        htmlPostHydration
+      });
+      console.warn(`[nuxt/hints:hydration] Component ${instance.type.name ?? instance.type.displayName ?? instance.type.__name ?? instance.type.__file} seems to have different html pre and post-hydration. Please make sure you don't have any hydration issue.`);
+    }
+  });
+}

package/dist/runtime/hydration/plugin.client.d.ts

@@ -0,0 +1,2 @@
+declare const _default: import("nuxt/app").Plugin<Record<string, unknown>> & import("nuxt/app").ObjectPlugin<Record<string, unknown>>;
+export default _default;

package/dist/runtime/hydration/plugin.client.js

@@ -0,0 +1,11 @@
+import { defineNuxtPlugin, useNuxtApp } from "#imports";
+import { defu } from "defu";
+export default defineNuxtPlugin({
+  name: "@nuxt/hints:hydration",
+  setup() {
+    const nuxtApp = useNuxtApp();
+    nuxtApp.__hints = defu(nuxtApp.__hints, {
+      hydration: []
+    });
+  }
+});

package/dist/runtime/third-party-scripts/nitro.plugin.d.ts

@@ -0,0 +1,2 @@
+import type { NitroApp } from 'nitropack/types';
+export default function (nitroApp: NitroApp): void;

package/dist/runtime/third-party-scripts/nitro.plugin.js

@@ -0,0 +1,48 @@
+export default function(nitroApp) {
+  nitroApp.hooks.hook("render:html", ({ head }) => {
+    head.unshift(`
+<script>
+window.__hints_TPC_start_time = Date.now();
+
+function __hints_TPC_saveTime(script, startTime) {
+    script.__hints_TPC_end_time = Date.now();
+    const scriptStartTime = startTime || script.__hints_TPC_start_time || window.__hints_TPC_start_time;
+    
+    const resourceEntries = performance.getEntriesByName(script.src)
+    const scriptEntry = resourceEntries.find(entry => entry.name === script.src)
+
+    if (scriptEntry) {
+        // Calculate parse + execute time using modern API
+        const navigationEntry = performance.getEntriesByType('navigation')[0]
+        const navigationStart = navigationEntry ? performance.timeOrigin : performance.timeOrigin
+        
+        script.requestTime = (scriptEntry.responseStart - scriptEntry.requestStart);
+        script.downloadTime = (scriptEntry.responseEnd - scriptEntry.responseStart);
+        script.totalNetworkTime = (scriptEntry.responseEnd - scriptEntry.startTime);
+        script.parseExecuteTime =  script.__hints_TPC_end_time - (navigationStart + scriptEntry.responseEnd);
+        script.loaded = true;
+        console.log('[@nuxt/hints]: \u{1F4CA} Detailed timing for', script.src, {
+            'Request': script.requestTime.toFixed(2) + 'ms',
+            'Download': script.downloadTime.toFixed(2) + 'ms',
+            'Total Network': script.totalNetworkTime.toFixed(2) + 'ms',
+            'Parse + Execute': script.parseExecuteTime.toFixed(2) + 'ms'
+        });
+    }
+}
+<\/script>
+`);
+    head.push(`
+<script>
+for (const script of document.scripts) {
+    if (script.src && !script.src.startsWith(window.location.origin)) {
+        script.__hints_TPC_start_time = window.__hints_TPC_start_time || Date.now();
+        script.onload = function(_) {
+            __hints_TPC_saveTime(script, script.__hints_TPC_start_time);
+        }
+        __hints_TPC_saveTime(script, script.__hints_TPC_start_time);
+    }
+}
+<\/script>
+  `);
+  });
+}

package/dist/runtime/third-party-scripts/plugin.client.d.ts

@@ -0,0 +1,2 @@
+declare const _default: import("nuxt/app").Plugin<Record<string, unknown>> & import("nuxt/app").ObjectPlugin<Record<string, unknown>>;
+export default _default;

package/dist/runtime/third-party-scripts/plugin.client.js

@@ -0,0 +1,88 @@
+import { defineNuxtPlugin, ref, useNuxtApp } from "#imports";
+const EXTENSIONS_SCHEMES_RE = /^(chrome-extension|moz-extension|safari-extension|ms-browser-extension):/;
+function isExtensionScript(src) {
+  try {
+    const url = new URL(src, window.location.origin);
+    return EXTENSIONS_SCHEMES_RE.test(url.protocol);
+  } catch {
+    return false;
+  }
+}
+function isSameOriginScript(src) {
+  try {
+    const url = new URL(src, window.location.origin);
+    return url.origin === window.location.origin;
+  } catch {
+    return false;
+  }
+}
+function isIgnoredScript(src) {
+  return isSameOriginScript(src) || isExtensionScript(src);
+}
+export default defineNuxtPlugin({
+  name: "nuxt-hints:third-party-scripts",
+  setup() {
+    const nuxtApp = useNuxtApp();
+    const scripts = nuxtApp.__hints_tpc = ref([]);
+    const isUsingNuxtScripts = !!nuxtApp.$scripts;
+    nuxtApp.hook("hints:scripts:added", (script) => {
+      scripts.value.push({ element: script, loaded: false });
+    });
+    nuxtApp.hook("hints:scripts:loaded", (script) => {
+      const existingScript = scripts.value.find((s) => s.element === script);
+      if (existingScript) {
+        existingScript.loaded = true;
+      } else {
+        console.warn(`[@nuxt/hints]: Script loaded event received for a script not tracked: ${script.src}. Please open an issue with a minimal reproduction if you think this is a bug.`);
+        scripts.value.push({ element: script, loaded: true });
+      }
+    });
+    nuxtApp.hooks.hookOnce("app:mounted", () => {
+      let hasThirdPartyScript = false;
+      for (const script of document.scripts) {
+        if (script.src && !isIgnoredScript(script.src)) {
+          hasThirdPartyScript = true;
+          onScriptAdded(script);
+        }
+      }
+      if (hasThirdPartyScript && !isUsingNuxtScripts) {
+        console.info("\u2139\uFE0F [@nuxt/hints]: Third-party scripts detected on page load: consider using @nuxt/scripts");
+      }
+    });
+    const observer = new MutationObserver((mutations) => {
+      for (const mutation of mutations) {
+        if (mutation.type === "childList") {
+          for (const node of mutation.addedNodes) {
+            if (isScript(node) && node.src && !isIgnoredScript(node.src)) {
+              onScriptAdded(node);
+            }
+          }
+        }
+      }
+    });
+    observer.observe(document.documentElement, {
+      childList: true,
+      subtree: true
+    });
+    function onScriptAdded(script) {
+      if (!script.crossOrigin) {
+        console.warn(`[@nuxt/hints]: Third-party script "${script.src}" is missing crossorigin attribute. Consider adding crossorigin="anonymous" for better security and error reporting.`);
+      }
+      nuxtApp.callHook("hints:scripts:added", script).then(() => {
+        if (!script.loaded) {
+          script.onload = () => {
+            window.__hints_TPC_saveTime(script, script.__hints_TPC_start_time);
+            nuxtApp.callHook("hints:scripts:loaded", script);
+          };
+        } else {
+          window.__hints_TPC_saveTime(script, script.__hints_TPC_start_time);
+          nuxtApp.callHook("hints:scripts:loaded", script);
+        }
+      });
+      console.info(`\u2139\uFE0F [@nuxt/hints]: Dynamically added third-party script detected: ${script.src}`);
+    }
+  }
+});
+function isScript(node) {
+  return node.nodeName === "SCRIPT";
+}

package/dist/runtime/types.d.ts

@@ -0,0 +1,48 @@
+import type { ComponentInternalInstance, VNode, Ref } from 'vue'
+import type { LCPMetricWithAttribution, INPMetricWithAttribution, CLSMetricWithAttribution } from 'web-vitals/attribution'
+
+declare global {
+  interface Window {
+    __hints_TPC_start_time: number
+    __hints_TPC_saveTime: (script: HTMLScriptElement, startTime?: number) => void
+  }
+  interface HTMLScriptElement {
+    __hints_TPC_start_time?: number
+    __hints_TPC_end_time?: number
+    requestTime?: number
+    downloadTime?: number
+    totalNetworkTime?: number
+    parseExecuteTime?: number
+    loaded?: boolean
+  }
+  interface Element {
+    __vnode?: VNode
+  }
+}
+declare module '#app' {
+  interface RuntimeNuxtHooks {
+    'hints:scripts:added': (script: HTMLScriptElement) => void
+    'hints:scripts:loaded': (script: HTMLScriptElement) => void
+
+    'hints:webvitals:sync': (webvitals: NuxtApp['__hints']['webvitals']) => void
+    'hints:webvitals:lcp': (metric: LCPMetricWithAttribution) => void
+    'hints:webvitals:inp': (metric: INPMetricWithAttribution) => void
+    'hints:webvitals:cls': (metric: CLSMetricWithAttribution) => void
+  }
+
+  interface NuxtApp {
+    __hints_tpc: Ref<{ element: HTMLScriptElement, loaded: boolean }[]>
+    __hints: {
+      hydration: { instance: ComponentInternalInstance, vnode: VNode, htmlPreHydration: string | undefined, htmlPostHydration: string | undefined }[]
+      webvitals: {
+        lcp: Ref<LCPMetricWithAttribution[]>
+        inp: Ref<INPMetricWithAttribution[]>
+        cls: Ref<CLSMetricWithAttribution[]>
+      }
+    }
+    __tracerOverlay: typeof import('vite-plugin-vue-tracer/client/overlay')
+    __tracerRecord: typeof import('vite-plugin-vue-tracer/client/record')
+  }
+}
+
+export {}

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: import("nuxt/app").Plugin<Record<string, unknown>> & import("nuxt/app").ObjectPlugin<Record<string, unknown>>;
+export default _default;