Skip to content

instantcommerce/next-password-protect

Repository files navigation

Instant Commerce

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.