fix(auth)!: throw when a client has no asyncStorage for the pkce flow

[spydon]

Fixes SDK-2259.

Problem

A plain SupabaseClient(url, key) uses the pkce flow without an asyncStorage. The AuthClient constructor guarded this with an assert, which causes two problems:

• dart run and AOT builds skip asserts, so they fail later at the first pkce call with a null check error, far from the cause.
• The message comes from deep inside supabase_auth and doesn't say the fix belongs in the SupabaseClient constructor.

Changes

• SupabaseClient checks its authOptions before it builds anything else and throws an ArgumentError. The message names the fix (authOptions: AuthClientOptions(asyncStorage: MemoryAuthAsyncStorage()) or the implicit flow). When the code runs inside a package:test test, found through the #test.invoker zone value, the message also points to testSupabaseClient from supabase_test. The JSON isolate the client already spawned is disposed before the throw.
• AuthClient throws an ArgumentError instead of asserting, for both the pkce case and persistSession without a storage. Debug and release builds now fail the same way.
• exchangeCodeForSession throws an AuthException instead of asserting when there is no verifier store. This can still happen with the implicit flow and no storage.
• A SupabaseClient with a third-party accessToken no longer builds an AuthClient at all, since supabase.auth already throws in that mode. Without this, such clients would start throwing in release builds.
• MIGRATION.md gets a section about standalone and server clients needing an asyncStorage, also listed under the changes the compiler won't catch.

Breaking change

A client created without an asyncStorage under the pkce flow used to build fine in release builds. It now throws at construction.

[coderabbitai]

Warning

Review limit reached

You've used all free OSS reviews for now. Wait for the free limit to reset to keep reviewing this public repository.

Next included review available in 34 minutes.

Check out review usage here.

View limit details

Limit details: You’ve used all 4 included reviews currently available.

Learn how review limits work.

Review configuration:

⚙️ Run configuration

• Configuration used: Repository: supabase/supabase-flutter/.coderabbit.yaml
• Review profile: CHILL
• Plan: Advanced
• Run ID: 53b67d64-7370-4a0b-b670-81e2d14152af

📥 Commits

Reviewing files that changed from the base of the PR and between 4c16d3c and c597f88.

📒 Files selected for processing: 5

• MIGRATION.md
• packages/supabase/lib/src/supabase_client.dart
• packages/supabase/test/client_test.dart
• packages/supabase_auth/lib/src/auth_client.dart
• packages/supabase_auth/test/client_test.dart

• Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

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.}