outlit-sdk

by @OutlitAI in Development

# Install this skill:

npx skills add OutlitAI/outlit-agent-skills --skill "outlit-sdk"

Install specific skill from multi-skill repository

# Description

Integrate Outlit SDK for customer journey tracking and analytics. Triggers when users need to add Outlit to React, Next.js, Vue, Svelte, Angular, Astro, Node.js, Express, or Fastify apps. Covers SDK installation (@outlit/browser, @outlit/node), auth provider integration (Clerk, NextAuth, Supabase, Auth0, Firebase), GDPR consent management, event tracking, user lifecycle events (activate, engaged, inactive), customer billing status (trialing, paid, churned), and Stripe webhook integration.

# SKILL.md

name: outlit-sdk
description: Integrate Outlit SDK for customer journey tracking and analytics. Triggers when users need to add Outlit to React, Next.js, Vue, Svelte, Angular, Astro, Node.js, Express, or Fastify apps. Covers SDK installation (@outlit/browser, @outlit/node), auth provider integration (Clerk, NextAuth, Supabase, Auth0, Firebase), GDPR consent management, event tracking, user lifecycle events (activate, engaged, inactive), customer billing status (trialing, paid, churned), and Stripe webhook integration.

Outlit Integration

Guides complete integration of Outlit SDK into web applications and Node.js servers, from installation through production deployment.

Overview

Outlit is a customer journey platform that tracks users from anonymous visitors through their complete lifecycle as paying customers. This skill helps integrate the Outlit SDK by:

Analyzing the project structure
Installing the appropriate SDK package
Setting up framework-specific configuration
Integrating with authentication providers
Implementing consent management (GDPR compliance)
Adding custom event tracking

Installation

To add this skill to your Claude Code environment:

npx add-skill outlitai/outlit-agent-skills
# or
bunx add-skill outlitai/outlit-agent-skills

Integration Workflow

Step 1: Analyze Project

Run the project detection script to understand the environment:

python scripts/detect_project.py [project_path]

This detects:
- Framework (React, Next.js, Vue, Node.js, etc.)
- Package manager (npm, yarn, pnpm, bun)
- TypeScript vs JavaScript
- Existing auth provider
- Current Outlit installation

Use the detection results to guide all subsequent steps.

Step 2: Install SDK

Use the installation script or manual installation:

# Using script
./scripts/install_sdk.sh @outlit/browser

# Or manually with detected package manager
npm install @outlit/browser    # For browser apps
npm install @outlit/node       # For Node.js servers
npm install @outlit/core       # For custom implementations

Package Selection:
- @outlit/browser — React, Next.js, Vue, Svelte, Angular, static sites
- @outlit/node — Express, Fastify, NestJS, serverless functions
- @outlit/core — Custom implementations, shared utilities

Step 3: Add Public Key

Users need to add their Outlit public key to environment variables:

Browser apps:

# .env.local or .env
NEXT_PUBLIC_OUTLIT_KEY=pk_xxx      # Next.js
REACT_APP_OUTLIT_KEY=pk_xxx        # Create React App
VITE_OUTLIT_KEY=pk_xxx             # Vite

Server apps:

# .env
OUTLIT_KEY=pk_xxx

Users get their public key from Outlit dashboard → Settings → Website Tracking.

Step 4: Framework-Specific Setup

Choose the appropriate setup based on the detected framework. See frameworks.md for complete patterns.

React

Copy template from assets/react/OutlitProvider.tsx and modify as needed:

import { OutlitProvider } from '@outlit/browser/react'

function App() {
  return (
    <OutlitProvider publicKey={import.meta.env.VITE_OUTLIT_KEY}>
      <YourApp />
    </OutlitProvider>
  )
}

Next.js App Router

Copy template from assets/nextjs/layout.tsx:

// app/layout.tsx
import { OutlitProvider } from '@outlit/browser/react'

export default function RootLayout({ children }) {
  return (
    <html>
      <body>
        <OutlitProvider publicKey={process.env.NEXT_PUBLIC_OUTLIT_KEY!}>
          {children}
        </OutlitProvider>
      </body>
    </html>
  )
}

Next.js Pages Router

Copy template from assets/nextjs/_app.tsx.

Node.js / Express

Copy templates from assets/node/:
- outlit.config.ts — Core configuration
- express-middleware.ts — Express middleware (if using Express)

For other frameworks, consult frameworks.md reference.

Step 5: Auth Integration (If Detected)

If an auth provider was detected, integrate it with Outlit. See auth-providers.md for patterns.

Common pattern:

<OutlitProvider
  publicKey="pk_xxx"
  user={currentUser ? {
    email: currentUser.email,
    userId: currentUser.id,
    traits: { name: currentUser.name }
  } : null}
>
  {children}
</OutlitProvider>

Supported auth providers:
- Clerk
- NextAuth / Auth.js
- Supabase
- Auth0
- Firebase Auth
- Custom solutions

For GDPR compliance, implement consent management. See consent-management.md.

