Kinde Auth SDK for NextJS

Kinde NextJS is the official SDK for integrating Kinde authentication into Next.js applications.

For detailed implementation guides, API references, and integration steps, refer to the official Kinde NextJS SDK documentation.

If you prefer a pre-configured starting point, you can use the NextJS starter kit.

To experiment with the SDK in a local environment, you can run the playground. This process clones the NextJS app router starter kit into a /playground directory and links the SDK locally using npm link.

1. Prepare the playground:

   npm run dev:prepare

2. Configure credentials: Add your Kinde credentials to the .env.local file generated inside the /playground directory.
3. Start the playground:

   npm run dev

The playground will be available at http://localhost:3000.

npm run dev:prepare
# Add credentials to /playground/.env.local
npm run dev

The SessionManager allows you to toggle between persistent and non-persistent sessions via the persistent property.

• Persistent (true): Cookies are set with a maxAge of TWENTY_NINE_DAYS (29 days).
• Non-persistent (false): Cookies are treated as session cookies (no maxAge specified, meaning they expire when the browser session ends).

You can set this during initialization via the options object or by modifying the property on the returned instance.

To access authentication state and methods in your client components, you must wrap your application (or a specific part of your component tree) with the KindeProvider. This provider handles the session check and makes user data, tokens, and feature flags available via context.

import { KindeProvider } from '@kinde-oss/kinde-auth-nextjs/react';

export default function App({ children }) {
  return (
    <KindeProvider>
      {children}
    </KindeProvider>
  );
}

In Next.js Pages Router applications, use getKindeServerSession(req, res) to obtain a session handler object. This handler provides methods to retrieve user information, tokens, permissions, and feature flags from the current session.

Important Compatibility Note:

• This method is designed exclusively for the Pages Router.
• It is not compatible with the App Router. App Router users should use the refreshData method in useKindeBrowserClient instead.

import { getKindeServerSession } from "@kinde-oss/kinde-auth-nextjs";

export async function getServerSideProps({ req, res }) {
  const { getKindeServerSession } = await getKindeServerSession(req, res);
  
  const user = await getUser();
  const isAuthenticated = await isAuthenticated();
  const accessToken = await getAccessToken();

  return {
    props: {
      user,
      isAuthenticated,
    },
  };
}

The @kinde-oss/kinde-auth-nextjs SDK provides hooks and a provider to manage authentication state and browser client access within your React components.

• KindeProvider: A context provider that must wrap your application to enable Kinde authentication features.
• useKindeAuth: A hook to access the current authentication state (e.g., whether a user is logged in, user details, etc.).
• useKindeBrowserClient: A hook to access the Kinde browser client for advanced client-side operations.

import { KindeProvider, useKindeAuth } from "@kinde-oss/kinde-auth-nextjs";

function App() {
  return (
    <KindeProvider>
      <MyComponent />
    </KindeProvider>
  );
}

function MyComponent() {
  const { isAuthenticated, user } = useKindeAuth();
  // ...
}

If you need to force a re-check of the user's session (for example, after a background update or a permission change), call the refreshData() method provided by the useKindeAuth hook.

const { refreshData } = useKindeAuth();

const handleUpdate = async () => {
  await refreshData();
  console.log('Session refreshed');
};

The useKindeAuth hook provides several properties to access the authenticated user's data and security tokens:

• user: The user object containing profile information.
• isAuthenticated: A boolean indicating if a user is currently logged in.
• isLoading: A boolean indicating if the initial session check is in progress.
• accessToken: The access token.
• idToken: The ID token.
• getAccessToken(), getToken(): Methods to retrieve the access token.
• getIdToken(), getIdTokenRaw(): Methods to retrieve the ID token.
• getUser(), getUserOrganizations(): Methods to retrieve user and organization data.