ca0ed1e2a8
**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> ) } ```
3.1 KiB
id, title
| id | title |
|---|---|
| example | Example Code |
Get started with NextAuth.js
The example code below describes how to add authentication to a Next.js app.
:::tip The easiest way to get started is to clone the example app and follow the instructions in README.md. You can try out a live demo at next-auth-example.vercel.app :::
Add API route
To add NextAuth.js to a project create a file called [...nextauth].js in pages/api/auth.
Read more about how to add authentication providers.
import NextAuth from "next-auth"
import Providers from "next-auth/providers"
export default NextAuth({
// Configure one or more authentication providers
providers: [
Providers.GitHub({
clientId: process.env.GITHUB_ID,
clientSecret: process.env.GITHUB_SECRET,
}),
// ...add more providers here
],
})
All requests to /api/auth/* (signin, callback, signout, etc) will automatically be handed by NextAuth.js.
:::tip See the options documentation for how to configure providers, databases and other options. :::
Add React Hook
The useSession() React Hook in the NextAuth.js client is the easiest way to check if someone is signed in.
import { signIn, signOut, useSession } from "next-auth/react"
export default function Page() {
const [session, loading] = useSession()
return (
<>
{!session && (
<>
Not signed in <br />
<button onClick={() => signIn()}>Sign in</button>
</>
)}
{session && (
<>
Signed in as {session.user.email} <br />
<button onClick={() => signOut()}>Sign out</button>
</>
)}
</>
)
}
:::tip
You can use the useSession hook from anywhere in your application (e.g. in a header component).
:::
Add session state
To allow session state to be shared between pages - which improves performance, reduces network traffic and avoids component state changes while rendering - you can use the NextAuth.js Provider in pages/_app.js.
import { SessionProvider } from "next-auth/react"
export default function App({
Component,
pageProps: { session, ...pageProps }
}) {
return (
<SessionProvider session={session}>
<Component {...pageProps} />
</SessionProvider>
)
}
:::tip Check out the client documentation to see how you can improve the user experience and page performance by using the NextAuth.js client. :::
Deploying to production
When deploying your site set the NEXTAUTH_URL environment variable to the canonical URL of the website.
NEXTAUTH_URL=https://example.com
:::tip In production, this needs to be set as an environment variable on the service you use to deploy your app.
To set environment variables on Vercel, you can use the dashboard or the vercel env pull command.
:::