Skip to content


Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?

Next Password

Add password protection to your Next.js application. (next > v12.0.0)


This project is licensed under the BSL: You cannot use this licensed work for any commercial purposes. (only personal & non-commercial).

For commercial purposes, use the password protection service provided by the Vercel platform.

This is a community open source project, NOT associated with Vercel.


Run yarn add next-password to install.


1. Import to middleware

Create a _middleware.ts file in the /pages directory and fill it:

// pages/_middleware.ts
import { initPasswordMiddleware } from 'next-password/middleware'

export default initPasswordMiddleware('/')

2. Create login page

Create a auth.tsx file in the /pages directory and fill it:

// pages/auth.tsx
export { default } from 'next-password'

Add your password

Set environment variable

The initial password for the project is process.env.PASSWORD, you can configure this environment variable in two ways:

Add envs in next.config.js
// next.config.js
module.exports = {
  env: {
    PASSWORD: 'test',

Ignore password

Skip password check in the specified environment.

Ignore password in next.config.js
// next.config.js
// this will remove password in all environments
module.exports = {
  env: {
Ignore password in local
// .env.local
// when developing locally, you can skip the password checking.



Whenever a user successfully enters a password (saving a persistent session), NextPassword will turn on httpOnly by default, which prevents most scripts from getting cookies during cross-site attacks. Also, NextPassword will only store the digest in the cookie, which effectively ensures that your plaintext is not compromised.

In addition, you can also set salt to enhance the security of weak passwords. When salt is missing, NextPassword will generate a hash value of fixed salt.


The implementation of NextPassword is based on the Edge Functions of Vercel. Password checking is not on the server side, but is deployed on hundreds of edge nodes around the world. Whenever a user accesses, only the password check on the nearest edge node to the user is triggered.

The login page (/pages/auth) generated by NextPassword is completely STATIC, which means that the login page gets full client-side caches and traditional CDN node caches.

So NextPassword provides the most responsive password protection experience in theory, no matter how many pages you protect.

Open design

NextPassword's edge function code is isolated from the client code, so they don't have to interact with each other at all. The size of the middleware is about 3.9kb(gzipped), Auth component are approximately 20kb(gzipped, can be cached).

In addition, NextPassword supports server-side rendering styles, this allows you to package styles in the first html text to improve the first screen experience, or to render metadata for sharing on social media. refer to server-render styles.



The initPasswordMiddleware function will only run in Edge Functions.

type initPasswordMiddleware = (
  path: string | string[],
  options: Options,
) => void
Parameter Description Type Default
path Page paths, starting with / string string[] /
options.password value of password string process.env.PASSWORD
options.maxAge expiration of cookie number 1000 * 60 * 60 (1h)
options.authComponentName name of the login page string auth
options.exactMatch strict matching of path to protected pages boolean false
options.logoutPath logout path string /logout
options.salt the string used to serialize the password string -

Login component

You can set some props on the login component to customize the page.

Export custom login page
// pages/auth.tsx
import Login from 'next-password'

const Auth = () => (
  <Login displayProvided buttonText="go">
      Click on <a href="">this link</a> to contact me.
export default Auth
Props Description Type Default
dark show dark mode boolean false
shadow shadow of login card boolean true
displayProvided Show link to next-password boolean false
warningText default prompt content string -
forbiddenText password error prompt content string -
cardTitle title of login card string Authentication
buttonText text of login button string Login





Use password to protect your Next.js application.