Release Notes
Supabase.js v2 release notes.
2.0.0#
Install the latest with npm install @supabase/supabase-js
.
Explicit constructor options#
All client specific options within the constructor are keyed to the library: PR:
1const supabase = createClient(apiURL, apiKey, {
2 db: {
3 schema: 'public',
4 },
5 auth: {
6 storage: AsyncStorage,
7 autoRefreshToken: true,
8 persistSession: true,
9 detectSessionInUrl: true,
10 },
11 realtime: {
12 channels,
13 endpoint,
14 },
15 global: {
16 fetch: customFetch,
17 headers: DEFAULT_HEADERS,
18 },
19})
Typescript support#
The libraries now support typescript.
1// v2 - definitions are injected in `createClient()`
2import type { Database } from './DatabaseDefinitions'
3const supabase = createClient<Database>(SUPABASE_URL, ANON_KEY)
4const { data } = await supabase.from('messages').select().match({ id: 1 })
5
6// v1 -- previously definitions were injected in the `from()` method
7supabase.from<Definitions['Message']>('messages').select('*')
Types can be generated via the CLI:
supabase start supabase gen types typescript --local > DatabaseDefinitions.ts
Data operations return minimal#
.insert()
/ .upsert()
/ .update()
/ .delete()
don't return rows by default: PR.
Previously, these methods return inserted/updated/deleted rows by default (which caused some confusion), 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, e.g.:
1const { data, error } = await supabase
2 .from('my_table')
3 .delete()
4 .eq('id', 1)
5 .select()
New ordering defaults#
.order()
now defaults to Postgres’s default: PR.
Previously nullsFirst
defaults to false
, meaning null
s are ordered last. This is bad for performance if e.g. the column uses an index with NULLS FIRST
(which is the default direction for indexes).
Cookies and localstorage namespace#
Storage key name in the Auth library has changed to include project reference which means that existing websites that had their JWT expiry set to a longer time could find their users logged out with this upgrade.
1const defaultStorageKey = `sb-${new URL(this.authUrl).hostname.split('.')[0]}-auth-token`
New Auth Types#
Typescript typings have been reworked. Session
interface now guarantees that it will always have an access_token
, refresh_token
and user
1interface Session {
2 provider_token?: string | null
3 access_token: string
4 expires_in?: number
5 expires_at?: number
6 refresh_token: string
7 token_type: string
8 user: User
9}
New Auth methods#
We're removing the signIn()
method in favor of more explicit function signatures:
signInWithPassword()
, signInWithOtp()
, and signInWithOtp()
.
1// v2
2const { data } = await supabase.auth.signInWithPassword({
3 email: 'hello@example',
4 password: 'pass',
5})
6// v1
7const { data } = await supabase.auth.signIn({
8 email: 'hello@example',
9 password: 'pass',
10})
New Realtime methods#
There is a new channel()
method in the Realtime library, which will be used for our Multiplayer updates.
1supabase
2 .channel('any_string_you_want')
3 .on('presence', { event: 'track' }, (payload) => {
4 console.log(payload)
5 })
6 .subscribe()
7
8supabase
9 .channel('any_string_you_want')
10 .on(
11 'postgres_changes',
12 {
13 event: 'INSERT',
14 schema: 'public',
15 table: 'movies',
16 },
17 (payload) => {
18 console.log(payload)
19 }
20 )
21 .subscribe()
We will deprecate the .from().on().subscribe()
method previosuly used for listening to postgres changes.
Deprecated setAuth()#
Deprecated and removed setAuth()
. To set a custom access_token
jwt instead, pass the custom header into the createClient()
method provided: (PR)
All changes#
supabase-js
shouldThrowOnError
has been removed until all the client libraries support this option (PR).
postgrest-js
- TypeScript typings have been reworked PR
- Use
undefined
instead ofnull
for function params, types, etc. (https://github.com/supabase/postgrest-js/pull/278) - Some features are now obsolete: (https://github.com/supabase/postgrest-js/pull/275)
- filter shorthands (e.g.
cs
vs.contains
) body
in response (vs.data
)upsert
ing through the.insert()
methodauth
method onPostgrestClient
- client-level
throwOnError
- filter shorthands (e.g.
gotrue-js
supabase-js
client allows passing astorageKey
param which will allow the user to set the key used in local storage for storing the session. By default, this will be namespace-d with the supabase project ref. (PR)signIn
method is now split intosignInWithPassword
,signInWithOtp
,signInWithOAuth
(PR)- Deprecated and removed
session()
,user()
in favour of usinggetSession()
instead.getSession()
will always return a valid session if a user is already logged in, meaning no more random logouts. (PR) - Deprecated and removed setting for
multitab
support becausegetSession()
and gotrue’s reuse interval setting takes care of session management across multiple tabs (PR) - No more throwing of random errors, gotrue-js v2 always returns a custom error type: (PR)
AuthSessionMissingError
- Indicates that a session is expected but missing
AuthNoCookieError
- Indicates that a cookie is expected but missing
AuthInvalidCredentialsError
- Indicates that the incorrect credentials were passed
- Renamed the
api
namespace toadmin
, theadmin
namespace will only contain methods that should only be used in a trusted server-side environment with the service role key - Moved
resetPasswordForEmail
,getUser
andupdateUser
to theGoTrueClient
which means they will be accessible from thesupabase.auth
namespace insupabase-js
instead of having to dosupabase.auth.api
to access them - Removed
sendMobileOTP
,sendMagicLinkEmail
in favor ofsignInWithOtp
- Removed
signInWithEmail
,signInWithPhone
in favor ofsignInWithPassword
- Removed
signUpWithEmail
,signUpWithPhone
in favor ofsignUp
- Replaced
update
withupdateUser
storage-js
- Return types are more strict. Functions types used to indicate that the data returned could be null even if there was no error. We now make use of union types which only mark the data as null if there is an error and vice versa. (PR)
- The
upload
andupdate
function returns the path of the object uploaded as thepath
parameter. Previously the returned value had the bucket name prepended to the path which made it harder to pass the value on to other storage-js methods since all methods take the bucket name and path separately. We also chose to call the returned valuepath
instead ofKey
(PR) getPublicURL
only returns the public URL inside the data object. This keeps it consistent with our other methods of returning only within the data object. No error is returned since this method cannot does not throw an error (PR)- signed urls are returned as
signedUrl
instead ofsignedURL
in bothcreateSignedUrl
andcreateSignedUrls
(PR) - Encodes URLs returned by
createSignedUrl
,createSignedUrls
andgetPublicUrl
(PR) createsignedUrl
used to return a url directly and and within the data object. This was inconsistent. Now we always return values only inside the data object across all methods. (PR)createBucket
returns a data object instead of the name of the bucket directly. (PR)- Fixed types for metadata (PR)
- Better error types make it easier to track down what went wrong quicker.
SupabaseStorageClient
is no longer exported. UseStorageClient
instead. (PR).
realtime-js
RealtimeSubscription
class no longer exists and replaced byRealtimeChannel
.RealtimeClient
'sdisconnect
method now returns type ofvoid
. It used to return type ofPromise<{ error: Error | null; data: boolean }
.- Removed
removeAllSubscriptions
andremoveSubscription
methods fromSupabaseClient
class. - Removed
SupabaseRealtimeClient
class. - Removed
SupabaseQueryBuilder
class. - Removed
SupabaseEventTypes
type.- Thinking about renaming this to something like
RealtimePostgresChangeEvents
and moving it torealtime-js
v2.
- Thinking about renaming this to something like
- Removed
.from(’table’).on(’INSERT’, () ⇒ {}).subscribe()
in favor of new Realtime client API.
functions-js
- supabase-js v1 only threw an error if the fetch call itself threw an error (network errors, etc) and not if the function returned HTTP errors like 400s or 500s. We have changed this behaviour to return an error if your function throws an error.
- We have introduced new error types to distinguish between different kinds of errors. A
FunctionsHttpError
error is returned if your function throws an error,FunctionsRelayError
if the Supabase Relay has an error processing your function andFunctionsFetchError
if there is a network error in calling your function. - The correct content-type headers are automatically attached when sending the request if you don’t pass in a
Content-Type
header and pass in an argument to your function. We automatically attach the content type forBlob
,ArrayBuffer
,File
,FormData
,String
. If it doesn’t match any of these we assume the payload isjson
, we serialise the payload as JSON and attach the content type asapplication/json
. responseType
does not need to be explicitly passed in. We parse the response based on theContent-Type
response header sent by the function. We support parsing the responses astext
,json
,blob
,form-data
and are parsed astext
by default.