@timoconnellaus/ai-ui-annotate-nextjs
v0.0.1
Published
Next.js plugin for AI UI Annotate - add inline annotations to your React components during development.
Readme
@timoconnellaus/ai-ui-annotate-nextjs
Next.js plugin for AI UI Annotate - add inline annotations to your React components during development.
Installation
npm install @timoconnellaus/ai-ui-annotate-nextjs
# or
yarn add @timoconnellaus/ai-ui-annotate-nextjs
# or
pnpm add @timoconnellaus/ai-ui-annotate-nextjs
# or
bun add @timoconnellaus/ai-ui-annotate-nextjsRequirements
- Next.js 13.0.0 or later
- React 18.0.0 or later
Usage
1. Configure next.config.js
Wrap your Next.js configuration with withAiUiAnnotate:
// next.config.js (or next.config.ts)
import { withAiUiAnnotate } from '@timoconnellaus/ai-ui-annotate-nextjs'
export default withAiUiAnnotate({
hotkey: 'alt', // optional, default: 'alt'
port: 8234, // optional, default: 8234
})({
// your existing Next.js config
reactStrictMode: true,
})2. Add the Script Component
Add the AiUiAnnotateScript component to inject the runtime.
App Router (Next.js 13+)
// app/layout.tsx
import { AiUiAnnotateScript } from '@timoconnellaus/ai-ui-annotate-nextjs'
export default function RootLayout({
children,
}: {
children: React.ReactNode
}) {
return (
<html>
<body>
{children}
<AiUiAnnotateScript hotkey="alt" port={8234} />
</body>
</html>
)
}Pages Router
// pages/_app.tsx
import type { AppProps } from 'next/app'
import { AiUiAnnotateScript } from '@timoconnellaus/ai-ui-annotate-nextjs'
export default function MyApp({ Component, pageProps }: AppProps) {
return (
<>
<Component {...pageProps} />
<AiUiAnnotateScript hotkey="alt" port={8234} />
</>
)
}Configuration Options
| Option | Type | Default | Description |
|--------|------|---------|-------------|
| hotkey | string | "alt" | The key to hold for enabling annotation mode. Supported: alt, option, ctrl, meta, shift |
| port | number | 8234 | WebSocket server port (must be 1024-65535) |
| outputDir | string | ".ai-ui-annotate" | Directory for storing annotation data |
How It Works
Build Transform: During development, the webpack loader transforms your JSX/TSX files to inject
data-componentanddata-sourceattributes on React elements.WebSocket Server: A WebSocket server starts automatically when you run
next dev, enabling real-time communication for annotations.Runtime Script: The
AiUiAnnotateScriptcomponent initializes the annotation UI when you hold the configured hotkey.
Development Only
This plugin is designed for development use only:
- The config wrapper returns a pass-through in production (
NODE_ENV=production) - The script component renders nothing in production
- No annotation code is included in production builds
Troubleshooting
Port Already in Use
If you see "port already in use", either:
- Stop the process using that port
- Configure a different port in both the config wrapper and script component
// Use a different port
withAiUiAnnotate({ port: 8235 })({ /* config */ })
<AiUiAnnotateScript port={8235} />SSR Hydration Errors
The AiUiAnnotateScript component uses 'use client' and only renders after client-side mount to prevent hydration mismatches. If you encounter issues, ensure you're using the component correctly in your layout.
Transform Not Working
Ensure your files have .js, .jsx, .ts, or .tsx extensions. The loader skips node_modules automatically.
License
MIT