### Install React Grab with bun

Source: https://github.com/aidenybai/react-grab/blob/main/apps/website/public/llms.txt

Install React Grab using bun.

```bash
bun add react-grab@latest
```

--------------------------------

### Install React Grab with npm

Source: https://github.com/aidenybai/react-grab/blob/main/apps/website/public/llms.txt

Install React Grab using npm.

```bash
npm install react-grab@latest
```

--------------------------------

### Install React Grab using Node API

Source: https://github.com/aidenybai/react-grab/blob/main/packages/cli/README.md

The `installReactGrab` function orchestrates project setup non-interactively. It detects the project, installs `react-grab`, and applies framework-specific setup. It returns a structured result object.

```typescript
import { installReactGrab } from "@react-grab/cli/api";

const result = await installReactGrab({ cwd: process.cwd() });

console.log(result.framework); // "next" | "vite" | "tanstack" | "webpack"
console.log(result.didInstallPackage); // whether react-grab was added to deps
console.log(result.didChangeFile); // whether an entry file was modified
console.log(result.transform.filePath); // the file that was (or would be) edited
```

--------------------------------

### Install React Grab with yarn

Source: https://github.com/aidenybai/react-grab/blob/main/apps/website/public/llms.txt

Install React Grab using yarn.

```bash
yarn add react-grab@latest
```

--------------------------------

### Apply Transform and Install Skill

Source: https://github.com/aidenybai/react-grab/blob/main/packages/cli/README.md

Install necessary packages if they are missing, then apply the previewed transformation if successful and no prior changes were detected. Finally, install the React Grab skill.

```typescript
if (!project.hasReactGrab) {
  await installPackages(getPackagesToInstall(), {
    cwd: project.projectRoot,
    packageManager: project.packageManager,
  });
}

if (transform.success && transform.newContent && !transform.noChanges) {
  applyTransform(transform);
}

await installSkill({ cwd: project.projectRoot });
```

--------------------------------

### Build Core CSS and Start Openstory

Source: https://github.com/aidenybai/react-grab/blob/main/apps/openstory/README.md

Build the core CSS once before running the development server. Then, start openstory using the provided filter.

```bash
pnpm --filter react-grab prebuild

pnpm --filter @react-grab/openstory dev
```

--------------------------------

### Initialize React Grab CLI

Source: https://github.com/aidenybai/react-grab/blob/main/packages/cli/README.md

Use `npx grab@latest init` for interactive setup. Add `-y` for non-interactive setup. Use `-k` to set a custom shortcut.

```bash
# Interactive setup
npx grab@latest init

# Non-interactive setup
npx grab@latest init -y

# Set a custom shortcut
npx grab@latest init -k "Meta+K"
```

--------------------------------

### Install React Grab with pnpm

Source: https://github.com/aidenybai/react-grab/blob/main/apps/website/public/llms.txt

Install React Grab using pnpm.

```bash
pnpm add react-grab@latest
```

--------------------------------

### Install React Grab Package

Source: https://github.com/aidenybai/react-grab/blob/main/apps/website/public/install.md

Manually install the react-grab package using npm, yarn, pnpm, or bun. This is an alternative if the CLI installation fails.

```bash
npm install react-grab@latest
```

```bash
yarn add react-grab@latest
```

```bash
pnpm add react-grab@latest
```

```bash
bun add react-grab@latest
```

--------------------------------

### Clone Repository and Install Dependencies

Source: https://github.com/aidenybai/react-grab/blob/main/CONTRIBUTING.md

Clone the React Grab repository and install project dependencies using pnpm. Ensure Node.js and pnpm are installed.

```bash
git clone https://github.com/YOUR_USERNAME/react-grab.git
cd react-grab
ni
```

--------------------------------

### Installation Functions

Source: https://github.com/aidenybai/react-grab/blob/main/packages/cli/README.md

These functions handle the installation and removal of packages and skills related to React Grab.

```APIDOC
## Installation

### Functions
- `installPackages(packages: string[], options: { cwd: string, packageManager: string })`: Installs specified packages with given options. Guards on `project.hasReactGrab` to avoid reinstalling.
- `getPackagesToInstall()`: Returns a list of packages that need to be installed.
- `installSkill(options: { cwd: string })`: Installs the React Grab skill.
- `removeSkill(options: { cwd: string })`: Removes the React Grab skill.
```

