nuxt-devtools-observatory 0.1.19 → 0.1.22

package/README.md

@@ -14,18 +14,49 @@ Nuxt DevTools extension providing five missing observability features:
 pnpm add nuxt-devtools-observatory
 ```
 
+You can configure all observability features and limits from your consuming project's `nuxt.config.ts` or `.env` file. All options in `.env.example` are supported as either environment variables or as properties under the `observatory` key in your Nuxt config. Options set in `nuxt.config.ts` take precedence over `.env` values.
+
+**Available options:**
+
+- `instrumentServer` (boolean) — Instrument the server for SSR/Nitro fetch and composable tracking (set via `OBSERVATORY_INSTRUMENT_SERVER` or `VITE_OBSERVATORY_INSTRUMENT_SERVER`)
+- `fetchDashboard` (boolean) — Enable useFetch dashboard
+- `provideInjectGraph` (boolean) — Enable provide/inject graph
+- `composableTracker` (boolean) — Enable composable tracker
+- `renderHeatmap` (boolean) — Enable render heatmap
+- `transitionTracker` (boolean) — Enable transition tracker
+- `heatmapThresholdCount` (number) — Highlight components with N+ renders in heatmap
+- `heatmapThresholdTime` (number) — Highlight components with render time above this (ms)
+- `heatmapHideInternals` (boolean) — Hide node_modules and internal components in the render heatmap for a cleaner view
+- `maxFetchEntries` (number) — Max fetch entries to keep in memory
+- `maxPayloadBytes` (number) — Max payload size (bytes) per fetch entry
+- `maxTransitions` (number) — Max transition entries to keep in memory
+- `maxComposableHistory` (number) — Max composable history events per entry
+- `maxComposableEntries` (number) — Max composable entries to keep in memory
+- `maxRenderTimeline` (number) — Max render timeline events per entry
+
+See `.env.example` for all environment variable names.
+
 ```ts
 // nuxt.config.ts
 export default defineNuxtConfig({
     modules: ['nuxt-devtools-observatory'],
 
     observatory: {
-        fetchDashboard: true,
-        provideInjectGraph: true,
-        composableTracker: true,
-        renderHeatmap: true,
-        transitionTracker: true,
-        heatmapThresholdCount: 5, // highlight components with 5+ renders
+        instrumentServer: true, // Instrument the server for SSR/Nitro fetch and composable tracking. Enable this when using SSR so server-side composable calls are captured. Disable for SPA projects to avoid double-registration caused by the transform running on both builds.
+        fetchDashboard: true, // Enable useFetch dashboard
+        provideInjectGraph: true, // Enable provide/inject graph
+        composableTracker: true, // Enable composable tracker
+        renderHeatmap: true, // Enable render heatmap
+        transitionTracker: true, // Enable transition tracker
+        heatmapThresholdCount: 5, // Highlight components with 5+ renders
+        heatmapThresholdTime: 1600, // Highlight components with render time above this (ms)
+        heatmapHideInternals: true, // Hide node_modules and internal components in the render heatmap
+        maxFetchEntries: 200, // Max fetch entries to keep in memory
+        maxPayloadBytes: 10000, // Max payload size (bytes) per fetch entry
+        maxTransitions: 500, // Max transition entries to keep in memory
+        maxComposableHistory: 50, // Max composable history events per entry
+        maxComposableEntries: 300, // Max composable entries to keep in memory
+        maxRenderTimeline: 100, // Max render timeline events per entry
     },
 
     devtools: { enabled: true },

package/client/.env

@@ -12,3 +12,5 @@ VITE_OBSERVATORY_MAX_COMPOSABLE_ENTRIES=300
 VITE_OBSERVATORY_MAX_RENDER_TIMELINE=100
 VITE_OBSERVATORY_HEATMAP_THRESHOLD_COUNT=3
 VITE_OBSERVATORY_HEATMAP_THRESHOLD_TIME=1600
+VITE_OBSERVATORY_HEATMAP_HIDE_INTERNALS=true
+VITE_OBSERVATORY_INSTRUMENT_SERVER=true

package/client/.env.example

@@ -12,3 +12,5 @@ VITE_OBSERVATORY_MAX_COMPOSABLE_ENTRIES=300
 VITE_OBSERVATORY_MAX_RENDER_TIMELINE=100
 VITE_OBSERVATORY_HEATMAP_THRESHOLD_COUNT=3
 VITE_OBSERVATORY_HEATMAP_THRESHOLD_TIME=1600
+VITE_OBSERVATORY_HEATMAP_HIDE_INTERNALS=true
+VITE_OBSERVATORY_INSTRUMENT_SERVER=true

package/dist/module.d.mts

@@ -1,6 +1,14 @@
 import * as _nuxt_schema from '@nuxt/schema';
 
 interface ModuleOptions {
+    /**
+     * Instrument composables, provide/inject, fetch, and transitions on the
+     * server build as well as the client build. Enable this when using SSR so
+     * server-side composable calls are captured. Disable for SPA projects to
+     * avoid double-registration caused by the transform running on both builds.
+     * @default false
+     */
+    instrumentServer?: boolean;
     /**
      * Maximum number of fetch entries to keep in memory
      * @default 200
@@ -56,6 +64,11 @@ interface ModuleOptions {
      * @default true
      */
     transitionTracker?: boolean;
+    /**
+     * Hide node_modules/internal components in the render heatmap
+     * @default false
+     */
+    heatmapHideInternals?: boolean;
     /**
      * Minimum render count / ms threshold to highlight in the heatmap
      * @default 3

package/dist/module.json

@@ -4,7 +4,7 @@
   "compatibility": {
     "nuxt": "^3.0.0 || ^4.0.0"
   },
-  "version": "0.1.19",
+  "version": "0.1.22",
   "builder": {
     "@nuxt/module-builder": "1.0.2",
     "unbuild": "3.6.1"

package/dist/module.mjs

@@ -285,21 +285,42 @@ const traverse = _traverse.default ?? _traverse;
 const generate = _generate.default ?? _generate;
 const COMPOSABLE_RE = /\buse[A-Z]/;
 const SKIP_LIST = /* @__PURE__ */ new Set([
+  // useFetch family — tracked by the fetch dashboard
   "useFetch",
   "useAsyncData",
   "useLazyFetch",
   "useLazyAsyncData",
-  "useState",
-  "useRoute",
-  "useRouter",
+  // Nuxt auto-imports
+  "useCookie",
+  "useRequestEvent",
+  "useRequestHeaders",
+  "useRequestURL",
+  "useResponseHeader",
   "useNuxtApp",
   "useRuntimeConfig",
+  "useRoute",
+  "useRouter",
+  "useNuxtData",
+  "useError",
+  "useState",
+  "useAppConfig",
+  // Nuxt head
   "useHead",
   "useSeoMeta",
   "useServerSeoMeta",
-  "useNuxtData",
-  "useError",
-  "useRequestHeaders"
+  "useHeadSafe",
+  // Nuxt i18n (common plugin)
+  "useI18n",
+  "useLocalePath",
+  "useLocaleRoute",
+  // Vue built-ins
+  "useSlots",
+  "useAttrs",
+  "useModel",
+  "useTemplateRef",
+  "useId",
+  "useCssModule",
+  "useCssVars"
 ]);
 function composableTrackerPlugin() {
   return {
@@ -345,6 +366,14 @@ function composableTrackerPlugin() {
             if (SKIP_LIST.has(name)) {
               return;
             }
+            const binding = path.scope.getBinding(name);
+            if (binding?.path.isImportSpecifier() || binding?.path.isImportDefaultSpecifier()) {
+              const importDecl = binding.path.parentPath?.node;
+              const source = importDecl?.source?.value ?? "";
+              if (source && !source.startsWith(".") && !source.startsWith("/")) {
+                return;
+              }
+            }
             let parent = path.parentPath;
             let isWrapped = false;
             while (parent) {
@@ -385,11 +414,13 @@ function composableTrackerPlugin() {
         const importLine = `import { __trackComposable } from 'nuxt-devtools-observatory/runtime/composable-registry';
 `;
         const output = generate(ast, { retainLines: true }, scriptCode);
+        const alreadyImported = output.code.includes("nuxt-devtools-observatory/runtime/composable-registry");
+        const prefix = alreadyImported ? "" : importLine;
         let finalCode;
         if (isVue) {
-          finalCode = code.slice(0, scriptStart) + (scriptCode.includes("__trackComposable") ? "" : importLine) + output.code + code.slice(scriptStart + scriptCode.length);
+          finalCode = code.slice(0, scriptStart) + prefix + output.code + code.slice(scriptStart + scriptCode.length);
         } else {
-          finalCode = (scriptCode.includes("__trackComposable") ? "" : importLine) + output.code;
+          finalCode = prefix + output.code;
         }
         return { code: finalCode, map: output.map };
       } catch (err) {
@@ -519,11 +550,12 @@ const module$1 = defineNuxtModule({
     compatibility: { nuxt: "^3.0.0 || ^4.0.0" }
   },
   defaults: {
-    fetchDashboard: true,
-    provideInjectGraph: true,
-    composableTracker: true,
-    renderHeatmap: true,
-    transitionTracker: true,
+    instrumentServer: process.env.OBSERVATORY_INSTRUMENT_SERVER === "true",
+    fetchDashboard: process.env.OBSERVATORY_FETCH_DASHBOARD === "true",
+    provideInjectGraph: process.env.OBSERVATORY_PROVIDE_INJECT_GRAPH === "true",
+    composableTracker: process.env.OBSERVATORY_COMPOSABLE_TRACKER === "true",
+    renderHeatmap: process.env.OBSERVATORY_RENDER_HEATMAP === "true",
+    transitionTracker: process.env.OBSERVATORY_TRANSITION_TRACKER === "true",
     heatmapThresholdCount: process.env.OBSERVATORY_HEATMAP_THRESHOLD_COUNT ? Number(process.env.OBSERVATORY_HEATMAP_THRESHOLD_COUNT) : 3,
     heatmapThresholdTime: process.env.OBSERVATORY_HEATMAP_THRESHOLD_TIME ? Number(process.env.OBSERVATORY_HEATMAP_THRESHOLD_TIME) : 1600,
     maxFetchEntries: process.env.OBSERVATORY_MAX_FETCH_ENTRIES ? Number(process.env.OBSERVATORY_MAX_FETCH_ENTRIES) : 200,
@@ -531,7 +563,8 @@ const module$1 = defineNuxtModule({
     maxTransitions: process.env.OBSERVATORY_MAX_TRANSITIONS ? Number(process.env.OBSERVATORY_MAX_TRANSITIONS) : 500,
     maxComposableHistory: process.env.OBSERVATORY_MAX_COMPOSABLE_HISTORY ? Number(process.env.OBSERVATORY_MAX_COMPOSABLE_HISTORY) : 50,
     maxComposableEntries: process.env.OBSERVATORY_MAX_COMPOSABLE_ENTRIES ? Number(process.env.OBSERVATORY_MAX_COMPOSABLE_ENTRIES) : 300,
-    maxRenderTimeline: process.env.OBSERVATORY_MAX_RENDER_TIMELINE ? Number(process.env.OBSERVATORY_MAX_RENDER_TIMELINE) : 100
+    maxRenderTimeline: process.env.OBSERVATORY_MAX_RENDER_TIMELINE ? Number(process.env.OBSERVATORY_MAX_RENDER_TIMELINE) : 100,
+    heatmapHideInternals: process.env.OBSERVATORY_HEATMAP_HIDE_INTERNALS === "true"
   },
   setup(options, nuxt) {
     if (!nuxt.options.dev) {
@@ -542,11 +575,16 @@ const module$1 = defineNuxtModule({
     }
     const resolver = createResolver(import.meta.url);
     const resolved = {
+      ...defaults,
+      ...options,
+      // Allow runtime overrides via env
+      heatmapHideInternals: typeof process.env.OBSERVATORY_HEATMAP_HIDE_INTERNALS !== "undefined" ? process.env.OBSERVATORY_HEATMAP_HIDE_INTERNALS === "true" : typeof options.heatmapHideInternals !== "undefined" ? options.heatmapHideInternals : defaults.heatmapHideInternals,
       fetchDashboard: options.fetchDashboard ?? (process.env.OBSERVATORY_FETCH_DASHBOARD ? process.env.OBSERVATORY_FETCH_DASHBOARD === "true" : true),
       provideInjectGraph: options.provideInjectGraph ?? (process.env.OBSERVATORY_PROVIDE_INJECT_GRAPH ? process.env.OBSERVATORY_PROVIDE_INJECT_GRAPH === "true" : true),
       composableTracker: options.composableTracker ?? (process.env.OBSERVATORY_COMPOSABLE_TRACKER ? process.env.OBSERVATORY_COMPOSABLE_TRACKER === "true" : true),
       renderHeatmap: options.renderHeatmap ?? (process.env.OBSERVATORY_RENDER_HEATMAP ? process.env.OBSERVATORY_RENDER_HEATMAP === "true" : true),
       transitionTracker: options.transitionTracker ?? (process.env.OBSERVATORY_TRANSITION_TRACKER ? process.env.OBSERVATORY_TRANSITION_TRACKER === "true" : true),
+      instrumentServer: options.instrumentServer ?? (process.env.OBSERVATORY_INSTRUMENT_SERVER ? process.env.OBSERVATORY_INSTRUMENT_SERVER === "true" : false),
       heatmapThresholdCount: options.heatmapThresholdCount ?? (process.env.OBSERVATORY_HEATMAP_THRESHOLD_COUNT ? Number(process.env.OBSERVATORY_HEATMAP_THRESHOLD_COUNT) : 3),
       heatmapThresholdTime: options.heatmapThresholdTime ?? (process.env.OBSERVATORY_HEATMAP_THRESHOLD_TIME ? Number(process.env.OBSERVATORY_HEATMAP_THRESHOLD_TIME) : 1600),
       maxFetchEntries: options.maxFetchEntries ?? (process.env.OBSERVATORY_MAX_FETCH_ENTRIES ? Number(process.env.OBSERVATORY_MAX_FETCH_ENTRIES) : 200),
@@ -566,17 +604,18 @@ const module$1 = defineNuxtModule({
       aliases["nuxt-devtools-observatory/runtime/fetch-registry"] = resolver.resolve("./runtime/composables/fetch-registry");
       config.resolve = { ...config.resolve, alias: aliases };
     });
+    const vitePluginScope = resolved.instrumentServer ? { server: true, client: true } : { server: false, client: true };
     if (resolved.fetchDashboard) {
-      addVitePlugin(fetchInstrumentPlugin());
+      addVitePlugin(fetchInstrumentPlugin(), vitePluginScope);
     }
     if (resolved.provideInjectGraph) {
-      addVitePlugin(provideInjectPlugin());
+      addVitePlugin(provideInjectPlugin(), vitePluginScope);
     }
     if (resolved.composableTracker) {
-      addVitePlugin(composableTrackerPlugin());
+      addVitePlugin(composableTrackerPlugin(), vitePluginScope);
     }
     if (resolved.transitionTracker) {
-      addVitePlugin(transitionTrackerPlugin());
+      addVitePlugin(transitionTrackerPlugin(), vitePluginScope);
     }
     if (resolved.fetchDashboard || resolved.provideInjectGraph || resolved.composableTracker || resolved.renderHeatmap || resolved.transitionTracker) {
       addPlugin(resolver.resolve("./runtime/plugin"));
@@ -630,8 +669,7 @@ ${configScript}`);
       }
     });
     nuxt.options.runtimeConfig.public.observatory = {
-      heatmapThresholdCount: resolved.heatmapThresholdCount,
-      heatmapThresholdTime: resolved.heatmapThresholdTime,
+      instrumentServer: resolved.instrumentServer,
       clientOrigin,
       fetchDashboard: resolved.fetchDashboard,
       provideInjectGraph: resolved.provideInjectGraph,
@@ -643,7 +681,10 @@ ${configScript}`);
       maxTransitions: resolved.maxTransitions,
       maxComposableHistory: resolved.maxComposableHistory,
       maxComposableEntries: resolved.maxComposableEntries,
-      maxRenderTimeline: resolved.maxRenderTimeline
+      maxRenderTimeline: resolved.maxRenderTimeline,
+      heatmapHideInternals: resolved.heatmapHideInternals,
+      heatmapThresholdCount: resolved.heatmapThresholdCount,
+      heatmapThresholdTime: resolved.heatmapThresholdTime
     };
   }
 });

package/dist/runtime/composables/composable-registry.js

@@ -298,7 +298,7 @@ export function __trackComposable(name, callFn, meta) {
     return callFn();
   }
   const instance = getCurrentInstance();
-  const id = `${name}::${instance?.uid ?? "global"}::${meta.file}:${meta.line}::${Date.now()}::${Math.random().toString(36).slice(2, 7)}`;
+  const id = instance ? `${name}::${instance.uid}::${meta.file}:${meta.line}::${Date.now()}::${Math.random().toString(36).slice(2, 7)}` : `${name}::global::${meta.file}:${meta.line}`;
   const trackedIntervals = [];
   const clearedIntervals = /* @__PURE__ */ new Set();
   const alreadyPatched = !!window.setInterval.__obs;
@@ -373,7 +373,17 @@ export function __trackComposable(name, callFn, meta) {
     line: meta.line,
     route: registry.getRoute()
   };
-  registry.register(entry);
+  if (!instance && registry.getAll().some((e) => e.id === id)) {
+    registry.update(id, {
+      status: "mounted",
+      refs,
+      watcherCount: trackedWatchers.length,
+      intervalCount: trackedIntervals.length,
+      route: registry.getRoute()
+    });
+  } else {
+    registry.register(entry);
+  }
   if (instance) {
     registry.registerLiveRefs(id, liveRefMap);
     registry.registerRawRefs(id, rawRefMap);

package/dist/runtime/composables/render-registry.js

@@ -1,9 +1,12 @@
+import { useRuntimeConfig } from "#app";
 export function setupRenderRegistry(nuxtApp, options = {}) {
   const entries = /* @__PURE__ */ new Map();
   const pendingTriggeredRenders = /* @__PURE__ */ new Set();
   const renderStartTimes = /* @__PURE__ */ new Map();
   let currentRoute = "/";
-  const MAX_TIMELINE = typeof process !== "undefined" && process.env.OBSERVATORY_MAX_RENDER_TIMELINE ? Number(process.env.OBSERVATORY_MAX_RENDER_TIMELINE) : 100;
+  const config = useRuntimeConfig().public.observatory;
+  const MAX_TIMELINE = config.maxRenderTimeline ?? 100;
+  const HIDE_INTERNALS = config.heatmapHideInternals ?? false;
   let dirty = true;
   let cachedSnapshot = "[]";
   function markDirty() {
@@ -12,10 +15,28 @@ export function setupRenderRegistry(nuxtApp, options = {}) {
   function setRoute(path) {
     currentRoute = path;
   }
+  function isInternalInstance(instance) {
+    const file = instance.$.type.__file;
+    return !file || file.includes("node_modules");
+  }
+  function nearestTrackedAncestorUid(instance) {
+    let cursor = instance.$parent;
+    while (cursor) {
+      if (!isInternalInstance(cursor)) {
+        return cursor.$.uid;
+      }
+      cursor = cursor.$parent;
+    }
+    return void 0;
+  }
   function ensureEntry(instance) {
     const uid = instance.$.uid;
     if (!entries.has(uid)) {
-      entries.set(uid, makeEntry(uid, instance, currentRoute));
+      if (HIDE_INTERNALS && isInternalInstance(instance)) {
+        return null;
+      }
+      const parentUid = HIDE_INTERNALS ? nearestTrackedAncestorUid(instance) : instance.$parent?.$.uid;
+      entries.set(uid, makeEntry(uid, instance, currentRoute, parentUid));
       markDirty();
     }
     return entries.get(uid);
@@ -111,6 +132,9 @@ export function setupRenderRegistry(nuxtApp, options = {}) {
     },
     mounted() {
       const entry = ensureEntry(this);
+      if (!entry) {
+        return;
+      }
       entry.mountCount++;
       const isHydration = options.isHydrating?.() ?? false;
       if (isHydration && entry.mountCount === 1) {
@@ -133,6 +157,9 @@ export function setupRenderRegistry(nuxtApp, options = {}) {
     },
     renderTriggered({ key, type }) {
       const entry = ensureEntry(this);
+      if (!entry) {
+        return;
+      }
       entry.triggers.push({ key: String(key), type, timestamp: performance.now() });
       pendingTriggeredRenders.add(entry.uid);
       if (entry.triggers.length > 50) {
@@ -142,6 +169,9 @@ export function setupRenderRegistry(nuxtApp, options = {}) {
     },
     updated() {
       const entry = ensureEntry(this);
+      if (!entry) {
+        return;
+      }
       pendingTriggeredRenders.delete(entry.uid);
       entry.rerenders++;
       markRectDirty(entry.uid);
@@ -213,7 +243,7 @@ export function setupRenderRegistry(nuxtApp, options = {}) {
   }
   return { getAll, getSnapshot, snapshot, reset, setRoute };
 }
-function makeEntry(uid, instance, route) {
+function makeEntry(uid, instance, route, parentUid) {
   const type = instance.$.type;
   const parentType = instance.$parent?.$?.type;
   const element = describeElement(instance.$el);
@@ -231,7 +261,7 @@ function makeEntry(uid, instance, route) {
     avgMs: 0,
     triggers: [],
     timeline: [],
-    parentUid: instance.$parent?.$.uid,
+    parentUid,
     isPersistent: false,
     isHydrationMount: false,
     route

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "nuxt-devtools-observatory",
-    "version": "0.1.19",
+    "version": "0.1.22",
     "description": "Nuxt DevTools: useFetch Dashboard, provide/inject Graph, Composable Tracker, Render Heatmap",
     "license": "MIT",
     "repository": {