viewport-debugger-ui

v1.0.2

Published

a year ago

A lightweight utility for debugging viewport sizes and media queries in the browser console

0High
0Medium
0Low

development-yam

viewport debug tailwind media-queries responsive nextjs next statamic

npm install viewport-debugger-ui


## Basic Usage

```typescript
import { createViewportDebugger } from 'viewport-debugger-ui';

// Create a debugger instance with default options
const debugger = createViewportDebugger();

// Enable debugging (shows overlay)
debugger.enable();

// Disable debugging when done
debugger.disable();

Configuration

You can customize the debugger behavior by passing options:

const debugger = createViewportDebugger({
  updateInterval: 500,        // Update frequency in milliseconds (default: 1000)
  showMediaQueries: true,     // Show active media queries (default: true)
  compactMode: false          // Start in compact mode (default: false)
});

API Reference

`createViewportDebugger(options?)`

Creates a new viewport debugger instance.

Options

| Option | Type | Default | Description | |--------|------|---------|-------------| | updateInterval | number | 1000 | Frequency of viewport updates in milliseconds | | showMediaQueries | boolean | true | Whether to display active media queries | | compactMode | boolean | false | Enable compact display mode |

`ViewportDebugger` Methods

| Method | Description | |--------|-------------| | enable() | Starts the debugger and shows the overlay | | disable() | Stops the debugger and removes the overlay | | toggleCompactMode() | Toggles between compact and full display modes |

React Integration Example

import { useEffect, useState } from 'react';
import { createViewportDebugger, type ViewportDebugger } from 'viewport-debugger-ui';

function App() {
  const [debugger, setDebugger] = useState<ViewportDebugger | null>(null);

  useEffect(() => {
    const instance = createViewportDebugger({
      updateInterval: 500,
      showMediaQueries: true
    });

    setDebugger(instance);
    instance.enable();

    return () => instance.disable();
  }, []);

  return (
    <div>
      <h1>Your App Content</h1>
    </div>
  );
}

Next.js Integration Example

Here's how to integrate the viewport debugger with Next.js:

For Next.js App Router

// app/viewport-debugger.tsx
'use client'

import { useEffect } from 'react'
import { createViewportDebugger } from 'viewport-debugger-ui'

export function ViewportDebugger() {
  useEffect(() => {
    // Only run in development environment and browser
    if (process.env.NODE_ENV === 'development' && typeof window !== 'undefined') {
      const debugger = createViewportDebugger({
        updateInterval: 500,
        showMediaQueries: true
      })
      debugger.enable()
      
      return () => debugger.disable()
    }
  }, [])
  
  // This component doesn't render anything
  return null
}

Then import it in your root layout:

// app/layout.tsx
import { ViewportDebugger } from './viewport-debugger'

export default function RootLayout({
  children,
}: {
  children: React.ReactNode
}) {
  return (
    <html lang="en">
      <body>
        {children}
        <ViewportDebugger />
      </body>
    </html>
  )
}

For Next.js Pages Router

// components/ViewportDebugger.tsx
import { useEffect } from 'react'
import { createViewportDebugger } from 'viewport-debugger-ui'

export function ViewportDebugger() {
  useEffect(() => {
    // Only run in development environment and browser
    if (process.env.NODE_ENV === 'development' && typeof window !== 'undefined') {
      const debugger = createViewportDebugger({
        updateInterval: 500,
        showMediaQueries: true
      })
      debugger.enable()
      
      return () => debugger.disable()
    }
  }, [])
  
  // This component doesn't render anything
  return null
}

Then import it in your _app.tsx:

// pages/_app.tsx
import type { AppProps } from 'next/app'
import { ViewportDebugger } from '../components/ViewportDebugger'

export default function App({ Component, pageProps }: AppProps) {
  return (
    <>
      <Component {...pageProps} />
      <ViewportDebugger />
    </>
  )
}

Statamic Integration Example

Here's how to integrate the viewport debugger with Statamic:

First, install the package in your Statamic project:

npm install viewport-debugger-ui

Create a new JavaScript file (e.g., resources/js/viewport-debug.js):

import { createViewportDebugger } from 'viewport-debugger-ui';

// Only enable in development environment
if (process.env.NODE_ENV === 'development') {
  const debugger = createViewportDebugger({
    updateInterval: 500,
    showMediaQueries: true
  });
  debugger.enable();
}

Add it to your Vite configuration (vite.config.js):

export default defineConfig({
  build: {
    input: [
      'resources/js/site.js',
      'resources/js/viewport-debug.js', // Add this line
      'resources/css/site.css',
    ],
  }
});

Import it in your Antlers layout file (resources/views/layout.antlers.html):

<!DOCTYPE html>
<html lang="{{ site:short_locale }}">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>{{ title ?? site:name }}</title>
    {{ vite src="resources/js/viewport-debug.js" }} <!-- Add this line -->
</head>
<body>
    {{ template_content }}
    {{ vite src="resources/js/site.js" }}
</body>
</html>

This setup will automatically enable the viewport debugger in development mode while keeping it disabled in production. The debugger overlay will appear in the top-right corner of your Statamic site, showing viewport dimensions and active media queries.

You can also conditionally enable it based on Statamic's environment variables:

if ({{ environment }} === 'local') {
    const debugger = createViewportDebugger();
    debugger.enable();
}

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme