Quick Start

This guide walks you through installing Presage, creating rules, and rendering your first adaptive component.

Installation

pnpm add @presage-kit/core @presage-kit/react

For Vue, replace @presage-kit/react with @presage-kit/vue.

1. Create an Adaptive Client

The client is the central hub. It holds your rules, tracks events, and resolves which variant to show.

src/lib/adaptive-client.ts

import {
  createAdaptiveClient,
  createLocalStorageDriver,
} from '@presage-kit/core'

export const client = createAdaptiveClient({
  rules: [
    {
      id: 'new-user-guided-tour',
      adaptationId: 'onboarding',
      priority: 10,
      conditions: {
        all: [
          { field: 'maturity', operator: 'eq', value: 'new' },
        ],
      },
      action: { type: 'show', variantId: 'guided-tour' },
    },
    {
      id: 'power-user-skip-onboarding',
      adaptationId: 'onboarding',
      priority: 20,
      conditions: {
        all: [
          { field: 'maturity', operator: 'in', value: ['active', 'power'] },
        ],
      },
      action: { type: 'show', variantId: 'minimal' },
    },
  ],
  persistence: {
    driver: createLocalStorageDriver('my-app'),
  },
})

2. Wrap Your App with the Provider

The provider makes the client available to every component in your tree.

src/App.tsx

import { AdaptiveProvider } from '@presage-kit/react'
import { client } from './lib/adaptive-client'
import { Onboarding } from './components/Onboarding'

export function App() {
  return (
    <AdaptiveProvider client={client}>
      <Onboarding />
    </AdaptiveProvider>
  )
}

3. Build an Adaptive Component

Use <Adaptive> and <Variant> to declare what each user segment sees.

src/components/Onboarding.tsx

import { Adaptive, Variant } from '@presage-kit/react'

export function Onboarding() {
  return (
    <Adaptive id="onboarding" defaultVariant="standard">
      <Variant id="guided-tour">
        <div>
          <h2>Welcome! Let us show you around.</h2>
          <p>This guided tour will walk you through the key features.</p>
        </div>
      </Variant>
      <Variant id="standard">
        <div>
          <h2>Welcome back</h2>
          <p>Here is what is new since your last visit.</p>
        </div>
      </Variant>
      <Variant id="minimal">
        <div>
          <p>Good to see you again.</p>
        </div>
      </Variant>
    </Adaptive>
  )
}

4. Identify the User

After authentication, tell Presage who the user is.

client.identify('user-123', {
  role: 'admin',
  plan: 'pro',
  signupDate: '2025-01-15',
  company: 'Acme Corp',
})

5. Track Events

Record meaningful actions. Presage auto-computes signals from these events.

// Track feature usage
client.track('feature_used', { featureId: 'dashboard-export' })

// Track clicks
client.track('click', { elementId: 'sidebar-analytics' })

// Track any custom event
client.track('completed_onboarding')

6. Watch the UI Adapt

As events accumulate, Presage recomputes behavioral signals and maturity. When the user context crosses a rule threshold, the component re-renders with the matching variant — no page reload needed.

Full Working Example

Here is everything together in a single file:

import { createAdaptiveClient, createLocalStorageDriver } from '@presage-kit/core'
import { AdaptiveProvider, Adaptive, Variant } from '@presage-kit/react'

const client = createAdaptiveClient({
  rules: [
    {
      id: 'new-user-tour',
      adaptationId: 'onboarding',
      priority: 10,
      conditions: {
        all: [{ field: 'maturity', operator: 'eq', value: 'new' }],
      },
      action: { type: 'show', variantId: 'guided-tour' },
    },
    {
      id: 'power-user-minimal',
      adaptationId: 'onboarding',
      priority: 20,
      conditions: {
        any: [
          { field: 'maturity', operator: 'eq', value: 'active' },
          { field: 'maturity', operator: 'eq', value: 'power' },
        ],
      },
      action: { type: 'show', variantId: 'minimal' },
    },
  ],
  persistence: {
    driver: createLocalStorageDriver('quickstart'),
  },
})

// Identify after auth
client.identify('user-42', {
  role: 'editor',
  plan: 'pro',
  signupDate: '2025-03-01',
})

function Onboarding() {
  return (
    <Adaptive id="onboarding" defaultVariant="standard">
      <Variant id="guided-tour">
        <GuidedTour />
      </Variant>
      <Variant id="standard">
        <StandardWelcome />
      </Variant>
      <Variant id="minimal">
        <MinimalGreeting />
      </Variant>
    </Adaptive>
  )
}

function GuidedTour() {
  return <p>Step-by-step guided tour for new users.</p>
}

function StandardWelcome() {
  return <p>Standard welcome screen.</p>
}

function MinimalGreeting() {
  return <p>Welcome back!</p>
}

export default function App() {
  return (
    <AdaptiveProvider client={client}>
      <Onboarding />
    </AdaptiveProvider>
  )
}

Next Steps

• Core Concepts — Understand the building blocks in depth
• Rules Engine Guide — Master all 14 operators and boolean logic
• React Adapter — Full component and hook reference