--------------------------------

### Run Openstory Playground

Source: https://github.com/aidenybai/react-grab/blob/main/CONTRIBUTING.md

Start the Openstory playground locally to test react-grab against realistic DOM fixtures. This opens at http://localhost:6006.

```bash
pnpm --filter @react-grab/openstory dev
```

--------------------------------

### installReactGrab

Source: https://github.com/aidenybai/react-grab/blob/main/packages/cli/README.md

A high-level, non-interactive orchestrator that detects the project, installs `react-grab` with the detected package manager, and applies framework-specific development-only setup. It returns a structured result instead of printing or exiting.

```APIDOC
## installReactGrab(options?)

### Description
Installs and configures React Grab programmatically.

### Method
`installReactGrab`

### Parameters
#### Options
- **cwd** (string) - Optional - Project directory (default: `process.cwd()`)
- **framework** (Framework) - Optional - Override framework detection
- **nextRouterType** (NextRouterType) - Optional - Override Next.js router detection (`app` / `pages`)
- **packageManager** (PackageManager) - Optional - Override package-manager detection
- **skipPackageInstall** (boolean) - Optional - Skip installing the `react-grab` npm package
- **skipTransform** (boolean) - Optional - Skip editing the framework entry file
- **dryRun** (boolean) - Optional - Compute the changes without installing or writing
- **installPackageOptions** (Omit<InstallPackageOptions, "cwd" | "packageManager">) - Optional - Passed through to `installPackages` (e.g. `silent`, `isDev`); `cwd`/`packageManager` are controlled by the orchestrator

### Returns
A structured result object containing information about the installation.

### Result Object Fields
- **framework** (string) - Detected or overridden framework (`"next"` | `"vite"` | `"tanstack"` | `"webpack"`)
- **didInstallPackage** (boolean) - Whether `react-grab` was added to dependencies
- **didChangeFile** (boolean) - Whether an entry file was modified
- **transform.filePath** (string) - The path of the file that was (or would be) edited

### Error Handling
Failures throw a `ReactGrabInstallError` whose `code` identifies the cause, with the original error preserved on `error.cause`:
- `unsupported-framework`: framework has no automatic setup (Remix, Astro, SvelteKit, Gatsby)
- `unknown-framework`: no supported framework detected
- `transform-failed`: entry file could not be located or edited
- `install-failed`: package manager failed to install `react-grab`
- `write-failed`: edited file could not be written

### Notes
- Configures a single project at `cwd` and does not walk a monorepo.
- Pass `dryRun: true` to compute the change set without installing or writing.

### Request Example
```ts
import { installReactGrab } from "@react-grab/cli/api";

const result = await installReactGrab({ cwd: process.cwd() });

console.log(result.framework);
console.log(result.didInstallPackage);
console.log(result.didChangeFile);
console.log(result.transform.filePath);
```
```

--------------------------------

### Build and Run Development Mode

Source: https://github.com/aidenybai/react-grab/blob/main/CONTRIBUTING.md

Build all packages within the project and start the development server. These commands are essential for local development and testing.

```bash
nr build
nr dev
```

--------------------------------

### Install React Grab with Webpack

Source: https://github.com/aidenybai/react-grab/blob/main/README.md

First, install React Grab using npm. Then, conditionally import it in your main entry file (e.g., src/index.tsx or src/main.tsx) for development builds.

```bash
npm install react-grab
```

```tsx
if (process.env.NODE_ENV === "development") {
  import("react-grab");
}
```

--------------------------------

### Initialize React Grab with Options

Source: https://github.com/aidenybai/react-grab/blob/main/apps/website/public/install.md

Examples of initializing React Grab with specific options, such as overriding the framework, setting the router type, or defining a custom shortcut key.

```bash
npx grab@latest init -f next -r app -y
```

```bash
npx grab@latest init -k "Meta+K" -y
```

--------------------------------

### Webpack Manual Installation

Source: https://github.com/aidenybai/react-grab/blob/main/packages/react-grab/README.md

Install react-grab and add this import statement at the top of your main entry file (e.g., src/index.tsx or src/main.tsx) for Webpack projects.

```bash
npm install react-grab
```

--------------------------------

### Example Copied Context

Source: https://github.com/aidenybai/react-grab/blob/main/packages/grab/README.md

This is an example of the context copied when using React Grab, showing the element and its component stack with source locations.

```txt
[<a class="ml-auto inline-block text-sm" href="#">Forgot your password?</a> in LoginForm (at components/login-form.tsx:46:19)]
```

--------------------------------

### Example Copied Element

Source: https://github.com/aidenybai/react-grab/blob/main/apps/website/public/llms.txt

This is an example of the output format when copying a UI element. It includes the HTML, file path, and line number.

```plaintext
<a class="ml-auto inline-block text-sm" href="#">
  Forgot your password?
</a>
in LoginForm at components/login-form.tsx:46:19
```

--------------------------------

### Install Playwright Dependencies

Source: https://github.com/aidenybai/react-grab/blob/main/AGENTS.md

Install the necessary Chromium browser for Playwright E2E tests. This command should be run before executing Playwright tests.

```bash
npx --prefix packages/react-grab playwright install chromium --with-deps
```

--------------------------------

### Register a Basic Plugin

Source: https://github.com/aidenybai/react-grab/blob/main/packages/grab/README.md

Register a plugin with a name and custom hooks. This example shows how to log the selected element's tag name.

```javascript
import { registerPlugin } from "grab";

registerPlugin({
  name: "my-plugin",
  hooks: {
    onElementSelect: (element) => {
      console.log("Selected:", element.tagName);
    },
  },
});
```

--------------------------------

### Register a Basic Plugin

Source: https://github.com/aidenybai/react-grab/blob/main/README.md

Use `registerPlugin` to add custom functionality. This example shows how to log the selected element's tag name.

```javascript
import { registerPlugin } from "react-grab";

registerPlugin({
  name: "my-plugin",
  hooks: {
    onElementSelect: (element) => {
      console.log("Selected:", element.tagName);
    },
  },
});
```

--------------------------------

### Start React Grab Watcher

Source: https://github.com/aidenybai/react-grab/blob/main/skills/react-grab/SKILL.md

Starts the background watcher for new grabs and prints them as JSON. Use `--max-age 0` to ensure all grabs are delivered, regardless of age, preventing stale grabs from being dropped. This command blocks until a grab is available.

```bash
npx react-grab@latest pull --max-age 0
```

--------------------------------

### Configure React Grab Behavior

Source: https://github.com/aidenybai/react-grab/blob/main/apps/website/public/install.md

Examples of customizing React Grab's behavior using the CLI, such as setting a new shortcut key, enabling hold mode with a specific duration, or adjusting context lines.

```bash
npx grab@latest config -k "Meta+K"
```

```bash
npx grab@latest config -m hold --hold-duration 150
```

```bash
npx grab@latest config --context-lines 5
```

--------------------------------

### Register Plugin with Actions in React

Source: https://github.com/aidenybai/react-grab/blob/main/README.md

When using React, register plugins within a `useEffect` hook to manage their lifecycle. This example adds a custom action to the context menu.

```jsx
import { registerPlugin, unregisterPlugin } from "react-grab";

useEffect(() => {
  registerPlugin({
    name: "my-plugin",
    actions: [
      {
        id: "my-action",
        label: "My Action",
        shortcut: "M",
        onAction: (context) => {
          console.log("Action on:", context.element);
          context.hideContextMenu();
        },
      },
    ],
  });

  return () => unregisterPlugin("my-plugin");
}, []);
```

--------------------------------

### Webpack Main Entry File Import

Source: https://github.com/aidenybai/react-grab/blob/main/packages/grab/README.md

Add this import to the top of your main entry file (e.g., `src/index.tsx` or `src/main.tsx`) for React Grab with Webpack in development. Ensure 'grab' is installed.

```bash
npm install grab
```

```tsx
if (process.env.NODE_ENV === "development") {
  import("grab");
}
```

--------------------------------

### Initialize React Grab CLI

Source: https://github.com/aidenybai/react-grab/blob/main/packages/grab/README.md

Run this command at your project root to initialize React Grab.

```bash
npx grab@latest init
```

--------------------------------

### Build Openstory Project

Source: https://github.com/aidenybai/react-grab/blob/main/apps/openstory/README.md

Build the @react-grab/openstory project. Static build output is written to dist/ and deployed to https://openstory.react-grab.dev.

```bash
pnpm --filter @react-grab/openstory build
```

--------------------------------

### Initialize React Grab CLI

Source: https://github.com/aidenybai/react-grab/blob/main/apps/website/public/llms.txt

