@keak/sdk

v2.2.9

Published

a month ago

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

Downloads

126

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

Framework-Specific Setup

Next.js App Router

Add the useKeak() hook to your root layout:

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

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

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

// 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!

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:

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

Module not found errors: Ensure the SDK is properly installed and the auto-setup has completed
TypeScript errors: Ensure your project has compatible TypeScript and React versions (React >=16.8.0)
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 for detailed troubleshooting steps.

License

MIT