Next.js

The @banata-auth/nextjs package is the normal app-side integration for Next.js.

Use it when your app needs to:

• proxy /api/auth/* requests to your Banata instance
• keep auth cookies on your own domain
• bind auth flows to a Banata project with a server-side API key
• read auth state in server components and server actions

npm install @banata-auth/nextjs

The Recommended Pattern

1. Create a project in the Banata dashboard
2. Create a project-scoped API key
3. Store that key in your app's server environment
4. Point the Next.js auth route at your Banata .convex.site URL

The browser never sees the API key. The Next.js server injects it while proxying auth traffic.

Entry Points

Route Handler

// src/app/api/auth/[...all]/route.ts
import { createRouteHandler } from "@banata-auth/nextjs";
 
export const { GET, POST, PUT, PATCH, DELETE } = createRouteHandler({
  convexSiteUrl: process.env.NEXT_PUBLIC_CONVEX_SITE_URL!,
  apiKey: process.env.BANATA_API_KEY!,
});

What apiKey Does

• binds the app to a single Banata project
• lets Banata resolve project config from the key itself
• avoids exposing project credentials to the browser

project.clientId and project.projectId are still available as legacy scope hints, but project-scoped apps should prefer the API key.

Server Helpers

Use createBanataAuthServer() when you also need server-side auth utilities:

// src/lib/auth-server.ts
import { createBanataAuthServer } from "@banata-auth/nextjs/server";
 
export const {
  handler,
  isAuthenticated,
  getToken,
  preloadAuthQuery,
  fetchAuthQuery,
  fetchAuthMutation,
  fetchAuthAction,
} = createBanataAuthServer({
  convexUrl: process.env.NEXT_PUBLIC_CONVEX_URL!,
  convexSiteUrl: process.env.NEXT_PUBLIC_CONVEX_SITE_URL!,
  apiKey: process.env.BANATA_API_KEY!,
});

Then wire your route file to that handler:

// src/app/api/auth/[...all]/route.ts
import { handler } from "@/lib/auth-server";
 
export const { GET, POST, PUT, PATCH, DELETE } = handler;

createBanataAuthServer() uses the same server-side API-key binding for:

• the route proxy
• /api/auth/convex/token
• isAuthenticated()
• authenticated Convex query/mutation/action helpers

Middleware

// middleware.ts
import { banataAuthProxy } from "@banata-auth/nextjs/middleware";
 
export default banataAuthProxy({
  publicRoutes: ["/", "/sign-in", "/api/webhooks/(.*)"],
  signInUrl: "/sign-in",
});
 
export const config = {
  matcher: ["/((?!_next|static|favicon.ico|.*\\..*).*)"],
};

The middleware checks for the Better Auth session cookie and redirects unauthenticated requests.

Example File Layout

src/
|-- app/
|   |-- api/auth/[...all]/route.ts
|   |-- sign-in/page.tsx
|   `-- dashboard/page.tsx
`-- lib/
    |-- auth-client.ts
    `-- auth-server.ts

Environment Variables

NEXT_PUBLIC_CONVEX_URL=https://your-banata-instance.convex.cloud
NEXT_PUBLIC_CONVEX_SITE_URL=https://your-banata-instance.convex.site
NEXT_PUBLIC_SITE_URL=http://localhost:3000
BANATA_API_KEY=sk_test_your_project_key

BANATA_API_KEY must stay server-side. Do not expose it with a NEXT_PUBLIC_ prefix.

Self-Hosting Note

Self-hosting does not change this Next.js integration model.

If you run Banata yourself, your app still:

1. signs in to a Banata dashboard
2. creates a project
3. creates a project-scoped API key
4. uses @banata-auth/nextjs exactly the same way

The only thing that changes is which Banata instance the app points to.