Run this command at your project root to initialize React Grab. Use the -y flag to skip interactive prompts.

```bash
npx grab@latest init -y
```

--------------------------------

### Key Commands Reference

Source: https://github.com/aidenybai/react-grab/blob/main/AGENTS.md

A quick reference for common development commands in the React Grab project. These commands are available at the root of the project.

```bash
ni # (or pnpm install)
nr build # (or pnpm build)
nr dev # - watches core packages
pnpm test # - runs Playwright E2E + Vitest CLI tests
pnpm lint # - oxlint on react-grab package
pnpm typecheck # - tsc on react-grab package
pnpm format # - oxfmt
npm_command=exec node packages/cli/dist/cli.js
pnpm --filter @react-grab/e2e-app-vite dev # (port 5175, lives in apps/e2e-app-vite)
pnpm --filter @react-grab/e2e-app-next dev # (port 5176, lives in apps/e2e-app-next)
```

--------------------------------

### Configure React Grab CLI

Source: https://github.com/aidenybai/react-grab/blob/main/packages/cli/README.md

Use `npx grab@latest configure` for interactive configuration. Use `--mode` and `--hold-duration` to set activation mode to hold.

```bash
# Change activation mode to hold
npx grab@latest configure --mode hold --hold-duration 500

# Interactive configuration wizard
npx grab@latest configure
```

--------------------------------

### React Grab CLI Help Commands

Source: https://github.com/aidenybai/react-grab/blob/main/apps/website/public/llms.txt

Discover all available commands and flags for the React Grab CLI.

```bash
npx grab@latest --help
```

```bash
npx grab@latest init --help
```

```bash
npx grab@latest config --help
```

--------------------------------

### Initialization Logic

Source: https://github.com/aidenybai/react-grab/blob/main/packages/react-grab/docs/architecture.md

This code demonstrates the initialization flow of the react-grab package, including checks for browser environment, disabled state, and flushing of pending plugins. It also handles API assignment and event dispatching.

```typescript
if (typeof window !== "undefined" && !window.__REACT_GRAB_DISABLED__) {
  const api = init();
  window.__REACT_GRAB__ = api;
  flushPendingPlugins();
  window.dispatchEvent(new CustomEvent("react-grab:init"));
} else {
  // SSR or disabled environment, return no-op API
  window.__REACT_GRAB__ = createNoOpAPI();
}
```

--------------------------------

### Run All Tests (including Perf)

Source: https://github.com/aidenybai/react-grab/blob/main/packages/react-grab/perf/README.md

Execute all tests, including the performance scenarios. This command can be run from the root of the repository or within the packages/react-grab/ directory.

```bash
pnpm test
```

--------------------------------

### Configure React Grab CLI

Source: https://github.com/aidenybai/react-grab/blob/main/apps/website/public/llms.txt

Use this command to configure React Grab options such as shortcut keys and activation mode.

```bash
npx grab@latest config
```

--------------------------------

### Configure Vite Entry File

Source: https://github.com/aidenybai/react-grab/blob/main/apps/website/public/install.md

Import react-grab in your main entry file (e.g., src/main.tsx) for development environments in Vite projects.

```tsx
if (import.meta.env.DEV) {
  import("react-grab");
}
```

--------------------------------

### Reconfigure React Grab Settings

Source: https://github.com/aidenybai/react-grab/blob/main/packages/cli/README.md

Run this command to update React Grab options. It launches an interactive wizard if no flags are provided.

```bash
npx grab@latest configure
```

--------------------------------

### Detect Project and Preview Transform

Source: https://github.com/aidenybai/react-grab/blob/main/packages/cli/README.md

Use these functions to detect the current project's configuration and preview transformations without applying them. Ensure the project is detected before previewing changes.

```typescript
import {
  detectProject,
  previewTransform,
  applyTransform,
  installPackages,
  getPackagesToInstall,
  installSkill,
} from "@react-grab/cli/api";

const project = await detectProject(process.cwd());
const transform = previewTransform(
  project.projectRoot,
  project.framework,
  project.nextRouterType,
  project.isReactGrabConfigured,
);
```

--------------------------------

### Build Profiling Version

Source: https://github.com/aidenybai/react-grab/blob/main/packages/react-grab/perf/README.md

Build the project with unminified symbols to ensure accurate profiling data. This command should be paired with trace dumping for detailed flame chart analysis.

