supabase/apps/temp-docs/docs/reference/javascript/upgrade-guide.mdx

---
id: upgrade-guide
title: Upgrade to supabase-js v2
description: 'Learn how to upgrade to supabase-js v2.'
---

import Tabs from '@theme/Tabs'
import TabItem from '@theme/TabItem'

supabase-js v2 focuses on "quality-of-life" improvements for developers and addresses some of the largest pain points in v1. v2 includes type support, a rebuilt Auth library with async methods, improved errors, and more.

No new features will be added to supabase-js v1 , but we'll continuing merging security fixes to v1, with maintenance patches for the next 3 months.

## Upgrade the client library

```sh
npm install @supabase/supabase-js@2
```

_Optionally_ if you are using custom configuration with `createClient` then follow below:

<Tabs
  groupId="version"
  values={[
    {label: 'Before', value: '1.x'},
    {label: 'After', value: '2.x'},
  ]}>

<TabItem value="1.x">

```ts title="src/supabaseClient.ts"
const supabaseClient = createClient(SUPABASE_URL, SUPABASE_ANON_KEY, {
  schema: 'custom',
  persistSession: false,
})
```

</TabItem>

<TabItem value="2.x">

```ts title="src/supabaseClient.ts"
const supabaseClient = createClient(SUPABASE_URL, SUPABASE_ANON_KEY, {
  db: {
    schema: 'custom',
  },
  auth: {
    persistSession: true,
  },
})
```

</TabItem>
</Tabs>

