Open Serverless Auth Toolkit for Next.js

Common errors

• Error: `createAuthMiddleware` must be called with an object containing `domain` or `NEXT_PUBLIC_DOMAIN` environment variable must be set.

  cause The Edge Middleware cannot determine the central authentication hub's domain, which is essential for redirecting unauthenticated users and managing cross-subdomain cookies.
  fix Set `process.env.NEXT_PUBLIC_DOMAIN` to the full domain of your auth hub (e.g., `auth.yourdomain.com`) in your Next.js application's environment variables, or explicitly pass the `domain` option to `createAuthMiddleware({ domain: 'auth.yourdomain.com' })`.

• TypeError: Cannot read properties of null (reading 'email') OR ReferenceError: user is not defined

  cause The `user` object returned by `getUserData()` is `null` (indicating an unauthenticated state or an error during retrieval), and your code attempts to access its properties without a null check.
  fix Always implement a null check for the `user` object and handle the unauthenticated state, typically by redirecting the user to a login page or an unauthorized page, e.g., `if (!user) { redirect('/unauthorized'); }`.

• TypeError: (0 , open_serverless_auth__WEBPACK_IMPORTED_MODULE_0__.createAuthMiddleware) is not a function

  cause This error often indicates a CommonJS (CJS) vs. ESM import mismatch in an environment that expects ESM, such as the Next.js Edge Runtime for middleware. It can also occur if the bundle is corrupted or tree-shaking removed the function.
  fix Ensure you are using `import { createAuthMiddleware } from 'open-serverless-auth';` and not `require()`. Verify that your `middleware.ts` file is correctly configured as an ESM module if not already default.

Warnings

• gotcha Using the `devBypassUser` option in `createAuthMiddleware` allows unauthenticated access and injects a dummy user. While the library implements checks to automatically ignore this configuration when `process.env.NODE_ENV === 'production'`, developers should be aware of its security implications and never attempt to override these protections in live environments.
  Fix: Rely on the library's built-in `NODE_ENV` check. If custom environment-specific bypasses are needed, implement them securely and independently, ensuring they are strictly isolated from production deployments.
• gotcha This package is designed exclusively for Next.js 13+ applications utilizing the App Router. It leverages Next.js Edge Runtime for middleware and Server Components for `getUserData()`, making it incompatible with the Pages Router or older Next.js versions.
  Fix: Ensure your Next.js project is version 13 or newer and configured to use the App Router. Migrate existing Pages Router applications if necessary.
• gotcha The `matcher` configuration in `middleware.ts` is critical for defining which routes are protected. An improperly configured `matcher` can either leave sensitive routes unprotected or block legitimate access to static assets, API routes, or other Next.js internal paths.
  Fix: Carefully review and test your `matcher` array. The recommended pattern `/((?!api|_next/static|_next/image|favicon.ico).*)` typically covers most use cases by protecting all non-static, non-API routes. Adjust this pattern meticulously for any custom route requirements.

Install

• npm install open-serverless-auth npm
• yarn add open-serverless-auth yarn
• pnpm add open-serverless-auth pnpm

Imports

• createAuthMiddleware
  wrong:

  const { createAuthMiddleware } = require('open-serverless-auth');

  correct:

  import { createAuthMiddleware } from 'open-serverless-auth';

  Primarily used in `middleware.ts` for Next.js Edge Runtime, which mandates ESM. Using `require` will result in runtime errors.
• getUserData
  wrong:

  const { getUserData } = require('open-serverless-auth');

  correct:

  import { getUserData } from 'open-serverless-auth';

  A server-side helper for retrieving authenticated user data in Next.js Server Components. Server Components are ESM-only, making CommonJS `require` unsuitable.

Quickstart

Demonstrates setting up Edge Middleware for authentication and retrieving user data in a Next.js Server Component.

import { createAuthMiddleware, getUserData } from 'open-serverless-auth';
import { redirect } from 'next/navigation';

// --- src/middleware.ts ---
export const middleware = createAuthMiddleware({
  // The domain of your central auth hub, e.g., 'auth.yourdomain.com'
  // Falls back to process.env.NEXT_PUBLIC_DOMAIN if not provided.
  // domain: process.env.NEXT_PUBLIC_DOMAIN,

  // For local development only: Bypasses auth and injects a dummy user.
  // This is automatically ignored in production environments.
  devBypassUser: {
    id: "local-dev-id",
    email: "developer@example.com",
    role: "ADMIN",
    rules: { customPermission: true }
  }
});

export const config = {
  // Protect all routes except API routes, static assets, and favicon.ico
  matcher: ['/((?!api|_next/static|_next/image|favicon.ico).*)'],
};

// --- src/app/dashboard/page.tsx (Server Component) ---
export default async function DashboardPage() {
  const user = await getUserData();

  if (!user) {
    // Redirect unauthenticated users to a login page or an unauthorized page
    redirect('/unauthorized');
  }

  return (
    <div>
      <h1>Welcome back, {user.email}!</h1>
      <p>Your role: {user.role}</p>
      <p>Permissions: {JSON.stringify(user.rules)}</p>
    </div>
  );
}