Integrate Hanko with Next.js

Create a Next.js application

Run the following command to create a new Next.js application:

When setting up Next.js, you’ll choose either the App Router or the Pages Router. Be sure to follow the proper directory structure and add the matching code for the router you selected.

This creates a new Next.js application using the latest version and default settings.

npx create-next-app@latest project-name

Install `@teamhanko/hanko-elements`

Once you’ve initialized your NextJS app, installing hanko-elements provides you with access to the prebuilt components: hanko-auth and hanko-profile. This installs the Hanko Elements package, providing pre-built authentication components.

cd project-name
npm install @teamhanko/hanko-elements

cd project-name
pnpm add @teamhanko/hanko-elements

cd project-name
bun add @teamhanko/hanko-elements

cd project-name
yarn add @teamhanko/hanko-elements

Set up your Hanko project

Go to the Hanko Console and create a project for this application.

During creation make sure to input the URL you will be developing on as the APP URL. (Most likely http://localhost:3000)

Add your Hanko API URL

Retrieve your API URL from the Hanko Console, and paste this in a .env file. Set up your environment variable for the Hanko API URL. The NEXT_PUBLIC_ prefix makes it accessible in the browser.

.env.local

NEXT_PUBLIC_HANKO_API_URL=https://f4****-4802-49ad-8e0b-3d3****ab32.hanko.io

If you are self-hosting you need to provide the URL of your running Hanko backend.

Create Hanko components

Create a folder called components and create two files, HankoAuth.tsx and HankoProfile.jsx.

Add Typescript types

To get these elements to work with typescript, currently we must add the types to the project. To do do this, create a file called custom.d.ts and place it in your apps root / src folder. Add TypeScript declarations for Hanko Web Components to enable type checking and IntelliSense support.

src/custom.d.ts

import { HankoAuthElementProps, HankoProfileElementProps, HankoEventsElementProps } from "@teamhanko/hanko-elements";

declare module "react" {
  namespace JSX {
    interface IntrinsicElements {
        "hanko-auth": HankoAuthElementProps;
        "hanko-login": HankoAuthElementProps;
        "hanko-registration": HankoAuthElementProps;
        "hanko-profile": HankoProfileElementProps;
        "hanko-events": HankoEventsElementProps;
    }
  }
}

Now lets setup the HankoAuth.tsx file to create a functioning login page. Here we subscribe to the onSessionCreated event, this triggers when a user successfully logs in. You can use these event to perform any desired action. (e.g. redirect to your dashboard). For more information please refer to the Auth component page.

App directory
Pages directory

App Router version: This authentication component handles session events and redirects users after successful login.

components/HankoAuth.tsx

"use client"; //Only for NextJS App Router
 
import { useEffect, useCallback, useState } from "react";
import { useRouter } from "next/navigation";
import { register, Hanko } from "@teamhanko/hanko-elements";
 
const hankoApi = process.env.NEXT_PUBLIC_HANKO_API_URL || '';
 
export default function HankoAuth() {
  const router = useRouter();
 
  const [hanko, setHanko] = useState<Hanko>();
 
  useEffect(() => setHanko(new Hanko(hankoApi)), []);
 
  const redirectAfterLogin = useCallback(() => {
    // change this to the page you wish to be redirected to
    router.replace("/dashboard");
  }, [router]);
 
  useEffect(
    () =>
      hanko?.onSessionCreated(() => {
        // successfully logged in
        redirectAfterLogin();
      }),
    [hanko, redirectAfterLogin]
  );
 
  useEffect(() => {
    register(hankoApi).catch((error) => {
      // handle error
      console.log(error);
    });
  }, []);
 
  return <hanko-auth />;
}

Pages Router version: This authentication component uses next/router instead of next/navigation.

components/HankoAuth.tsx

import { useEffect, useCallback, useState } from "react";
import { useRouter } from "next/router";
import { register, Hanko } from "@teamhanko/hanko-elements";

const hankoApi = process.env.NEXT_PUBLIC_HANKO_API_URL || '';

export default function HankoAuth() {
  const router = useRouter();

  const [hanko, setHanko] = useState<Hanko>();

  useEffect(() => setHanko(new Hanko(hankoApi)), []);

  const redirectAfterLogin = useCallback(() => {
    // change this to the page you wish to be redirected to
    router.replace("/dashboard");
  }, [router]);

  useEffect(
    () =>
      hanko?.onSessionCreated(() => {
        //succesfully logged in
        redirectAfterLogin();
      }),
    [hanko, redirectAfterLogin]
  );

  useEffect(() => {
    register(hankoApi).catch((error) => {
      // handle error
      console.log(error)
    });
  }, []);

  return <hanko-auth />;
}

Now simply import the component you just created.

App directory
Pages directory

App Router login page that renders the HankoAuth component.

app/login/page.tsx

import HankoAuth from "@/components/HankoAuth";

export default function LoginPage() {
  return (
      <HankoAuth/>
  );
}

Pages Router login page that renders the HankoAuth component.

pages/login.tsx

import HankoAuth from "@/components/HankoAuth";

export default function LoginPage() {
  return (
      <HankoAuth/>
  );
}

By now, your sign-up and sign-in features should be working. You should see an interface similar to this 👇

Profile page with `<hanko-profile>`

After setting up HankoAuth, let’s set up the HankoProfile.jsx file to create an interface where users can manage their email addresses and login methods. For more information please refer to the Profile component page.

App directory
Pages directory

App Router profile component for managing user emails and credentials.

components/HankoProfile.jsx

"use client" //Only for NextJS App Router

import { useEffect } from "react";
import { register } from "@teamhanko/hanko-elements";

const hankoApi = process.env.NEXT_PUBLIC_HANKO_API_URL || '';

export default function HankoProfile() {
  useEffect(() => {
    register(hankoApi).catch((error) => {
      // handle error
    });
  }, []);

return <hanko-profile />;
}

Pages Router profile component for managing user emails and credentials.

components/HankoProfile.jsx

import { useEffect } from "react";
import { register } from "@teamhanko/hanko-elements";

const hankoApi = process.env.NEXT_PUBLIC_HANKO_API_URL || '';

export default function HankoProfile() {
  useEffect(() => {
    register(hankoApi).catch((error) => {
      // handle error
    });
  }, []);

  return <hanko-profile />;
}

After you created the HankoProfile component, simply import it into any page.

App directory
Pages directory

app/dashboard/page.tsx

import HankoProfile from "@/components/HankoProfile";

export default function Dashboard() {
  return (
    <div>
      <HankoProfile/>
    </div>
  );
}

pages/dashboard.tsx

import HankoProfile from "@/components/HankoProfile";

export default function Dashboard() {
  return (
    <div>
      <HankoProfile/>
    </div>
  );
}

It should look something like this 👇

Implement logout functionality

You can use @teamhanko/hanko-elements to easily logout users. Here we will make a logout button. Create LogoutButton.tsx and insert the code below.

App directory
Pages directory

App Router logout button component that handles session cleanup and navigation.

components/LogoutButton.tsx

"use client"; //Only for NextJS App Router
 
import { useState, useEffect } from "react";
import { useRouter } from "next/navigation";
import { Hanko } from "@teamhanko/hanko-elements";
 
const hankoApi = process.env.NEXT_PUBLIC_HANKO_API_URL || '';
 
export default function LogoutBtn() {
  const router = useRouter();
  const [hanko, setHanko] = useState<Hanko>();
 
  useEffect(() => setHanko(new Hanko(hankoApi ?? "")), []);
 
  const logout = async () => {
    try {
      await hanko?.logout();
      router.push("/");
      router.refresh();
      return;
    } catch (error) {
      console.error("Error during logout:", error);
    }
  };
 
  return <button onClick={logout}>Logout</button>;
}

Pages Router logout button component using router.reload() instead of refresh().

components/LogoutButton.tsx

import { useState, useEffect } from "react";
import { useRouter } from "next/router";
import { Hanko } from "@teamhanko/hanko-elements";

const hankoApi = process.env.NEXT_PUBLIC_HANKO_API_URL || '';

export default function LogoutBtn() {
  const router = useRouter();
  const [hanko, setHanko] = useState<Hanko>();

  useEffect(() => setHanko(new Hanko(hankoApi ?? "")), []);

  const logout = async () => {
    try {
      await hanko?.logout();
      router.push("/");
      router.reload();
      return;
    } catch (error) {
      console.error("Error during logout:", error);
    }
  };

  return <button onClick={logout}>Logout</button>;
}

Customize component styles

You can customize the appearance of hanko-auth and hanko-profile components using CSS variables and parts. Refer to our customization guide.

Securing routes with middleware

To verify the session token in your Next.js application, we’re using the session/validate API request. By checking for a valid session token this middleware will ensure secure access to specific routes, like /dashboard and /protected.
The middleware extracts and verifies the session token, and redirect unauthorized users back to the home or login page. For more info on middlewares and where to put the middleware.ts file,
please refer to NextJS Middleware.

Middleware tends to not always work after creating it, if this is the case try restarting your next app.

This Next.js middleware protects routes by validating Hanko session tokens.

middleware.ts

import { NextResponse, NextRequest } from "next/server";

const hankoApi = process.env.NEXT_PUBLIC_HANKO_API_URL;

export async function middleware(req: NextRequest) {
const token = req.cookies.get("hanko")?.value;

  const validationOptions = {
    method: 'POST',
    headers: {'Content-Type': 'application/json'},
    body: `{"session_token":"${token}"}`
  }

  try {
    const validationResponse = await fetch(
      new URL(`${hankoApi}/sessions/validate`),//Hanko session validation
      validationOptions
    );

    if (!validationResponse.ok) {
      throw new Error('Session validation failed');
    }
    
    const responseData = await validationResponse.json();

    if(!responseData.is_valid){
      throw new Error('Session token not valid');
    }

  } catch (error) {
    console.log(error)
    return NextResponse.redirect(new URL("/", req.url));// URL to redirect the user to
  }
}

export const config = {
  matcher: ["/dashboard"],
};

To verify that it works, logout on your app and go to /dashboard, you should get redirected back.

Getting user data

Client side

Lets use the Hanko SDK to get user data. Lets update the dashboard page to log some of the information from the user and session.

App directory
Pages directory

App Router dashboard with client-side user data retrieval using the Hanko SDK.

app/dashboard/page.tsx

"use client" //Only for NextJS App Router

import HankoProfile from "../components/HankoProfile";
import LogoutButton from "../components/LogoutButton";

import { Hanko } from "@teamhanko/hanko-elements";
import { useState, useEffect } from "react";

const hankoApi = process.env.NEXT_PUBLIC_HANKO_API_URL || "";

export default function Dashboard() {
    const [hanko, setHanko] = useState<Hanko>();

    useEffect(() => setHanko(new Hanko(hankoApi)), []);
      useEffect(() => {
        hanko?.getCurrentUser()
          .then((user) => {
            console.log("User profile:", user);// Log user Profile
            console.log(user.emails?.[0]?.address);
            console.log(user.user_id);
          })
      }, [hanko]);

  return (
    <div>
      <HankoProfile/>
      <LogoutButton/>
    </div>
  );
}

Pages Router dashboard with client-side user data retrieval.

pages/dashboard.tsx

import HankoProfile from "@/components/HankoProfile";
import LogoutButton from "@/components/LogoutButton";

import { Hanko } from "@teamhanko/hanko-elements";
import { useState, useEffect } from "react";

const hankoApi = process.env.NEXT_PUBLIC_HANKO_API_URL || "";

export default function Dashboard() {
    const [hanko, setHanko] = useState<Hanko>();

    useEffect(() => setHanko(new Hanko(hankoApi)), []);
      useEffect(() => {
        hanko?.getCurrentUser()
          .then((user) => {
            console.log("User profile:", user);// Log user Profile
            console.log(user.emails?.[0]?.address);
            console.log(user.user_id);
          })
      }, [hanko]);

  return (
    <div>
      <HankoProfile/>
      <LogoutButton/>
    </div>
  );
}

Server side

On the server side, you can extract the userID from the session token, which you can use to fetch the user’s data from the Hanko Public API. This server-side function validates sessions and fetches user data using the Hanko API.

getUserData.ts

import { cookies } from "next/headers";

const hankoApi = process.env.NEXT_PUBLIC_HANKO_API_URL || '';

export async function getUserData() {

  try {
    const token = (await cookies()).get("hanko")?.value;

    const validationOptions = {
      method: 'POST',
      headers: {'Content-Type': 'application/json'},
      body: `{"session_token":"${token}"}`
    }

    const validationResponse = await fetch(hankoApi + '/sessions/validate', validationOptions); //Get session data
    if (!validationResponse.ok) {
      throw new Error("validation was not succesfull");
    }
    const validationData = await validationResponse.json();

    if(!validationData.is_valid){ //Validate session data
      throw new Error("validation was not succesfull");
    }

    const userid = validationData.user_id; //use user id to request data
    const userResponse = await fetch(hankoApi + '/users/' + userid, validationOptions);
    if (!userResponse.ok) {
      throw new Error("Could not get user data");
    }
    const userData = await userResponse.json();

    return userData;

    } catch (error) {
      console.log(error)
      return null;
    }
}

Getting started

Guides

Using the Hanko API

Integrations

Resources

FAQ & support

Integrate Hanko with Next.js

Create a Next.js application

Install `@teamhanko/hanko-elements`

Set up your Hanko project

Add your Hanko API URL

Create Hanko components

Add Typescript types

Profile page with `<hanko-profile>`

Implement logout functionality

Customize component styles

Securing routes with middleware

Getting user data

Client side

Server side

Try it yourself

Next.js example (App router)

Next.js example (Pages router)

​Create a Next.js application

​Install @teamhanko/hanko-elements

​Set up your Hanko project

​Add your Hanko API URL

​Create Hanko components

​Add Typescript types

​Login page with <hanko-auth>

​Profile page with <hanko-profile>

​Implement logout functionality

​Customize component styles

​Securing routes with middleware

​Getting user data

​Client side

​Server side

​Try it yourself

Next.js example (App router)

Next.js example (Pages router)

Create a Next.js application

Install `@teamhanko/hanko-elements`

Set up your Hanko project

Add your Hanko API URL

Create Hanko components

Add Typescript types

Login page with `<hanko-auth>`

Profile page with `<hanko-profile>`

Implement logout functionality

Customize component styles

Securing routes with middleware

Getting user data

Client side

Server side

Try it yourself