nextjs-ide-helper 1.0.0

package/README.md

@@ -0,0 +1,167 @@
+# 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
+
+```bash
+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`:
+
+```javascript
+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:
+
+```javascript
+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:
+
+```tsx
+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):
+```tsx
+// src/components/Button.tsx
+import React from 'react';
+
+const Button = ({ children, onClick }) => {
+  return (
+    <button onClick={onClick}>
+      {children}
+    </button>
+  );
+};
+
+export default Button;
+```
+
+After (automatically transformed):
+```tsx
+// 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

package/lib/index.d.ts

@@ -0,0 +1,5 @@
+export { withCursorButton } from './withCursorButton';
+export type { WithCursorButtonOptions } from './withCursorButton';
+declare const withCursorHelper: any;
+export default withCursorHelper;
+export { withCursorHelper };

package/lib/index.js

@@ -0,0 +1,10 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.withCursorHelper = exports.withCursorButton = void 0;
+// Main exports
+var withCursorButton_1 = require("./withCursorButton");
+Object.defineProperty(exports, "withCursorButton", { enumerable: true, get: function () { return withCursorButton_1.withCursorButton; } });
+// Next.js plugin
+const withCursorHelper = require('./plugin');
+exports.withCursorHelper = withCursorHelper;
+exports.default = withCursorHelper;

package/lib/loader.js

@@ -0,0 +1,79 @@
+const path = require('path');
+
+/**
+ * Webpack loader that automatically wraps React components with cursor buttons
+ * @param {string} source - The source code of the file
+ * @returns {string} - The transformed source code
+ */
+module.exports = function cursorButtonLoader(source) {
+  const filename = this.resourcePath;
+  const options = this.getOptions() || {};
+  
+  const {
+    componentPaths = ['src/components'],
+    projectRoot = process.cwd(),
+    importPath = 'nextjs-cursor-helper',
+    enabled = process.env.NODE_ENV === 'development'
+  } = options;
+
+  // Only process if enabled
+  if (!enabled) {
+    return source;
+  }
+  
+  // Only process files in specified component directories
+  const shouldProcess = componentPaths.some(componentPath => 
+    filename.includes(path.resolve(projectRoot, componentPath))
+  );
+  
+  if (!shouldProcess || (!filename.endsWith('.tsx') && !filename.endsWith('.jsx'))) {
+    return source;
+  }
+
+  // Check if it's already wrapped
+  if (source.includes('withCursorButton')) {
+    return source;
+  }
+
+  // Check if it has a default export that looks like a React component
+  const defaultExportMatch = source.match(/export\s+default\s+(\w+)/);
+  if (!defaultExportMatch) {
+    return source;
+  }
+
+  const componentName = defaultExportMatch[1];
+  
+  // Check if component name starts with uppercase (React component convention)
+  if (!componentName || componentName[0] !== componentName[0].toUpperCase()) {
+    return source;
+  }
+
+  // Get relative path from project root
+  const relativePath = path.relative(projectRoot, filename);
+
+  // Find the last import to insert our import after it
+  const imports = source.match(/^import.*$/gm) || [];
+  
+  let modifiedSource;
+  
+  if (imports.length === 0) {
+    // No imports found, add at top
+    const importStatement = `import { withCursorButton } from '${importPath}';\n`;
+    const wrappedExport = `export default withCursorButton(${componentName}, '${relativePath}', { projectRoot: '${projectRoot}' });`;
+    modifiedSource = importStatement + source.replace(/export\s+default\s+\w+;?/, wrappedExport);
+  } else {
+    const lastImportIndex = source.lastIndexOf(imports[imports.length - 1]) + imports[imports.length - 1].length;
+    
+    // Add import statement
+    const importStatement = `\nimport { withCursorButton } from '${importPath}';`;
+    
+    // Replace the export
+    const wrappedExport = `export default withCursorButton(${componentName}, '${relativePath}', { projectRoot: '${projectRoot}' });`;
+    
+    modifiedSource = source.slice(0, lastImportIndex) + 
+                     importStatement + 
+                     source.slice(lastImportIndex).replace(/export\s+default\s+\w+;?/, wrappedExport);
+  }
+
+  return modifiedSource;
+};

package/lib/plugin.js

