From ea4a28273b80424c513e82d9411e0f451c2d6f37 Mon Sep 17 00:00:00 2001 From: DonOmalVindula Date: Sun, 6 Sep 2026 10:43:03 +0530 Subject: [PATCH] docs(nextjs): point the sample, JSDoc and quick start at the middleware entry point asgardeoMiddleware and createRouteMatcher moved to the Edge-safe `@asgardeo/nextjs/middleware` entry point when the token refresh was added to the middleware, but the bundled sample still imported them from `@asgardeo/nextjs/server` (which no longer exports them), the JSDoc examples imported them from the package root, and the quick start described a `new AsgardeoNext()` / `asgardeo.middleware()` setup that never existed. - Fix the imports in samples/teamspace-nextjs and the JSDoc examples. - Rewrite the quick start's middleware step and the embedded login step (the sign-in page path is configured through NEXT_PUBLIC_ASGARDEO_SIGN_IN_URL, which both the provider and the middleware read); drop the stray Auth.js references. - Document the middleware entry point in the README. Co-Authored-By: Claude Fable 5.1 --- .changeset/nextjs-middleware-import-path.md | 5 ++ packages/nextjs/QUICKSTART.md | 53 ++++--------------- packages/nextjs/README.md | 30 +++++++++++ .../server/middleware/asgardeoMiddleware.ts | 4 +- samples/teamspace-nextjs/middleware.ts | 2 +- 5 files changed, 49 insertions(+), 45 deletions(-) create mode 100644 .changeset/nextjs-middleware-import-path.md diff --git a/.changeset/nextjs-middleware-import-path.md b/.changeset/nextjs-middleware-import-path.md new file mode 100644 index 000000000..cfee90845 --- /dev/null +++ b/.changeset/nextjs-middleware-import-path.md @@ -0,0 +1,5 @@ +--- +'@asgardeo/nextjs': patch +--- + +Point the bundled sample, the JSDoc examples and the quick start at `@asgardeo/nextjs/middleware`, the Edge-safe entry point that has exported `asgardeoMiddleware` and `createRouteMatcher` since the token refresh moved into the middleware. The quick start showed a `new AsgardeoNext()` / `asgardeo.middleware()` setup that does not exist, and the sample still imported the middleware from `@asgardeo/nextjs/server`, which no longer exports it. The README now documents the middleware entry point. diff --git a/packages/nextjs/QUICKSTART.md b/packages/nextjs/QUICKSTART.md index 7781965d6..d86d4496d 100644 --- a/packages/nextjs/QUICKSTART.md +++ b/packages/nextjs/QUICKSTART.md @@ -1,6 +1,6 @@ # `@asgardeo/nextjs` Quickstart -This guide will help you quickly integrate Asgardeo authentication into your Next.js application using Auth.js. +This guide will help you quickly integrate Asgardeo authentication into your Next.js application. ## Prerequisites @@ -79,23 +79,12 @@ ASGARDEO_CLIENT_SECRET="" ## Step 5: Setup the Middleware -Create a `middleware.ts` file in your project root to handle authentication: +Create a `middleware.ts` file in your project root. The middleware keeps the session cookie fresh and lets you protect routes. Next.js runs it in the Edge runtime, so import it from `@asgardeo/nextjs/middleware`: -```bash -import { AsgardeoNext } from '@asgardeo/nextjs'; -import { NextRequest } from 'next/server'; - -const asgardeo = new AsgardeoNext(); +```typescript +import { asgardeoMiddleware } from '@asgardeo/nextjs/middleware'; -asgardeo.initialize({ - baseUrl: process.env.NEXT_PUBLIC_ASGARDEO_BASE_URL, - clientId: process.env.NEXT_PUBLIC_ASGARDEO_CLIENT_ID, - clientSecret: process.env.ASGARDEO_CLIENT_SECRET, -}); - -export async function middleware(request: NextRequest) { - return await asgardeo.middleware(request); -} +export default asgardeoMiddleware(); export const config = { matcher: [ @@ -105,6 +94,8 @@ export const config = { }; ``` +The middleware reads `NEXT_PUBLIC_ASGARDEO_BASE_URL`, `NEXT_PUBLIC_ASGARDEO_CLIENT_ID` and `ASGARDEO_CLIENT_SECRET` from the environment, so no further configuration is needed. + ## Step 6: Configure the Provider Wrap your application with the `AsgardeoProvider` in your main entry file i.e. `app/layout.tsx`: @@ -214,33 +205,12 @@ yarn dev ## Step 10: Embedded Login Page (Optional) -If you want to use an embedded login page instead of redirecting to Asgardeo, you can use the `SignIn` component: - -Configure the path of the sign-in page in the `middleware.ts` file: - -```diff -import { AsgardeoNext } from '@asgardeo/nextjs'; -import { NextRequest } from 'next/server'; +If you want to use an embedded login page instead of redirecting to Asgardeo, you can use the `SignIn` component. -const asgardeo = new AsgardeoNext(); - -asgardeo.initialize({ - baseUrl: process.env.NEXT_PUBLIC_ASGARDEO_BASE_URL, - clientId: process.env.NEXT_PUBLIC_ASGARDEO_CLIENT_ID, - clientSecret: process.env.ASGARDEO_CLIENT_SECRET, -+ signInUrl: '/signin', -}); +Tell the SDK where the sign-in page lives by adding its path to your `.env` file. Both the provider and the middleware read it, so `SignInButton` navigates there and protected routes redirect there: -export async function middleware(request: NextRequest) { - return await asgardeo.middleware(request); -} - -export const config = { - matcher: [ - '/((?!_next|[^?]*\\.(?:html?|css|js(?!on)|jpe?g|webp|png|gif|svg|ttf|woff2?|ico|csv|docx?|xlsx?|zip|webmanifest)).*)', - '/(api|trpc)(.*)', - ], -}; +```bash +NEXT_PUBLIC_ASGARDEO_SIGN_IN_URL="/signin" ``` Then, create a new page for the sign-in component in `app/signin/page.tsx`: @@ -276,7 +246,6 @@ Once you have set this up, clicking on the "Sign In" button will render the embe ### Additional Resources -- **[Auth.js Documentation](https://authjs.dev/)** - Learn more about Auth.js features and configuration - **[Asgardeo Documentation](https://wso2.com/asgardeo/docs/)** - Comprehensive guide to Asgardeo features - **[Next.js Documentation](https://nextjs.org/docs)** - Learn more about Next.js features and best practices diff --git a/packages/nextjs/README.md b/packages/nextjs/README.md index 58d183e04..ef00fe742 100644 --- a/packages/nextjs/README.md +++ b/packages/nextjs/README.md @@ -12,6 +12,36 @@ Get started with Asgardeo in your Next.js application in minutes. Follow our [Next.js Quick Start Guide](https://wso2.com/asgardeo/docs/quick-starts/nextjs/) for step-by-step instructions on integrating authentication into your app. +## Middleware + +`asgardeoMiddleware` and `createRouteMatcher` are exported from `@asgardeo/nextjs/middleware`. Next.js runs +`middleware.ts` in the Edge runtime, so this entry point only depends on Edge-safe code. The root entry and +`@asgardeo/nextjs/server` pull in the Node.js client and cannot be used from `middleware.ts`. + +```ts +// middleware.ts +import {asgardeoMiddleware, createRouteMatcher} from '@asgardeo/nextjs/middleware'; + +const isProtectedRoute = createRouteMatcher(['/dashboard(.*)']); + +export default asgardeoMiddleware(async (asgardeo, req) => { + if (isProtectedRoute(req)) { + return asgardeo.protectRoute(); + } +}); + +export const config = { + matcher: [ + '/((?!_next|[^?]*\\.(?:html?|css|js(?!on)|jpe?g|webp|png|gif|svg|ttf|woff2?|ico|csv|docx?|xlsx?|zip|webmanifest)).*)', + '/(api|trpc)(.*)', + ], +}; +``` + +`protectRoute()` redirects unauthenticated requests to `signInUrl` (`NEXT_PUBLIC_ASGARDEO_SIGN_IN_URL`) when it is +configured. The middleware also refreshes the access token shortly before it expires, so keep the matcher broad +enough to cover the pages and server actions of your app. + ## Redirect URLs The SDK sends `afterSignInUrl` (`NEXT_PUBLIC_ASGARDEO_AFTER_SIGN_IN_URL`, or the `afterSignInUrl` prop of diff --git a/packages/nextjs/src/server/middleware/asgardeoMiddleware.ts b/packages/nextjs/src/server/middleware/asgardeoMiddleware.ts index 0abda1db2..cdbad6447 100644 --- a/packages/nextjs/src/server/middleware/asgardeoMiddleware.ts +++ b/packages/nextjs/src/server/middleware/asgardeoMiddleware.ts @@ -117,7 +117,7 @@ const replaceCookieInHeader = (cookieHeader: string, name: string, value: string * @example * ```typescript * // middleware.ts - Basic usage (config read from env vars automatically) - * import { asgardeoMiddleware } from '@asgardeo/nextjs'; + * import { asgardeoMiddleware } from '@asgardeo/nextjs/middleware'; * * export default asgardeoMiddleware(); * @@ -129,7 +129,7 @@ const replaceCookieInHeader = (cookieHeader: string, name: string, value: string * @example * ```typescript * // With route protection - * import { asgardeoMiddleware, createRouteMatcher } from '@asgardeo/nextjs'; + * import { asgardeoMiddleware, createRouteMatcher } from '@asgardeo/nextjs/middleware'; * * const isProtectedRoute = createRouteMatcher(['/dashboard(.*)']); * diff --git a/samples/teamspace-nextjs/middleware.ts b/samples/teamspace-nextjs/middleware.ts index 8f701ca4b..b8705888e 100644 --- a/samples/teamspace-nextjs/middleware.ts +++ b/samples/teamspace-nextjs/middleware.ts @@ -1,4 +1,4 @@ -import {asgardeoMiddleware, createRouteMatcher} from '@asgardeo/nextjs/server'; +import {asgardeoMiddleware, createRouteMatcher} from '@asgardeo/nextjs/middleware'; const isProtectedRoute = createRouteMatcher(['/dashboard', '/dashboard/(.*)']);