npm package: @keak/sdk
Description: Production-ready A/B testing and experimentation SDK for React applications with visual editing, source mapping, and real-time variant testing
Author: Keak Team
Latest version: 2.2.9

# Keak SDK

Production-ready A/B testing and experimentation SDK for React applications with visual editing, source mapping, and real-time variant testing.

## Quick Start

### 1. Install the SDK

```bash
npm install @keak/sdk
```

All dependencies are bundled with the SDK - no additional packages required.

### 2. Auto-Setup

The CLI setup runs automatically after installation. If it doesn't run, trigger it manually:

```bash
npx keak-setup
```

The installer will:
- Detect your React framework (Next.js, CRA, Vite, etc.)
- Find your main entry file (`src/index.tsx`, `app/layout.tsx`, etc.)
- Add the `useKeak()` hook automatically
- Create a backup of your original file
- Automatically configure source mapping (enables precise element-to-code mapping)

### 3. Next.js 15 Setup

If you're using Next.js 15, you'll need additional configuration to enable source mapping. See the [Next.js 15 Setup Guide](./NEXTJS_15_SETUP.md) for detailed instructions.

## Framework-Specific Setup

### Next.js App Router

Add the `useKeak()` hook to your root layout:

```tsx
// app/layout.tsx
'use client';

import { useKeak, KeakToolbar } from '@keak/sdk';

export default function RootLayout({ children }) {
  useKeak({ debug: true });

  return (
    <html lang="en">
      <body>
        {children}
        <KeakToolbar position="bottom-right" />
      </body>
    </html>
  );
}
```

### Next.js Pages Router

Add the `useKeak()` hook to your `_app.tsx`:

```tsx
// pages/_app.tsx
import { useKeak, KeakToolbar } from '@keak/sdk';
import type { AppProps } from 'next/app';

export default function App({ Component, pageProps }: AppProps) {
  useKeak({ debug: true });

  return (
    <>
      <Component {...pageProps} />
      <KeakToolbar position="bottom-right" />
    </>
  );
}
```

### Create React App (CRA)

Add the `useKeak()` hook to your main App component:

```tsx
// src/App.tsx
import { useKeak, KeakToolbar } from '@keak/sdk';

function App() {
  useKeak({ debug: true });

  return (
    <div className="App">
      {/* Your app content */}
      <KeakToolbar position="bottom-right" />
    </div>
  );
}

export default App;
```

### Vite

Add the `useKeak()` hook to your main App component:

```tsx
// src/App.tsx
import { useKeak, KeakToolbar } from '@keak/sdk';

function App() {
  useKeak({ debug: true });

  return (
    <>
      <div className="app">
        {/* Your app content */}
      </div>
      <KeakToolbar position="bottom-right" />
    </>
  );
}

export default App;
```

## Basic Usage

### Simple Setup

The `useKeak()` hook initializes the SDK with minimal configuration. No API key required!

```tsx
import { useKeak } from '@keak/sdk';

function App() {
  useKeak({ debug: true });

  return (
    <div>
      {/* Your app components */}
    </div>
  );
}
```

### Create Experiments

Wrap your content with `Experiment` and `Variant` components:

```tsx
import { Experiment, Variant } from '@keak/sdk';

export default function HeroHome() {
  return (
    <section>
      <h1>Create stunning web experiences</h1>
      
      <Experiment name="hero-description">
        <Variant name="control">
          <p>Our landing page template works on all devices, so you only have to set it up once, and get beautiful results forever.</p>
        </Variant>
        <Variant name="treatment">
          <p>Tired of generic templates and endless tweaks? Our expertly crafted landing page solution guarantees pixel-perfect performance and stunning conversions on every device.</p>
        </Variant>
      </Experiment>
    </section>
  );
}
```

### Using the Hook

You can also use the `useExperiment` hook for programmatic access:

```tsx
import { useExperiment } from '@keak/sdk';

function MyComponent() {
  const { variant, track, isInExperiment } = useExperiment('my-experiment');
  
  return (
    <div>
      {variant === 'treatment' && <NewFeature />}
      <button onClick={() => track('button_clicked')}>
        Click me
      </button>
    </div>
  );
}
```

## Project Structure

```
keak-sdk/
├── src/
│   ├── index.tsx          # Main SDK entry point
│   ├── toolbar/           # Floating toolbar components
│   └── scripts/           # Build and utility scripts
├── dist/                  # Built output (generated)
├── package.json           # Package configuration
└── tsconfig.json          # TypeScript configuration
```

## Available Scripts

- `npm run build` - Build the SDK for production
- `npm run dev` - Build the SDK in watch mode for development
- `npm run prepublishOnly` - Build before publishing

## Troubleshooting

### Common Issues

1. **Module not found errors**: Ensure the SDK is properly installed and the auto-setup has completed
2. **TypeScript errors**: Ensure your project has compatible TypeScript and React versions (React >=16.8.0)
3. **useKeak hook not working**: Run `npx keak-setup` to ensure the hook is properly added to your entry file

### Next.js 15 Issues

If you're using Next.js 15 and experiencing source mapping issues, refer to the [Next.js 15 Setup Guide](./NEXTJS_15_SETUP.md) for detailed troubleshooting steps.

## License

MIT