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
}
```
**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>
* Constrain the adapters type generics more accurately
* Add types for the incoming messages to events callbacks
* Code review comments from @lluia
* Rebase from trunk and fix merge conflicts
* Update documentation
* Rip out generics
* fix(build): export aliases from client (#1909)
* docs(provider): update providers documentation (#1900)
* docs(providers): update providers documentation
- delineate clearly the 3 provider types (oauth, email, credentials)
- make each section structure consistent
- update the option list for every provider type
- use emojis
* docs(providers): instructions on new provider types
* docs(providers): remove emojis
To stay consistent with the rest of our documentation, for now we should not emojis on the sections of our documentation pages.
* docs(providers): reword sentence
Co-authored-by: Balázs Orbán <info@balazsorban.com>
* docs(providers): add tip on overriding options
* docs(providers): clarify `params` option usage
* docs(providers): make names list inline
Co-authored-by: Balázs Orbán <info@balazsorban.com>
* fix(ts): unset generics defaults for overriding (#1891)
Co-authored-by: Lluis Agusti <hi@llu.lu>
* fix(ts): tweak Adapter related types (#1914)
Contains the following squashed commits:
* fix(ts): make first adapter parameter non-optional
* fix(ts): make defaulted values non-optional internally
* test(ts): fix linting
* fix(page): don't pass params to custom signout page (#1912)
* For the custom signout page addressed two issues with the query params being added to the signout url. A conditional check on the error value is now made before adding it as a query param. Also added a conditional check on the callbackUrl and if present that then gets appended as a query param to the signout api call.
* Changed fix for bug #192 to have no querystring params in the custom signout page url.
Co-authored-by: anubisoft <anubisoftprez@gmail.com>
Co-authored-by: Lluis Agusti <hi@llu.lu>
* docs(www): fix typo (#1922)
* docs(provider): Update IdentityServer 4 demo configuration (#1932)
* Responding to code review comments
* Fix tests
* Fix lint error
Co-authored-by: Lluis Agusti <hi@llu.lu>
Co-authored-by: Balázs Orbán <info@balazsorban.com>
Co-authored-by: Kristóf Poduszló <kripod@protonmail.com>
Co-authored-by: Anubisoft <1471887+anubisoft@users.noreply.github.com>
Co-authored-by: anubisoft <anubisoftprez@gmail.com>
Co-authored-by: Ernie Miranda <emiranda04@users.noreply.github.com>
Co-authored-by: Mathis Møller <thisen-dk@hotmail.com>
Contains the following squashed commits:
* fix(ts): make first adapter parameter non-optional
* fix(ts): make defaulted values non-optional internally
* test(ts): fix linting
* chore: add beta to release flow/GH actions
* feat(ts): expose types from the package (#1665)
* chore(types): move existing types to the repo
* feat(ts): expose types from the main package
* chore(deps): bring back `react-dom` version range
* chore(ts): cleanup deps and comments
* chore(ci): run types tests on a separate workflow
* chore(ci): fix typo on types workflow
* fix(ts): correctly export sub-module types (#1677)
* chore(types): build types script
Adds a script that moves the declaration files we have in `./types` to `./dist` relative to the files they intend to type.
This is the first step, we still need to change what we declare in `package.json`, add the script to the CI pipeline if we're happy with it and figure out how to type `next-auth/jwt`.
* refactor(lint): fix build-types script
* fix(ts): add .d.ts sub-module files to package.json
#1677 seemed to miss this
* fix(built): typo in package.json
* fix(build): fix release
* feat(ts): support module augmentation (#1681)
* chore(ts): remove unused imports
* refactor(ts): clean up CallbackOptions
* docs(ts): explain Module Augmentation
* docs(ts): don't use @ in folder name "types"
* test(ts): make jwt params optional
* docs(ts): fix typo (TypeScript -> NextAuth.js)
* style: replace ts-standard with eslint/prettier (#1724)
* style: move from ts-standard to eslint/prettier
* fix: install remaining eslint-config-standard peer deps
* fix: add remaining missing dependencies/config
Co-authored-by: Balázs Orbán <info@balazsorban.com>
* docs(lint): update contributing.md (#1760)
Regarding ESLint / Prettier use and link to their VSCode extensions
* refactor(ts): de-duplicate types (#1690)
* refactor(ts): deduplicate internal types
* refactor(ts): ease up providers typings
* test(ts): fix failing TS tests
* test(ts): rename TS property to fix test
* docs(ts): mention TS docs in README.md
* feat(ts): move/update client types
* refactor(TS): rename some types
* test(ts): fix client tests
* docs(ts): move function descriptions to .d.ts
* chore: fix lint error
* refactor(ts): separate internal types
* chore: simplify build-types script
* chore: update type import paths in src
* chore(build): create root files at build
* chore: remove unnecessary .npmignore
* chore: run prettier on types
* fix(ts): clean up jwt types
* fix(ts): make getToken return type depend on raw param
* docs(page): explain page errors, add theming note
* docs(ts): add JSDoc to NextAuthOptions props
* chore(ts): remove unused import
* docs(ts): change JSDOC docs notation
* refactor(build): extract module entries into enum
* chore(ts): move ClientSafeProvider
* chore(ts): simplify GetTokenParams generic
* style(lint): fix linting errors
* chore: re-add generic extension to GetTokenParams
* fix(ts): extract EmailConfigServerOptions to interface
* fix(ts): use relative imports
* Merge branch 'main' into beta
* Merge main into beta
* fix(ts): fix typos, add more links to documentation
* test(ts): update JWT getToken test
* fix(build): fix tsconfig.json formatting
* test(ts): use absolute imports in test files
* fix(ts): add missing callbacks JSDoc
* docs: mention TS in FAQ, fix typos
* docs: fix some typos in the docs
Co-authored-by: Lluis Agusti <hi@llu.lu>
Co-authored-by: Nico Domino <yo@ndo.dev>
