JSPM

  • ESM via JSPM
  • ES Module Entrypoint
  • Export Map
  • Keywords
  • License
  • Repository URL
  • TypeScript Types
  • README
  • Created
  • Published
  • Downloads 82
  • Score
    100M100P100Q70447F
  • License MIT

FixDog - In-browser IDE to fix your frontend

Package Exports

  • fixdog
  • fixdog/client
  • fixdog/init
  • fixdog/package.json

Readme

uidog-sdk-next

Next.js integration for UiDog using Bippy - element source detection for React apps.

This package provides Alt+click element inspection for Next.js applications, allowing you to click on any element in your app and see its source location (file, line, column) in a sidebar UI.

Features

  • Alt+click any element to inspect its source location
  • Hover highlighting when Alt is pressed
  • Sidebar UI for viewing element info and making edit requests
  • Supports VS Code, Cursor, WebStorm, Atom, Sublime editors
  • Works with Next.js 14+ (App Router and Pages Router)
  • Zero build configuration - just import and use

Requirements

  • Next.js 14.0.0 or higher
  • React 17.0.0 or higher
  • Development mode only (_debugSource is stripped in production)

Installation

npm install uidog-sdk-next
# or
yarn add uidog-sdk-next
# or
pnpm add uidog-sdk-next

Quick Start

Step 1: Create the instrumentation file

Bippy must load before React to properly hook into React's internals. The setup differs based on your Next.js version.

Create instrumentation-client.ts in your project root (same level as package.json):

// instrumentation-client.ts
import "uidog-sdk-next/client";

That's it! The package will auto-initialize with default settings.

Next.js 14.x - 15.2

For older Next.js versions, add the import at the very top of your _app.tsx or root layout:

Pages Router (pages/_app.tsx):

// pages/_app.tsx
import "uidog-sdk-next/client"; // MUST be the first import!

import type { AppProps } from "next/app";

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

App Router (app/layout.tsx):

// app/layout.tsx
import "uidog-sdk-next/client"; // MUST be the first import!

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

Step 2: Start your development server

npm run dev

Step 3: Use it!

  1. Hold Alt (Option on Mac) and hover over elements - you'll see a blue highlight
  2. Alt+click on any element to open the sidebar
  3. The sidebar shows the element's source location (file, line, column)
  4. Type a message describing changes you want to make

Configuration

Using UiDogProvider (Optional)

For more control over configuration, wrap your app with UiDogProvider:

// app/layout.tsx (App Router)
import "uidog-sdk-next/client"; // Still need this first!
import { UiDogProvider } from "uidog-sdk-next/init";

export default function RootLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <html lang="en">
      <body>
        <UiDogProvider
          editor="cursor" // Editor to open: 'vscode' | 'cursor' | 'webstorm' | 'atom' | 'sublime'
          modifier="alt" // Key modifier: 'alt' | 'ctrl' | 'meta' | 'shift'
          enableSidebar={true} // Show sidebar UI (set to false for console-only mode)
          apiEndpoint="https://api.ui.dog" // API endpoint for edit requests
        >
          {children}
        </UiDogProvider>
      </body>
    </html>
  );
}

Configuration Options

Option Type Default Description
editor string 'cursor' Editor to open. Options: 'vscode', 'vscode-insiders', 'cursor', 'webstorm', 'atom', 'sublime'
modifier string 'alt' Key to hold for element selection. Options: 'alt', 'ctrl', 'meta', 'shift'
enableSidebar boolean true Show the sidebar UI. If false, logs to console instead
apiEndpoint string 'https://api.ui.dog' API endpoint for edit session requests
projectPath string '' Project root path for resolving relative file paths

Programmatic Configuration

You can also configure before auto-initialization:

// instrumentation-client.ts
import { configureUiDogNext } from "uidog-sdk-next/client";

configureUiDogNext({
  editor: "vscode",
  modifier: "alt",
  enableSidebar: true,
});

Manual Initialization

If you need full control, disable auto-init and initialize manually:

// instrumentation-client.ts
import { disableAutoInit } from "uidog-sdk-next/client";
disableAutoInit();

// Later, in your app code:
import { initializeUiDogNext } from "uidog-sdk-next";

initializeUiDogNext({
  editor: "cursor",
  enableSidebar: true,
});

Complete Example: Next.js 15 App Router

Project Structure

my-next-app/
├── instrumentation-client.ts    # UiDog initialization
├── app/
│   ├── layout.tsx               # Root layout with UiDogProvider
│   ├── page.tsx                 # Home page
│   └── components/
│       └── Button.tsx           # Example component
├── package.json
└── next.config.js

Step-by-Step Setup

1. Install the package:

npm install uidog-sdk-next

2. Create instrumentation-client.ts in project root:

// instrumentation-client.ts
import "uidog-sdk-next/client";

3. Update app/layout.tsx:

// app/layout.tsx
import { UiDogProvider } from "uidog-sdk-next/init";
import "./globals.css";

export const metadata = {
  title: "My App",
};

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

4. Create a component to test (app/components/Button.tsx):

// app/components/Button.tsx
"use client";

interface ButtonProps {
  children: React.ReactNode;
  onClick?: () => void;
}

export function Button({ children, onClick }: ButtonProps) {
  return (
    <button
      onClick={onClick}
      className="px-4 py-2 bg-blue-500 text-white rounded hover:bg-blue-600"
    >
      {children}
    </button>
  );
}

