[Builder] Next.js - old-12-only

What will we build?

In this quickstart, we will add the Frontegg hosted login box to your Next.js application.

In 5 minutes from now, your application will have a login box with Sign in, Sign up, and SSO. All this with just a few lines of code using redirects, Open Id Connect, and OAuth2.

⚡️ The code in the sample below is available in our Frontegg Samples repository in GitHub ⚡️

⚡ Before you start: ⚡


We are working on supporting Next.js version 13. Contact us to get updates!


Getting your Frontegg subdomain and clientId

Frontegg creates a unique subdomain and client id for every environment created on the account. In order to retrieve the clientId subdomain that will act as the FRONTEGG_BASE_URL in the integration, navigate to your environment 'Settings' menu, copy the Frontegg domain and clientId and use them in .env.local file.

STEP 1: Create Frontegg Next.js sample app that is based on Next.js version 12


If you have an existing app with Next.js version 12, skip this step.

To create a new app based on our sample, run the below commands.

npx create-next-app --example "https://github.com/frontegg/frontegg-nextjs" --example-path "apps/example" my-nextjs-app-name

cd my-nextjs-app-name
yarn create next-app --example "https://github.com/frontegg/frontegg-nextjs" --example-path "apps/example" my-nextjs-app-name

cd my-nextjs-app-name

STEP 2: Install

Run the following command to install the project with all its dependencies.

npm install


Breaking Changes from v5

@frontegg/nextjs v5 and above have been updated to support nextjs SSR, and thus have breaking changes.


Note - the files in this guide are in typescript - if you are working in js, simply change the file types and remove the typing

STEP 3: Configure the App file, Router, Middleware files

When integrating Next.js application with Frontegg, Next.js custom app and several files should be added. Make sure that these exist in the cloned project.

Custom Next.js App file under ./pages/_app.tsx:

Create ./pages/_app.tsx file and paste the below code inside.

import { withFronteggApp } from '@frontegg/nextjs';

function CustomApp({ Component, pageProps }: AppProps) {
  return <Component {...pageProps} />;

export default withFronteggApp(CustomApp, 
    hostedLoginBox: true


Existing custom Next.js app

If you have custom app already (the file _app.tsx exists), wrap and replace the default export component with withFronteggApp function and pass your original component.

Create API File

Create file under ./pages/api/frontegg/[...frontegg-middleware].ts and paste the code below:

export { fronteggMiddleware as default } from '@frontegg/nextjs';

Create page entry

Create file under ./pages/[...frontegg-router].tsx and paste the code below:

export {
  FronteggRouter as default,
  FronteggRouterProps as getServerSideProps,
} from '@frontegg/nextjs';


File Names

The locations and the files names of ./pages/[...frontegg-router].tsx, ./pages/api/frontegg/[...frontegg-middleware].ts and ./pages/_app.tsx should be exactly as described (including the brackets and the three dots)

STEP 4 Setup Environment

To setup your Next.js application to communicate with Frontegg, you have to create a new file named .env.local under your root project directory, this file will be used to store environment variables that will be used, configuration options:

# The AppUrl you set during integration - this is to tell Frontegg your application hostname

# The Frontegg domain is your unique URL to connect to the Frontegg gateway

# Your Frontegg application's Client ID

# The statless session encruption password, used to encrypt
# jwt before sending it to the client side.
# For quick password generation use the following command:
#    node -e "console.log(crypto.randomBytes(32).toString('hex'))"

# The statless session cookie name - you should not change this

Remember to replace the relevant fields in this file with your personal information!

STEP 5 (optional) NextRequest


Support for NextJS middleware is available from @frontegg/nextjs v6.4.0

To prevent access of an unauthenticated user to all routes, use Next.js middlewares.

NOTE: If you were using Middleware prior to 12.2, please see the upgrade guide.

import { NextResponse } from "next/server";
import type { NextRequest } from "next/server";
import { getSession } from '@frontegg/nextjs';

export const middleware = async (request: NextRequest) => {
  const session = await getSession(request);

  console.log("middleware session", session);
    // redirect unauthenticated user to /account/login page
    return NextResponse.redirect(new URL('/account/login', req.url))
  return NextResponse.next();

export const config = {
  matcher: "/(.*)",

STEP 6: Redirect to login

You can use the Frontegg withSSRSession , you can automatically redirect users to the login screen if they are not authenticated.


note - in the getServerSideProps method you can get data from an external service to pull relevant data for a logged in user, we used the prop products. See the commented code for an example:

import { GetServerSideProps } from 'next';
import { withSSRSession, useAuth } from '@frontegg/nextjs';

export default function MyPage({ products }) {
  const {user} = useAuth();
  //baseUrl should be your FRONTEGG_APP_URL from .env.local
  const baseUrl =  'FRONTEGG_APP_URL'
  const logout = () => {
    window.location.href = `${baseUrl}/account/logout`;

  return (
      <h1>My Page</h1>
        <img src={user?.profilePictureUrl} alt={user?.name}/>
        <span>Logged in as: {user?.name}</span>
        <button onClick={logout}>Log out</button>

export const getServerSideProps: GetServerSideProps = withSSRSession(
  async (context, session) => {
//     const { data } = await fetch('{external}/product', {
//      headers: {
//        Authorization: 'bearer ' + session.accessToken,
//      },
//    });
    return { props: { } };

STEP 7 (optional) getSession

As an extension of step 4, for any page that requires an AccessToken on the server side (e.g. you'd like to load the data only if a user is logged in), you can use the getSession method. Remember to replace external with the link to your external service.

import { GetServerSideProps } from 'next';
import { getSession } from '@frontegg/nextjs';

export default function MyPage({ products }) {
  return (
      <h1>My Page</h1>

export const getServerSideProps: GetServerSideProps = async (context) => {
  const session = await getSession(context.req);
  if (session) {
    const { data } = await fetch('{external}/product', {
      headers: {
        Authorization: 'bearer ' + session.accessToken,
    return { props: { products: data } };

  return { props: { products: [] } };

STEP 8 (optional) customLoader

import "../styles/globals.css";

export default withFronteggApp(CustomApp, 
    hostedLoginBox: true, 
    customLoader: true,
    authOptions: {
    // keepSessionAlive: true // Uncomment this in order to maintain the session alive

Add _document.tsx file under the pages folder.

import { Html, Head, Main, NextScript } from 'next/document';

export default function Document() {
  return (
      <Head />
        <Main />
        <NextScript />
        <div className="custom-loader"> I am a custom loader!</div>

Add the following styles to styles/globals.css:

.custom-loader {
    width: 100vw;
    height: 100vh;
    background: red;
    display: none;
    position: fixed;
    top: 0;
    left: 0;
    text-align: center;
    justify-content: center;
    align-items: center;
    font-size: 50px;
    color: white;

body.frontegg-loading .custom-loader {
    display: flex;

On the Frontegg portal, verify under the hosted login configuration, http://localhost:3000/oauth/callback is listed as the allowed redirectUrl.


Great, Frontegg is now integrated with your app!

Try it now!

Run your app and you should be automatically redirected to your hosted login box.