```bash
pnpm build:profiling
```

```bash
pnpm --filter react-grab build:profiling
```

--------------------------------

### Run CLI in Development

Source: https://github.com/aidenybai/react-grab/blob/main/AGENTS.md

Execute the CLI tool in development mode. Ensure the `npm_command` environment variable is set correctly.

```bash
npm_command=exec node packages/cli/dist/cli.js
```

--------------------------------

### Define Plugin Actions with Target

Source: https://github.com/aidenybai/react-grab/blob/main/packages/grab/README.md

Define actions for plugins, specifying their visibility. Actions can appear in the context menu (default) or the toolbar.

```javascript
actions: [
  {
    id: "inspect",
    label: "Inspect",
    shortcut: "I",
    onAction: (ctx) => console.dir(ctx.element),
  },
  {
    id: "toggle-freeze",
    label: "Freeze",
    // Only show in the toolbar
    target: "toolbar",
    isActive: () => isFrozen,
    onAction: () => toggleFreeze(),
  },
];
```

--------------------------------

### Vite Integration

Source: https://github.com/aidenybai/react-grab/blob/main/apps/website/public/llms.txt

Add this script to your `index.html` for Vite integration. It dynamically imports React Grab in development mode.

```html
<!doctype html>
<html lang="en">
  <head>
    <script type="module">
      if (import.meta.env.DEV) {
        import("react-grab");
      }
    </script>
  </head>
  <body>
    <div id="root"></div>
    <script type="module" src="/src/main.tsx"></script>
  </body>
</html>
```

--------------------------------

### Run CLI Tests

Source: https://github.com/aidenybai/react-grab/blob/main/CONTRIBUTING.md

Execute the test suite specifically for the CLI package. This helps ensure the command-line interface functions as expected.

```bash
pnpm --filter @react-grab/cli test
```

--------------------------------

### Configure Next.js (App Router) Layout

Source: https://github.com/aidenybai/react-grab/blob/main/apps/website/public/install.md

Add the Script component to your app/layout.tsx file to include React Grab for development environments.

```jsx
import Script from "next/script";

export default function RootLayout({ children }) {
  return (
    <html lang="en">
      <head>
        {process.env.NODE_ENV === "development" && (
          <Script
            src="//unpkg.com/react-grab/dist/index.global.js"
            crossOrigin="anonymous"
            strategy="beforeInteractive"
          />
        )}
      </head>
      <body>{children}</body>
    </html>
  );
}
```

--------------------------------

### Run Project Checks

Source: https://github.com/aidenybai/react-grab/blob/main/AGENTS.md

Execute all automated checks, including E2E tests, linting, type checking, and formatting. These should be run before committing code.

```bash
pnpm test # runs e2e tests
pnpm lint
pnpm typecheck # runs type checking
pnpm format
```

--------------------------------

### Write Baseline Performance Data

Source: https://github.com/aidenybai/react-grab/blob/main/packages/react-grab/perf/README.md

Run performance tests and write the results to perf/baseline/<scenario>.json. This establishes a baseline for future comparisons.

```bash
pnpm test:perf:baseline
```

--------------------------------

### Lint and Format Code

Source: https://github.com/aidenybai/react-grab/blob/main/CONTRIBUTING.md

Check for linting errors and automatically fix them. Format the code using oxfmt to maintain a consistent style across the project.

```bash
nr lint
nr lint:fix
nr format
```

--------------------------------

### Dump Performance Traces

Source: https://github.com/aidenybai/react-grab/blob/main/packages/react-grab/perf/README.md

Run performance tests with tracing enabled, dumping detailed trace files to perf/<label>/<scenario>.trace.json. These traces can be loaded into Chrome DevTools for in-depth analysis.

```bash
PERF_TRACE=1 pnpm test:perf --grep <name>
```

--------------------------------

### Run Performance Tests with Custom Label

Source: https://github.com/aidenybai/react-grab/blob/main/packages/react-grab/perf/README.md

Execute performance tests and write results to perf/feature/<scenario>.json, using a custom label (e.g., 'feature'). This helps categorize performance runs.

```bash
PERF_LABEL=feature pnpm test:perf
```

--------------------------------

### Vite Main Entry File Import

Source: https://github.com/aidenybai/react-grab/blob/main/packages/grab/README.md

Add this import to the top of your main entry file (e.g., `src/main.tsx`) for React Grab with Vite in development.

```tsx
if (import.meta.env.DEV) {
  import("grab");
}
```

--------------------------------

### Create a New Branch

Source: https://github.com/aidenybai/react-grab/blob/main/CONTRIBUTING.md

Create a new Git branch for your feature or fix. Use a descriptive name following the conventional commit structure.

```bash
git checkout -b feat/your-feature-name
```

--------------------------------

### Add a Changeset

Source: https://github.com/aidenybai/react-grab/blob/main/CONTRIBUTING.md

Add a changeset for modifications that will be published to packages. This process helps in generating accurate changelogs.

```bash
nr changeset
```

--------------------------------

### Peek for New Grabs Without Blocking

Source: https://github.com/aidenybai/react-grab/blob/main/skills/react-grab/SKILL.md

Checks for new grabs without blocking the current process. If output is empty, no new grabs are available. If a grab is printed, it indicates the user has redirected focus, and the current task should be abandoned for the newest grab.

```bash
npx react-grab@latest pull --max-age 0 --wait 0
```

--------------------------------

### Project Detection Functions

Source: https://github.com/aidenybai/react-grab/blob/main/packages/cli/README.md

These functions are used to detect various aspects of a React project, including the project itself, its framework, package manager, and React Grab configuration.

```APIDOC
## Project Detection

### Functions
- `detectProject(cwd: string)`: Detects the React project in the current working directory.
- `detectFramework(cwd: string)`: Detects the framework used by the project.
- `detectPackageManager(cwd: string)`: Detects the package manager used by the project.
- `detectNextRouterType(cwd: string)`: Detects the Next.js router type.
- `detectReactGrab(cwd: string)`: Detects if React Grab is configured in the project.
- `detectReactGrabConfigured(cwd: string)`: Detects if React Grab is configured.
- `detectUnsupportedFramework(cwd: string)`: Detects if the project uses an unsupported framework.
- `findReactProjects(cwd: string)`: Finds all React projects in the current working directory.
```

--------------------------------

### Run Only Performance Scenarios

Source: https://github.com/aidenybai/react-grab/blob/main/packages/react-grab/perf/README.md

Execute only the performance-related test scenarios using the --grep flag. This is useful for focusing on performance regressions.

```bash
pnpm test:perf
```

--------------------------------

### Next.js App Router Integration

Source: https://github.com/aidenybai/react-grab/blob/main/apps/website/public/llms.txt

Add this script to your `app/layout.tsx` for Next.js App Router integration. It loads React Grab in development mode.

```jsx
import Script from "next/script";

export default function RootLayout({ children }) {
  return (
    <html>
      <head>
        {process.env.NODE_ENV === "development" && (
          <Script
            src="//unpkg.com/react-grab/dist/index.global.js"
            crossOrigin="anonymous"
            strategy="beforeInteractive"
          />
        )}
      </head>
      <body>{children}</body>
    </html>
  );
}
```

--------------------------------

### State Diagram for Interaction Lifecycle

Source: https://github.com/aidenybai/react-grab/blob/main/packages/react-grab/docs/architecture.md

This Mermaid diagram illustrates the various states and transitions within the react-grab interaction lifecycle, from initial idle state through holding, active phases (hovering, frozen, dragging), and completion states (copying, justCopied).

```mermaid
stateDiagram-v2
    [*] --> idle
    idle --> holding : key pressed
    holding --> active : hold duration met
    holding --> idle : key released early
    idle --> active : toggle activation

    state active {
        [*] --> hovering
        hovering --> frozen : click element
        frozen --> hovering : unfreeze
        hovering --> dragging : pointer drag
        dragging --> justDragged : pointer up
        justDragged --> hovering : timeout
    }

    active --> copying : copy triggered
    copying --> justCopied : copy complete
    justCopied --> active : was hold-activated, keep inspecting
    justCopied --> idle : was toggle-activated, done
    active --> idle : deactivate
```

--------------------------------

### Webpack Integration

Source: https://github.com/aidenybai/react-grab/blob/main/apps/website/public/llms.txt

Add this import to your main entry file (e.g., `src/index.tsx`) for Webpack integration. It loads React Grab in development mode.

```tsx
if (process.env.NODE_ENV === "development") {
  import("react-grab");
}
```

--------------------------------

### Transformation Functions