@@ -0,0 +1,61 @@
+const path = require('path');
+
+/**
+ * Configuration options for the NextJS Cursor Helper plugin
+ * @typedef {Object} CursorHelperOptions
+ * @property {string[]} [componentPaths=['src/components']] - Paths to scan for React components
+ * @property {string} [projectRoot=process.cwd()] - Root directory of the project
+ * @property {string} [importPath='nextjs-cursor-helper/withCursorButton'] - Import path for withCursorButton
+ * @property {boolean} [enabled=process.env.NODE_ENV === 'development'] - Enable/disable the plugin
+ */
+
+/**
+ * NextJS Cursor Helper plugin
+ * @param {CursorHelperOptions} options - Configuration options
+ * @returns {function} Next.js config modifier function
+ */
+function withCursorHelper(options = {}) {
+  const defaultOptions = {
+    componentPaths: ['src/components'],
+    projectRoot: process.cwd(),
+    importPath: 'nextjs-cursor-helper/withCursorButton',
+    enabled: process.env.NODE_ENV === 'development'
+  };
+
+  const config = { ...defaultOptions, ...options };
+
+  return (nextConfig = {}) => {
+    return {
+      ...nextConfig,
+      webpack: (webpackConfig, context) => {
+        const { dev, isServer } = context;
+
+        // Only apply in development and for client-side
+        if (config.enabled && dev && !isServer) {
+          const rule = {
+            test: /\.tsx?$/,
+            include: config.componentPaths.map(p => path.resolve(config.projectRoot, p)),
+            use: [
+              {
+                loader: require.resolve('./loader'),
+                options: config
+              }
+            ],
+            enforce: 'pre'
+          };
+
+          webpackConfig.module.rules.unshift(rule);
+        }
+
+        // Call the existing webpack function if it exists
+        if (typeof nextConfig.webpack === 'function') {
+          return nextConfig.webpack(webpackConfig, context);
+        }
+
+        return webpackConfig;
+      }
+    };
+  };
+}
+
+module.exports = withCursorHelper;

package/lib/withCursorButton.d.ts

@@ -0,0 +1,6 @@
+import React from 'react';
+export interface WithCursorButtonOptions {
+    projectRoot?: string;
+    enabled?: boolean;
+}
+export declare function withCursorButton<T extends object>(WrappedComponent: React.ComponentType<T>, filePath: string, options?: WithCursorButtonOptions): React.FC<T>;

package/lib/withCursorButton.js

@@ -0,0 +1,44 @@
+"use strict";
+'use client';
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.withCursorButton = withCursorButton;
+const jsx_runtime_1 = require("react/jsx-runtime");
+const react_1 = require("react");
+const CursorButton = ({ filePath, projectRoot }) => {
+    const handleClick = () => {
+        const fullPath = projectRoot ? `${projectRoot}/${filePath}` : filePath;
+        window.open(`cursor://file${fullPath}`, '_blank');
+    };
+    return ((0, jsx_runtime_1.jsx)("button", { onClick: handleClick, style: {
+            position: 'absolute',
+            top: '8px',
+            right: '8px',
+            background: '#007acc',
+            color: 'white',
+            border: 'none',
+            borderRadius: '4px',
+            padding: '4px 8px',
+            fontSize: '12px',
+            cursor: 'pointer',
+            zIndex: 1000,
+            opacity: 0.7,
+            transition: 'opacity 0.2s',
+            fontFamily: 'monospace'
+        }, onMouseEnter: (e) => (e.currentTarget.style.opacity = '1'), onMouseLeave: (e) => (e.currentTarget.style.opacity = '0.7'), title: `Open ${filePath} in Cursor`, children: "\uD83D\uDCDD" }));
+};
+function withCursorButton(WrappedComponent, filePath, options = {}) {
+    const { projectRoot, enabled = process.env.NODE_ENV === 'development' } = options;
+    const WithCursorButtonComponent = (props) => {
+        const [isClient, setIsClient] = (0, react_1.useState)(false);
+        (0, react_1.useEffect)(() => {
+            setIsClient(true);
+        }, []);
+        // In production or when disabled, just return the component without wrapper
+        if (!enabled || !isClient) {
+            return (0, jsx_runtime_1.jsx)(WrappedComponent, { ...props });
+        }
+        return ((0, jsx_runtime_1.jsxs)("div", { style: { position: 'relative' }, children: [(0, jsx_runtime_1.jsx)(CursorButton, { filePath: filePath, projectRoot: projectRoot }), (0, jsx_runtime_1.jsx)(WrappedComponent, { ...props })] }));
+    };
+    WithCursorButtonComponent.displayName = `withCursorButton(${WrappedComponent.displayName || WrappedComponent.name})`;
+    return WithCursorButtonComponent;
+}

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "nextjs-ide-helper",
+  "version": "1.0.0",
+  "description": "A Next.js plugin that automatically adds cursor buttons to React components for seamless IDE integration",
+  "main": "lib/index.js",
+  "types": "lib/index.d.ts",
+  "files": [
+    "lib",
+    "src"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "prepare": "npm run build",
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "keywords": [
+    "nextjs",
+    "react",
+    "cursor",
+    "ide",
+    "development",
+    "webpack",
+    "plugin",
+    "components"
+  ],
+  "author": "Your Name",
+  "license": "MIT",
+  "peerDependencies": {
+    "next": ">=13.0.0",
+    "react": ">=18.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.19.9",
+    "@types/react": "^18.3.23",
+    "typescript": "^5.8.3"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/yourusername/nextjs-cursor-helper.git"
+  },
+  "bugs": {
+    "url": "https://github.com/yourusername/nextjs-cursor-helper/issues"
+  },
+  "homepage": "https://github.com/yourusername/nextjs-cursor-helper#readme"
+}

