# PostHog.js Quick Start Guide

Get started with PostHog.js in minutes.

## Installation

```bash
npm install posthog-js
```

## Basic Setup

### 1. Initialize PostHog

```typescript { .api }
import posthog from 'posthog-js';

posthog.init('<your-project-api-key>', {
    api_host: 'https://us.i.posthog.com',
    loaded: (posthog) => {
        console.log('PostHog loaded!');
    }
});
```

### 2. Track Events

```typescript { .api }
// Capture custom events
posthog.capture('button_clicked', {
    button_id: 'signup',
    location: 'header'
});
```

### 3. Identify Users

```typescript { .api }
// After user logs in
posthog.identify('user-123', {
    email: 'user@example.com',
    name: 'John Doe',
    plan: 'pro'
});
```

### 4. Use Feature Flags

```typescript { .api }
// Check if feature is enabled
if (posthog.isFeatureEnabled('new-dashboard')) {
    showNewDashboard();
} else {
    showOldDashboard();
}
```

### 5. Start Session Recording

```typescript { .api }
// Enable session recording
posthog.startSessionRecording();
```

## Common Patterns

### React Integration

```typescript
import { useEffect } from 'react';
import posthog from 'posthog-js';

function App() {
    useEffect(() => {
        posthog.init('your-api-key', {
            api_host: 'https://us.i.posthog.com',
            capture_pageview: 'history_change'
        });
    }, []);
    
    return <YourApp />;
}
```

### User Lifecycle

```typescript { .api }
// On signup
function handleSignup(userId: string, email: string) {
    posthog.alias(userId);  // Link anonymous events
    posthog.identify(userId, { email });
}

// On logout
function handleLogout() {
    posthog.reset();  // Clear user state
}
```

### Feature Flag with Callback

```typescript { .api }
// Wait for flags to load
posthog.onFeatureFlags((flags) => {
    if (flags['new-feature']) {
        enableNewFeature();
    }
});
```

## Configuration Options

### Essential Settings

```typescript { .api }
posthog.init('your-api-key', {
    // API endpoint
    api_host: 'https://us.i.posthog.com',  // or 'https://eu.i.posthog.com'
    
    // Event capture
    autocapture: true,
    capture_pageview: 'history_change',
    
    // Privacy
    opt_out_capturing_by_default: false,
    
    // Session recording
    session_recording: {
        enabled: true,
        maskAllInputs: true
    },
    
    // Person profiles
    person_profiles: 'identified_only'
});
```

## Next Steps

### Learn More
- **[Best Practices](./best-practices.md)** - Production deployment guide
- **[Reference Documentation](../reference/initialization.md)** - Complete API reference
- **[Examples](../examples/real-world-scenarios.md)** - Real-world usage patterns

### Common Tasks
- **Privacy Compliance** → [Reference: Privacy & Consent](../reference/privacy.md)
- **A/B Testing** → [Reference: Feature Flags](../reference/feature-flags.md)
- **Error Tracking** → [Reference: Error Tracking](../reference/error-tracking.md)
- **Session Replay** → [Reference: Session Recording](../reference/session-recording.md)

## Troubleshooting

### Events Not Appearing?

```typescript { .api }
// Enable debug mode
posthog.debug(true);

// Check status
console.log('Is capturing:', posthog.is_capturing());
console.log('Config:', posthog.config);
```

### Feature Flags Not Working?

```typescript { .api }
// Check if flags loaded
console.log('Flags loaded:', posthog.featureFlags.hasLoadedFlags);

// Force reload
posthog.reloadFeatureFlags();
```

### Need Help?
- Check [troubleshooting sections](../reference/error-tracking.md) in reference docs
- Review [common issues](./best-practices.md#common-anti-patterns-to-avoid)
- Enable debug mode: `posthog.debug(true)`

## Additional Resources

- **PostHog Docs:** https://posthog.com/docs
- **GitHub:** https://github.com/PostHog/posthog-js
- **NPM:** https://www.npmjs.com/package/posthog-js
