next-password-protect

Password protect your Next.js deployments. View demo (Password is secret)

---

example-with-custom-logo.mov

How it works

This library adds a password prompt to your Next.js deployment. It consists of two main parts:

1. Two serverless API routes:
   • A login route that checks if a password is correct and sets a cookie with a JWT in case it is.
   • A check route that validates if you have the authorization cookie with a valid JWT.
2. A HOC (Higher-Order Component) that wraps Next.js App and adds a check that validates if you are logged in. If you do, then you can view the app normally; otherwise, you are presented with a password prompt.

Important: The recommended use case for this library is in a staging or preview environment. By taking advantage of webpack's DefinePlugin, we can make sure this library is only included in certain environments, keeping the production bundle size small.

This library is NOT meant as a secure password authentication wrapper, but rather as a way to keep nosey people out.

Installation

yarn add next-password-protect
# or
npm install next-password-protect

Usage

There are 3 steps to enabling password protect: setting a global variable, adding the API routes, and adding the HOC to _app.

Step 1

In order to be able to take advantage of dead code elimination, it is recommended to add an environment variable like process.env.PASSWORD_PROTECT, and enable the library based on that variable. To set this variable, add the following to next.config.js:

module.exports = {
  env: {
    // Add any logic you want here, returning `true` to enable password protect.
    PASSWORD_PROTECT: process.env.ENVIRONMENT === 'staging',
  }
});

Step 2

Add two api routes, one with the loginHandler and one with the passwordCheckHandler api function. You can name them anything, as long as you pass the names to loginApiUrl and checkApiUrl respectively, in the next step. By default it expects /login and /passwordCheck.

import { loginHandler } from "next-password-protect";

export default loginHandler("YOUR_SECRET_PASSWORD", {
  // Options go here (optional)
  cookieName: "next-password-protect",
});

import { passwordCheckHandler } from "next-password-protect";

export default passwordCheckHandler("YOUR_SECRET_PASSWORD", {
  // Options go here (optional)
  cookieName: "next-password-protect",
});

Step 3

Add the withPasswordProtect HOC to the default export of App in pages/_app.tsx:

import { withPasswordProtect } from "next-password-protect";

// Before: export default App;
export default process.env.PASSWORD_PROTECT
  ? withPasswordProtect(App, {
    // Options go here (optional)
    loginApiUrl: "/login",
  })
  : App;

Note: make sure to specify loginApiUrl and/or checkApiUrl if the api route(s) are not default.

API

API routes handlers

loginHandler(password: string, options)

The options object can contain any of the following options:

Option	Description	Default value
cookieMaxAge	Cookie Max-Age attribute	undefined
cookieName	The name of the authorization cookie	'next-password-protect'
cookieSameSite	SameSite cookie attribute	false
cookieSecure	Secure flag on the cookie	process.env.NODE_ENV === 'production'

passwordCheckHandler(password: string, options)

The options object can contain any of the following options:

Option	Description	Default value
cookieName	The name of the authorization cookie	'next-password-protect'

Next App HOC

withPasswordProtect(App: NextApp, options)

The options object can contain any of the following options:

Option	Description	Default value
checkApiUrl	Relative path of the api route handled by passwordCheckHandler	'/api/passwordCheck'
loginApiUrl	Relative path of the api route handled by loginHandler	'/api/login'
loginComponent	Supply your own React component to show as login prompt	LoginComponent
loginComponentProps	Properties object to customize the login prompt, without overriding the entire component (see below)	{}
bypassProtection	Bypass protection for specific routes, decided by callback with NextRouter param	({ route }) => false

The loginComponentProps object can contain any of the following options:

Option	Description	Default value
backUrl	Show a link with this URL to go back to main website	undefined
buttonBackgroundColor	Login button background color	'#01EDBC'
buttonColor	Login button color	'#111'
logo	Show a logo above the prompt (img src)	undefined

Advanced

Custom login component

To change the default login component, a React component can be supplied to the withPasswordProtect HOC. In order for the library to function properly, make sure your login component has password input that is validated by the the api route. You can use src/hoc/LoginComponent.tsx as a starting point.

Caveats

AMP is not yet supported, because the LoginComponent failed AMP validation. On an AMP page, nothing is rendered. This could be fixed by changing LoginComponent to valid AMP.