Skip to main content
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
  • Auth + Web3
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)
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
  • Auth + Web3
route.ts
import { handler } from "@civic/auth/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
  • Auth + Web3
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).*)',
  ],
}
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
  • Auth + Web3
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);

​
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): 
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
  • Auth + Web3
TitleBar.ts
import { UserButton } from "@civic/auth/react";

export function TitleBar() {
  return (
    <div>
      <h1>My App</h1>
      <UserButton />
    </div>
  );
};
or if you need to rollout your own button:
  • Auth
  • Auth + Web3
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>
    );
}
or the useUser hook, for retrieving information about the user in code:
  • Auth
  • Auth + Web3
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>
}
You can also pass onSignIn and onSignOut callbacks to the useUser hook to trigger actions when the user signs in or out:
  • Auth
  • Auth + Web3
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>
}
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
  • Auth + Web3
import { getUser } from "@civic/auth/nextjs";

const user = await getUser();
For example, in a Next.js Server Component:
  • Auth
  • Auth + Web3
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>
}
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
  • Auth + Web3
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
FieldRequiredDefaultExampleDescription
clientIdYes-2cc5633d-2c92-48da-86aa-449634f274b9The key obtained on signup to auth.civic.com
loginSuccessUrlNo-/myCustomSuccessEndpointIn a NextJS app, we will redirect your user to this page once the login is finished. If not set, users will be sent back to the root of your app.
callbackUrlNo/api/auth/callback/api/myroute/callbackIf you cannot host Civic’s SDK handlers in the default location, you can specify a custom callback route here. This is where you must attach Civic’s GET handler as described here, so Civic can complete the OAuth token exchange. Use loginSuccessUrl to redirect after login.
loginUrlNo//adminThe 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.
logoutUrlNo//goodbyeThe path your user will be sent to after a successful log-out.
includeNo["/*"]["/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.
excludeNo-["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.
basePathNo//my-appAllows 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.
baseUrlNo-https://myapp.comThe 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
  • Auth + Web3
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)
The baseUrl parameter is only needed for reverse proxy deployments. Standard deployments (like direct Vercel hosting) work without this configuration.