Building a Next.js App with Biometrics

Dylan Brookes
February 22, 2022

Developers can now easily increase security, and decrease sign-in friction with boimetrics - a form of passwordless user authentication. Passage makes it easy to embed biometrics into your application, and in this example, we’ll run through how to add biometrics to your Next.js application.

By adding Passage to your Next.js application, your users will be able to log into your application using biometrics built into their devices (i.e. Face ID, Touch ID, Windows Hello, etc.) or via magic links sent to their email or cell phone (via SMS). This article will walk you through how to create a Next.js app, setup the components, and authenticate users using the passage-node SDK.

If you are already familiar with Next.js, you can go straight to our full example application on GitHub or skip to the "Add User Authentication with Passage" section to learn how to integrate biometric authentication into an existing application.


You will need to have Node >= 12.22.0 and npm >= 5.6 on your machine.  To create a Next.js app run:

Run Your Next.js App

Congratulations! You now have a Next.js app up and running, now it’s time to add Passage to authenticate your users with biometrics.

Build Views for the Application

In Next.js, the files in the pages folder are the views rendered relative to the root directory for the app. For example, if you add the page pages/dashboard.js, it will be accessible by navigating to localhost:3000/dashboard (if you’re familiar with PHP, this is similar to how HTML and PHP files are served in the public_html folder).

In this application, we will have two pages index.js (which will serve as the log-in screen), and dashboard.js.  The index.js page will contain Passage’s <passage-auth/> custom element, which enables user authentication.  The dashboard.js page will be an authenticated route and will block any unauthenticated users from viewing the dashboard.

During our setup, it already created an index.js page, but we’ll need to create the dashboard.js page with the following command:

Let’s start with building the Login view pages/index.js. Replace the code in index.js with the following:

Now we will build a simple Dashboard view pages/dashboard.js:

Creating the Banner Component

Now let’s create a Banner component that we can add to pages/_app.js, making it visible throughout the application.  Let’s create a component directory and create the banner.js file.

Lets build components/banner.js with this code:

For the Banner component, the styles will need to be added to styles/Banner.module.css

Create the file:

And insert this code:

Now let’s add the Banner component to pages/_app.js so that it will appear throughout the app:

Now let’s add a footer and some styling to pages/_app.js:

Create the styling file:

With the following code:

Add User Authentication with Passage

Now it is time to add passwordless authentication to your application using Passage. First, install the Passage custom element from npm:

Then import the package in the view where you intend to authenticate users. In this case, pages/index.js. Note that since Next.js is server-side rendered, we will have to use the useEffect hook from React. Your index.js file should look like this:

Importing this script will register the Passage custom element for use in your Next.js page. For more information about custom elements refer to the online documentation.

Note: For Typescript Next.js applications, you’ll need to add the following type declaration to your typings.d.ts file:

Create an application in the Passage Console (here) with the following settings:

  • Authentication Origin: http://localhost:3000
  • Redirect URL: /dashboard

Below is a screenshot from creating a Passage App in the Passage Console:

Once the application has been created, copy the Application ID from the console into a .env file in the root of React app’s repository.

A Passage API key will also be needed later on. Generate a new API Key and add it to your .env file as PASSAGE_API_KEY=<Your New Passage API Key Here>

Your .env file should now look something like this:

Now add the passage-auth custom element to pages/index.js and retrieve the appID from the .env file using the getStaticProps() function:

Verifying User Authentication

Next, import the Passage Node.js SDK to authenticate users accessing the dashboard page. Install the dependency with the following command:

To use the Passage Node SDK, it will need to be added to pages/dashboard.js. Replace the code in your dashboard.js page with the following:

Now unauthenticated users that visit /dashboard will be shown an unauthorized page, while authenticated user will be shown their Passage User ID.

Now run the app, to see Passage biometric authentication in action:


You now have a Next.js application that uses passwordless authentication!  Biometric authentication with Passage not only increases the security of your application, but provides your users with a frictionless login experience.

You can see the finished application on GitHub here.

Learn More About Passage

To learn more about Passage and biometric authentication for web applications, you can:

  • Explore our dashboard to view and create users, customize your application, and add friends
  • Read our guides for other tech stacks and learn how to authorize requests in your backend server
  • Join our Discord and say hi

‍Passage is in beta and actively seeking feedback on the product. If you have feedback, bug reports, or feature requests, we would love to hear from you. You can email us at or fill out this form.