{"id":16868,"library":"open-serverless-auth","title":"Open Serverless Auth Toolkit for Next.js","description":"This package, `open-serverless-auth` (current version 0.2.0), provides a toolkit for integrating Next.js applications with a centralized Open Serverless Auth hub. It includes an Edge Middleware for protecting downstream applications by redirecting unauthorized users, and Server Action/Component helpers like `getUserData()` to retrieve authenticated user information. Its primary differentiator is simplifying centralized authentication architecture across subdomains using cross-subdomain cookies, abstracting away complex login UI development on client apps. It's designed to work seamlessly with Next.js App Router and assumes a peer dependency on `next` version 13 or higher. The current version suggests it's relatively new, likely in active development with potentially frequent updates, although a specific release cadence isn't stated. The core value proposition is enabling easy setup of a centralized authentication system, offloading authentication concerns from individual client applications.","status":"active","version":"0.2.0","language":"javascript","source_language":"en","source_url":null,"tags":["javascript","typescript"],"install":[{"cmd":"npm install open-serverless-auth","lang":"bash","label":"npm"},{"cmd":"yarn add open-serverless-auth","lang":"bash","label":"yarn"},{"cmd":"pnpm add open-serverless-auth","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Required for Next.js Edge Middleware and Server Components functionality, specifically Next.js 13+ App Router.","package":"next","optional":false}],"imports":[{"note":"Primarily used in `middleware.ts` for Next.js Edge Runtime, which mandates ESM. Using `require` will result in runtime errors.","wrong":"const { createAuthMiddleware } = require('open-serverless-auth');","symbol":"createAuthMiddleware","correct":"import { createAuthMiddleware } from 'open-serverless-auth';"},{"note":"A server-side helper for retrieving authenticated user data in Next.js Server Components. Server Components are ESM-only, making CommonJS `require` unsuitable.","wrong":"const { getUserData } = require('open-serverless-auth');","symbol":"getUserData","correct":"import { getUserData } from 'open-serverless-auth';"}],"quickstart":{"code":"import { createAuthMiddleware, getUserData } from 'open-serverless-auth';\nimport { redirect } from 'next/navigation';\n\n// --- src/middleware.ts ---\nexport const middleware = createAuthMiddleware({\n  // The domain of your central auth hub, e.g., 'auth.yourdomain.com'\n  // Falls back to process.env.NEXT_PUBLIC_DOMAIN if not provided.\n  // domain: process.env.NEXT_PUBLIC_DOMAIN,\n\n  // For local development only: Bypasses auth and injects a dummy user.\n  // This is automatically ignored in production environments.\n  devBypassUser: {\n    id: \"local-dev-id\",\n    email: \"developer@example.com\",\n    role: \"ADMIN\",\n    rules: { customPermission: true }\n  }\n});\n\nexport const config = {\n  // Protect all routes except API routes, static assets, and favicon.ico\n  matcher: ['/((?!api|_next/static|_next/image|favicon.ico).*)'],\n};\n\n// --- src/app/dashboard/page.tsx (Server Component) ---\nexport default async function DashboardPage() {\n  const user = await getUserData();\n\n  if (!user) {\n    // Redirect unauthenticated users to a login page or an unauthorized page\n    redirect('/unauthorized');\n  }\n\n  return (\n    <div>\n      <h1>Welcome back, {user.email}!</h1>\n      <p>Your role: {user.role}</p>\n      <p>Permissions: {JSON.stringify(user.rules)}</p>\n    </div>\n  );\n}","lang":"typescript","description":"Demonstrates setting up Edge Middleware for authentication and retrieving user data in a Next.js Server Component."},"warnings":[{"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.","message":"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.","severity":"gotcha","affected_versions":">=0.2.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=0.2.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=0.2.0"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"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' })`.","cause":"The Edge Middleware cannot determine the central authentication hub's domain, which is essential for redirecting unauthenticated users and managing cross-subdomain cookies.","error":"Error: `createAuthMiddleware` must be called with an object containing `domain` or `NEXT_PUBLIC_DOMAIN` environment variable must be set."},{"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'); }`.","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.","error":"TypeError: Cannot read properties of null (reading 'email') OR ReferenceError: user is not defined"},{"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.","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.","error":"TypeError: (0 , open_serverless_auth__WEBPACK_IMPORTED_MODULE_0__.createAuthMiddleware) is not a function"}],"ecosystem":"npm","meta_description":null}