package/src/index.ts

@@ -0,0 +1,8 @@
+// Main exports
+export { withCursorButton } from './withCursorButton';
+export type { WithCursorButtonOptions } from './withCursorButton';
+
+// Next.js plugin
+const withCursorHelper = require('./plugin');
+export default withCursorHelper;
+export { withCursorHelper };

package/src/loader.js

@@ -0,0 +1,79 @@
+const path = require('path');
+
+/**
+ * Webpack loader that automatically wraps React components with cursor buttons
+ * @param {string} source - The source code of the file
+ * @returns {string} - The transformed source code
+ */
+module.exports = function cursorButtonLoader(source) {
+  const filename = this.resourcePath;
+  const options = this.getOptions() || {};
+  
+  const {
+    componentPaths = ['src/components'],
+    projectRoot = process.cwd(),
+    importPath = 'nextjs-cursor-helper/withCursorButton',
+    enabled = process.env.NODE_ENV === 'development'
+  } = options;
+
+  // Only process if enabled
+  if (!enabled) {
+    return source;
+  }
+  
+  // Only process files in specified component directories
+  const shouldProcess = componentPaths.some(componentPath => 
+    filename.includes(path.resolve(projectRoot, componentPath))
+  );
+  
+  if (!shouldProcess || (!filename.endsWith('.tsx') && !filename.endsWith('.jsx'))) {
+    return source;
+  }
+
+  // Check if it's already wrapped
+  if (source.includes('withCursorButton')) {
+    return source;
+  }
+
+  // Check if it has a default export that looks like a React component
+  const defaultExportMatch = source.match(/export\s+default\s+(\w+)/);
+  if (!defaultExportMatch) {
+    return source;
+  }
+
+  const componentName = defaultExportMatch[1];
+  
+  // Check if component name starts with uppercase (React component convention)
+  if (!componentName || componentName[0] !== componentName[0].toUpperCase()) {
+    return source;
+  }
+
+  // Get relative path from project root
+  const relativePath = path.relative(projectRoot, filename);
+
+  // Find the last import to insert our import after it
+  const imports = source.match(/^import.*$/gm) || [];
+  
+  let modifiedSource;
+  
+  if (imports.length === 0) {
+    // No imports found, add at top
+    const importStatement = `import { withCursorButton } from '${importPath}';\n`;
+    const wrappedExport = `export default withCursorButton(${componentName}, '${relativePath}', { projectRoot: '${projectRoot}' });`;
+    modifiedSource = importStatement + source.replace(/export\s+default\s+\w+;?/, wrappedExport);
+  } else {
+    const lastImportIndex = source.lastIndexOf(imports[imports.length - 1]) + imports[imports.length - 1].length;
+    
+    // Add import statement
+    const importStatement = `\nimport { withCursorButton } from '${importPath}';`;
+    
+    // Replace the export
+    const wrappedExport = `export default withCursorButton(${componentName}, '${relativePath}', { projectRoot: '${projectRoot}' });`;
+    
+    modifiedSource = source.slice(0, lastImportIndex) + 
+                     importStatement + 
+                     source.slice(lastImportIndex).replace(/export\s+default\s+\w+;?/, wrappedExport);
+  }
+
+  return modifiedSource;
+};

package/src/plugin.js

