Next.JS

Prefer AI-assisted setup? Use our AI prompts for Next.js to automatically integrate Civic Auth using Claude, ChatGPT, or other AI assistants. Includes a step-by-step video tutorial!

Quick Start

Integrate Civic Auth into your Next.js application using the following steps (a working example is available in our github examples repo):

Important: Make sure your application is using Next.js version ^14.2.25 or ^15.2.3 (or higher). Earlier versions are affected by a security vulnerability (CVE-2025-29927) that may allow middleware to be bypassed.

This guide assumes you are using Typescript. Please adjust the snippets as needed to remove the types if you are using plain JS.

If you plan to use Web3 features, select “Auth + Web3” from the tabs below.

1. Add the Civic Auth Plugin

This is where you give your app the Client ID provided when you sign up at auth.civic.com.

Important: The next.config.ts file goes in your project root directory, NOT in the src/ directory.

The defaults should work out of the box for most customers, but if you want to configure your app, see below for details.

Auth

next.config.ts

import { createCivicAuthPlugin } from "@civic/auth/nextjs"
import type { NextConfig } from "next";

const nextConfig: NextConfig = {
  /* config options here */
};

const withCivicAuth = createCivicAuthPlugin({
  clientId: "YOUR CLIENT ID"
});

export default withCivicAuth(nextConfig)

Auth + Web3

next.config.ts

import { createCivicAuthPlugin } from "@civic/auth-web3/nextjs"
import type { NextConfig } from "next";

const nextConfig: NextConfig = {
  /* config options here */
};

const withCivicAuth = createCivicAuthPlugin({
  clientId: "YOUR CLIENT ID"
});

export default withCivicAuth(nextConfig)

Typescript support in configuration files was introduced in Next 15.

If your config file is a JS file (next.config.mjs), make sure to change the extension to .ts, or remove the type information.

2. Create the Civic Auth API Route

This is where your app will handle login and logout requests.

Important: This API route file goes in the src/ directory structure:

src/app/api/auth/[...civicauth]/route.ts

Auth

route.ts

import { handler } from "@civic/auth/nextjs"

export const GET = handler()
export const POST = handler()

Auth + Web3

route.ts

import { handler } from "@civic/auth-web3/nextjs"

export const GET = handler()
export const POST = handler()

These steps apply to the App Router. If you are using the Pages Router, please contact Civic in our developer community for integration steps.

3. Middleware

Middleware is used to protect your backend routes, server components and server actions from unauthenticated requests.

Using the Civic Auth middleware ensures that only logged-in users have access to secure parts of your service.

Important: The middleware file goes in the src/ directory:

src/middleware.ts

Auth

src/middleware.ts

import { authMiddleware } from "@civic/auth/nextjs/middleware"

export default authMiddleware();

export const config = {
  // include the paths you wish to secure here
  matcher: [
    /*
    * Match all request paths except:
    * - _next directory (Next.js static files)
    * - favicon.ico, sitemap.xml, robots.txt
    * - image files
    */
    '/((?!_next|favicon.ico|sitemap.xml|robots.txt|.*\\.jpg|.*\\.png|.*\\.svg|.*\\.gif).*)',
  ],
}

Auth + Web3

src/middleware.ts

import { authMiddleware } from "@civic/auth-web3/nextjs/middleware"

export default authMiddleware();

export const config = {
  // include the paths you wish to secure here
  matcher: [
    /*
    * Match all request paths except:
    * - _next directory (Next.js static files)
    * - favicon.ico, sitemap.xml, robots.txt
    * - image files
    */
    '/((?!_next|favicon.ico|sitemap.xml|robots.txt|.*\\.jpg|.*\\.png|.*\\.svg|.*\\.gif).*)',
  ],
}

Note: The default matcher does not include the root path (”/”). If you display authenticated elements (like UserButton) on the root page, add ”/” to the matcher array to ensure user state is refreshed during middleware prior to page load.

Middleware Chaining

If you are already using middleware in your Next.js app, then you can chain them with Civic Auth as follows:

Auth

src/middleware.ts

import { auth } from "@civic/auth/nextjs/middleware"
import { NextRequest, NextResponse } from "next/server";

const withCivicAuth = auth();

const otherMiddleware = (request: NextRequest) => {
    console.log("my middleware");
    return NextResponse.next();
}

export default withCivicAuth(otherMiddleware);

Auth + Web3

src/middleware.ts

import { auth } from "@civic/auth-web3/nextjs/middleware"
import { NextRequest, NextResponse } from "next/server";

