nextjs-ide-helper

v1.5.4

Published

19 days ago

A Next.js plugin that automatically adds IDE buttons to React components for seamless IDE integration. Supports Cursor, VS Code, WebStorm, and Atom.

0High
0Medium
0Low

yanneman

nextjs react cursor vscode webstorm atom ide development webpack turbopack plugin components

NextJS IDE Helper

A Next.js plugin that automatically adds IDE buttons to React components in development mode, enabling seamless IDE integration and faster development workflow. Supports Cursor, VS Code, WebStorm, and Atom.

Features

🚀 Automatic Integration: Automatically wraps React components with IDE buttons
🎯 Smart Detection: Only processes components in specified directories
🔧 Zero Configuration: Works out of the box with sensible defaults (Cursor as default IDE)
🏎️ Development Only: Only active in development mode, no production overhead
🎨 Non-intrusive: Minimal blue dot indicators that don't disrupt your layout
👁️ Toggle Visibility: Floating button to show/hide all IDE dots instantly
⚡ Hydration Safe: No SSR/client hydration mismatches
📱 TypeScript Support: Full TypeScript definitions included
🔌 Multi-IDE Support: Supports Cursor, VS Code, WebStorm, and Atom
🎭 Multiple Component Patterns: Supports all React component export patterns
🔍 AST-Based Processing: Uses robust Abstract Syntax Tree parsing for accurate code transformation

Installation

npm install nextjs-ide-helper

Quick Start

1. Configure Next.js

Add the plugin to your next.config.js:

const withIdeHelper = require('nextjs-ide-helper');

/** @type {import('next').NextConfig} */
const nextConfig = {
  // your existing config
};

module.exports = withIdeHelper()(nextConfig);

2. That's it!

All React components in your src/components directory will automatically get IDE buttons in development mode (defaults to Cursor IDE).

User Interface

IDE Indicator Dots

Each wrapped component displays a small blue dot (10x10px) in the top-right corner:

Click the dot to open the component's source file in your IDE
Hover to see the file path tooltip
The dots are subtle (60% opacity) and brighten on hover

Toggle Button

A floating toggle button appears in the bottom-right corner of your page:

Blue = IDE dots are visible
Gray = IDE dots are hidden
Click to toggle all dots on/off instantly

This lets you quickly hide the dots when you want an unobstructed view of your app, then bring them back when needed.

Configuration

You can customize the plugin behavior:

const withIdeHelper = require('nextjs-ide-helper');

const nextConfig = {
  // your existing config
};

module.exports = withIdeHelper({
  componentPaths: ['src/components', 'components', 'src/ui'], // directories to scan (supports glob patterns)
  projectRoot: process.cwd(), // project root directory
  importPath: 'nextjs-ide-helper/withIdeButton', // import path for the HOC
  enabled: process.env.NODE_ENV === 'development', // enable/disable
  ideType: 'cursor' // IDE to use: 'cursor', 'vscode', 'webstorm', 'atom'
})(nextConfig);

Configuration Options

| Option | Type | Default | Description | |--------|------|---------|-------------| | componentPaths | string[] | ['src/components'] | Directories to scan for React components (supports glob patterns) | | projectRoot | string | process.cwd() | Root directory of your project | | importPath | string | 'nextjs-ide-helper/withIdeButton' | Import path for the withIdeButton HOC | | enabled | boolean | process.env.NODE_ENV === 'development' | Enable/disable the plugin | | ideType | 'cursor' \| 'vscode' \| 'webstorm' \| 'atom' | 'cursor' | IDE to open files in |

Glob Pattern Support

The componentPaths option supports glob patterns for matching nested directory structures:

module.exports = withIdeHelper({
  componentPaths: [
    'src/components/**',           // matches all nested directories under src/components
    '**/components/**',           // matches components directories anywhere in the project
    'app/**/ui/**',               // matches ui directories nested anywhere under app
    'modules/*/components/**'     // matches components in any module subdirectory
  ]
})(nextConfig);

Glob Pattern Examples:

* - matches any characters within a single directory level
** - matches any number of directories and subdirectories recursively
src/components/* - matches src/components/Button.tsx but not src/components/ui/Button.tsx
src/components/** - matches both src/components/Button.tsx and src/components/ui/forms/Button.tsx
**/components/** - matches app/components/Button.tsx, modules/feature/components/deep/Widget.tsx, etc.

Manual Usage

You can also manually wrap components:

import { withIdeButton } from 'nextjs-ide-helper';

const MyComponent = () => {
  return <div>Hello World</div>;
};

// Default (Cursor)
export default withIdeButton(MyComponent, 'src/components/MyComponent.tsx');

// With specific IDE
export default withIdeButton(MyComponent, 'src/components/MyComponent.tsx', {
  ideType: 'vscode'
});

Supported Component Patterns

The plugin automatically detects and wraps all types of React component export patterns:

Named Export Components

// Named arrow function exports
export const Button = () => <button>Click me</button>;
export const Modal = () => <div>Modal content</div>;

// Named function exports
export function MyButton() {
  return <button>Function Button</button>;
}

export function MyModal() {
  return <div>Function Modal</div>;
}

// Mixed named and default exports
export const HeaderButton = () => <button>Header</button>;

const MainComponent = () => <div>Main</div>;
export default MainComponent;

// TypeScript named exports
interface ButtonProps {
  onClick: () => void;
}

export const TypedButton = ({ onClick }: ButtonProps) => (
  <button onClick={onClick}>Typed Button</button>
);

Default Export Components

Named Components

// Standard pattern
const MyComponent = () => <div>Hello</div>;
export default MyComponent;

// Variable declaration
const MyComponent = function() {
  return <div>Hello</div>;
};
export default MyComponent;

Direct Export Function Components

// Named function
export default function MyComponent() {
  return <div>Hello</div>;
}

// Anonymous function
export default function() {
  return <div>Hello</div>;
}

Arrow Function Components

// Anonymous arrow function
export default () => {
  return <div>Hello</div>;
};

// Arrow function with parameters
export default (props) => {
  return <div>Hello {props.name}</div>;
};

Class Components

// Named class
export default class MyComponent extends React.Component {
  render() {
    return <div>Hello</div>;
  }
}

// TypeScript class
export default class MyComponent extends Component<Props> {
  render() {
    return <div>Hello</div>;
  }
}

TypeScript Components

// Function with TypeScript
interface Props {
  title: string;
}

export default function MyComponent(props: Props) {
  return <div>{props.title}</div>;
}

// Arrow function with TypeScript
export default (props: Props) => {
  return <div>{props.title}</div>;
};

How It Works

AST-Based Processing: Uses Babel's Abstract Syntax Tree parser for robust code analysis
Webpack Loader: The plugin uses a custom webpack loader to transform your React components at build time
Automatic Detection: It scans specified directories for .tsx and .jsx files
Smart Wrapping: Only wraps components that export a default React component (PascalCase names)
Development Only: The IDE buttons only appear in development mode
Hydration Safe: Uses client-side state to prevent SSR/hydration mismatches