Source: https://github.com/aidenybai/react-grab/blob/main/packages/cli/README.md

These functions are used to preview and apply transformations to the project files. They allow for granular control over code modifications.

```APIDOC
## Transformations

### Functions
- `previewTransform(projectRoot: string, framework: string, nextRouterType: string, isReactGrabConfigured: boolean)`: Previews a transformation for the project.
- `previewOptionsTransform(projectRoot: string, options: any)`: Previews a transformation with custom options.
- `previewCdnTransform(projectRoot: string)`: Previews a CDN transformation.
- `applyTransform(transform: any)`: Applies a previously previewed transformation to the project files. Writes `transform.newContent` to `transform.filePath`.
- `hasFrameworkEntryPoint(projectRoot: string)`: Checks if the project has a framework entry point.
```

--------------------------------

### Commit Changes

Source: https://github.com/aidenybai/react-grab/blob/main/CONTRIBUTING.md

Commit your changes with a descriptive message following the conventional commit format. This ensures clarity in the project's history.

```bash
git commit -m "feat: add new feature"
```

--------------------------------

### Next.js Pages Router Integration

Source: https://github.com/aidenybai/react-grab/blob/main/apps/website/public/llms.txt

Include this script in your `pages/_document.tsx` for Next.js Pages Router integration. It loads React Grab in development mode.

```jsx
import { Html, Head, Main, NextScript } from "next/document";

export default function Document() {
  return (
    <Html lang="en">
      <Head>
        {process.env.NODE_ENV === "development" && (
          <Script
            src="//unpkg.com/react-grab/dist/index.global.js"
            crossOrigin="anonymous"
            strategy="beforeInteractive"
          />
        )}
      </Head>
      <body>
        <Main />
        <NextScript />
      </body>
    </Html>
  );
}
```

--------------------------------

### Next.js App Router Layout Script

Source: https://github.com/aidenybai/react-grab/blob/main/packages/grab/README.md

Add this script to your `app/layout.tsx` for React Grab in Next.js App Router.

```jsx
import Script from "next/script";

export default function RootLayout({ children }) {
  return (
    <html>
      <head>
        {process.env.NODE_ENV === "development" && (
          <Script
            src="//unpkg.com/grab/dist/index.global.js"
            crossOrigin="anonymous"
            strategy="beforeInteractive"
          />
        )}
      </head>
      <body>{children}</body>
    </html>
  );
}
```

--------------------------------

### Next.js Pages Router Document Script

Source: https://github.com/aidenybai/react-grab/blob/main/packages/grab/README.md

Add this script to your `pages/_document.tsx` for React Grab in Next.js Pages Router.

```jsx
import { Html, Head, Main, NextScript } from "next/document";

export default function Document() {
  return (
    <Html lang="en">
      <Head>
        {process.env.NODE_ENV === "development" && (
          <Script
            src="//unpkg.com/grab/dist/index.global.js"
            crossOrigin="anonymous"
            strategy="beforeInteractive"
          />
        )}
      </Head>
      <body>
        <Main />
        <NextScript />
      </body>
    </Html>
  );
}
```

--------------------------------

### Stop React Grab Watcher

Source: https://github.com/aidenybai/react-grab/blob/main/skills/react-grab/SKILL.md

Stops the React Grab watcher and prevents further pulls. This command should be run when the user indicates they want to stop the process.

```bash
npx react-grab@latest stop
```

--------------------------------

### Performance Report JSON Structure

Source: https://github.com/aidenybai/react-grab/blob/main/packages/react-grab/perf/README.md

This is the expected JSON structure for performance reports. It includes aggregate data, per-sample results, and baseline comparisons.

```json
{
  "scenario": "hover-in-selection-mode",
  "label": "current",
  "samples": 3,
  "aggregate": { "inp": 0, "longTasks": {...}, "frames": {...}, ... },
  "perSample": [ ... ],
  "baseline": { ... },
  "recordedAt": "..."
}
```

--------------------------------

### Viewport Meta Tag for Mobile Input

Source: https://github.com/aidenybai/react-grab/blob/main/apps/website/AGENTS.md

Include this meta tag in your HTML to ensure proper font sizing and prevent double-tap zoom on mobile devices.

```html
<meta
  name="viewport"
  content="width=device-width, initial-scale=1, maximum-scale=1, viewport-fit=cover"
/>
```