@@ -0,0 +1,61 @@
+const path = require('path');
+
+/**
+ * Configuration options for the NextJS Cursor Helper plugin
+ * @typedef {Object} CursorHelperOptions
+ * @property {string[]} [componentPaths=['src/components']] - Paths to scan for React components
+ * @property {string} [projectRoot=process.cwd()] - Root directory of the project
+ * @property {string} [importPath='nextjs-cursor-helper/withCursorButton'] - Import path for withCursorButton
+ * @property {boolean} [enabled=process.env.NODE_ENV === 'development'] - Enable/disable the plugin
+ */
+
+/**
+ * NextJS Cursor Helper plugin
+ * @param {CursorHelperOptions} options - Configuration options
+ * @returns {function} Next.js config modifier function
+ */
+function withCursorHelper(options = {}) {
+  const defaultOptions = {
+    componentPaths: ['src/components'],
+    projectRoot: process.cwd(),
+    importPath: 'nextjs-cursor-helper/withCursorButton',
+    enabled: process.env.NODE_ENV === 'development'
+  };
+
+  const config = { ...defaultOptions, ...options };
+
+  return (nextConfig = {}) => {
+    return {
+      ...nextConfig,
+      webpack: (webpackConfig, context) => {
+        const { dev, isServer } = context;
+
+        // Only apply in development and for client-side
+        if (config.enabled && dev && !isServer) {
+          const rule = {
+            test: /\.tsx?$/,
+            include: config.componentPaths.map(p => path.resolve(config.projectRoot, p)),
+            use: [
+              {
+                loader: require.resolve('./loader.js'),
+                options: config
+              }
+            ],
+            enforce: 'pre'
+          };
+
+          webpackConfig.module.rules.unshift(rule);
+        }
+
+        // Call the existing webpack function if it exists
+        if (typeof nextConfig.webpack === 'function') {
+          return nextConfig.webpack(webpackConfig, context);
+        }
+
+        return webpackConfig;
+      }
+    };
+  };
+}
+
+module.exports = withCursorHelper;

package/src/withCursorButton.tsx

@@ -0,0 +1,78 @@
+'use client';
+import React, { useState, useEffect } from 'react';
+
+interface CursorButtonProps {
+  filePath: string;
+  projectRoot?: string;
+}
+
+const CursorButton: React.FC<CursorButtonProps> = ({ filePath, projectRoot }) => {
+  const handleClick = () => {
+    const fullPath = projectRoot ? `${projectRoot}/${filePath}` : filePath;
+    window.open(`cursor://file${fullPath}`, '_blank');
+  };
+
+  return (
+    <button
+      onClick={handleClick}
+      style={{
+        position: 'absolute',
+        top: '8px',
+        right: '8px',
+        background: '#007acc',
+        color: 'white',
+        border: 'none',
+        borderRadius: '4px',
+        padding: '4px 8px',
+        fontSize: '12px',
+        cursor: 'pointer',
+        zIndex: 1000,
+        opacity: 0.7,
+        transition: 'opacity 0.2s',
+        fontFamily: 'monospace'
+      }}
+      onMouseEnter={(e) => (e.currentTarget.style.opacity = '1')}
+      onMouseLeave={(e) => (e.currentTarget.style.opacity = '0.7')}
+      title={`Open ${filePath} in Cursor`}
+    >
+      📝
+    </button>
+  );
+};
+
+export interface WithCursorButtonOptions {
+  projectRoot?: string;
+  enabled?: boolean;
+}
+
+export function withCursorButton<T extends object>(
+  WrappedComponent: React.ComponentType<T>,
+  filePath: string,
+  options: WithCursorButtonOptions = {}
+) {
+  const { projectRoot, enabled = process.env.NODE_ENV === 'development' } = options;
+
+  const WithCursorButtonComponent: React.FC<T> = (props) => {
+    const [isClient, setIsClient] = useState(false);
+
+    useEffect(() => {
+      setIsClient(true);
+    }, []);
+
+    // In production or when disabled, just return the component without wrapper
+    if (!enabled || !isClient) {
+      return <WrappedComponent {...props} />;
+    }
+
+    return (
+      <div style={{ position: 'relative' }}>
+        <CursorButton filePath={filePath} projectRoot={projectRoot} />
+        <WrappedComponent {...props} />
+      </div>
+    );
+  };
+
+  WithCursorButtonComponent.displayName = `withCursorButton(${WrappedComponent.displayName || WrappedComponent.name})`;
+
+  return WithCursorButtonComponent;
+}