From 66df16cdff76a0d2940073e0bcb17db22347f3c3 Mon Sep 17 00:00:00 2001
From: Tyler <18113850+dshukertjr@users.noreply.github.com>
Date: Fri, 21 Oct 2022 21:12:06 +0900
Subject: [PATCH] fix: apply redirect for links to the old Dart docs (#9724)
* fix: update some old flutter code to the current version
* feat: add flutter upgrade guides until stream
* fix: make primaryKey named parameter in flutter docs
* complete flutter upgrade guide
* add redirects for incoming traffic for old dart docs
---
.../_supabase_dart/upgrade-guide.mdx | 499 ++++++++++++++++++
apps/reference/nav/supabase_dart_sidebars.js | 4 +-
apps/www/lib/redirects.js | 55 ++
spec/supabase_dart_v1.yml | 89 ++--
4 files changed, 591 insertions(+), 56 deletions(-)
create mode 100644 apps/reference/_supabase_dart/upgrade-guide.mdx
diff --git a/apps/reference/_supabase_dart/upgrade-guide.mdx b/apps/reference/_supabase_dart/upgrade-guide.mdx
new file mode 100644
index 00000000000..da6a3e6188d
--- /dev/null
+++ b/apps/reference/_supabase_dart/upgrade-guide.mdx
@@ -0,0 +1,499 @@
+---
+id: upgrade-guide
+title: Upgrade to supabase-flutter v1
+description: 'Learn how to upgrade to supabase-flutter v1.'
+---
+
+import Tabs from '@theme/Tabs'
+import TabItem from '@theme/TabItem'
+
+supabase-flutter focuses on improving the developer experience and making it easier to use. This guide will help you upgrade from supabase-flutter v0 to v1.
+
+## Upgrade the client library
+
+Update the package in your pubspec.yaml file.
+
+```yaml
+supabase_flutter: ^1.0.0
+```
+
+## Error handling
+
+The way supabase-flutter throws error has changed in v1. In v0, errors were returned as a response. In v1, errors are thrown as exceptions. This makes it more intuitive as a Flutter developer to handle errors.
+
+
+
+
+
+
+```dart
+final res = await supabase.from('my_table').select().execute();
+final error = res.error;
+if(error != null) {
+ // handle error
+}
+final data = res.data;
+```
+
+
+
+
+```dart
+try {
+ final data = supabase.from('my_table').select();
+} catch (error) {
+ // handle error
+}
+```
+
+
+
+
+
+## Auth methods
+
+The signIn() method has been deprecated in favor of more explicit method signatures to help with type hinting. Previously it was difficult for developers to know what they were missing (e.g., a lot of developers didn't realize they could use passwordless magic links).
+
+### Listening to auth state change
+
+`onAuthStateChange` now returns a `Stream`.
+
+
+
+
+
+```dart
+final authSubscription = supabase.auth.onAuthStateChange((event, session) {
+ // handle auth state change
+});
+
+// Unsubscribe when no longer needed
+authSubscription.data?.unsubscribe();
+```
+
+
+
+
+```dart
+final authSubscription = supabase.auth.onAuthStateChange.listen((data) {
+ final AuthChangeEvent event = data.event;
+ final Session? session = data.session;
+ // handle auth state change
+ });
+
+// Unsubscribe when no longer needed
+authSubscription.cancel();
+```
+
+
+
+### Sign in with email and password
+
+
+
+
+
+```dart
+await supabase.auth.signIn(email: email, password: password);
+```
+
+
+
+
+```dart
+await supabase.auth.signInWithPassword(email: email, password: password);
+```
+
+
+
+### Sign in with magic link
+
+
+
+
+```dart
+await supabase.auth.signIn(email: email);
+```
+
+
+
+
+```dart
+await supabase.auth.signInWithOtp(email: email);
+```
+
+
+
+### Sign in with a third-party OAuth provider
+
+
+
+
+```dart
+await supabase.auth.signInWithProvider(
+ Provider.github,
+ options: AuthOptions(
+ redirectTo: kIsWeb
+ ? null
+ : 'io.supabase.flutter://reset-callback/'),
+);
+```
+
+
+
+
+```dart
+await supabase.auth.signInWithOAuth(
+ Provider.github,
+ redirectTo: kIsWeb ? null : 'io.supabase.flutter://reset-callback/',
+);
+```
+
+
+
+### Sign in with phone
+
+
+
+
+```dart
+await supabase.auth.signIn(
+ phone: '+13334445555',
+ password: 'example-password',
+);
+```
+
+
+
+
+```dart
+await supabase.auth.signInWithPassword(
+ phone: '+13334445555',
+ password: 'example-password',
+);
+```
+
+
+
+### Sign in with phone using OTP
+
+
+
+
+```dart
+final res = await supabase.auth.signIn(phone: phone);
+```
+
+
+
+
+```dart
+await supabase.auth.signInWithOtp(
+ phone: phone,
+);
+
+// After receiving a SMS with a OTP.
+await supabase.auth.verifyOTP(
+ type: OtpType.sms,
+ token: token,
+ phone: phone,
+);
+```
+
+
+
+### Reset password for email
+
+
+
+
+```dart
+await supabase.auth.api.resetPasswordForEmail(
+ email,
+ options:
+ AuthOptions(redirectTo: 'io.supabase.flutter://reset-callback/'),
+);
+```
+
+
+
+
+```dart
+await supabase.auth.resetPasswordForEmail(
+ email,
+ redirectTo: kIsWeb ? null : 'io.supabase.flutter://reset-callback/',
+);
+```
+
+
+
+### Get the user's current session
+
+
+
+
+```dart
+ final session = supabase.auth.session();
+```
+
+
+
+
+```dart
+final Session? session = supabase.auth.currentSession;
+```
+
+
+
+### Get the logged-in user
+
+
+
+
+```dart
+final user = supabase.auth.user();
+```
+
+
+
+
+```dart
+final User? user = supabase.auth.currentUser;
+```
+
+
+
+### Update user data for a logged-in user
+
+
+
+
+```dart
+await supabase.auth.update(
+ UserAttributes(data: {'hello': 'world'})
+);
+```
+
+
+
+
+```dart
+await supabase.updateUser(
+ UserAttributes(
+ data: { 'hello': 'world' },
+ ),
+);
+```
+
+
+
+## Data methods
+
+`.insert()` / `.upsert()` / `.update()` / `.delete()` don't return rows by default.
+
+Previously, these methods return inserted/updated/deleted rows by default (which caused [some confusion](https://github.com/supabase/supabase/discussions/1548)), and you can opt to not return it by specifying `returning: 'minimal'`. Now the default behavior is to not return rows. To return inserted/updated/deleted rows, add a `.select()` call at the end.
+
+Also, calling `.execute()` at the end of the query was a requirement in v0, but in v1 `.execute` is deperecated.
+
+### Insert without returning inserted data
+
+
+
+
+
+```dart
+await supabase
+ .from('my_table')
+ .insert(data, returning: ReturningOption.minimal)
+ .execute();
+
+```
+
+
+
+
+```dart
+await supabase.from('my_table').insert(data);
+```
+
+
+
+### Insert with returning inserted data
+
+
+
+
+
+```dart
+final res = await supabase
+ .from('my_table')
+ .insert(data)
+ .execute();
+```
+
+
+
+
+```dart
+final insertedData = await supabase.from('my_table').insert(data).select();
+```
+
+
+
+## Realtime methods
+
+### Stream
+
+`.stream()` no longer needs the `.execute()` at the end. Also, filtering by `eq` is a lot easier now. `primaryKey` is now a named parameter to make it more obvious what to pass.
+
+
+
+
+
+```dart
+supabase.from('my_table:id=eq.120')
+ .stream(['id'])
+ .listen();
+```
+
+
+
+
+```dart
+supabase.from('my_table')
+ .stream(primaryKey: ['id'])
+ .eq('id', '120')
+ .listen();
+```
+
+
+
+### Subscribe
+
+
+
+
+
+```dart
+final subscription = supabase
+ .from('countries')
+ .on(SupabaseEventTypes.all, (payload) {
+ // Handle realtime payload
+ })
+ .subscribe();
+```
+
+
+
+
+```dart
+final channel = supabase.channel('*');
+channel.on(
+ RealtimeListenTypes.postgresChanges,
+ ChannelFilter(event: '*', schema: '*'),
+ (payload, [ref]) {
+ // Handle realtime payload
+ },
+).subscribe();
+```
+
+
+
+### Unsubscribe
+
+
+
+
+
+```dart
+supabase.removeSubscription(subscription);
+```
+
+
+
+
+```dart
+await supabase.removeChannel(channel);
+```
+
+
\ No newline at end of file
diff --git a/apps/reference/nav/supabase_dart_sidebars.js b/apps/reference/nav/supabase_dart_sidebars.js
index b98e3b02558..106bf0ca333 100644
--- a/apps/reference/nav/supabase_dart_sidebars.js
+++ b/apps/reference/nav/supabase_dart_sidebars.js
@@ -6,7 +6,7 @@ const sidebars = {
{
type: 'category',
label: 'Getting Started',
- items: ['intro', 'installing', 'initializing'],
+ items: ['intro', 'installing', 'initializing', 'upgrade-guide'],
collapsed: true,
},
{
@@ -23,7 +23,7 @@ const sidebars = {
'generated/auth-currentuser',
'generated/auth-updateuser',
'generated/auth-onauthstatechange',
- 'generated/reset-password-email',
+ 'generated/auth-resetpasswordforemail',
],
collapsed: true,
},
diff --git a/apps/www/lib/redirects.js b/apps/www/lib/redirects.js
index bed6e889a50..9c9c0335d0e 100644
--- a/apps/www/lib/redirects.js
+++ b/apps/www/lib/redirects.js
@@ -1475,4 +1475,59 @@ module.exports = [
source: '/docs/reference/javascript/getsubscriptions',
destination: '/docs/reference/javascript/v1/getsubscriptions',
},
+
+ // supabase-flutter v0 to v1 redirects
+ // v0: /auth-update
+ // v1: /auth-updateuser
+ {
+ permanent: true,
+ source: '/docs/reference/dart/auth-update',
+ destination: '/docs/reference/dart/auth-updateuser',
+ },
+ // v0: /auth-api-resetpasswordforemail
+ // v1: /auth-resetpasswordforemail
+ {
+ permanent: true,
+ source: '/docs/reference/dart/reset-password-email',
+ destination: '/docs/reference/dart/auth-resetpasswordforemail',
+ },
+ // signIn method is now split into signInWithPassword ,signInWithPasswordless ,signInWithOAuth
+ // send traffic to v0 docs instead
+ {
+ permanent: true,
+ source: '/docs/reference/dart/auth-signin',
+ destination: '/docs/reference/dart/v0/auth-signin',
+ },
+ // v0: /auth-session
+ // v1: /auth-currentsession
+ {
+ permanent: true,
+ source: '/docs/reference/dart/auth-session',
+ destination: '/docs/reference/dart/auth-currentsession',
+ },
+ // v0: /auth-user
+ // v1: /auth-currentuser
+ {
+ permanent: true,
+ source: '/docs/reference/dart/auth-user',
+ destination: '/docs/reference/dart/auth-currentuser',
+ },
+ // v0: /auth-signinwithprovider
+ // v1: /auth-signinwithoauth
+ {
+ permanent: true,
+ source: '/docs/reference/dart/v0/auth-signinwithprovider',
+ destination: '/docs/reference/dart/auth-signinwithoauth',
+ },
+ // realtime methods been replaced with new names
+ {
+ permanent: true,
+ source: '/docs/reference/dart/removesubscription',
+ destination: '/docs/reference/dart/v0/removesubscription',
+ },
+ {
+ permanent: true,
+ source: '/docs/reference/dart/getsubscriptions',
+ destination: '/docs/reference/dart/v0/getsubscriptions',
+ },
]
diff --git a/spec/supabase_dart_v1.yml b/spec/supabase_dart_v1.yml
index c90740c4a2d..5ea1953b524 100644
--- a/spec/supabase_dart_v1.yml
+++ b/spec/supabase_dart_v1.yml
@@ -100,7 +100,7 @@ pages:
dart: |
```dart
await supabase.auth.signInWithOtp(
- phone: 'example@email.com',
+ phone: '+13334445555',
);
```
auth.signInWithOAuth():
@@ -115,7 +115,7 @@ pages:
isSpotlight: true
dart: |
```dart
- await supabase.auth.signInWithProvider(Provider.github);
+ await supabase.auth.signInWithOAuth(Provider.github);
```
- name: With `redirectTo`
description: |
@@ -123,11 +123,9 @@ pages:
Note that `redirectTo` should be null for Flutter Web.
dart: |
```dart
- await supabase.auth.signInWithProvider(
+ await supabase.auth.signInWithOAuth(
Provider.github,
- options: const AuthOptions(
- redirectTo: kIsWeb ? null : 'io.supabase.flutter://reset-callback/',
- ),
+ redirectTo: kIsWeb ? null : 'io.supabase.flutter://reset-callback/',
);
```
- name: With scopes
@@ -136,8 +134,10 @@ pages:
You may also need to specify the scopes in the provider's OAuth app settings, depending on the provider.
dart: |
```dart
- await supabase.auth.signInWithProvider(Provider.github,
- options: const AuthOptions(scopes: 'repo gist notifications'));
+ await supabase.auth.signInWithOAuth(
+ Provider.github,
+ scopes: 'repo gist notifications'
+ );
...
// after user comes back from signin flow
@@ -263,71 +263,52 @@ pages:
isSpotlight: true
dart: |
```dart
- final subscription = supabase.auth.onAuthStateChange(
- (event, session) {
- print(session?.user.id);
- // handle auth state change
- },
- );
+ final authSubscription = supabase.auth.onAuthStateChange.listen((data) {
+ final AuthChangeEvent event = data.event;
+ final Session? session = data.session;
+ });
```
- name: Listen to a specific event
dart: |
```dart
- final subscription = supabase.auth.onAuthStateChange(
- (event, session) {
- if (event == AuthChangeEvent.signedIn) {
- print(session?.user.id);
- // handle signIn
- }
- },
- );
+ final authSubscription = supabase.auth.onAuthStateChange.listen((data) {
+ final AuthChangeEvent event = data.event;
+ if (event == AuthChangeEvent.signedIn) {
+ // handle signIn
+ }
+ });
```
- name: Unsubscribe from auth subscription
dart: |
```dart
- final subscription = supabase.auth.onAuthStateChange((event, session) {});
+ final authSubscription = supabase.auth.onAuthStateChange((event, session) {});
- subscription.data?.unsubscribe();
+ authSubscription.cancel();
```
- Reset Password (Email):
+ auth.resetPasswordForEmail:
+ title: 'resetPasswordForEmail()'
description: |
Sends a reset request to an email address.
notes: |
- Sends a reset request to an email address.
-
- When the user clicks the reset link in the email they will be forwarded to:
-
- `#access_token=x&refresh_token=y&expires_in=z&token_type=bearer&type=recovery`
-
- Your app must detect `type=recovery` in the fragment and display a password reset form to the user.
-
- You should then use the access_token in the url and new password to update the user as follows:
+ Sends a password reset request to an email address. When the user clicks the reset link in the email they are redirected back to your application. Prompt the user for a new password and call auth.updateUser():
```dart
- final res = await supabase.auth.api.updateUser(
- accessToken,
- UserAttributes(password: 'NEW_PASSWORD'),
+ await supabase.auth.resetPasswordForEmail(
+ 'sample@email.com',
+ redirectTo: kIsWeb ? null : 'io.supabase.flutter://reset-callback/',
);
```
examples:
- name: Reset password for Flutter
isSpotlight: true
dart: |
- You can pass `redirectTo` to open the app via deeplink when user opens the password reset email.
+ `redirectTo` is used to open the app via deeplink when user opens the password reset email.
```dart
- final res = await supabase.auth.api.resetPasswordForEmail(
- 'user@example.com',
- options: AuthOptions(redirectTo: kIsWeb
- ? null
- : 'io.supabase.flutter://reset-callback/'),
+ await supabase.auth.resetPasswordForEmail(
+ 'sample@email.com',
+ redirectTo: kIsWeb ? null : 'io.supabase.flutter://reset-callback/',
);
```
- - name: Reset password
- isSpotlight: true
- dart: |
- ```dart
- final res = await supabase.auth.api.resetPasswordForEmail('user@example.com');
- ```
invoke():
title: 'invoke()'
description: |
@@ -782,7 +763,7 @@ pages:
dart: |
```dart
supabase.from('countries')
- .stream(['id'])
+ .stream(primaryKey: ['id'])
.listen((List> data) {
// Do something awesome with the data
});
@@ -794,7 +775,7 @@ pages:
dart: |
```dart
supabase.from('countries')
- .stream(['id'])
+ .stream(primaryKey: ['id'])
.eq('id', '120')
.listen((List> data) {
// Do something awesome with the data
@@ -804,7 +785,7 @@ pages:
dart: |
```dart
supabase.from('countries')
- .stream(['id'])
+ .stream(primaryKey: ['id'])
.order('name', ascending: true)
.listen((List> data) {
// Do something awesome with the data
@@ -814,7 +795,7 @@ pages:
dart: |
```dart
supabase.from('countries')
- .stream(['id'])
+ .stream(primaryKey: ['id'])
.order('name', ascending: true)
.limit(10)
.listen((List> data) {
@@ -837,7 +818,7 @@ pages:
class _MyWidgetState extends State {
// Persist the stream in a local variable to prevent refetching upon rebuilds
- final _stream = supabase.from('countries').stream(['id']);
+ final _stream = supabase.from('countries').stream(primaryKey: ['id']);
@override
Widget build(BuildContext context) {