feat: separate entry point for dynamic imports

[mandarini]

What kind of change does this PR introduce?

This PR introduces a temporary solution to address critical bundler issues with dynamic imports while providing a bridge to v3. It creates two distinct entry points: a bundler-safe main export and a temporary auto-detection export for Node.js compatibility.

What is the current behavior?

The current implementation uses dynamic imports in the main export, causing several critical issues:

• Bundler warnings: Webpack shows Critical dependency: the request of a dependency is an expression
• Deployment issues: Various edge runtimes fail due to dynamic import restrictions

Current problematic code in Node.js environments:

// This causes bundler issues due to dynamic require()
import { RealtimeClient } from "@supabase/realtime-js" 
const client = new RealtimeClient(url) // Works in Node.js but breaks bundlers

What is the new behavior?

🚀 Main Export - Bundler Safe

The main export removes all dynamic imports to eliminate bundler issues:

// ✅ Main export - No bundler warnings, explicit control
import { RealtimeClient } from "@supabase/realtime-js"
import ws from "ws" // Required for Node.js < 22

const client = new RealtimeClient(url, { transport: ws })

Inconvenience: Node.js < 22 users must now provide WebSocket transport explicitly.

🔧 Temporary Auto Export - Dynamic Loading

For users who need automatic WebSocket detection (with bundler trade-offs):

// ⚠️  Temporary solution - will be removed in v3
import { RealtimeClient } from "@supabase/realtime-js/auto"
const client = new RealtimeClient(url) // Auto-detects WebSocket

Additional information

⚠️ Breaking change for Node.js < 22 users only

// ❌ Before - worked but caused bundler issues
import { RealtimeClient } from "@supabase/realtime-js"
const client = new RealtimeClient(url)

// ✅ After - explicit transport required  
import { RealtimeClient } from "@supabase/realtime-js"
import ws from "ws"
const client = new RealtimeClient(url, { transport: ws })

// 🔄 Temporary bridge - use /auto (will be removed in v3)
import { RealtimeClient } from "@supabase/realtime-js/auto"  
const client = new RealtimeClient(url)

Browser and Node.js 22+ users**

No changes required.

📦 Package Structure

{
  "exports": {
    ".": {
      "types": "./dist/module/index.d.ts",
      "import": "./dist/module/index.js",      // No dynamic imports
      "require": "./dist/main/index.js"        // No dynamic imports  
    },
    "./auto": {
      "types": "./dist/module/index.auto.d.ts", 
      "import": "./dist/module/index.auto.js",  // Has dynamic imports
      "require": "./dist/main/index.auto.js"    // Has dynamic imports
    }
  }
}

🔍 Technical Details

• Main export: Clean WebSocket factory without dynamic imports
• Auto export: Extends main factory with dynamic ws loading
• Improved errors: Clear guidance when WebSocket is unavailable
• Fallback strategy: Auto export tries native first, then dynamic loading

🗺️ Roadmap

• v2.x: Dual exports (main = explicit, auto = dynamic)
• v3.0: Single export with mandatory explicit transport for Node.js < 22
• Goal: Zero dynamic imports, maximum bundler compatibility

Why This Is Not a Breaking Change

While the main export behavior changes for Node.js < 22 users, this is not considered a breaking change for the following reasons:

Current Implementation Is Already Broken

The existing dynamic import approach already fails in many production environments:

// Current code that appears to "work" but actually breaks:
import { RealtimeClient } from "@supabase/realtime-js";
const client = new RealtimeClient(url);

Production failures include:

• Webpack bundler warnings and potential build failures
• Runtime crashes
• Deployment failures in various edge runtimes
• Critical dependency warnings that can break CI/CD pipelines

We Provide a Compatibility Path

Users who need the previous (problematic) behavior can use the /auto export:

// Exact same functionality as before, just different import path
import { RealtimeClient } from "@supabase/realtime-js/auto"
const client = new RealtimeClient(url) // ✅ Works exactly like before

Impact Analysis

• Browser users: No change required - continues working identically
• Node.js 22+ users: No change required - continues working identically
• Node.js < 22 users:
  • Production apps (affected by bundler issues): This is a fix - they can use transport
  • Development/testing: Can use /auto for identical behavior

Fix Rather Than Break

This change fixes broken functionality rather than breaking working functionality:

// Before: Appeared to work but caused production issues
import { RealtimeClient } from "@supabase/realtime-js"
const client = new RealtimeClient(url) // Bundler warnings, runtime failures

// After: Clear, working solutions
// Option 1: Production-ready (recommended)
import { RealtimeClient } from "@supabase/realtime-js" 
import ws from "ws"
const client = new RealtimeClient(url, { transport: ws })

// Option 2: Same as before, explicit import path
import { RealtimeClient } from "@supabase/realtime-js/auto"
const client = new RealtimeClient(url)