@supabase/supabase-js 2.111.1-canary.0 → 2.112.0-beta.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@supabase/supabase-js",
-  "version": "2.111.1-canary.0",
+  "version": "2.112.0-beta.0",
   "description": "Isomorphic Javascript SDK for Supabase",
   "keywords": [
     "javascript",
@@ -49,26 +49,53 @@
         "default": "./dist/cors.cjs"
       }
     },
+    "./tracing": {
+      "react-native": {
+        "types": "./dist/tracing.d.cts",
+        "default": "./dist/tracing.cjs"
+      },
+      "import": {
+        "types": "./dist/tracing.d.mts",
+        "default": "./dist/tracing.mjs"
+      },
+      "require": {
+        "types": "./dist/tracing.d.cts",
+        "default": "./dist/tracing.cjs"
+      }
+    },
     "./dist/*": "./dist/*",
     "./package.json": "./package.json"
   },
-  "sideEffects": false,
+  "sideEffects": [
+    "./dist/tracing.cjs",
+    "./dist/tracing.mjs",
+    "./src/tracing.ts"
+  ],
   "repository": {
     "type": "git",
     "url": "https://github.com/supabase/supabase-js.git",
     "directory": "packages/core/supabase-js"
   },
   "dependencies": {
-    "@supabase/auth-js": "2.111.1-canary.0",
-    "@supabase/functions-js": "2.111.1-canary.0",
-    "@supabase/realtime-js": "2.111.1-canary.0",
-    "@supabase/storage-js": "2.111.1-canary.0",
-    "@supabase/postgrest-js": "2.111.1-canary.0"
+    "@supabase/auth-js": "2.112.0-beta.0",
+    "@supabase/postgrest-js": "2.112.0-beta.0",
+    "@supabase/realtime-js": "2.112.0-beta.0",
+    "@supabase/functions-js": "2.112.0-beta.0",
+    "@supabase/storage-js": "2.112.0-beta.0"
+  },
+  "peerDependencies": {
+    "@opentelemetry/api": ">=1.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@opentelemetry/api": {
+      "optional": true
+    }
   },
   "devDependencies": {
     "@arethetypeswrong/cli": "^0.18.2",
     "@jest/globals": "^30.0.0",
     "@jest/types": "^30.0.0",
+    "@opentelemetry/api": "^1.9.0",
     "@types/jest": "30.0.0",
     "@types/jsonwebtoken": "^8.5.8",
     "@types/node": "20.19.9",
@@ -129,14 +156,14 @@
     "test:bun": "cd test/integration/bun && bun install && bun test",
     "test:expo": "cd test/integration/expo && npm test",
     "test:next": "cd test/integration/next && npm test",
-    "test:types": "tsd --files test/types/index.test-d.ts && tsd --typings dist/cors.d.cts --files test/types/cors.test-d.ts && jsr publish --dry-run --allow-dirty",
+    "test:types": "tsd --files test/types/index.test-d.ts && tsd --typings dist/cors.d.cts --files test/types/cors.test-d.ts && tsd --typings dist/tracing.d.cts --files test/types/tracing.test-d.ts && jsr publish --dry-run --allow-dirty",
     "test:exports": "attw --pack . --ignore-rules no-resolution",
-    "test:esm": "node test/module-resolution.test.mjs && node test/module-resolution-cors.test.mjs",
-    "test:cjs": "node test/module-resolution.test.cjs && node test/module-resolution-cors.test.cjs",
+    "test:esm": "node test/module-resolution.test.mjs && node test/module-resolution-cors.test.mjs && node test/module-resolution-tracing.test.mjs",
+    "test:cjs": "node test/module-resolution.test.cjs && node test/module-resolution-cors.test.cjs && node test/module-resolution-tracing.test.cjs",
     "test:hermes-compat": "node test/bundle-hermes-compat.test.cjs",
     "test:module-resolution": "npm run test:exports && npm run test:esm && npm run test:cjs && npm run test:hermes-compat",
-    "docs": "typedoc --options ../../../typedoc.base.mjs --entryPoints src/index.ts --entryPoints src/cors.ts --out docs/v2",
-    "docs:json": "typedoc --options ../../../typedoc.base.mjs --entryPoints src/index.ts --entryPoints src/cors.ts --json docs/v2/spec.json --excludeExternals",
+    "docs": "typedoc --options ../../../typedoc.base.mjs --entryPoints src/index.ts --entryPoints src/cors.ts --entryPoints src/tracing.ts --out docs/v2",
+    "docs:json": "typedoc --options ../../../typedoc.base.mjs --entryPoints src/index.ts --entryPoints src/cors.ts --entryPoints src/tracing.ts --json docs/v2/spec.json --excludeExternals",
     "serve:coverage": "pnpm nx test:coverage supabase-js && pnpm dlx serve test/coverage",
     "update:test-deps": "pnpm run update:test-deps:expo && pnpm run update:test-deps:next && pnpm run update:test-deps:deno && pnpm run update:test-deps:bun",
     "update:test-deps:expo": "cd test/integration/expo && pnpm install --ignore-workspace",

package/src/SupabaseClient.ts

@@ -288,10 +288,12 @@ export default class SupabaseClient<
    * Opt in to W3C trace context propagation so the `trace_id` from your
    * client-side spans is attached to Supabase requests and appears in API
    * Gateway and Edge Function logs. Requires `@opentelemetry/api` to be
-   * installed in your application. See [Tracing with the JS SDK](https://supabase.com/docs/guides/telemetry/client-side-tracing).
+   * installed in your application and the tracing runtime to be loaded via
+   * `import '@supabase/supabase-js/tracing'`. See [Tracing with the JS SDK](https://supabase.com/docs/guides/telemetry/client-side-tracing).
    *
    * @example With OpenTelemetry tracing
    * ```ts
+   * import '@supabase/supabase-js/tracing'
    * import { createClient } from '@supabase/supabase-js'
    * import { trace } from '@opentelemetry/api'
    *

package/src/lib/fetch.ts

@@ -1,11 +1,11 @@
 import {
-  extractTraceContext,
   parseTraceParent,
   shouldPropagateToTarget,
   getDefaultPropagationTargets,
   type TraceContext,
   type TracePropagationTarget,
 } from '@supabase/tracing'
+import { getTraceContextExtractor } from './tracingRegistry'
 import type { TracePropagationOptions } from './types'
 
 type Fetch = typeof fetch
@@ -95,7 +95,7 @@ export const fetchWithAuth = (
     }
 
     if (traceTargets) {
-      const traceHeaders = await getTraceHeaders(input, traceTargets, respectSampling)
+      const traceHeaders = getTraceHeaders(input, traceTargets, respectSampling)
 
       if (traceHeaders) {
         if (traceHeaders.traceparent && !headers.has('traceparent')) {
@@ -114,11 +114,43 @@ export const fetchWithAuth = (
   }
 }
 
-async function getTraceHeaders(
+let warnedMissingTracingRuntime = false
+
+/**
+ * For tests only. Resets the one-time missing-tracing-runtime warning.
+ *
+ * @internal
+ */
+export function _resetTracingRuntimeWarning(): void {
+  warnedMissingTracingRuntime = false
+}
+
+function getTraceHeaders(
   input: RequestInfo | URL,
   targets: TracePropagationTarget[],
   respectSampling: boolean
-): Promise<TraceContext | null> {
+): TraceContext | null {
+  // Read the registry before the target check so the warning fires on the
+  // first request with tracing enabled, not only on Supabase-target ones.
+  // Reading per request (one globalThis property access) deliberately
+  // supports late registration: with ESM evaluation order, `createClient`
+  // can run in a module evaluated before the application entry point's
+  // `import '@supabase/supabase-js/tracing'`.
+  const extractTraceContext = getTraceContextExtractor()
+
+  if (!extractTraceContext) {
+    if (!warnedMissingTracingRuntime) {
+      warnedMissingTracingRuntime = true
+      console.warn(
+        '@supabase/supabase-js: tracePropagation is enabled but the tracing runtime is not loaded, ' +
+          "so trace headers will not be attached. Add `import '@supabase/supabase-js/tracing'` at " +
+          'your application entry point (requires the OpenTelemetry API package to be installed). ' +
+          'The CDN/UMD build does not support trace propagation.'
+      )
+    }
+    return null
+  }
+
   const targetUrl: string | URL =
     typeof input === 'string' ? input : input instanceof URL ? input : input.url
 
@@ -126,7 +158,7 @@ async function getTraceHeaders(
     return null
   }
 
-  const traceContext = await extractTraceContext()
+  const traceContext = extractTraceContext()
 
   if (!traceContext || !traceContext.traceparent) {
     return null

package/src/lib/tracingRegistry.ts

@@ -0,0 +1,42 @@
+import type { TraceContextExtractor } from '@supabase/tracing'
+
+export type { TraceContextExtractor }
+
+// The extractor lives in a `Symbol.for()`-keyed slot on `globalThis` rather
+// than a module-level variable. Bundlers and the ESM/CJS dual build can load
+// this module more than once in a single application (e.g. the tracing
+// subpath resolved to `dist/tracing.mjs` while the main entry resolves to
+// `dist/index.cjs`) — separate module instances would each get their own
+// variable, but they all share the global symbol registry.
+//
+// The symbol string is a de-facto stable contract: module-resolution tests
+// read the slot directly, and changing it orphans registrations from other
+// copies of this package in the same process.
+const EXTRACTOR_KEY = Symbol.for('@supabase/supabase-js.traceContextExtractor')
+
+type ExtractorSlot = { [EXTRACTOR_KEY]?: TraceContextExtractor }
+
+/**
+ * Register the trace context extractor used by all Supabase clients in this
+ * process. Called by the `@supabase/supabase-js/tracing` subpath as an import
+ * side effect; the last registration wins.
+ */
+export function registerTraceContextExtractor(extractor: TraceContextExtractor): void {
+  ;(globalThis as ExtractorSlot)[EXTRACTOR_KEY] = extractor
+}
+
+/**
+ * The currently registered trace context extractor, if any.
+ */
+export function getTraceContextExtractor(): TraceContextExtractor | undefined {
+  return (globalThis as ExtractorSlot)[EXTRACTOR_KEY]
+}
+
+/**
+ * For tests only. Removes the registered extractor.
+ *
+ * @internal
+ */
+export function _unregisterTraceContextExtractor(): void {
+  delete (globalThis as ExtractorSlot)[EXTRACTOR_KEY]
+}

package/src/lib/types.ts

@@ -35,12 +35,17 @@ export type Fetch = typeof fetch
  * Gateway and Edge Function logs, so logs forwarded through Log Drains can
  * be correlated back to the originating client-side span.
  *
- * Requires `@opentelemetry/api` to be installed in the consuming application.
- * If it is not installed, or there is no active context at request time,
- * propagation silently no-ops.
+ * Requires two opt-in steps: install `@opentelemetry/api` in the consuming
+ * application, and load the tracing runtime with
+ * `import '@supabase/supabase-js/tracing'` at the application entry point.
+ * If the runtime is not loaded, the SDK logs a one-time warning and sends
+ * requests without trace headers; if there is no active context at request
+ * time, propagation silently no-ops. Not available via the CDN/UMD build.
  *
  * @example Enable with defaults
  * ```ts
+ * import '@supabase/supabase-js/tracing'
+ *
  * const supabase = createClient(url, key, {
  *   tracePropagation: { enabled: true },
  * })
@@ -63,6 +68,8 @@ export interface TracePropagationOptions {
    *
    * @example
    * ```ts
+   * import '@supabase/supabase-js/tracing'
+   *
    * const supabase = createClient(url, key, {
    *   tracePropagation: { enabled: true },
    * })
@@ -85,6 +92,8 @@ export interface TracePropagationOptions {
    *
    * @example Always propagate, ignore sampling
    * ```ts
+   * import '@supabase/supabase-js/tracing'
+   *
    * const supabase = createClient(url, key, {
    *   tracePropagation: { enabled: true, respectSamplingDecision: false },
    * })
@@ -262,10 +271,13 @@ export type SupabaseClientOptions<SchemaName> = {
    * active OpenTelemetry context and inject `traceparent` / `tracestate` /
    * `baggage` headers) or an object for fine-grained control.
    *
-   * Requires `@opentelemetry/api` to be installed in your application; if
-   * not present, the SDK silently no-ops. Trace headers are only attached
-   * to requests targeting Supabase domains, so third-party hosts called
-   * through a custom `fetch` are never tagged.
+   * Requires `@opentelemetry/api` to be installed in your application AND
+   * the tracing runtime to be loaded with
+   * `import '@supabase/supabase-js/tracing'` at your application entry
+   * point. Without that import, the SDK logs a one-time warning and sends
+   * requests without trace headers. Not available via the CDN/UMD build.
+   * Trace headers are only attached to requests targeting Supabase domains,
+   * so third-party hosts called through a custom `fetch` are never tagged.
    *
    * The resulting `trace_id` appears in Supabase logs (API Gateway, Edge
    * Functions), letting you correlate client-side spans with server-side
@@ -273,6 +285,7 @@ export type SupabaseClientOptions<SchemaName> = {
    *
    * @example Shorthand — opt in with defaults
    * ```ts
+   * import '@supabase/supabase-js/tracing'
    * import { createClient } from '@supabase/supabase-js'
    *
    * const supabase = createClient(url, key, { tracePropagation: true })
@@ -280,6 +293,7 @@ export type SupabaseClientOptions<SchemaName> = {
    *
    * @example With an active OpenTelemetry span
    * ```ts
+   * import '@supabase/supabase-js/tracing'
    * import { createClient } from '@supabase/supabase-js'
    * import { trace } from '@opentelemetry/api'
    *
@@ -295,6 +309,8 @@ export type SupabaseClientOptions<SchemaName> = {
    *
    * @example Advanced — always propagate, even for non-sampled traces
    * ```ts
+   * import '@supabase/supabase-js/tracing'
+   *
    * const supabase = createClient(url, key, {
    *   tracePropagation: { enabled: true, respectSamplingDecision: false },
    * })

package/src/lib/version.ts

@@ -4,4 +4,4 @@
 // - Debugging and support (identifying which version is running)
 // - Telemetry and logging (version reporting in errors/analytics)
 // - Ensuring build artifacts match the published package version
-export const version = '2.111.1-canary.0'
+export const version = '2.112.0-beta.0'

package/src/tracing.ts

@@ -0,0 +1,26 @@
+/**
+ * Opt-in OpenTelemetry runtime for `tracePropagation`.
+ *
+ * Importing this module registers the OpenTelemetry trace context extractor
+ * used by every Supabase client in the process. It has no exports — the
+ * import itself is the opt-in:
+ *
+ * ```ts
+ * import '@supabase/supabase-js/tracing'
+ * import { createClient } from '@supabase/supabase-js'
+ *
+ * const supabase = createClient(url, key, { tracePropagation: true })
+ * ```
+ *
+ * Requires `@opentelemetry/api` to be installed — this module imports it
+ * directly, so bundlers include it and resolution fails loudly when it is
+ * missing. Without this import, enabling `tracePropagation` logs a one-time
+ * warning and requests are sent without trace headers.
+ *
+ * @module tracing
+ */
+import { propagation, context } from '@opentelemetry/api'
+import { createTraceContextExtractor } from '@supabase/tracing'
+import { registerTraceContextExtractor } from './lib/tracingRegistry'
+
+registerTraceContextExtractor(createTraceContextExtractor({ propagation, context }))