Basic pattern:

<OutlitProvider
  publicKey="pk_xxx"
  autoTrack={hasConsent}  // Only track if consent granted
>
  {!hasConsent && <ConsentBanner />}
  {children}
</OutlitProvider>

Copy assets/react/ConsentBanner.tsx template for a ready-to-use consent banner.

Step 7: Custom Event Tracking

Help users implement custom event tracking based on their needs.

Browser example:

import { useOutlit } from '@outlit/browser/react'

function MyComponent() {
  const { track, user } = useOutlit()

  const handleUpgrade = () => {
    track('subscription_upgraded', { plan: 'pro' })
    user.activate({ milestone: 'upgraded' })
  }

  return <button onClick={handleUpgrade}>Upgrade</button>
}

Server example:

import { outlit } from '@/lib/outlit'

outlit.track({
  email: '[email protected]',
  eventName: 'subscription_created',
  properties: { plan: 'pro' }
})

await outlit.flush()

See patterns.md for event taxonomy and best practices.

Step 8: Verify Installation

Guide users to verify the installation:

Check Network Tab:
Open DevTools → Network
Look for requests to app.outlit.ai/api/i/v1/...
Status 200 = working correctly
Check Outlit Dashboard:
Visit Outlit dashboard
Navigate to Events or Live View
Verify events appear in real-time
Test Key Features:
Pageviews (automatic)
Form submissions (automatic if enabled)
Custom events (manual tracking)
User identification

Common Customizations

Custom Tracking Hook

For React apps, copy assets/react/useTracking.ts for a custom hook with common tracking operations.

Server-Side Webhooks

For billing integration, copy assets/node/stripe-webhook.ts as a starting point for Stripe webhooks.

Modify for other providers (Paddle, Chargebee, etc.) following the same pattern:
- Extract customer email/ID
- Track billing events
- Update customer status (trialing, paid, churned)
- Always flush before response

API Routes

For Next.js apps, copy assets/nextjs/api-route.ts or assets/nextjs/server-action.ts for server-side tracking.

Troubleshooting

No Events in Dashboard

Verify public key has correct framework prefix (NEXT_PUBLIC_, VITE_, REACT_APP_)
Confirm OutlitProvider wraps entire app
Check isTrackingEnabled() if using consent management
Network tab: requests should go to app.outlit.ai/api/i/v1/...

Events Not Linked to Users

Call identify() or setUser() immediately after signup/login.

Server-Side Events Missing

Always await outlit.flush() before function returns (especially serverless).

Quick Reference

For complete API documentation, see api-reference.md.

Key imports:

// Browser (React)
import { OutlitProvider, useOutlit } from '@outlit/browser/react'

// Node.js
import { Outlit } from '@outlit/node'

Resources

References

Load these references as needed for detailed guidance:

frameworks.md — Framework-specific integration patterns (React, Next.js, Vue, Express, etc.)
auth-providers.md — Auth provider integration (Clerk, NextAuth, Supabase, Auth0, etc.)
consent-management.md — GDPR-compliant consent management patterns
api-reference.md — Complete API reference for all SDK methods
patterns.md — Best practices, event taxonomy, webhooks, error handling

Scripts

detect_project.py — Analyze project structure and environment
install_sdk.sh — Install Outlit SDK with detected package manager

Templates

Ready-to-use code templates in assets/:

react/ — OutlitProvider, useTracking hook, ConsentBanner
nextjs/ — App Router layout, Pages Router _app, API routes, Server Actions
node/ — Configuration, Express middleware, Stripe webhooks

Best Practices

Identify Early: Call identify() as soon as user info is available
Include Both IDs: Provide both email and userId for identity resolution
Flush in Serverless: Always await outlit.flush() before function exits
Track Lifecycle: Use user.activate(), customer.paid() for milestones
Use snake_case: Event names like subscription_created, not SubscriptionCreated

Implementation Checklist

Use this checklist to ensure complete integration:

[ ] SDK installed (@outlit/browser or @outlit/node)
[ ] Public key added to environment variables
[ ] Provider/initialization added to root component/file
[ ] Auth integration implemented (if applicable)
[ ] Consent management added (for EU users)
[ ] Custom events identified and implemented
[ ] User lifecycle events added (activate, paid, churned)
[ ] Installation verified in dashboard
[ ] TypeScript types working correctly
[ ] Error handling implemented
[ ] Documentation added for team

# Supported AI Coding Agents

This skill is compatible with the SKILL.md standard and works with all major AI coding agents:

⚡ Amp 🚀 Antigravity 🤖 Claude Code 🦀 Clawdbot 📝 Codex ▶️ Cursor 🤖 Droid 💎 Gemini CLI 🐙 GitHub Copilot 🪿 Goose 📊 Kilo Code 🔧 Kiro CLI 💻 OpenCode 🦘 Roo Code 🌲 Trae 🏄 Windsurf

Learn more about the SKILL.md standard and how to use these skills with your preferred AI coding agent.