@shipflow/overlay

v0.1.18

Published

a month ago

Shipflow overlay runtime integrating React Grab with a Cursor agent workflow.

Downloads

126

0High
0Medium
0Low

buildwitherik

jonathangus

shipflow overlay react nextjs cursor react-grab

@shipflow/overlay

Shipflow combines React Grab with Cursor Agent so any React project can select and edit components in context.

Installation

npm install -D @shipflow/overlay

Quickstart

Wrap your Next config:

// next.config.ts
import { withShipflowOverlay } from '@shipflow/overlay/next';

const nextConfig = {
  /* your config */
};

export default withShipflowOverlay(nextConfig, {
  logClipboardEndpoint: '/api/log-clipboard',
});

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):

// 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 (
    <html lang="en">
      <body>
        {children}
        {process.env.NODE_ENV === 'development' && <ShipflowOverlay />}
      </body>
    </html>
  );
}

For Client Component layouts (has "use client" directive):

// 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 (
    <html lang="en">
      <body>
        {children}
        {process.env.NODE_ENV === 'development' && <ShipflowOverlay />}
      </body>
    </html>
  );
}

Wire the API route:

// 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();

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

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:

withShipflowOverlay(config, {
  enableInProduction?: boolean;  // Enable in production (default: false)
});

API handler:

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 milliseconds

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

@shipflow/overlay

Installation

Quickstart

CLI helper

Configuration

License