next-meta-debug

v1.0.0

Published

5 months ago

A development-only package for debugging Next.js page metadata in the browser console

Downloads

0High
0Medium
0Low

srdarkseer

nextjs next.js metadata seo debug development react typescript pages-router app-router

next-meta-debug

A development-only package for debugging Next.js page metadata in the browser console and with a visual interface.

Features

🔍 Console Logging: Logs all page metadata to the browser console with organized, grouped output
🎨 Visual Debugger: Beautiful Tailwind CSS-styled floating debug panel with tabbed interface
🪝 React Hook: useMetaDebug hook for programmatic access to metadata
📱 Comprehensive Coverage: Extracts meta tags, Open Graph, Twitter Cards, structured data, links, and scripts
🌙 Dark Mode Support: Built-in dark mode support for the visual debugger
📋 Copy to Clipboard: One-click copy of all metadata as JSON
🚀 Zero Dependencies: No external APIs or services required
🔧 Cross-Version Compatible: Works with Next.js 12+ and both Pages Router & App Router

Installation

npm install next-meta-debug
# or
yarn add next-meta-debug
# or
pnpm add next-meta-debug

Quick Start

1. Visual Debugger Component

Add the debug component to your layout or page:

import { MetaDebugComponent } from "next-meta-debug";

export default function Layout({ children }) {
  return (
    <html>
      <body>
        {children}
        {/* Only show in development */}
        {process.env.NODE_ENV === "development" && <MetaDebugComponent />}
      </body>
    </html>
  );
}

2. Console Logging

For console-only debugging:

import { extractPageMetadata, formatMetadataForConsole } from "next-meta-debug";

// In your component
useEffect(() => {
  if (typeof window !== "undefined") {
    const metadata = extractPageMetadata();
    formatMetadataForConsole(metadata);
  }
}, []);

3. React Hook

For programmatic access:

import { useMetaDebug } from "next-meta-debug";

function MyComponent() {
  const { metadata, title, description, logMetadata, toggleDebug } =
    useMetaDebug();

  return (
    <div>
      <h1>{title}</h1>
      <p>{description}</p>
      <button onClick={() => logMetadata()}>Log to Console</button>
      <button onClick={() => toggleDebug()}>Toggle Debug</button>
    </div>
  );
}

API Reference

MetaDebugComponent

A floating debug panel component with tabbed interface.

<MetaDebugComponent
  options={{
    enabled: true,
    logLevel: "info",
    includeStructuredData: true,
    includeScripts: true,
    includeLinks: true,
    groupByType: true,
    showTimestamp: true,
  }}
  showVisualDebugger={true}
  className="custom-class"
/>

Props:

options: DebugOptions configuration
showVisualDebugger: Whether to show the visual debugger (default: true)
className: Additional CSS classes

useMetaDebug Hook

Returns metadata and debug functions.

const {
  metadata, // Full metadata object
  isEnabled, // Whether debugging is enabled
  extractMetadata, // Function to extract metadata
  logMetadata, // Function to log to console
  toggleDebug, // Function to toggle debug state

  // Convenience properties
  title,
  description,
  keywords,
  author,
  robots,
  canonical,
  viewport,
  metaTags,
  openGraphTags,
  twitterTags,
  linkTags,
  scriptTags,
  structuredData,
} = useMetaDebug(options);

Utility Functions

extractPageMetadata()

Extracts all metadata from the current page DOM.

import { extractPageMetadata } from "next-meta-debug";

const metadata = extractPageMetadata();

formatMetadataForConsole(metadata, options)

Formats and logs metadata to the console with organized output.

import { formatMetadataForConsole } from "next-meta-debug";

formatMetadataForConsole(metadata, {
  groupByType: true,
  showTimestamp: true,
});

Metadata Types

The package extracts the following types of metadata:

Page Information: Title, description, keywords, author, robots, canonical URL, viewport
Meta Tags: All <meta> tags with name, property, http-equiv, and charset attributes
Open Graph Tags: All og:* properties for social media sharing
Twitter Card Tags: All twitter:* properties for Twitter sharing
Link Tags: All <link> tags including stylesheets, icons, and canonical URLs
Script Tags: All <script> tags with source URLs and inline content
Structured Data: JSON-LD structured data for SEO

Debug Options

interface DebugOptions {
  enabled?: boolean; // Enable/disable debugging
  logLevel?: "info" | "warn" | "error" | "debug"; // Console log level
  includeStructuredData?: boolean; // Include structured data in output
  includeScripts?: boolean; // Include script tags in output
  includeLinks?: boolean; // Include link tags in output
  groupByType?: boolean; // Group console output by metadata type
  showTimestamp?: boolean; // Show timestamp in console output
}

Visual Debugger Features

The visual debugger provides:

Floating Button: Fixed position debug button that expands into a panel
Tabbed Interface: Organized tabs for different metadata types
Responsive Design: Adapts to different screen sizes
Dark Mode: Automatic dark mode support
Copy to Clipboard: Export metadata as JSON
Console Integration: Direct console logging from the UI

Development vs Production

This package is designed for development use only. In production builds, the components and functions will still work but should be conditionally rendered:

{
  process.env.NODE_ENV === "development" && <MetaDebugComponent />;
}

Examples

Next.js App Router

// app/layout.tsx
import { MetaDebugComponent } from "next-meta-debug";

export default function RootLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <html lang="en">
      <body>
        {children}
        {process.env.NODE_ENV === "development" && <MetaDebugComponent />}
      </body>
    </html>
  );
}

Next.js Pages Router

// pages/_app.tsx
import { MetaDebugComponent } from "next-meta-debug";

function MyApp({ Component, pageProps }) {
  return (
    <>
      <Component {...pageProps} />
      {process.env.NODE_ENV === "development" && <MetaDebugComponent />}
    </>
  );
}

export default MyApp;

Custom Debug Component

import { useMetaDebug } from "next-meta-debug";

function CustomDebugPanel() {
  const { metadata, logMetadata } = useMetaDebug({
    enabled: true,
    groupByType: true,
  });

  if (!metadata) return null;

  return (
    <div className="fixed top-4 right-4 bg-white p-4 rounded shadow-lg">
      <h3 className="font-bold mb-2">Page Metadata</h3>
      <div className="text-sm space-y-1">
        <div>
          <strong>Title:</strong> {metadata.title}
        </div>
        <div>
          <strong>Description:</strong> {metadata.description}
        </div>
        <div>
          <strong>Meta Tags:</strong> {metadata.meta.length}
        </div>
      </div>
      <button
        onClick={logMetadata}
        className="mt-2 px-3 py-1 bg-blue-500 text-white rounded text-xs"
      >
        Log to Console
      </button>
    </div>
  );
}

Compatibility

This package is designed to work with:

Next.js: 12.0.0 and above
React: 17.0.0 and above
React DOM: 17.0.0 and above
Node.js: 16.0.0 and above
Routing Systems: Both Pages Router and App Router
Browsers: Modern browsers with ES2017+ support

Contributing

Fork the repository
Create your feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add some amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Author

Sushant R. Dangal - @srdarkseer

GitHub: srdarkseer
LinkedIn: srdarkseer
Twitter: @srdarkseer

Support

If you have any questions or need help, please open an issue on GitHub.

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

next-meta-debug

Features

Installation

Quick Start

1. Visual Debugger Component

2. Console Logging

3. React Hook

API Reference

MetaDebugComponent

useMetaDebug Hook

Utility Functions

extractPageMetadata()

formatMetadataForConsole(metadata, options)

Metadata Types

Debug Options

Visual Debugger Features

Development vs Production

Examples

Next.js App Router

Next.js Pages Router

Custom Debug Component

Compatibility

Contributing

License

Author

Support