Next.js Basic Auth Middleware

Common errors

• TypeError: (0 , nextjs_basic_auth_middleware__WEBPACK_IMPORTED_MODULE_0__.createApiPage) is not a function

  cause Attempting to use `createApiPage` after upgrading to version 3.x.
  fix The `createApiPage` function was removed in v3.0.0. Remove all calls to `createApiPage` as the 401 response is now handled internally by `createNextAuthMiddleware`.

• Error: The edge runtime does not support Node.js 'http' module.

  cause Using an older version of the middleware that relied on Node.js APIs within the Edge Runtime, or an incorrect `config.matcher` that applies the middleware to incompatible environments.
  fix Ensure you are using `nextjs-basic-auth-middleware` v3.x with Next.js >=13.1. This version is designed for the Edge Runtime. Verify your `config.matcher` to ensure it only applies to routes where middleware is intended to run.

• Internal Server Error (500) when providing a malformed Authorization header.

  cause Previous versions of the middleware could throw an unhandled exception when processing invalid or malformed basic auth headers, resulting in a 500 server error instead of a graceful 401.
  fix Upgrade to `nextjs-basic-auth-middleware@^3.1.1` to fix this issue. This version correctly catches exceptions and returns a 401 status code.

• Basic authentication fails when passwords contain a colon ':' character.

  cause Older versions of the `parseCredentials` logic incorrectly split credentials on every colon, failing to parse passwords containing the character.
  fix Upgrade to `nextjs-basic-auth-middleware@^3.1.1`. The updated `parseCredentials` function now correctly splits only on the *first* colon, allowing colons in passwords.

Warnings

• breaking Version 3.0.0 removed the `createApiPage` export and changed the 401 response mechanism. It now uses Middleware responses directly instead of redirecting to an API page. This is a cleaner approach but requires adapting existing v2 implementations.
  Fix: Remove any usage of `createApiPage`. The `createNextAuthMiddleware` function now handles the 401 response internally using `NextResponse`.
• breaking Version 3.0.0 introduced a breaking change by requiring Next.js version 13.1 or higher due to its reliance on newer Middleware response capabilities. Previous versions of Next.js are not supported with v3.x of this package.
  Fix: Ensure your project's `next` dependency is `^13.1.0` or higher. For Next.js 12 or 13.0, you must use `nextjs-basic-auth-middleware` version 2.x.
• breaking Version 2.0.0 contained breaking changes by removing 'SSR Middleware' functionality and updating the Next.js middleware implementation to use API pages for 401 error messages. This was superseded by v3.0.0's changes.
  Fix: If migrating from v1 to v2, adapt to the API page approach. If migrating to v3 directly, follow v3 instructions and ignore v2's API page mechanism.
• gotcha Version 3.1.1 fixed several security and correctness issues, including catching exceptions from malformed authorization headers (preventing 500s), allowing colons in passwords, and eliminating a timing leak in credential comparison. Older versions may be vulnerable to these issues.
  Fix: Upgrade to `nextjs-basic-auth-middleware@^3.1.1` or the latest stable version to incorporate these critical fixes.
• gotcha When integrating `nextBasicAuthMiddleware` into a custom middleware chain, be aware that if authentication fails, the middleware will immediately return a 401 response and stop processing any subsequent middleware functions. Place it strategically.
  Fix: Place `nextBasicAuthMiddleware` at the point in your middleware chain where you intend to halt further processing if authentication is not provided or fails, typically after any prerequisite checks.

Install

• npm install nextjs-basic-auth-middleware npm
• yarn add nextjs-basic-auth-middleware yarn
• pnpm add nextjs-basic-auth-middleware pnpm

Imports

• createNextAuthMiddleware
  wrong:

  const createNextAuthMiddleware = require('nextjs-basic-auth-middleware').createNextAuthMiddleware;

  correct:

  import { createNextAuthMiddleware } from 'nextjs-basic-auth-middleware';

  This package, like Next.js Middleware itself, is ESM-first. Use `import` syntax. CommonJS `require` will likely lead to errors.
• nextBasicAuthMiddleware
  wrong:

  const nextBasicAuthMiddleware = require('nextjs-basic-auth-middleware').nextBasicAuthMiddleware;

  correct:

  import { nextBasicAuthMiddleware } from 'nextjs-basic-auth-middleware';

  Use this named import for integrating basic auth checks within a larger, custom Next.js middleware function.
• AuthOptions

  import type { AuthOptions } from 'nextjs-basic-auth-middleware';

  When using TypeScript, import `AuthOptions` to type the configuration object passed to the middleware functions.

Quickstart

This quickstart demonstrates how to implement basic authentication across all routes in a Next.js application using `createNextAuthMiddleware`. It shows how to define users directly and configures the middleware with a custom realm and message. The `config.matcher` is set to protect all routes.

import { createNextAuthMiddleware } from 'nextjs-basic-auth-middleware';
import type { NextRequest } from 'next/server';

// Define your basic authentication credentials.
// In a real application, fetch these securely from environment variables or a secret management service.
// Example using environment variables for overriding:
// BASIC_AUTH_CREDENTIALS=myuser:mypassword|admin:adminpass
const users = [
  { name: 'testuser', password: 'testpassword' },
  { name: 'another', password: 'secretpassword' }
];

const authOptions = {
  users: users,
  realm: 'Restricted Area',
  message: 'Authentication Required - Please provide valid credentials.'
};

export const middleware = createNextAuthMiddleware(authOptions);

export const config = {
  // Matcher to apply basic auth to all routes.
  // Adjust this regex to secure specific paths, e.g., ['/admin/:path*']
  matcher: ['/(.*)']
};