5. Use the component (app/page.tsx):

// app/page.tsx
import { Button } from "./components/Button";

export default function Home() {
  return (
    <main className="p-8">
      <h1 className="text-2xl font-bold mb-4">My App</h1>
      <Button>Click me</Button>
    </main>
  );
}

6. Start the dev server:

npm run dev

7. Test it:

  • Open http://localhost:3000
  • Hold Alt and hover over the button - you'll see a blue highlight
  • Alt+click on the button
  • The sidebar opens showing Button.tsx with line and column numbers

Complete Example: Next.js 14 Pages Router

Project Structure

my-next-app/
├── pages/
│   ├── _app.tsx                 # App wrapper with UiDog
│   ├── index.tsx                # Home page
│   └── components/
│       └── Card.tsx             # Example component
├── package.json
└── next.config.js

Step-by-Step Setup

1. Install the package:

npm install uidog-sdk-next

2. Update pages/_app.tsx:

// pages/_app.tsx
import "uidog-sdk-next/client"; // MUST be first!

import type { AppProps } from "next/app";
import { UiDogProvider } from "uidog-sdk-next/init";
import "../styles/globals.css";

export default function App({ Component, pageProps }: AppProps) {
  return (
    <UiDogProvider editor="vscode">
      <Component {...pageProps} />
    </UiDogProvider>
  );
}

3. Create a component (pages/components/Card.tsx):

// pages/components/Card.tsx
interface CardProps {
  title: string;
  description: string;
}

export function Card({ title, description }: CardProps) {
  return (
    <div className="border rounded-lg p-4 shadow-sm">
      <h2 className="text-xl font-semibold">{title}</h2>
      <p className="text-gray-600 mt-2">{description}</p>
    </div>
  );
}

4. Use the component (pages/index.tsx):

// pages/index.tsx
import { Card } from "./components/Card";

export default function Home() {
  return (
    <div className="p-8">
      <h1 className="text-2xl font-bold mb-4">My App</h1>
      <Card
        title="Welcome"
        description="Alt+click on this card to see its source location!"
      />
    </div>
  );
}

5. Start and test:

npm run dev

Vite (React) quick start

  • Development only. Import before React mounts so Bippy can hook DevTools.
  • Add at the very top of your entry (e.g., src/main.tsx):
if (import.meta.env.DEV) {
  import("uidog-sdk-next/client");
}
  • Start Vite with npm run dev and use Alt+click. For library DOM (or anything without _debugSource), you'll see the DOM snapshot fallback instead of source mapping.

API Reference

Main Exports (uidog-sdk-next)

import {
  initializeUiDogNext, // Initialize UiDog manually
  cleanupUiDogNext, // Cleanup all listeners and UI
  isUiDogNextInitialized, // Check if initialized
  openSidebar, // Programmatically open sidebar
  closeSidebar, // Programmatically close sidebar
  buildEditorUrl, // Build editor URL from source location
} from "uidog-sdk-next";

Client Exports (uidog-sdk-next/client)

import {
  configureUiDogNext, // Configure options before auto-init
  disableAutoInit, // Disable auto-initialization
  initializeUiDogNext, // Manual initialization
} from "uidog-sdk-next/client";

Provider Export (uidog-sdk-next/init)

import { UiDogProvider } from "uidog-sdk-next/init";

Troubleshooting

"Could not find source for element"

This can happen when:

  1. Production mode: Source info (_debugSource) is stripped in production builds. Make sure you're running in development mode (npm run dev).

  2. Server Components: React Server Components render on the server and don't have fibers on the client. Only client components can be inspected.

  3. Library components: Components from node_modules are filtered out. You can only inspect your own source code.

When source isn't available (e.g., server-rendered DOM), the sidebar will show a DOM snapshot instead: trimmed outerHTML, text content, attributes, and bounding box. This gives you “something to grab,” but still no file/line info without a client boundary.

  1. Make sure you imported 'uidog-sdk-next/client' before any React imports
  2. Check the browser console for [UiDog Next] Initialized message
  3. Verify you're holding the correct modifier key (Alt by default)

Element highlighting doesn't work

  1. Check that enableSidebar is true (default)
  2. Try a different modifier key: modifier="ctrl" or modifier="meta"
  3. Some browser extensions may intercept Alt+click - try disabling them

Import order issues

The import must be first:

// CORRECT
import "uidog-sdk-next/client";
import { useState } from "react";

// WRONG - React loads before bippy can hook in
import { useState } from "react";
import "uidog-sdk-next/client";

How It Works

  1. Bippy hooks into React: When you import 'uidog-sdk-next/client', Bippy installs a hook at window.__REACT_DEVTOOLS_GLOBAL_HOOK__ before React loads.

  2. React reports fiber info: As React renders, it reports fiber tree data to the hook, including _debugSource metadata.

  3. Alt+click detection: When you Alt+click an element, we find its React fiber and extract the source location.

  4. Sidebar UI: The sidebar displays the source info and allows you to describe changes you want to make.

Limitations

  • Development only: _debugSource is stripped in production React builds
  • Client components only: Server Components don't have client-side fibers
  • React 17-19: Bippy supports these React versions
  • Next.js 14+: Older versions may work but are not tested

License

MIT

  • uidog-sdk - Original SDK for Vite/Webpack apps
  • Bippy - React fiber inspection toolkit
  • LocatorJS - Alternative approach using Babel transforms