docs(nextjs): point the sample, JSDoc and quick start at the middleware entry point

.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.

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="<your-app-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
 

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

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(.*)']);
  *

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/(.*)']);