const withCivicAuth = auth();

const otherMiddleware = (request: NextRequest) => {
    console.log("my middleware");
    return NextResponse.next();
}

export default withCivicAuth(otherMiddleware);

4. Frontend Integration

Add the Civic Auth context to your app to give your frontend access to the logged-in user.

Important: Your layout file should be in the src/ directory structure (typically src/app/layout.tsx):

Auth

import { CivicAuthProvider } from "@civic/auth/nextjs";

function Layout({ children }) {
  return (
  // ... the rest of your app layout
  <CivicAuthProvider>
    {children}
  </CivicAuthProvider>
  )
}

Unlike the pure React integration, you do not have to add your client ID again here!

Make sure to create the Civic Auth API route, as it serves the essential PKCE code challenge.

Usage

Getting User Information on the Frontend

The Next.js integration can use all the components described in the React integration page, such as the UserButton , for showing a Sign-In button and displaying the username:

Auth

TitleBar.ts

import { UserButton } from "@civic/auth/react";

export function TitleBar() {
  return (
    <div>
      <h1>My App</h1>
      <UserButton />
    </div>
  );
};

Auth + Web3

TitleBar.ts

import { UserButton } from "@civic/auth-web3/react";

export function TitleBar() {
  return (
    <div>
      <h1>My App</h1>
      <UserButton />
    </div>
  );
};

or if you need to rollout your own button:

Auth

TitleBar.ts

import { useUser } from "@civic/auth/react";
import { useCallback } from "react";

export function TitleBar() {
    const { signIn } = useUser();
    
    const doSignIn = useCallback(() => {
      console.log("Starting sign-in process");
      signIn()
        .then(() => {
          console.log("Sign-in completed successfully");
        })
        .catch((error) => {
          console.error("Sign-in failed:", error);
        });
    }, [signIn]);

    return (
      <div>
        <h1>My App</h1>
        <button onClick={doSignIn}>
          Sign in
        </button>
      </div>
    );
}

Auth + Web3

TitleBar.ts

import { useUser } from "@civic/auth-web3/react";
import { useCallback } from "react";

export function TitleBar() {
    const { signIn } = useUser();
    
    const doSignIn = useCallback(() => {
      console.log("Starting sign-in process");
      signIn()
        .then(() => {
          console.log("Sign-in completed successfully");
        })
        .catch((error) => {
          console.error("Sign-in failed:", error);
        });
    }, [signIn]);

    return (
      <div>
        <h1>My App</h1>
        <button onClick={doSignIn}>
          Sign in
        </button>
      </div>
    );
}

or the useUser hook, for retrieving information about the user in code:

Auth

MyComponent.ts

import { useUser } from "@civic/auth/react";

export function MyComponent() {
  const { user } = useUser();

  if (!user) return <div>User not logged in</div>

  return <div>Hello { user.name }!</div>
}

Auth + Web3

MyComponent.ts

import { useUser } from "@civic/auth-web3/react";

export function MyComponent() {
  const { user } = useUser();

  if (!user) return <div>User not logged in</div>

  return <div>Hello { user.name }!</div>
}

You can also pass onSignIn and onSignOut callbacks to the useUser hook to trigger actions when the user signs in or out:

Auth

MyComponent.ts

import { useUser } from "@civic/auth/react";

export function MyComponent() {
  const { user } = useUser({
    onSignIn: () => {
      console.log("User signed in");
      // do something here
    },
    onSignOut: () => {
      console.log("User signed out");
      // do something here
    }
  });

  if (!user) return <div>User not logged in</div>

  return <div>Hello { user.name }!</div>
}

Auth + Web3

MyComponent.ts

import { useUser } from "@civic/auth-web3/react";

export function MyComponent() {
  const { user } = useUser({
    onSignIn: () => {
      console.log("User signed in");
      // do something here
    },
    onSignOut: () => {
      console.log("User signed out");
      // do something here
    }
  });

  if (!user) return <div>User not logged in</div>

  return <div>Hello { user.name }!</div>
}

See the React Usage page for more details.

Getting User Information on the Backend

Retrieve user information on backend code, such as in React Server Components, React Server Actions, or api routes using getUser:

Auth

import { getUser } from "@civic/auth/nextjs";

const user = await getUser();

Auth + Web3

import { getUser } from "@civic/auth-web3/nextjs";

const user = await getUser();

For example, in a Next.js Server Component:

Auth

import { getUser } from "@civic/auth/nextjs";

