--- 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: 1. Analyzing the project structure 2. Installing the appropriate SDK package 3. Setting up framework-specific configuration 4. Integrating with authentication providers 5. Implementing consent management (GDPR compliance) 6. Adding custom event tracking ## Installation To add this skill to your Claude Code environment: ```sh 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: ```bash 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: ```bash # 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:** ```bash # .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:** ```bash # .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](references/frameworks.md) for complete patterns. #### React Copy template from `assets/react/OutlitProvider.tsx` and modify as needed: ```tsx import { OutlitProvider } from '@outlit/browser/react' function App() { return ( ) } ``` #### Next.js App Router Copy template from `assets/nextjs/layout.tsx`: ```tsx // app/layout.tsx import { OutlitProvider } from '@outlit/browser/react' export default function RootLayout({ children }) { return ( {children} ) } ``` #### 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](references/frameworks.md) reference. ### Step 5: Auth Integration (If Detected) If an auth provider was detected, integrate it with Outlit. See [auth-providers.md](references/auth-providers.md) for patterns. **Common pattern:** ```tsx {children} ``` **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](references/consent-management.md). **Basic pattern:** ```tsx {!hasConsent && } {children} ``` 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:** ```tsx import { useOutlit } from '@outlit/browser/react' function MyComponent() { const { track, user } = useOutlit() const handleUpgrade = () => { track('subscription_upgraded', { plan: 'pro' }) user.activate({ milestone: 'upgraded' }) } return } ``` **Server example:** ```ts import { outlit } from '@/lib/outlit' outlit.track({ email: 'user@example.com', eventName: 'subscription_created', properties: { plan: 'pro' } }) await outlit.flush() ``` See [patterns.md](references/patterns.md) for event taxonomy and best practices. ### Step 8: Verify Installation Guide users to verify the installation: 1. **Check Network Tab:** - Open DevTools → Network - Look for requests to `app.outlit.ai/api/i/v1/...` - Status 200 = working correctly 2. **Check Outlit Dashboard:** - Visit Outlit dashboard - Navigate to Events or Live View - Verify events appear in real-time 3. **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 1. Verify public key has correct framework prefix (`NEXT_PUBLIC_`, `VITE_`, `REACT_APP_`) 2. Confirm `OutlitProvider` wraps entire app 3. Check `isTrackingEnabled()` if using consent management 4. 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](references/api-reference.md). **Key imports:** ```ts // 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](references/frameworks.md)** — Framework-specific integration patterns (React, Next.js, Vue, Express, etc.) - **[auth-providers.md](references/auth-providers.md)** — Auth provider integration (Clerk, NextAuth, Supabase, Auth0, etc.) - **[consent-management.md](references/consent-management.md)** — GDPR-compliant consent management patterns - **[api-reference.md](references/api-reference.md)** — Complete API reference for all SDK methods - **[patterns.md](references/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 1. **Identify Early**: Call `identify()` as soon as user info is available 2. **Include Both IDs**: Provide both email and userId for identity resolution 3. **Flush in Serverless**: Always `await outlit.flush()` before function exits 4. **Track Lifecycle**: Use `user.activate()`, `customer.paid()` for milestones 5. **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