[Docs] Comprehensive TypeScript SDK v4 migration guide - LangChain, LlamaIndex, raw Anthropic SDK

[Sajith15]

Describe the feature or potential improvement

Context:

The Langfuse TypeScript SDK was completely rewritten in v4 (August 2025), moving to an OpenTelemetry-based architecture. This is a significant breaking change from v3. Based on the GitHub Discussions, several teams are hitting friction migrating, particularly around:

1. The new @langfuse/otel package and LangfuseSpanProcessor setup
2. Next.js / edge runtime compatibility (crypto module not available - see discussion 🚀 Langfuse TypeScript SDK v4 is here #8403)
3. Migrating from manual langfuse.trace() + trace.generation() calls to the new OTel span model
4. LangChain.js v0.3 callback handler changes
5. Self-hosted Langfuse users needing specific platform version minimums

What I want to write:

A MIGRATION_V3_V4.md document (or a new docs page) covering:

Section 1 - Core SDK migration
Side-by-side before/after for every major pattern:

• Creating traces manually (v3 langfuse.trace() → v4 OTel span model)
• Scoring (langfuse.score() → v4 equivalent)
• Flushing on shutdown (await langfuse.shutdownAsync() - unchanged)

Section 2 - Framework integrations
Before/after for:

• LangChain.js callback handler setup
• LlamaIndexTS callback system
• Raw OpenAI SDK wrapping via observeOpenAI()
• Anthropic SDK wrapping

Section 3 - Platform-specific gotchas

• Next.js edge runtime (crypto unavailable - workaround: use Node.js runtime for instrumentation)
• Cloudflare Workers
• Self-hosted minimum version requirements

Section 4 - Self-hosted Docker upgrade path

I've gone through the migration myself and hit most of these issues. This guide would have saved me several hours. Is this a PR the docs team would accept? I can also include runnable code examples in a GitHub Gist I can link from the guide.

Additional information

No response

[pratimapatel2008]

Thanks for sharing this. Let me check with our docs team.

[Sajith15]

Sure @pratimapatel2008 , I'd be happy to contribute in updating this if approved!

[pratimapatel2008]

@Sajith15 I have checked internally. Please feel free to submit a PR and our team will review.