Console Plugin

Console analytics plugin: log all tour events with colored output for debugging analytics integration in development

Overview

The console plugin outputs analytics events to the browser console with colored formatting. It's designed for development and debugging - not for production use.

Installation

No additional dependencies required. The plugin is included with @tour-kit/analytics.

import { consolePlugin } from '@tour-kit/analytics'

Basic Usage

app/providers.tsx

import { AnalyticsProvider, consolePlugin } from '@tour-kit/analytics'

export function Providers({ children }) {
  return (
    <AnalyticsProvider
      config={{
        plugins: [consolePlugin()]
      }}
    >
      {children}
    </AnalyticsProvider>
  )
}

Options

Prop

Type

Custom Prefix

Change the log prefix:

consolePlugin({
  prefix: '📊 Analytics'
})

// Output:
// 📊 Analytics tour_started

Collapsed Groups

Use collapsed console groups to reduce noise:

consolePlugin({
  collapsed: true
})

Events will be logged in collapsed groups that can be expanded in the console.

Custom Colors

Customize colors for different event types:

consolePlugin({
  colors: {
    tour: '#3b82f6',  // Blue
    step: '#22c55e',  // Green
    hint: '#f97316'   // Orange
  }
})

Console Output Format

Each event is logged as a group with the following structure:

🎯 TourKit tour_started
  Tour: onboarding
  Step: welcome (0/5)
  Duration: 1234ms
  Metadata: { source: 'dashboard' }
  Timestamp: 2024-01-20T10:30:00.000Z

Event with Metadata

analytics.track('step_completed', {
  tourId: 'onboarding',
  stepId: 'welcome',
  stepIndex: 0,
  metadata: {
    source: 'dashboard',
    user_type: 'free'
  }
})

Console output:

🎯 TourKit step_completed
  Tour: onboarding
  Step: welcome (0/5)
  Duration: 2340ms
  Metadata: { source: 'dashboard', user_type: 'free' }
  Timestamp: 2024-01-20T10:30:02.340Z

Development Only

Conditionally load the console plugin in development:

lib/analytics.ts

import {
  consolePlugin,
  posthogPlugin,
  type AnalyticsConfig
} from '@tour-kit/analytics'

const isDev = process.env.NODE_ENV === 'development'

export const analyticsConfig: AnalyticsConfig = {
  plugins: [
    ...(isDev ? [consolePlugin({ collapsed: false })] : []),
    posthogPlugin({
      apiKey: process.env.NEXT_PUBLIC_POSTHOG_KEY!
    })
  ]
}

Debugging with Console Plugin

Use the console plugin alongside production plugins to debug:

import {
  AnalyticsProvider,
  consolePlugin,
  posthogPlugin
} from '@tour-kit/analytics'

<AnalyticsProvider
  config={{
    plugins: [
      // See events in console before they're sent
      consolePlugin({ collapsed: false }),
      // Production tracking
      posthogPlugin({ apiKey: 'phc_xxx' })
    ],
    debug: true
  }}
>
  {children}
</AnalyticsProvider>

User Identification

The console plugin also logs user identification:

analytics.identify('user-123', {
  email: '[email protected]',
  plan: 'pro'
})

Console output:

🎯 TourKit User Identified: user-123
{ email: '[email protected]', plan: 'pro' }

Example Output

Tour Started

🎯 TourKit tour_started
  Tour: product-tour
  Duration: 0ms
  Metadata: { totalSteps: 5 }
  Timestamp: 2024-01-20T10:30:00.000Z

Step Viewed

🎯 TourKit step_viewed
  Tour: product-tour
  Step: create-project (1/5)
  Metadata: { source: 'dashboard' }
  Timestamp: 2024-01-20T10:30:01.000Z

Hint Clicked

🎯 TourKit hint_clicked
  Tour: keyboard-shortcuts-hint
  Metadata: { position: 'bottom-right' }
  Timestamp: 2024-01-20T10:30:05.000Z

Best Practices

Do not use the console plugin in production. It adds unnecessary console noise and may expose sensitive event data in browser dev tools.

Recommended Setup

// ✅ Good - Only in development
const plugins = process.env.NODE_ENV === 'development'
  ? [consolePlugin(), productionPlugin()]
  : [productionPlugin()]

// ❌ Bad - Always loaded
const plugins = [consolePlugin(), productionPlugin()]

Debug Alongside Production

// ✅ Good - Debug flag controls console plugin
<AnalyticsProvider
  config={{
    plugins: [
      ...(debug ? [consolePlugin()] : []),
      posthogPlugin({ apiKey: 'phc_xxx' })
    ]
  }}
>
  {children}
</AnalyticsProvider>

Plugin Overview - Plugin system architecture
AnalyticsProvider - Configure analytics
Custom Plugins - Build your own plugin

Console Plugin

On this page