npm - nextjs-performance-guard - Versions diffs - 1.0.0 - Mend

nextjs-performance-guard 1.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (18) hide show

package/LICENSE +23 -0
package/README.md +251 -0
package/dist/bundleGuard.d.ts +6 -0
package/dist/bundleGuard.d.ts.map +1 -0
package/dist/bundleGuard.js +134 -0
package/dist/componentGuard.d.ts +4 -0
package/dist/componentGuard.d.ts.map +1 -0
package/dist/componentGuard.js +134 -0
package/dist/index.d.ts +5 -0
package/dist/index.d.ts.map +1 -0
package/dist/index.js +3 -0
package/dist/routeAnalyzer.d.ts +21 -0
package/dist/routeAnalyzer.d.ts.map +1 -0
package/dist/routeAnalyzer.js +167 -0
package/dist/types.d.ts +31 -0
package/dist/types.d.ts.map +1 -0
package/dist/types.js +1 -0
package/package.json +53 -0

package/LICENSE ADDED Viewed

@@ -0,0 +1,23 @@
+MIT License
+Copyright (c) 2024 nextjs-performance-guard contributors
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md ADDED Viewed

@@ -0,0 +1,251 @@
+# nextjs-performance-guard
+> A Next.js developer performance guard that detects heavy components, large bundles, and slow routes in development.
+[![npm version](https://img.shields.io/npm/v/nextjs-performance-guard.svg)](https://www.npmjs.com/package/nextjs-performance-guard)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+## What Problem Does This Solve?
+Performance issues in Next.js applications often go unnoticed until they reach production. By the time users experience slow load times, heavy components, or bloated bundles, it's too late. `nextjs-performance-guard` provides real-time performance warnings during development, helping you catch and fix issues before they ship.
+## Why Performance Guard Matters
+- **Early Detection**: Catch performance regressions during development, not in production
+- **Actionable Warnings**: Clear, debounced console warnings with specific metrics
+- **Zero Production Impact**: Automatically disabled in production builds
+- **Framework-Agnostic**: Works with both App Router and Pages Router
+- **Lightweight**: No runtime dependencies, tree-shakable, ESM-only
+## Installation
+```bash
+npm install --save-dev nextjs-performance-guard
+```
+## Usage
+### App Router
+#### 1. Heavy Component Detection
+Wrap components that might be performance bottlenecks:
+```tsx
+// app/components/DashboardCard.tsx
+import { withPerformanceGuard } from 'nextjs-performance-guard';
+function DashboardCard({ data }: { data: any }) {
+  // Your component logic
+  return <div>...</div>;
+}
+export default withPerformanceGuard(DashboardCard);
+```
+#### 2. Client Bundle Size Guard
+Add bundle analysis to your root layout:
+```tsx
+// app/layout.tsx
+import { analyzeClientBundle } from 'nextjs-performance-guard';
+import { useEffect } from 'react';
+export default function RootLayout({ children }: { children: React.ReactNode }) {
+  useEffect(() => {
+    analyzeClientBundle({ maxSizeKB: 170 });
+  }, []);
+  return <html>{children}</html>;
+}
+```
+#### 3. Route Load Analyzer
+Track route performance in your layout:
+```tsx
+// app/layout.tsx
+import { analyzeRoutes } from 'nextjs-performance-guard';
+import { useEffect } from 'react';
+export default function RootLayout({ children }: { children: React.ReactNode }) {
+  useEffect(() => {
+    const analyzer = analyzeRoutes({ routeLoadThreshold: 1000 });
+    // Measure client-side navigation
+    return () => {
+      analyzer.measureNavigation();
+    };
+  }, []);
+  return <html>{children}</html>;
+}
+```
+### Pages Router
+#### 1. Heavy Component Detection
+Same as App Router:
+```tsx
+// components/HeavyComponent.tsx
+import { withPerformanceGuard } from 'nextjs-performance-guard';
+function HeavyComponent() {
+  return <div>...</div>;
+}
+export default withPerformanceGuard(HeavyComponent);
+```
+#### 2. Client Bundle Size Guard
+Add to `_app.tsx`:
+```tsx
+// pages/_app.tsx
+import { analyzeClientBundle } from 'nextjs-performance-guard';
+import { useEffect } from 'react';
+export default function App({ Component, pageProps }: AppProps) {
+  useEffect(() => {
+    analyzeClientBundle({ maxSizeKB: 170 });
+  }, []);
+  return <Component {...pageProps} />;
+}
+```
+#### 3. Route Load Analyzer
+Add to `_app.tsx`:
+```tsx
+// pages/_app.tsx
+import { analyzeRoutes } from 'nextjs-performance-guard';
+import { useEffect } from 'react';
+import { useRouter } from 'next/router';
+export default function App({ Component, pageProps }: AppProps) {
+  const router = useRouter();
+  const analyzer = analyzeRoutes({ routeLoadThreshold: 1000 });
+  useEffect(() => {
+    const handleRouteChange = () => {
+      analyzer.measureNavigation();
+    };
+    router.events.on('routeChangeComplete', handleRouteChange);
+    return () => {
+      router.events.off('routeChangeComplete', handleRouteChange);
+    };
+  }, [router]);
+  return <Component {...pageProps} />;
+}
+```
+## Configuration Options
+All functions accept an optional `PerformanceGuardConfig`:
+```typescript
+interface PerformanceGuardConfig {
+  enabled?: boolean;              // Override NODE_ENV check (default: auto)
+  componentThreshold?: number;    // Render time threshold in ms (default: 16)
+  bundleThresholdKB?: number;     // Bundle size threshold in KB (default: 170)
+  routeLoadThreshold?: number;   // Route load threshold in ms (default: 1000)
+  debounceMs?: number;            // Warning debounce time in ms (default: 1000-2000)
+}
+```
+### Example with Custom Configuration
+```tsx
+import { withPerformanceGuard } from 'nextjs-performance-guard';
+export default withPerformanceGuard(MyComponent, {
+  componentThreshold: 32,  // Warn if render > 32ms
+  debounceMs: 2000,        // Debounce warnings by 2s
+});
+```
+## Warning Examples
+### Heavy Component
+```
+⚠️ [Next Perf Guard] Heavy component detected: DashboardCard (render: 68ms) (re-renders: 15)
+```
+### Large Bundle
+```
+⚠️ [Next Perf Guard] Client bundle exceeds 170kb on /dashboard (actual: 245kb)
+```
+### Slow Route
+```
+⚠️ [Next Perf Guard] Slow route detected: /profile (load: 1.9s) (hydration: 0.8s)
+```
+## Dev-Only Behavior
+`nextjs-performance-guard` automatically disables itself when:
+- `NODE_ENV === "production"`
+- Running in a production build
+- Server-side rendering (SSR) contexts
+All performance monitoring logic is guarded behind development checks, ensuring **zero runtime overhead** in production.
+## API Reference
+### `withPerformanceGuard<T>(Component, config?)`
+Wraps a React component to monitor render performance.
+**Returns**: The same component type, wrapped with performance monitoring.
+### `analyzeClientBundle(config?)`
+Analyzes the current page's client-side JavaScript bundle size.
+**Returns**: `Promise<BundleMetrics | null>` (null in production or if under threshold).
+### `analyzeRoutes(config?)`
+Creates a route analyzer instance that tracks load times, hydration delays, and navigation latency.
+**Returns**: `RouteAnalyzer` instance with methods:
+- `getMetrics(route?)`: Get metrics for a specific route or all routes
+- `measureNavigation()`: Manually trigger navigation measurement
+- `reset()`: Clear all collected metrics
+### Reset Functions
+- `resetComponentGuard()`: Clear component metrics
+- `resetBundleGuard()`: Clear bundle analysis cache
+- `resetRouteAnalyzer()`: Clear route metrics
+## Limitations
+- **Development Only**: Performance monitoring only works in development mode
+- **Client-Side Only**: Bundle and route analysis require browser APIs
+- **Heuristic-Based**: Component file size estimation is approximate
+- **Next.js 13+**: Requires Next.js 13 or higher (App Router or Pages Router)
+- **React 18+**: Requires React 18 or higher
+## License
+MIT
+## Contributing
+Contributions welcome! Please open an issue or pull request.

package/dist/bundleGuard.d.ts ADDED Viewed

@@ -0,0 +1,6 @@
+import type { BundleMetrics, PerformanceGuardConfig } from './types.js';
+export declare function analyzeClientBundle(config?: PerformanceGuardConfig & {
+    maxSizeKB?: number;
+}): Promise<BundleMetrics | null>;
+export declare function resetBundleGuard(): void;
+//# sourceMappingURL=bundleGuard.d.ts.map

package/dist/bundleGuard.d.ts.map ADDED Viewed

	@@ -0,0 +1 @@
1	+ {"version":3,"file":"bundleGuard.d.ts","sourceRoot":"","sources":["../src/bundleGuard.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,sBAAsB,EAAE,MAAM,YAAY,CAAC;AA+IxE,wBAAsB,mBAAmB,CACvC,MAAM,CAAC,EAAE,sBAAsB,GAAG;IAAE,SAAS,CAAC,EAAE,MAAM,CAAA;CAAE,GACvD,OAAO,CAAC,aAAa,GAAG,IAAI,CAAC,CAU/B;AAED,wBAAgB,gBAAgB,IAAI,IAAI,CAIvC"}

package/dist/bundleGuard.js ADDED Viewed

@@ -0,0 +1,134 @@
+const isDevelopment = () => {
+    return typeof process !== 'undefined' && process.env?.NODE_ENV !== 'production';
+};
+const defaultConfig = {
+    bundleThresholdKB: 170,
+    debounceMs: 2000,
+};
+class BundleGuard {
+    analyzedRoutes = new Set();
+    lastWarning = new Map();
+    config;
+    constructor(config = {}) {
+        this.config = {
+            bundleThresholdKB: config.bundleThresholdKB ?? defaultConfig.bundleThresholdKB,
+            debounceMs: config.debounceMs ?? defaultConfig.debounceMs,
+        };
+    }
+    shouldWarn(route) {
+        if (!isDevelopment())
+            return false;
+        const now = Date.now();
+        const lastWarnTime = this.lastWarning.get(route) ?? 0;
+        return now - lastWarnTime > this.config.debounceMs;
+    }
+    async getScriptSizes() {
+        if (typeof window === 'undefined') {
+            return { totalKB: 0, scripts: [] };
+        }
+        const scripts = Array.from(document.querySelectorAll('script[src]'));
+        const scriptData = [];
+        let totalBytes = 0;
+        for (const script of scripts) {
+            const src = script.src;
+            if (!src || !src.includes('_next/static')) {
+                continue;
+            }
+            try {
+                const response = await fetch(src, { method: 'HEAD' });
+                const contentLength = response.headers.get('content-length');
+                if (contentLength) {
+                    const sizeBytes = parseInt(contentLength, 10);
+                    const sizeKB = sizeBytes / 1024;
+                    totalBytes += sizeBytes;
+                    scriptData.push({ src, sizeKB: Math.round(sizeKB * 100) / 100 });
+                }
+            }
+            catch {
+                try {
+                    const response = await fetch(src);
+                    const blob = await response.blob();
+                    const sizeKB = blob.size / 1024;
+                    totalBytes += blob.size;
+                    scriptData.push({ src, sizeKB: Math.round(sizeKB * 100) / 100 });
+                }
+                catch {
+                    continue;
+                }
+            }
+        }
+        return {
+            totalKB: Math.round((totalBytes / 1024) * 100) / 100,
+            scripts: scriptData,
+        };
+    }
+    getCurrentRoute() {
+        if (typeof window === 'undefined') {
+            return '/';
+        }
+        try {
+            return window.location.pathname;
+        }
+        catch {
+            return '/';
+        }
+    }
+    async analyzeClientBundle(config) {
+        if (!isDevelopment()) {
+            return null;
+        }
+        const thresholdKB = config?.maxSizeKB ?? config?.bundleThresholdKB ?? this.config.bundleThresholdKB;
+        const route = this.getCurrentRoute();
+        if (this.analyzedRoutes.has(route)) {
+            return null;
+        }
+        this.analyzedRoutes.add(route);
+        try {
+            const { totalKB } = await this.getScriptSizes();
+            if (totalKB > thresholdKB) {
+                if (this.shouldWarn(route)) {
+                    const metrics = {
+                        route,
+                        sizeKB: totalKB,
+                        thresholdKB,
+                    };
+                    this.warn(metrics);
+                    this.lastWarning.set(route, Date.now());
+                    return metrics;
+                }
+            }
+        }
+        catch (error) {
+            if (isDevelopment()) {
+                console.debug('[Next Perf Guard] Bundle analysis failed:', error);
+            }
+        }
+        return null;
+    }
+    warn(metrics) {
+        const parts = [];
+        parts.push(`⚠️ [Next Perf Guard] Client bundle exceeds ${metrics.thresholdKB}kb`);
+        parts.push(`on ${metrics.route}`);
+        parts.push(`(actual: ${metrics.sizeKB}kb)`);
+        console.warn(parts.join(' '));
+    }
+    reset() {
+        this.analyzedRoutes.clear();
+        this.lastWarning.clear();
+    }
+}
+let globalBundleGuard = null;
+export async function analyzeClientBundle(config) {
+    if (!isDevelopment()) {
+        return null;
+    }
+    if (!globalBundleGuard) {
+        globalBundleGuard = new BundleGuard(config);
+    }
+    return globalBundleGuard.analyzeClientBundle(config);
+}
+export function resetBundleGuard() {
+    if (globalBundleGuard) {
+        globalBundleGuard.reset();
+    }
+}

package/dist/componentGuard.d.ts ADDED Viewed

@@ -0,0 +1,4 @@
+import type { PerformanceGuardConfig } from './types.js';
+export declare function withPerformanceGuard<T extends (...args: any[]) => any>(Component: T, config?: PerformanceGuardConfig): T;
+export declare function resetComponentGuard(): void;
+//# sourceMappingURL=componentGuard.d.ts.map

package/dist/componentGuard.d.ts.map ADDED Viewed

	@@ -0,0 +1 @@
1	+ {"version":3,"file":"componentGuard.d.ts","sourceRoot":"","sources":["../src/componentGuard.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAoB,sBAAsB,EAAE,MAAM,YAAY,CAAC;AAuJ3E,wBAAgB,oBAAoB,CAAC,CAAC,SAAS,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,GAAG,EACpE,SAAS,EAAE,CAAC,EACZ,MAAM,CAAC,EAAE,sBAAsB,GAC9B,CAAC,CAUH;AAED,wBAAgB,mBAAmB,IAAI,IAAI,CAI1C"}

package/dist/componentGuard.js ADDED Viewed

@@ -0,0 +1,134 @@
+const isDevelopment = () => {
+    return typeof process !== 'undefined' && process.env?.NODE_ENV !== 'production';
+};
+const defaultConfig = {
+    componentThreshold: 16, // ms (60fps = 16.67ms per frame)
+    debounceMs: 1000,
+};
+class ComponentGuard {
+    renderTimes = new Map();
+    renderCounts = new Map();
+    lastWarning = new Map();
+    config;
+    constructor(config = {}) {
+        this.config = {
+            componentThreshold: config.componentThreshold ?? defaultConfig.componentThreshold,
+            debounceMs: config.debounceMs ?? defaultConfig.debounceMs,
+        };
+    }
+    shouldWarn(componentName) {
+        if (!isDevelopment())
+            return false;
+        const now = Date.now();
+        const lastWarnTime = this.lastWarning.get(componentName) ?? 0;
+        return now - lastWarnTime > this.config.debounceMs;
+    }
+    recordRender(componentName, renderTime) {
+        if (!isDevelopment())
+            return;
+        const times = this.renderTimes.get(componentName) ?? [];
+        times.push(renderTime);
+        if (times.length > 10) {
+            times.shift();
+        }
+        this.renderTimes.set(componentName, times);
+        const count = this.renderCounts.get(componentName) ?? 0;
+        this.renderCounts.set(componentName, count + 1);
+    }
+    getAverageRenderTime(componentName) {
+        const times = this.renderTimes.get(componentName) ?? [];
+        if (times.length === 0)
+            return 0;
+        return times.reduce((a, b) => a + b, 0) / times.length;
+    }
+    estimateFileSize(componentName) {
+        if (typeof window === 'undefined')
+            return undefined;
+        try {
+            const component = window.__NEXT_DATA__?.props?.pageProps;
+            if (!component)
+                return undefined;
+            const scripts = document.querySelectorAll('script[src]');
+            let totalSize = 0;
+            scripts.forEach((script) => {
+                const src = script.getAttribute('src');
+                if (src && src.includes('_next/static')) {
+                    const sizeMatch = src.match(/\/_next\/static\/chunks\/(\d+)/);
+                    if (sizeMatch) {
+                        totalSize += parseInt(sizeMatch[1], 10);
+                    }
+                }
+            });
+            return totalSize > 0 ? totalSize : undefined;
+        }
+        catch {
+            return undefined;
+        }
+    }
+    measureRender(Component, componentName) {
+        if (!isDevelopment()) {
+            return Component;
+        }
+        const name = componentName || Component.displayName || Component.name || 'Unknown';
+        const GuardedComponent = ((...args) => {
+            const renderStart = performance.now();
+            const result = Component(...args);
+            const renderEnd = performance.now();
+            const renderTime = renderEnd - renderStart;
+            this.recordRender(name, renderTime);
+            const avgRenderTime = this.getAverageRenderTime(name);
+            const renderCount = this.renderCounts.get(name) ?? 0;
+            if (renderTime > this.config.componentThreshold ||
+                (avgRenderTime > this.config.componentThreshold && renderCount > 5)) {
+                if (this.shouldWarn(name)) {
+                    const fileSize = this.estimateFileSize(name);
+                    const metrics = {
+                        name,
+                        renderTime: Math.round(renderTime * 100) / 100,
+                        renderCount,
+                        fileSize,
+                    };
+                    this.warn(metrics);
+                    this.lastWarning.set(name, Date.now());
+                }
+            }
+            return result;
+        });
+        GuardedComponent.displayName = `withPerformanceGuard(${name})`;
+        return GuardedComponent;
+    }
+    warn(metrics) {
+        const parts = [];
+        parts.push(`⚠️ [Next Perf Guard] Heavy component detected: ${metrics.name}`);
+        if (metrics.renderTime > this.config.componentThreshold) {
+            parts.push(`(render: ${metrics.renderTime}ms)`);
+        }
+        if (metrics.renderCount > 10) {
+            parts.push(`(re-renders: ${metrics.renderCount})`);
+        }
+        if (metrics.fileSize && metrics.fileSize > 100000) {
+            parts.push(`(estimated size: ${Math.round(metrics.fileSize / 1024)}kb)`);
+        }
+        console.warn(parts.join(' '));
+    }
+    reset() {
+        this.renderTimes.clear();
+        this.renderCounts.clear();
+        this.lastWarning.clear();
+    }
+}
+let globalGuard = null;
+export function withPerformanceGuard(Component, config) {
+    if (!isDevelopment()) {
+        return Component;
+    }
+    if (!globalGuard) {
+        globalGuard = new ComponentGuard(config);
+    }
+    return globalGuard.measureRender(Component);
+}
+export function resetComponentGuard() {
+    if (globalGuard) {
+        globalGuard.reset();
+    }
+}

package/dist/index.d.ts ADDED Viewed

@@ -0,0 +1,5 @@
+export { withPerformanceGuard, resetComponentGuard } from './componentGuard.js';
+export { analyzeClientBundle, resetBundleGuard } from './bundleGuard.js';
+export { analyzeRoutes, resetRouteAnalyzer } from './routeAnalyzer.js';
+export type { PerformanceGuardConfig, ComponentMetrics, BundleMetrics, RouteMetrics, WarningOptions, WarningType, } from './types.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map ADDED Viewed

	@@ -0,0 +1 @@
1	+ {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,oBAAoB,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAC;AAChF,OAAO,EAAE,mBAAmB,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AACzE,OAAO,EAAE,aAAa,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AACvE,YAAY,EACV,sBAAsB,EACtB,gBAAgB,EAChB,aAAa,EACb,YAAY,EACZ,cAAc,EACd,WAAW,GACZ,MAAM,YAAY,CAAC"}

package/dist/index.js ADDED Viewed

@@ -0,0 +1,3 @@
+export { withPerformanceGuard, resetComponentGuard } from './componentGuard.js';
+export { analyzeClientBundle, resetBundleGuard } from './bundleGuard.js';
+export { analyzeRoutes, resetRouteAnalyzer } from './routeAnalyzer.js';

package/dist/routeAnalyzer.d.ts ADDED Viewed

@@ -0,0 +1,21 @@
+import type { RouteMetrics, PerformanceGuardConfig } from './types.js';
+declare class RouteAnalyzer {
+    private routeMetrics;
+    private lastWarning;
+    private navigationStartTime;
+    private hydrationStartTime;
+    private config;
+    constructor(config?: PerformanceGuardConfig);
+    private setupListeners;
+    private shouldWarn;
+    private getCurrentRoute;
+    private measureRouteLoad;
+    measureNavigation(): void;
+    private warn;
+    getMetrics(route?: string): RouteMetrics | Map<string, RouteMetrics>;
+    reset(): void;
+}
+export declare function analyzeRoutes(config?: PerformanceGuardConfig): RouteAnalyzer;
+export declare function resetRouteAnalyzer(): void;
+export {};
+//# sourceMappingURL=routeAnalyzer.d.ts.map

package/dist/routeAnalyzer.d.ts.map ADDED Viewed

@@ -0,0 +1 @@

+ {"version":3,"file":"routeAnalyzer.d.ts","sourceRoot":"","sources":["../src/routeAnalyzer.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,sBAAsB,EAAE,MAAM,YAAY,CAAC;AAWvE,cAAM,aAAa;IACjB,OAAO,CAAC,YAAY,CAAwC;IAC5D,OAAO,CAAC,WAAW,CAAkC;IACrD,OAAO,CAAC,mBAAmB,CAAuB;IAClD,OAAO,CAAC,kBAAkB,CAAuB;IACjD,OAAO,CAAC,MAAM,CAA8E;gBAEhF,MAAM,GAAE,sBAA2B;IAW/C,OAAO,CAAC,cAAc;IA8BtB,OAAO,CAAC,UAAU;IAQlB,OAAO,CAAC,eAAe;IAYvB,OAAO,CAAC,gBAAgB;IAqCxB,iBAAiB,IAAI,IAAI;IA+BzB,OAAO,CAAC,IAAI;IAmBZ,UAAU,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,YAAY,GAAG,GAAG,CAAC,MAAM,EAAE,YAAY,CAAC;IAOpE,KAAK,IAAI,IAAI;CAMd;AAID,wBAAgB,aAAa,CAAC,MAAM,CAAC,EAAE,sBAAsB,GAAG,aAAa,CAc5E;AAED,wBAAgB,kBAAkB,IAAI,IAAI,CAIzC"}

package/dist/routeAnalyzer.js ADDED Viewed

@@ -0,0 +1,167 @@
+const isDevelopment = () => {
+    return typeof process !== 'undefined' && process.env?.NODE_ENV !== 'production';
+};
+const defaultConfig = {
+    routeLoadThreshold: 1000,
+    debounceMs: 2000,
+};
+class RouteAnalyzer {
+    routeMetrics = new Map();
+    lastWarning = new Map();
+    navigationStartTime = null;
+    hydrationStartTime = null;
+    config;
+    constructor(config = {}) {
+        this.config = {
+            routeLoadThreshold: config.routeLoadThreshold ?? defaultConfig.routeLoadThreshold,
+            debounceMs: config.debounceMs ?? defaultConfig.debounceMs,
+        };
+        if (isDevelopment() && typeof window !== 'undefined') {
+            this.setupListeners();
+        }
+    }
+    setupListeners() {
+        if (typeof window === 'undefined')
+            return;
+        window.addEventListener('load', () => {
+            this.measureRouteLoad();
+        });
+        if (typeof document !== 'undefined') {
+            document.addEventListener('DOMContentLoaded', () => {
+                this.hydrationStartTime = performance.now();
+            });
+        }
+        if (typeof window !== 'undefined' && window.next?.router) {
+            const router = window.next.router;
+            const originalPush = router.push;
+            const originalReplace = router.replace;
+            router.push = (...args) => {
+                this.navigationStartTime = performance.now();
+                return originalPush.apply(router, args);
+            };
+            router.replace = (...args) => {
+                this.navigationStartTime = performance.now();
+                return originalReplace.apply(router, args);
+            };
+        }
+    }
+    shouldWarn(route) {
+        if (!isDevelopment())
+            return false;
+        const now = Date.now();
+        const lastWarnTime = this.lastWarning.get(route) ?? 0;
+        return now - lastWarnTime > this.config.debounceMs;
+    }
+    getCurrentRoute() {
+        if (typeof window === 'undefined') {
+            return '/';
+        }
+        try {
+            return window.location.pathname;
+        }
+        catch {
+            return '/';
+        }
+    }
+    measureRouteLoad() {
+        if (!isDevelopment() || typeof window === 'undefined') {
+            return;
+        }
+        const route = this.getCurrentRoute();
+        try {
+            const navigation = performance.getEntriesByType('navigation')[0];
+            const loadTime = navigation ? navigation.loadEventEnd - navigation.fetchStart : 0;
+            let hydrationTime;
+            if (this.hydrationStartTime) {
+                hydrationTime = performance.now() - this.hydrationStartTime;
+            }
+            const metrics = {
+                route,
+                loadTime: Math.round(loadTime),
+                hydrationTime: hydrationTime ? Math.round(hydrationTime) : undefined,
+            };
+            this.routeMetrics.set(route, metrics);
+            if (loadTime > this.config.routeLoadThreshold) {
+                if (this.shouldWarn(route)) {
+                    this.warn(metrics);
+                    this.lastWarning.set(route, Date.now());
+                }
+            }
+        }
+        catch (error) {
+            if (isDevelopment()) {
+                console.debug('[Next Perf Guard] Route load measurement failed:', error);
+            }
+        }
+    }
+    measureNavigation() {
+        if (!isDevelopment() || typeof window === 'undefined') {
+            return;
+        }
+        if (this.navigationStartTime === null) {
+            return;
+        }
+        const route = this.getCurrentRoute();
+        const navigationTime = performance.now() - this.navigationStartTime;
+        const existing = this.routeMetrics.get(route);
+        const metrics = {
+            route,
+            loadTime: existing?.loadTime ?? 0,
+            hydrationTime: existing?.hydrationTime,
+            navigationTime: Math.round(navigationTime),
+        };
+        this.routeMetrics.set(route, metrics);
+        this.navigationStartTime = null;
+        if (navigationTime > this.config.routeLoadThreshold) {
+            if (this.shouldWarn(route)) {
+                this.warn(metrics);
+                this.lastWarning.set(route, Date.now());
+            }
+        }
+    }
+    warn(metrics) {
+        const parts = [];
+        parts.push(`⚠️ [Next Perf Guard] Slow route detected: ${metrics.route}`);
+        if (metrics.loadTime > this.config.routeLoadThreshold) {
+            parts.push(`(load: ${(metrics.loadTime / 1000).toFixed(1)}s)`);
+        }
+        if (metrics.hydrationTime && metrics.hydrationTime > 500) {
+            parts.push(`(hydration: ${(metrics.hydrationTime / 1000).toFixed(1)}s)`);
+        }
+        if (metrics.navigationTime && metrics.navigationTime > this.config.routeLoadThreshold) {
+            parts.push(`(navigation: ${(metrics.navigationTime / 1000).toFixed(1)}s)`);
+        }
+        console.warn(parts.join(' '));
+    }
+    getMetrics(route) {
+        if (route) {
+            return this.routeMetrics.get(route) ?? { route, loadTime: 0 };
+        }
+        return new Map(this.routeMetrics);
+    }
+    reset() {
+        this.routeMetrics.clear();
+        this.lastWarning.clear();
+        this.navigationStartTime = null;
+        this.hydrationStartTime = null;
+    }
+}
+let globalRouteAnalyzer = null;
+export function analyzeRoutes(config) {
+    if (!isDevelopment()) {
+        return {
+            getMetrics: () => new Map(),
+            reset: () => { },
+            measureNavigation: () => { },
+        };
+    }
+    if (!globalRouteAnalyzer) {
+        globalRouteAnalyzer = new RouteAnalyzer(config);
+    }
+    return globalRouteAnalyzer;
+}
+export function resetRouteAnalyzer() {
+    if (globalRouteAnalyzer) {
+        globalRouteAnalyzer.reset();
+    }
+}

package/dist/types.d.ts ADDED Viewed

@@ -0,0 +1,31 @@
+export interface PerformanceGuardConfig {
+    enabled?: boolean;
+    componentThreshold?: number;
+    bundleThresholdKB?: number;
+    routeLoadThreshold?: number;
+    debounceMs?: number;
+}
+export interface ComponentMetrics {
+    name: string;
+    renderTime: number;
+    renderCount: number;
+    fileSize?: number;
+}
+export interface BundleMetrics {
+    route: string;
+    sizeKB: number;
+    thresholdKB: number;
+}
+export interface RouteMetrics {
+    route: string;
+    loadTime: number;
+    hydrationTime?: number;
+    navigationTime?: number;
+}
+export interface WarningOptions {
+    component?: ComponentMetrics;
+    bundle?: BundleMetrics;
+    route?: RouteMetrics;
+}
+export type WarningType = 'component' | 'bundle' | 'route';
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map ADDED Viewed

@@ -0,0 +1 @@

+ {"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,sBAAsB;IACrC,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,aAAa;IAC5B,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;IACjB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,cAAc;IAC7B,SAAS,CAAC,EAAE,gBAAgB,CAAC;IAC7B,MAAM,CAAC,EAAE,aAAa,CAAC;IACvB,KAAK,CAAC,EAAE,YAAY,CAAC;CACtB;AAED,MAAM,MAAM,WAAW,GAAG,WAAW,GAAG,QAAQ,GAAG,OAAO,CAAC"}

package/dist/types.js ADDED Viewed

	@@ -0,0 +1 @@
1	+ export {};

package/package.json ADDED Viewed

@@ -0,0 +1,53 @@
+{
+  "name": "nextjs-performance-guard",
+  "version": "1.0.0",
+  "description": "A Next.js developer performance guard that detects heavy components, large bundles, and slow routes in development",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "nextjs",
+    "next.js",
+    "performance",
+    "monitoring",
+    "development",
+    "bundle-size",
+    "react",
+    "performance-guard"
+  ],
+  "author": "",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/your-username/nextjs-performance-guard.git"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "peerDependencies": {
+    "next": ">=13.0.0",
+    "react": ">=18.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "@types/react": "^18.0.0",
+    "typescript": "^5.0.0"
+  }
+}