| 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
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:
./scripts/install_sdk.sh @outlit/browser
npm install @outlit/browser
npm install @outlit/node
npm install @outlit/core
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:
NEXT_PUBLIC_OUTLIT_KEY=pk_xxx
REACT_APP_OUTLIT_KEY=pk_xxx
VITE_OUTLIT_KEY=pk_xxx
Server apps:
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:
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 configurationexpress-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
Step 6: Consent Management (Optional)
For GDPR compliance, implement consent management. See consent-management.md.
Basic pattern:
<OutlitProvider
publicKey="pk_xxx"
autoTrack={hasConsent}
>
{!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: 'user@example.com',
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:
import { OutlitProvider, useOutlit } from '@outlit/browser/react'
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 environmentinstall_sdk.sh — Install Outlit SDK with detected package manager
Templates
Ready-to-use code templates in assets/:
react/ — OutlitProvider, useTracking hook, ConsentBannernextjs/ — App Router layout, Pages Router _app, API routes, Server Actionsnode/ — 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:
