Next.js Quickstart (Pages Router)

Add authentication to a Next.js Pages Router application using MonoCloud.

In this quickstart, you will:

Create a MonoCloud Web App
Install the MonoCloud Next.js SDK
Configure authentication middleware
Access the authenticated user on the server and client

Prerequisites

Before you begin, make sure you have:

A MonoCloud account and tenant
Node.js 16+ (npm, Yarn, or PNPM)
An existing Next.js project (or run npx create-next-app@latest)

A complete working example is available at: https://github.com/monocloud/nextjs-quickstart

Configure MonoCloud

In the MonoCloud Dashboard, create a new Web App
Select Next.js as your stack
Set the following URLs for local development:
- Callback URLs: http://localhost:3000/api/auth/callback
- Sign-out URLs: http://localhost:3000

Keep this tab open. You'll need the Domain, Client ID, and Client Secret next.

Install and configure the SDK

Install the SDK:

Terminal

npm install @monocloud/auth-nextjs

Create a .env.local file in your root:

.env.local

MONOCLOUD_AUTH_TENANT_DOMAIN=https://<your-domain>
MONOCLOUD_AUTH_CLIENT_ID=<your-client-id>
MONOCLOUD_AUTH_CLIENT_SECRET=<your-client-secret>
MONOCLOUD_AUTH_SCOPES=openid profile email
MONOCLOUD_AUTH_APP_URL=http://localhost:3000
MONOCLOUD_AUTH_COOKIE_SECRET=<random-secret>

Generate a cookie secret using: openssl rand -hex 32

Enable authentication middleware

Authentication is handled by a single middleware file. Create src/proxy.ts:

If you are using Next.js 15 or earlier, name this file src/middleware.ts instead.

src/proxy.ts

import { authMiddleware } from "@monocloud/auth-nextjs";

export default authMiddleware();

export const config = {
  matcher: ["/((?!_next/static|_next/image|favicon.ico|sitemap.xml|robots.txt).*)"],
};

This middleware runs for all page and API requests in the Pages Router.

Protect your UI

You can access the authenticated user on both the server and client, depending on where your component runs.

Server-side (Server rendered page)

src/pages/server.tsx

import { MonoCloudSession, getSession } from "@monocloud/auth-nextjs";
import { GetServerSideProps } from 'next';

type Props = {
  session?: MonoCloudSession;
};

export default function ServerPage({
  session,
}: Props) {
  if (!session?.user) {
    return <div>Please sign in</div>;
  }

  return (
    <div>
      <p>Hi {session.user.email}</p>
      <pre>{JSON.stringify(session, null, 2)}</pre>
    </div>
  );
}

export const getServerSideProps: GetServerSideProps<Props> = async (ctx) => {
  const session = await getSession(ctx.req, ctx.res);
  return { props: { session } };
};

Client-side (Hooks)

src/pages/client.tsx

import { useAuth } from "@monocloud/auth-nextjs/client";

export default function ClientPage() {
  const { user, isAuthenticated, isLoading } = useAuth();

  if (isLoading) {
    return <div>Loading...</div>;
  }

  if (!isAuthenticated) {
    return <div>Please sign in</div>;
  }

  return (
    <div>
      <p>Hi {user?.email}</p>
      <pre>{JSON.stringify(user, null, 2)}</pre>
    </div>
  );
};

Add sign-out

src/pages/index.tsx

import Link from "next/link";
import { SignOut } from "@monocloud/auth-nextjs/components";

export default function Home() {
  return (
    <main>
      <h1>MonoCloud Next.js Quickstart</h1>

      <nav>
        <Link href="/server">Server Page</Link>
        <br />
        <Link href="/client">Client Page</Link>
      </nav>

      <SignOut>Sign out</SignOut>
    </main>
  );
};

Run the application

Start the development server:

Terminal

npm run dev

Open http://localhost:3000 and:

Sign in or sign up
Visit /server to see server-side session data
Visit /client to see client-side authentication state
Sign out from the home page

Your Next.js Pages Router application is now authenticated with MonoCloud.

Next steps

👉 Next.js SDK API Reference