Shipflow overlay runtime integrating React Grab with a Cursor agent workflow.
npm install @shipflow/overlayShipflow combines React Grab with Cursor Agent so any React project can select and edit components in context.
``bash`
npm install -D @shipflow/overlay
1. Wrap your Next config:
`ts
// next.config.ts
import { withShipflowOverlay } from '@shipflow/overlay/next';
const nextConfig = {
/ your config /
};
export default withShipflowOverlay(nextConfig, {
logClipboardEndpoint: '/api/log-clipboard',
});
`
2. Render ShipflowOverlay in your root layout:
Import ShipflowOverlay directly from @shipflow/overlay using next/dynamic for optimal performance. The implementation differs based on whether your layout is a Server Component or Client Component:
For Server Component layouts (no "use client" directive):
`tsx
// app/layout.tsx
import dynamic from 'next/dynamic';
const ShipflowOverlay = dynamic(() =>
import('@shipflow/overlay').then((mod) => ({
default: mod.ShipflowOverlay,
})),
);
export default function RootLayout({
children,
}: {
children: React.ReactNode;
}) {
return (
For Client Component layouts (has
"use client" directive):
`tsx
// app/layout.tsx
'use client'; import dynamic from 'next/dynamic';
const ShipflowOverlay = dynamic(
() =>
import('@shipflow/overlay').then((mod) => ({
default: mod.ShipflowOverlay,
})),
{ ssr: false },
);
export default function RootLayout({
children,
}: {
children: React.ReactNode;
}) {
return (
{children}
{process.env.NODE_ENV === 'development' && }
);
}
`3. Wire the API route:
`ts
// app/api/shipflow/overlay/route.ts
import { createNextHandler } from '@shipflow/overlay/next'; export const runtime = 'nodejs';
export const dynamic = 'force-dynamic';
export const POST = createNextHandler();
`4. Cursor CLI: The package automatically searches for
cursor-agent in PATH and common installation directories. If not found, set CURSOR_AGENT_BIN to the absolute path.CLI helper
`bash
npx shipflow-overlay init
`Scaffolds the provider and API route, checks for
cursor-agent, and adds CURSOR_AGENT_BIN to .env.example.Configuration
Next.js config:
`ts
withShipflowOverlay(config, {
enableInProduction?: boolean; // Enable in production (default: false)
});
`API handler:
`ts
createNextHandler({
cursorAgentBinary?: string; // Custom binary path
timeoutMs?: number; // Timeout in ms (default: 240000)
allowInProduction?: boolean; // Allow in production (default: false)
});
`Environment variables:
-
CURSOR_AGENT_BIN: Absolute path to cursor-agent (if not in PATH)
- SHIPFLOW_OVERLAY_ENABLED: Set to "true" to enable overlay
- SHIPFLOW_OVERLAY_AGENT_TIMEOUT_MS`: Timeout in millisecondsMIT © Shipflow