NextJS Cursor Helper

A Next.js plugin that automatically adds cursor buttons to React components in development mode, enabling seamless IDE integration and faster development workflow.

Features

• 🚀 Automatic Integration: Automatically wraps React components with cursor buttons
• 🎯 Smart Detection: Only processes components in specified directories
• 🔧 Zero Configuration: Works out of the box with sensible defaults
• 🏎️ Development Only: Only active in development mode, no production overhead
• 🎨 Non-intrusive: Uses absolute positioning to avoid layout disruption
• ⚡ Hydration Safe: No SSR/client hydration mismatches
• 📱 TypeScript Support: Full TypeScript definitions included

Installation

npm install nextjs-cursor-helper --save-dev
# or
yarn add nextjs-cursor-helper --dev
# or
pnpm add nextjs-cursor-helper --save-dev

Quick Start

1. Configure Next.js

Add the plugin to your next.config.js:

const withCursorHelper = require('nextjs-cursor-helper');

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

module.exports = withCursorHelper()(nextConfig);

2. That's it!

All React components in your src/components directory will automatically get cursor buttons in development mode.

Configuration

You can customize the plugin behavior:

const withCursorHelper = require('nextjs-cursor-helper');

const nextConfig = {
  // your existing config
};

module.exports = withCursorHelper({
  componentPaths: ['src/components', 'components', 'src/ui'], // directories to scan
  projectRoot: process.cwd(), // project root directory
  importPath: 'nextjs-cursor-helper/withCursorButton', // import path for the HOC
  enabled: process.env.NODE_ENV === 'development' // enable/disable
})(nextConfig);

Configuration Options

| Option | Type | Default | Description | |--------|------|---------|-------------| | componentPaths | string[] | ['src/components'] | Directories to scan for React components | | projectRoot | string | process.cwd() | Root directory of your project | | importPath | string | 'nextjs-cursor-helper/withCursorButton' | Import path for the withCursorButton HOC | | enabled | boolean | process.env.NODE_ENV === 'development' | Enable/disable the plugin |

Manual Usage

You can also manually wrap components:

import { withCursorButton } from 'nextjs-cursor-helper';

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

export default withCursorButton(MyComponent, 'src/components/MyComponent.tsx');

How It Works

1. Webpack Loader: The plugin uses a custom webpack loader to transform your React components at build time
2. Automatic Detection: It scans specified directories for .tsx and .jsx files
3. Smart Wrapping: Only wraps components that export a default React component
4. Development Only: The cursor buttons only appear in development mode
5. Hydration Safe: Uses client-side state to prevent SSR/hydration mismatches

Example

Before (your original component):

// src/components/Button.tsx
import React from 'react';

const Button = ({ children, onClick }) => {
  return (
    <button onClick={onClick}>
      {children}
    </button>
  );
};

export default Button;

After (automatically transformed):

// src/components/Button.tsx (transformed by the plugin)
import React from 'react';
import { withCursorButton } from 'nextjs-cursor-helper/withCursorButton';

const Button = ({ children, onClick }) => {
  return (
    <button onClick={onClick}>
      {children}
    </button>
  );
};

export default withCursorButton(Button, 'src/components/Button.tsx', { projectRoot: '/path/to/project' });

Troubleshooting

Components not getting wrapped

1. Check that your components are in the specified componentPaths
2. Ensure your components export a default export with a capitalized name
3. Verify you're in development mode (NODE_ENV=development)

Hydration errors

The plugin is designed to prevent hydration errors, but if you encounter any:

1. Make sure you're using the latest version
2. Check that the 'use client' directive is present in the withCursorButton module
3. File an issue with details about your setup

Cursor not opening files

1. Ensure you have Cursor IDE installed
2. Check that the file paths are correct
3. Verify your browser allows cursor:// protocol links

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

MIT

Changelog

1.0.0

• Initial release
• Automatic component wrapping
• TypeScript support
• Hydration-safe implementation