![](\"https://github.com/storyofams/next-password-protect/workflows/Release/badge.svg\"){kind=icon}
\n \n \n ![](\"https://img.shields.io/npm/v/@charamza/next-password-protect\")
\n \n \n ![](\"https://codecov.io/gh/storyofams/next-password-protect/branch/master/graph/badge.svg?token=ZV0YT4HU5H\"){kind=icon}
\n \n \n ![](\"https://img.shields.io/github/stars/storyofams/next-password-protect.svg?style=social&label=Star&maxAge=86400\")
\n \n \n
\n \n \n \n \n \n \n \n \n \n
Password protect your Next.js deployments. View demo (Password is secret)
\n\n\n---\n\n[](https://user-images.githubusercontent.com/19343479/114987129-1a179180-9e95-11eb-9508-6c514f671ca9.mov)\n\n## How it works\n\nThis library adds a password prompt to your Next.js deployment. It consists of two main parts:\n1. Two serverless API routes:\n - A login route that checks if a password is correct and sets a cookie with a JWT in case it is.\n - A check route that validates if you have the authorization cookie with a valid JWT.\n2. A HOC ([Higher-Order Component](https://reactjs.org/docs/higher-order-components.html)) 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.\n\n**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.\n\n**This library is NOT meant as a secure password authentication wrapper, but rather as a way to keep nosey people out.**\n\n## Installation\n\n```sh\nyarn add @charamza/next-password-protect\n# or\nnpm install @charamza/next-password-protect\n```\n\n## Usage\n\nThere are 3 steps to enabling password protect: setting a global variable, adding the API routes, and adding the HOC to \\_app.\n\n### Step 1\n\nIn 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`:\n\n```javascript\nmodule.exports = {\n env: {\n // Add any logic you want here, returning `true` to enable password protect.\n PASSWORD_PROTECT: process.env.ENVIRONMENT === 'staging',\n }\n});\n```\n\n### Step 2\n\nAdd 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`.\n\n```javascript\nimport { loginHandler } from \"@charamza/next-password-protect\";\n\nexport default loginHandler(\"YOUR_SECRET_PASSWORD\", {\n // Options go here (optional)\n cookieName: \"next-password-protect\",\n});\n```\n\n```javascript\nimport { passwordCheckHandler } from \"@charamza/next-password-protect\";\n\nexport default passwordCheckHandler(\"YOUR_SECRET_PASSWORD\", {\n // Options go here (optional)\n cookieName: \"next-password-protect\",\n});\n```\n\n### Step 3\n\nAdd the `withPasswordProtect` HOC to the default export of `App` in `pages/_app.tsx`:\n\n```javascript\nimport { withPasswordProtect } from \"@charamza/next-password-protect\";\n\n// Before: export default App;\nexport default process.env.PASSWORD_PROTECT\n ? withPasswordProtect(App, {\n // Options go here (optional)\n loginApiUrl: \"/login\",\n })\n : App;\n```\n\n**Note**: make sure to specify `loginApiUrl` and/or `checkApiUrl` if the api route(s) are not default.\n\n## API\n\n### API routes handlers\n```loginHandler(password: string, options)```\n\nThe options object can contain any of the following options:\n\nOption | Description | Default value\n------ | ----------- | -------------\n`cookieMaxAge`| Cookie Max-Age attribute | `undefined`\n`cookieName`| The name of the authorization cookie | `'next-password-protect'`\n`cookieSameSite`| SameSite cookie attribute | `false`\n`cookieSecure`| Secure flag on the cookie | `process.env.NODE_ENV === 'production'`\n\n```passwordCheckHandler(password: string, options)```\n\nThe options object can contain any of the following options:\n\nOption | Description | Default value\n------ | ----------- | -------------\n`cookieName`| The name of the authorization cookie | `'next-password-protect'`\n\n\n### Next App HOC\n```withPasswordProtect(App: NextApp, options)```\n\nThe options object can contain any of the following options:\n\nOption | Description | Default value\n------ | ----------- | -------------\n`checkApiUrl`| Relative path of the api route handled by `passwordCheckHandler` | `'/api/passwordCheck'`\n`loginApiUrl`| Relative path of the api route handled by `loginHandler` | `'/api/login'`\n`loginComponent`| Supply your own React component to show as login prompt | `LoginComponent`\n`loginComponentProps`| Properties object to customize the login prompt, without overriding the entire component (see below) | `{}`\n`bypassProtection`| Bypass protection for specific routes, decided by callback with `NextRouter` param | `({ route }) => false`\n\nThe `loginComponentProps` object can contain any of the following options:\n\nOption | Description | Default value\n------ | ----------- | -------------\n`backUrl`| Show a link with this URL to go back to main website | `undefined`\n`buttonBackgroundColor`| Login button background color | `'#01EDBC'`\n`buttonColor`| Login button color | `'#111'`\n`logo` | Show a logo above the prompt (img src) | `undefined`\n\n## Advanced\n\n### Custom login component\n\nTo 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.\nYou can use `src/hoc/LoginComponent.tsx` as a starting point.\n\n## Caveats\n\nAMP 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.\n","readmeFilename":"README.md"}