Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/blazity/next-maintenance-mode
🛠️ The intuitive cost-efficient middleware for effortless maintenance mode toggling. Supported by multiple configuration options and a straightforward API. Ready to integrate with your Next.js app directory!
https://github.com/blazity/next-maintenance-mode
maintenance-mode maintenance-page middleware next13 nextjs react redis vercel
Last synced: 10 days ago
JSON representation
🛠️ The intuitive cost-efficient middleware for effortless maintenance mode toggling. Supported by multiple configuration options and a straightforward API. Ready to integrate with your Next.js app directory!
- Host: GitHub
- URL: https://github.com/blazity/next-maintenance-mode
- Owner: Blazity
- Created: 2023-09-06T09:41:41.000Z (about 1 year ago)
- Default Branch: main
- Last Pushed: 2024-01-23T16:58:15.000Z (10 months ago)
- Last Synced: 2024-04-22T21:10:34.879Z (7 months ago)
- Topics: maintenance-mode, maintenance-page, middleware, next13, nextjs, react, redis, vercel
- Language: TypeScript
- Homepage:
- Size: 4.88 MB
- Stars: 19
- Watchers: 2
- Forks: 1
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
Next.js Maintenance Mode 🛠️
## Overview
`next-maintenance-mode` is a middleware specially designed for Next.js applications, enabling you to easily toggle maintenance mode on and off. When activated, it redirects users to a designated maintenance page. Its compatibility with configuration providers such as Upstash and Edge Config allows for flexible and dynamic maintenance state management.
## Motivation
Setting up a maintenance mode in Next.js apps can be a hassle, particularly on certain hosting providers, which lack built-in support for this feature. Current methods are time-consuming and usually leave API routes vulnerable.
To solve this, we've created a straightforward solution that lets you choose between two different providers, making the setup process for maintenance mode quicker and more cost-effective, without skimping on security. This solution also includes an optional caching feature to help save bandwidth.
| Provider | Reads (free plan) |
| ------------------ | ---------------------- |
| Vercel/Edge-Config | 50k/month |
| Upstash/Redis | ~ 300k/month (10k/day) |
## Features
- ⚡️ **Next.js Compatibility**: Out-of-the-box integration with the new Next.js app directory, providing a smooth user experience.
- 🛠️ **Seamless Integration**: Designed to work hand-in-hand with Next.js applications, ensuring an intuitive setup process and seamless operation.
- 📚 **Provider Options**: Offers the flexibility to choose between Upstash and Edge Config as configuration providers, allowing you to tailor the solution to your existing workflow and tools.
- 💻 **Simple API**: One Wrapper to Rule Them All - `withMaintenanceMode`
- 💾 **Bandwidth Reduction**: Our optional caching feature reduces bandwidth usage, making your maintenance mode not only more efficient but also cost-effective.
- 🔄 **Dynamic Toggle**: Easily toggle maintenance mode on and off without the need for a complete app rebuild, saving you time and effort.
## Installation
To get started with `next-maintenance-mode`, you can install the package using your preferred package manager:
```bash
$ yarn add next-maintenance-mode
# or
$ npm install next-maintenance-mode
# or
$ pnpm i next-maintenance-mode
```
## Usage
To integrate `next-maintenance-mode` into your Next.js application, insert the following code into your middleware file.
```javascript
import { withMaintenanceMode } from 'next-maintenance-mode'
const middlewareOptions = {
provider: 'upstash' | 'edge-config', // Required
maintenancePageSlug: '/maintenance', // Optional
key: 'your_key_here', // Optional
cacheTime: 'number', //Optional - defined in ms for e.g. 60000 = one minute
}
withMaintenanceMode(
{
beforeCheck: NextMiddleware, // function which will be executed before checking the maintenance mode (if an instance of NextResponse is returned, checking maintenance mode status & afterCheck is skipped)
afterCheck: NextMiddleware, // function which will be executed after checking the maintenance mode (only if maintenance mode status is set to false)
},
'your_connection_string_here',
middlewareOptions,
)
```
Before using the middleware, you need to configure it with the necessary settings. Here are the options you can specify:
- **provider:** Identify your configuration provider, choose between 'upstash' or 'edge-config'. This field is mandatory.
- **maintenancePageSlug:** Specify the route to your maintenance page. The default setup directs to '/maintenance'.
- **key:** Create a unique key to indicate the maintenance mode state in your configuration provider, defaulting to 'isInMaintenanceMode'.
- **cacheTime:** Defined in milliseconds, determines how long data is stored in the cache before being refreshed. Utilizing an LRU (Least Recently Used) caching algorithm, helps to save bandwidth.
#### The connection string structure differs between Upstash and Edge Config:
- **For Upstash:** Include both the URL and token, formatted as **`url@token`**.
- **For Edge Config:** Specify the API endpoint or path given by Edge Config.
⚠️ Keep in mind, due to edge functions nature the LRU cache might occasionally reset, but it's nothing to worry about. If this happens, the status is automatically checked in the provider and updated. This won't affect passed middleware's functions - they are not cached.
### Setting maintenance status from different locations:
To toggle the maintenance mode status directly through code, you can use the updateMaintenanceModeStatus function. Here's how you can call this function with appropriate parameters:
```javascript
updateMaintenanceModeStatus(true, {
provider: 'upstash' | 'edge-config', // specify the provider
connectionString: 'your_connection_string_here', // provide your connection string
key?: 'your_key_here', // optional, default is "isInMaintenanceMode"
maintenanceEdgeConfigId?: 'your_edge_config_id_here', // necessary for edge-config provider
maintenanceModeVercelApiToken?: 'your_vercel_api_token_here', // necessary for edge-config provider
})
```
Example use cases:
- **Scheduled Updates:** Activate maintenance mode during pre-set times.
- **High Traffic**: Enable maintenance mode when traffic exceeds server capacity.
- **System Health**: Trigger maintenance mode in response to health check failures.
⚠️ Note that if caching is activated, alterations to the maintenance status might not take effect immediately.
### Access Parameters in Check Events:
You can directly access the following parameters during events:
- **req: NextRequest**
- **_next: NextFetchEvent**
These can be accessed in:
- `beforeCheck`
- `afterCheck`
**Example integration with next-auth:**
```javascript
import { NextFetchEvent, NextRequest, NextResponse } from "next/server";
import { withMaintenanceMode } from "next-maintenance-mode";
import { getToken } from "next-auth/jwt";
async function firstMiddleware(req: NextRequest, _next: NextFetchEvent) {
const token = await getToken({ req });
if (!token) {
return NextResponse.rewrite(new URL("/sign-in", req.nextUrl));
}
if (token.role === "admin") {
return NextResponse.next(); //If you want you can disable checking maintenance mode for users with an admin role
}
}
async function secondMiddleware(req: NextRequest, _next: NextFetchEvent) {
console.log("secondMiddleware");
}
export default withMaintenanceMode(
{ beforeCheck: firstMiddleware, afterCheck: secondMiddleware },
process.env.MAINTENANCE_MODE_CONNECTON_STRING as any,
{
provider: process.env.MAINTENANCE_MODE_PROVIDER as any,
maintenancePageSlug: process.env.MAINTENANCE_MODE_PAGE_SLUG,
key: process.env.MAINTENANCE_MODE_KEY,
}
);
export const config = {
matcher: ["/((?!api/auth|_next/static|_next/image|favicon.ico).*)"],
};
```
## Error Messages
There are specific error messages that may be encountered while using the middleware:
| Error Message | Description |
|---------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| Maintenance Key Missing Error | This error occurs if the maintenance key is not found in your configuration provider. It can be encountered when checking the maintenance mode state. |
| Invalid Connection String | This error is triggered when the connection string does not match the selected provider. |
| Unsupported Provider Error | This error is thrown when an unsupported provider is passed to the function. |
| Middleware Configuration Error | This error is thrown when neither `beforeCheck` nor `afterCheck` middleware functions are defined during the setup. It ensures that at least one of these functions is implemented to proceed with the maintenance mode check. |
## 🙌 Contribution
Contributions are always welcome! To contribute, please follow these steps:
1. Fork the repository.
2. Create a new branch with a descriptive name.
3. Make your changes, and commit them.
4. Push your changes to the forked repository.
5. Create a pull request, and we'll review your changes.
## 📡 Community
If you're looking for help or simply want to share your thoughts about the project, we encourage you to join our Discord community. Here's the link: [https://blazity.com/discord](https://blazity.com/discord). It's a space where we exchange ideas and help one another. Everyone's input is appreciated, and we look forward to welcoming you.