export async function MyServerComponent() {
  const user = await getUser();

  if (!user) return <div>User not logged in</div>

  return <div>Hello { user.name }!</div>
}

Auth + Web3

import { getUser } from "@civic/auth-web3/nextjs";

export async function MyServerComponent() {
  const user = await getUser();

  if (!user) return <div>User not logged in</div>

  return <div>Hello { user.name }!</div>
}

The name property is used as an example here, check out the React Usage page to see the entire basic user object structure.

Advanced Configuration

Civic Auth is a “low-code” solution, so most of the configuration takes place via the dashboard. Changes you make there will be updated automatically in your integration without any code changes. The only required parameter you need to provide is the client ID.

The integration also offers the ability customize the library according to the needs of your Next.js app. For example, to restrict authentication checks to specific pages and routes in your app. You can do so inside next.config.js as follows:

Auth

next.config.ts

import { createCivicAuthPlugin } from "@civic/auth/nextjs"

const withCivicAuth = createCivicAuthPlugin({
  clientId: "YOUR CLIENT ID",
  ... // other config
});

export default withCivicAuth(nextConfig) // your next config here

Auth + Web3

next.config.ts

import { createCivicAuthPlugin } from "@civic/auth-web3/nextjs"

const withCivicAuth = createCivicAuthPlugin({
  clientId: "YOUR CLIENT ID",
  ... // other config
});

export default withCivicAuth(nextConfig) // your next config here

Field	Required	Default	Example	Description
clientId	Yes	-	2cc5633d-2c92-48da-86aa-449634f274b9	The key obtained on signup to auth.civic.com
loginSuccessUrl	No	-	/myCustomSuccessEndpoint	Post-authentication redirect - Where to redirect your user after successful login. If not set, users will be sent back to the root of your app (/). This is different from callbackUrl, which is the OAuth callback endpoint.
callbackUrl	No	/api/auth/callback	/api/myroute/callback	OAuth 2.0 callback endpoint - The API route where Civic’s OAuth server redirects after authentication to complete the token exchange. This must match the route where you attach Civic’s GET handler as described here. After token exchange completes, users are redirected to loginSuccessUrl.
loginUrl	No	/	/admin	The path your user will be sent to if they access a resource that needs them to be logged in. If you have a dedicated login page, you can set it here.
logoutUrl	No	/	/goodbye	The path your user will be sent to after a successful log-out.
include	No	["/*"]	["/admin/*", "/api/admin/*"]	An array of path globs that require a user to be logged-in to access. If not set, will include all paths matched by your Next.js middleware.
exclude	No	-	["public/home"]	An array of path globs that are excluded from Civic Auth middleware. In some cases, it might be easier and safer to specify exceptions rather than keep an inclusion list up to date.
basePath	No	/	/my-app	Allows applications to be served from custom subpaths instead of the root domain. This enables seamless authentication integration when deploying your Next.js application within subdirectories, ensuring all auth-related routes and assets maintain proper functionality regardless of the URL structure.
baseUrl	No	-	https://myapp.com	The public-facing base URL for your application. Required when deploying behind reverse proxies (Cloudfront + Vercel, AWS ALB, nginx, etc.) to ensure authentication redirects use the correct public domain instead of internal origins.

Deploying Behind Reverse Proxies

When deploying your Next.js application behind reverse proxies (such as Cloudfront + Vercel, AWS Application Load Balancer, or nginx), you may encounter authentication issues where redirects fail because the middleware detects internal origins instead of your public domain.

Common symptoms:

• Authentication works locally but fails in production
• Users cannot log in after deployment
• Redirect loops during the authentication process
• Error messages about invalid redirect URLs

Solution: Set the baseUrl parameter in your Next.js configuration to specify your public-facing domain:

Auth

next.config.ts

import { createCivicAuthPlugin } from "@civic/auth/nextjs"

const withCivicAuth = createCivicAuthPlugin({
  clientId: "YOUR CLIENT ID",
  baseUrl: "https://myapp.com" // Your public domain
});

export default withCivicAuth(nextConfig)

Auth + Web3

next.config.ts

import { createCivicAuthPlugin } from "@civic/auth-web3/nextjs"

const withCivicAuth = createCivicAuthPlugin({
  clientId: "YOUR CLIENT ID",
  baseUrl: "https://myapp.com" // Your public domain
});

export default withCivicAuth(nextConfig)

The baseUrl parameter is only needed for reverse proxy deployments. Standard deployments (like direct Vercel hosting) work without this configuration.