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

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:

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 KeakProvider wrapper 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 for detailed instructions.

Basic Usage

Setup KeakProvider

The auto-setup will add KeakProvider to your app. If you need to configure it manually:

import { KeakProvider } from '@keak/sdk';

function App() {
  return (
    <KeakProvider config={{ apiKey: 'your-api-key' }}>
      {/* Your app components */}
    </KeakProvider>
  );
}

Create Experiments

Wrap your content with Experiment and Variant components:

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:

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. KeakProvider not found: Run npx keak-setup to ensure the provider 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 for detailed troubleshooting steps.

License

MIT