Unified API for all of our user-facing methods.
NOTE: `events.error` has been removed. This method has never been called in the core, so it did actually nothing. If you want to log errors to a third-party, check out the [`logger`](https://next-auth.js.org/configuration/options#logger) option instead.
BREAKING CHANGE:
Two event signatures changed to use named params, `signOut` and `updateUser`:
```diff
// [...nextauth].js
...
events: {
- signOut(tokenOrSession),
+ signOut({ token, session }), // token if using JWT, session if DB persisted sessions.
- updateUser(user)
+ updateUser({ user })
}
```
Similar to #2342, this aims to unify the user-facing API and provide an easier way to extend in the future.
In addition, this PR also solves the problem when the `logger.error` method sometimes did not print results, because `Error` instances are not serializable and will be printed as empty objects `"{}"`.
After this PR, we make any `Error` instances serializable as described here: https://iaincollins.medium.com/error-handling-in-javascript-a6172ccdf9afCloses#1602
Achieved by adding a `client: true` flag when logs are coming from the frontend.
BREAKING CHANGE:
The main change is that instead of an unknown number of parameters, the log events have at most two, where the second parameter is usually an object. In the case of the `error` event, it can also be an `Error` instance (that is serializable by `JSON.stringify`). If it is an object, an `Error` instance will be available on `metadata.error`, and `message` will default to `metadata.error.message`. This is done so that an error event always provides some kind of a stack to see where the error happened
```diff
// [...nextauth.js]
import log from "some-logger-service"
...
logger: {
- error(code, ...message) {},
+ error(code, metadata) {},
- warn(code, ...message) {},
+ warn(code) {}
- debug(code, ...message) {}
+ debug(code, metadata) {}
}
```
This change aligns the API with `openid-client`'s `checks` https://github.com/panva/node-openid-client/blob/main/docs/README.md#clientcallbackredirecturi-parameters-checks-extras, a library which we intend to migrate to in the future. Aligning our API early, so people get used to it.
Also, objectively the name `protection` might not have been as clear as I first thought. `checks` better describe the intention.
BREAKING CHANGE:
The `state` option on OAuth providers is now deprecated. Use `checks: ["state"]` instead.
`protections` is renamed to `checks`, here is an example:
```diff
- protection: ["pkce"]
+ checks: ["pkece"]
```
Furthermore, string values are not supported anymore. This is to be able to handle fewer cases internally.
```diff
- checks: "state"
+ checks: ["state"]
```
A living session could be a requirement for specific pages (like dashboards). If it doesn’t exist, the user should be redirected to a page asking them to sign in again.
Sometimes, a user might log out by accident, or by deleting cookies on purpose. If that happens (e.g. on a separate tab), then `useSession({ required: true })` should detect the absence of a session cookie and always return a non-nullable Session object type.
When `required: true` is set, the default behavior will be to redirect the user to the sign-in page. This can be overridden by an `action()` callback:
```js
const session = useSession({
required: true,
action() {
// ....
}
})
if (session.status === "Loading") return "Loading or not authenticated..."
// session.data is always defined here.
```
Co-authored-by: Kristóf Poduszló <kripod@protonmail.com>
Co-authored-by: Lluis Agusti <hi@llu.lu>
BREAKING CHANGE:
The `useSession` hook now returns an object. Here is how to accommodate for this change:
```diff
- const [ session, loading ] = useSession()
+ const { data: session, status } = useSession()
+ const loading = status === "loading"
```
With the new `status` option, you can test states much more clearly.
Some of our user-facing callbacks come with a bunch of parameters, and it is not always the case that a user needs all of them. Picking out certain parameters from the end of the list would require the user to define params that they wouldn't even need.
Therefore this PR changes such callbacks so the user can only pick the necessary parameters.
This comes with the bonus of better TS support on the `session` and `signIn` callbacks, where some parameters historically could have been different types.
In the `session` callback, the second param could have been `token` (when using JWT sessions) or `user` (when using DB persisted sessions). Now they are separate parameters.
In the `signIn` callback, we now separate `profile` (OAuth), `email` (Email) and `credentials` (Credentials) provider params.
BREAKING CHANGE:
The `callbacks` method signatures are changing the following way:
```diff
- signIn(user, account, profileOrEmailOrCredentials)
+ signIn({ user, account, profile, email, credentials })
```
```diff
- redirect(url, baseUrl)
+ redirect({ url, baseUrl })
```
```diff
- session(session, tokenOrUser)
+ session({ session, token, user })
```
```diff
- jwt(token, user, account, OAuthProfile, isNewUser)
+ jwt({ token, user, account, profile, isNewUser })
```
> NOTE: You only need to define the params that you actually need (no more need for `_` params.)
This way, if you only need `token` and `account` in the `jwt` callback, you can write:
```js
jwt({ token, account }) {
if(account) {
token.accessToken = account.access_token
}
return token
}
```
Node 10 has reached end-of-life, Next.js stopped supporting it in Next 11. Since we are a Next.js library, it doesn't make sense for us to support anything lower than that either.
I also upgraded a bunch of dependencies and dropped some that weren't necessary anymore.
BREAKING CHANGE:
The lowest supported Node version is 12. (We still support IE11 in browsers, until that is not dropped by Next.js itself)
Co-authored-by: Balázs Orbán <info@balazsorban.com>
* Add useState dependency
I went to execute the signin.js file and received an error that useState was undefined. Was able to reconcile this by adding the dependency.
Co-authored-by: Balázs Orbán <info@balazsorban.com>
Co-authored-by: Sangwon Park <dev.psw@gmail.com>
* fix(docs): scope expects space separated string
Currently the docs list string[] as possible type for scope.
However, It only accepts a string (with space as separator).
Co-authored-by: Balázs Orbán <info@balazsorban.com>
commit 665445818e
Author: Balázs Orbán <info@balazsorban.com>
Date: Sat Jun 12 17:11:53 2021 +0200
docs(config): link to next documentation instead of canary
commit 67cf2a11bb
Author: ndom91 <yo@ndo.dev>
Date: Sat Jun 12 16:42:48 2021 +0200
docs: fix alt client provider example
**What**:
These changes ensure that we work more tightly with React that can also result in unforeseen performance boosts. In case we would decide on expanding to other libraries/frameworks, a new file per framework could be added.
**Why**:
Some performance issues (https://github.com/nextauthjs/next-auth/issues/844) could only be fixed by moving more of the client code into the `Provider`.
**How**:
Refactoring `next-auth/client`
Related: #1461, #1084, #1462
BREAKING CHANGE:
**1.** `next-auth/client` is renamed to `next-auth/react`.
**2.** In the past, we exposed most of the functions with different names for convenience. To simplify our source code, the new React specific client code exports only the following functions, listed with the necessary changes:
- `setOptions`: Not exposed anymore, use `SessionProvider` props
- `options`: Not exposed anymore, use `SessionProvider` props
- `session`: Rename to `getSession`
- `providers`: Rename to `getProviders`
- `csrfToken`: Rename to `getCsrfToken`
- `signin`: Rename to `signIn`
- `signout`: Rename to `signOut`
- `Provider`: Rename to `SessionProvider`
**3.** `Provider` changes.
- `Provider` is renamed to `SessionProvider`
- The `options` prop is now flattened as the props of `SessionProvider`.
- `clientMaxAge` has been renamed to `staleTime`.
- `keepAlive` has been renamed to `refetchInterval`.
An example of the changes:
```diff
- <Provider options={{clientMaxAge: 0, keepAlive: 0}}>{children}</Provider>
+ <SessionProvider staleTime={0} refetchInterval={0}>{children}</SessionProvider>
```
**4.** It is now **required** to wrap the part of your application that uses `useSession` into a `SessionProvider`.
Usually, the best place for this is in your `pages/_app.jsx` file:
```jsx
import { SessionProvider } from "next-auth/react"
export default function App({
Component,
pageProps: { session, ...pageProps }
}) {
return (
// `session` comes from `getServerSideProps` or `getInitialProps`.
// Avoids flickering/session loading on first load.
<SessionProvider session={session}>
<Component {...pageProps} />
</SessionProvider>
)
}
```
* feat(adapter): remove built-in adapters and database
BREAKING CHANGE:
From now on, you will have to import your own adapter
Check out https://github.com/nextauthjs/adapters
The migration is super easy and has HUGE advantages for those not using TypeORM.
```diff
// [...nextauth].js
+ import TypeORMAdapter from "@next-auth/typeorm-legacy-adapter"
import NextAuth from "next-auth"
...
export default NextAuth({
- database: "yourconnectionstring",
+ adapter: TypeORMAdapter("yourconnectionstring")
})
```
Co-authored-by: Lluis Agusti <hi@llu.lu>
Co-authored-by: Giovanni Carnel <479046+g10@users.noreply.github.com>
