docs(realtime): document relationship of accessToken() and heartbeat

[PragTob]

We had feedback, that the access token would become invalid before reaching another heartbeat to be able to refresh, when using a 3rd party auth provider.

This was resolved by longer token life time, but the interplay of accessToken() and when it's called wasn't described in the docs.

I'm not 100% sure if we want to document it in this detail, as it makes it harder for us to change later, but it also feels like this interaction should be documented so users can have better guidance on when to refresh their access tokens to not run into the same issue. I.e. in the sample we got the access token expired at ~148.6s passed and a new heartbeat would have only gone off at ~150s.

📋 Checklist

• I have read the Contributing Guidelines
• My PR title follows the conventional commit format: <type>(<scope>): <description>
• I have run pnpm nx format to ensure consistent code formatting
• I have added tests for new functionality (if applicable)
• I have updated documentation (if applicable)

📝 Additional notes

Documentation is to the best of my (AI-assisted) understanding of how that part of the code works.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Team

Run ID: e654b234-15d6-4085-8eff-572a9da93e37

📥 Commits

Reviewing files that changed from the base of the PR and between 84af33f and 30b91a3.

📒 Files selected for processing (2)

• packages/core/realtime-js/src/RealtimeClient.ts
• packages/core/supabase-js/src/lib/types.ts

Included review availability: Your plan provides up to 8 included reviews per hour; 7 remain after this review.

---

📝 Summary

Summary by CodeRabbit

• Documentation
  • Clarified when the access token callback is called during connection and heartbeat updates.
  • Added guidance on token validity to help prevent Realtime channels from expiring unexpectedly.
  • Documented that Supabase Auth users should leave this option unset; it is intended for third-party authentication providers.

Walkthrough

The pull request adds documentation for accessToken behavior in SupabaseClientOptions and RealtimeClient. The documentation states that Supabase Auth users should leave the option unset. It describes callback execution on connection and each heartbeat. It also requires refreshed tokens to remain valid beyond the next callback to prevent channel expiry without automatic resubscription. No functional code, types, or signatures changed.

Merge Risk: ⚪ Minimal · up to 30b91

This clarifies when Realtime refreshes third-party access tokens and how long tokens must remain valid to avoid channel expiry. No runtime behavior changes, and no current merge-readiness risk remains.

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[pkg-pr-new]

Open in StackBlitz

@supabase/auth-js

npm i https://pkg.pr.new/@supabase/auth-js@2680

@supabase/functions-js

npm i https://pkg.pr.new/@supabase/functions-js@2680

@supabase/postgrest-js

npm i https://pkg.pr.new/@supabase/postgrest-js@2680

@supabase/realtime-js

npm i https://pkg.pr.new/@supabase/realtime-js@2680

@supabase/storage-js

npm i https://pkg.pr.new/@supabase/storage-js@2680

@supabase/supabase-js

npm i https://pkg.pr.new/@supabase/supabase-js@2680

commit: 30b91a3

[coveralls]

Coverage is 95.652% — tobipfeiffer/fdbkin-41306-document-accesstoken-and-heartbeatms-jwt-refresh-behavior into master. No base build found for master.