---
title: Next.js App Guide
description: Build a complete Next.js application with Authsome UI -- authentication, route protection, and user management.
---
This guide walks through building a full Next.js application with Authsome authentication from scratch. You will set up the provider, add middleware for route protection, create sign-in and sign-up pages, build a dashboard with user profile management, and add organization switching.
## 1. Create a Next.js app
```bash
npx create-next-app@latest my-authsome-app --typescript --tailwind --app --src-dir
cd my-authsome-app
```
## 2. Install Authsome packages
```bash
npm install @authsome/ui-nextjs @authsome/ui-react @authsome/ui-core @authsome/ui-components
```
## 3. Environment variables
```bash
# .env.local
NEXT_PUBLIC_AUTHSOME_URL=http://localhost:8080
AUTHSOME_API_URL=http://localhost:8080
NEXT_PUBLIC_AUTHSOME_KEY=pk_live_xxxxx # Optional: publishable key for auto-discovery
```
`NEXT_PUBLIC_AUTHSOME_URL` is used by client components. `AUTHSOME_API_URL` is used by server components and middleware (never exposed to the browser). `NEXT_PUBLIC_AUTHSOME_KEY` enables auto-discovery of which auth methods (social, passkey, MFA, etc.) are enabled on your backend.
## 4. Set up AuthProvider
Create a client-side providers component that wraps your app with `AuthProvider` and cookie-based storage:
```tsx
// src/app/providers.tsx
"use client";
import { AuthProvider, createCookieStorage } from "@authsome/ui-nextjs";
import type { ClientConfig } from "@authsome/ui-nextjs";
export function Providers({
children,
initialClientConfig,
}: {
children: React.ReactNode;
initialClientConfig?: ClientConfig;
}) {
return (
{children}
);
}
```
Update the root layout to use the providers with server-side autoconfig:
```tsx
// src/app/layout.tsx
import type { Metadata } from "next";
import { getClientConfig } from "@authsome/ui-nextjs";
import { Providers } from "./providers";
import "./globals.css";
export const metadata: Metadata = {
title: "My Authsome App",
description: "Next.js app with Authsome authentication",
};
export default async function RootLayout({
children,
}: {
children: React.ReactNode;
}) {
const clientConfig = await getClientConfig({
baseURL: process.env.AUTHSOME_API_URL!,
publishableKey: process.env.NEXT_PUBLIC_AUTHSOME_KEY,
});
return (
{children}
);
}
```
## 5. Add the proxy route handler
Create a catch-all API route that proxies requests to the Authsome backend. This is required for social login (OAuth callbacks), magic link verification, and cookie-based session management.
```ts
// src/app/api/authsome/[...path]/route.ts
import { createProxyHandler } from "@authsome/ui-nextjs/proxy";
const handler = createProxyHandler({
baseURL: process.env.NEXT_PUBLIC_AUTHSOME_URL!,
});
export { handler as GET, handler as POST, handler as PUT, handler as DELETE, handler as PATCH };
```
All requests to `/api/authsome/*` will be forwarded to the corresponding path on your Authsome backend. The handler automatically forwards cookies and authorization headers.
## 6. Add middleware for route protection
Create the middleware file at the project root. All routes except the ones listed in `publicPaths` will require authentication. The `authPaths` option redirects already-authenticated users away from sign-in/sign-up pages.
```ts
// src/middleware.ts
import { createAuthMiddleware } from "@authsome/ui-nextjs/middleware";
export default createAuthMiddleware({
baseURL: process.env.AUTHSOME_API_URL!,
signInPage: "/sign-in",
publicPaths: [
"/",
"/sign-in",
"/sign-up",
"/forgot-password",
"/reset-password",
"/api/authsome/*",
],
afterSignInUrl: "/dashboard",
});
export const config = {
matcher: ["/((?!_next/static|_next/image|favicon.ico).*)"],
};
```
> **Important:** Include `/api/authsome/*` in `publicPaths` so the proxy route handler is accessible without authentication.
## 7. Create the sign-in page
```tsx
// src/app/sign-in/page.tsx
"use client";
import { useRouter, useSearchParams } from "next/navigation";
import { SignInForm } from "@authsome/ui-components";
export default function SignInPage() {
const router = useRouter();
const searchParams = useSearchParams();
const redirect = searchParams.get("redirect") || "/dashboard";
return (
);
}
```
## 11. Add a forgot-password page
```tsx
// src/app/forgot-password/page.tsx
"use client";
import { ForgotPasswordForm } from "@authsome/ui-components";
export default function ForgotPasswordPage() {
return (
);
}
```
## 12. Project structure
After completing the guide, your project should look like this:
```
src/
app/
layout.tsx # Root layout with server-side autoconfig
providers.tsx # AuthProvider + cookie storage
page.tsx # Landing page (public)
sign-in/page.tsx # Sign-in page (public)
sign-up/page.tsx # Sign-up page (public)
forgot-password/page.tsx # Forgot password (public)
api/
authsome/
[...path]/route.ts # Proxy route handler
dashboard/
page.tsx # Dashboard (protected, server component)
dashboard-client.tsx # Dashboard (client component)
organizations/
page.tsx # Organization management
middleware.ts # Auth middleware
```
## 13. Deploy considerations
### Vercel
- Set `AUTHSOME_API_URL` and `NEXT_PUBLIC_AUTHSOME_URL` in the Vercel dashboard environment variables
- The middleware runs on Vercel's Edge Network, so token validation happens close to the user
- Ensure your Authsome API is reachable from Vercel's Edge functions
### Docker
```dockerfile
FROM node:20-alpine AS builder
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
RUN npm run build
FROM node:20-alpine
WORKDIR /app
COPY --from=builder /app/.next/standalone ./
COPY --from=builder /app/.next/static ./.next/static
COPY --from=builder /app/public ./public
ENV AUTHSOME_API_URL=http://authsome:8080
ENV NEXT_PUBLIC_AUTHSOME_URL=https://auth.example.com
EXPOSE 3000
CMD ["node", "server.js"]
```
### Security checklist
- Set `secure: true` in `createCookieStorage()` for production (HTTPS)
- Use `sameSite: "strict"` if your auth API is on the same domain
- Never expose `AUTHSOME_API_URL` (without `NEXT_PUBLIC_` prefix) to the client
- Consider adding CSP headers to prevent XSS attacks
- Enable rate limiting and account lockout on your Authsome server