Read more about the [constructor options](/docs/reference/javascript/release-notes#explicit-constructor-options).

### 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).

#### Sign in with email and password

<Tabs
  groupId="version"
  values={[
    {label: 'Before', value: '1.x'},
    {label: 'After', value: '2.x'},
  ]}>

<TabItem value="1.x">

```ts
const { user, error } = await supabase.auth.signIn({ email, password })
```

</TabItem>

<TabItem value="2.x">

```ts
const {
  data: { user },
  error,
} = await supabase.auth.signInWithPassword({ email, password })
```

</TabItem>
</Tabs>

#### Sign in with magic link

<Tabs
  groupId="version"
  values={[
    {label: 'Before', value: '1.x'},
    {label: 'After', value: '2.x'},
  ]}>

<TabItem value="1.x">

```ts
const { error } = await supabase.auth.signIn({ email })
```

</TabItem>

<TabItem value="2.x">

```ts
const { error } = await supabase.auth.signInWithOtp({ email })
```

</TabItem>
</Tabs>

#### Sign in with a third-party provider

<Tabs
  groupId="version"
  values={[
    {label: 'Before', value: '1.x'},
    {label: 'After', value: '2.x'},
  ]}>

<TabItem value="1.x">

```ts
const { error } = await supabase.auth.signIn({ provider })
```

</TabItem>

<TabItem value="2.x">

```ts
const { error } = await supabase.auth.signInWithOAuth({ provider })
```

</TabItem>
</Tabs>

#### Sign in with phone

<Tabs
  groupId="version"
  values={[
    {label: 'Before', value: '1.x'},
    {label: 'After', value: '2.x'},
  ]}>

<TabItem value="1.x">

```ts
const { error } = await supabase.auth.signIn({ phone, password })
```

</TabItem>

<TabItem value="2.x">

```ts
const { error } = await supabase.auth.signInWithPassword({ phone, password })
```

</TabItem>
</Tabs>

#### Sign in with phone using OTP

<Tabs
  groupId="version"
  values={[
    {label: 'Before', value: '1.x'},
    {label: 'After', value: '2.x'},
  ]}>

<TabItem value="1.x">

```ts
const { error } = await supabase.auth.api.sendMobileOTP(phone)
```

</TabItem>

<TabItem value="2.x">

```ts
const { data, error } = await supabase.auth.signInWithOtp({ phone })

// After receiving a SMS with a OTP.
const { data, error } = await supabase.auth.verifyOtp({ phone, token })
```

</TabItem>
</Tabs>

#### Reset password for email

<Tabs
  groupId="version"
  values={[
    {label: 'Before', value: '1.x'},
    {label: 'After', value: '2.x'},
  ]}>

<TabItem value="1.x">

```ts
const { data, error } = await supabase.auth.api.resetPasswordForEmail(email)
```

</TabItem>

<TabItem value="2.x">

```ts
const { data, error } = await supabase.auth.resetPasswordForEmail(email)
```

</TabItem>
</Tabs>

#### Get the user's current session

<Tabs
  groupId="version"
  values={[
    {label: 'Before', value: '1.x'},
    {label: 'After', value: '2.x'},
  ]}>

<TabItem value="1.x">

```ts
const session = supabase.auth.session()
```

</TabItem>

<TabItem value="2.x">

```ts
const {
  data: { session },
} = await supabase.auth.getSession()
```

</TabItem>
</Tabs>

#### Get the logged-in user

<Tabs
  groupId="version"
  values={[
    {label: 'Before', value: '1.x'},
    {label: 'After', value: '2.x'},
  ]}>

<TabItem value="1.x">

```ts
const user = supabase.auth.user()
```

</TabItem>

<TabItem value="2.x">

```ts
const {
  data: { session },
} = await supabase.auth.getSession()
const { user } = session
```

</TabItem>
</Tabs>

#### Update user data for a logged-in user

<Tabs
  groupId="version"
  values={[
    {label: 'Before', value: '1.x'},
    {label: 'After', value: '2.x'},
  ]}>

<TabItem value="1.x">

```ts
const { user, error } = await supabase.auth.update({ attributes })
```

</TabItem>

<TabItem value="2.x">

```ts
const {
  data: { user },
  error,
} = await supabase.auth.updateUser({ attributes })
```

</TabItem>
</Tabs>

#### Use a custom `access_token` JWT with Supabase

<Tabs
  groupId="version"
  values={[
    {label: 'Before', value: '1.x'},
    {label: 'After', value: '2.x'},
  ]}>

<TabItem value="1.x">

```ts
const { user, error } = supabase.auth.setAuth(access_token)
```

</TabItem>

<TabItem value="2.x">

```ts
const supabase = createClient(SUPABASE_URL, SUPABASE_ANON_KEY, {
  global: {
    headers: {
      Authorization: `Bearer ${access_token}`,
    },
  },
})
```

</TabItem>
</Tabs>

### Data methods

`.insert()` / `.upsert()` / `.update()` / `.delete()` don't return rows by default: [PR](https://github.com/supabase/postgrest-js/pull/276).

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.

#### Insert and return data

<Tabs
  groupId="version"
  values={[
    {label: 'Before', value: '1.x'},
    {label: 'After', value: '2.x'},
  ]}>

<TabItem value="1.x">

```ts
const { data, error } = await supabase.auth.insert({ new_data })
```

</TabItem>

<TabItem value="2.x">

```ts
const { data, error } = await supabase.auth.insert({ new_data }).select()
```

</TabItem>
</Tabs>

#### Update and return data

<Tabs
  groupId="version"
  values={[
    {label: 'Before', value: '1.x'},
    {label: 'After', value: '2.x'},
  ]}>

<TabItem value="1.x">

```ts
const { data, error } = await supabase.auth.update({ new_data }).eq('id', id)
```

</TabItem>

<TabItem value="2.x">

```ts
const { data, error } = await supabase.auth.update({ new_data }).eq('id', id).select()
```

</TabItem>
</Tabs>

### Realtime methods

#### Subscribe

<Tabs
  groupId="version"
  values={[
    {label: 'Before', value: '1.x'},
    {label: 'After', value: '2.x'},
  ]}>

<TabItem value="1.x">

```ts
const userListener = supabase
  .from('users')
  .on('*', (payload) => handleAllEventsPayload(payload.new))
  .subscribe()
```

</TabItem>

<TabItem value="2.x">

```ts
const userListener = supabase
  .channel('public:user')
  .on('postgres_changes', { event: '*', schema: 'public', table: 'user' }, (payload) =>
    handleAllEventsPayload()
  )
  .subscribe()
```

</TabItem>
</Tabs>

#### Unsubscribe

<Tabs
  groupId="version"
  values={[
    {label: 'Before', value: '1.x'},
    {label: 'After', value: '2.x'},
  ]}>

<TabItem value="1.x">

```ts
userListener.unsubscribe()
```

</TabItem>

<TabItem value="2.x">

```ts
supabase.removeChannel(userListener)
```

</TabItem>
</Tabs>