https://github.com/betahuhn/express-redirection
⚡♻️ Quick redirect configuration for Express.js
https://github.com/betahuhn/express-redirection
express middleware nodejs redirects
Last synced: 7 months ago
JSON representation
⚡♻️ Quick redirect configuration for Express.js
- Host: GitHub
- URL: https://github.com/betahuhn/express-redirection
- Owner: BetaHuhn
- License: mit
- Created: 2021-08-27T18:40:43.000Z (about 4 years ago)
- Default Branch: master
- Last Pushed: 2023-03-06T08:04:58.000Z (over 2 years ago)
- Last Synced: 2025-01-21T16:34:56.853Z (9 months ago)
- Topics: express, middleware, nodejs, redirects
- Language: JavaScript
- Homepage: https://readme.fish/betahuhn/express-redirection
- Size: 440 KB
- Stars: 1
- Watchers: 4
- Forks: 0
- Open Issues: 8
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Funding: .github/FUNDING.yml
- License: LICENSE
Awesome Lists containing this project
README
# ⚡♻️ Express Redirection[](https://github.com/BetaHuhn/express-redirection/actions?query=workflow%3A%22Node+CI%22) [](https://github.com/BetaHuhn/express-redirection/actions?query=workflow%3A%22Release+CI%22) [](https://github.com/BetaHuhn/express-redirection/blob/master/LICENSE) 
Quick redirect configuration for Express.js
## Features
- **🔌 Quick integration** - *can be used directly as an Express middleware*
- **🔨 Easy Customization** - *use a simple JSON file to define your redirects*
- **♻️ Path rewrites** - *capture and rewrite parts of your routes*
- **🚦 Conditional redirects** - *redirect based on specific hosts, ips, headers, query strings or cookie values*## 🚀 Get started
Install [express-redirection](https://github.com/BetaHuhn/express-redirection) via NPM:
```shell
npm install express-redirection
```*Requires express to be installed*
## 📚 Usage
Create a redirect config `redirects.json` and define your redirects:
*redirects.json*
```json
[
{ "src": "/user", "dest": "/api/user" },
{ "src": "/view-source", "dest": "https://github.com/betahuhn/express-redirection", "statusCode": 308 },
{
"src": "/:path((?!uk/).*)",
"dest": "/uk/:path*",
"has": {
"header": {
"cf-ipcountry": "GB"
}
},
"statusCode": 307
}
]
```Use the middleware with Express:
*index.js*
```js
const express = require('express')
const redirectMiddleware = require('express-redirection')const app = express()
// Load the redirects from the redirects.json file
const redirects = require('./redirects.json')// Use the middleware and pass it the redirects
app.use(redirectMiddleware(redirects))
```> Note: Make sure to use the middleware before any other routes
That's it 🎉
Take a look below to see how to use the `redirects.json` file.
## ⚙️ Configuration
`app.use(redirectMiddleware(redirects))` accepts a JSON array containing redirects to perform. Each item needs to at least include a `src` and `dest` attribute. `src` needs to be a relative pathname, `dist` can be a absolute URL or relative pathname. See below for the rest of the options.
It is recommended to define the redirects in a `redirects.json` file and load it with `require`, but you can also define it programmatically as a JSON object:
*index.js*
```js
const redirects = [ { src: '/foo', dest: '/bar' } ]app.use(redirectMiddleware(redirects))
```### Redirect object definition
Here are all the options you can use in the redirect object:
- `src`: A pattern that matches each incoming pathname (excluding querystring). The pattern must follow the syntax from [path-to-regexp](https://github.com/pillarjs/path-to-regexp).
- `dest`: A location destionation defined as a relative pathname or external URL. You can reuse path params from the `src` here.
- `statusCode`: A [HTTP status](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html) to return to the client. Defaults to `301`.
- `method`: A [HTTP Request Method](https://datatracker.ietf.org/doc/html/rfc7231#section-4) to match the request to.
- `protocol`: The protocol to match the request to. Either `http` or `https` (for TLS requests).
- `has`: An optional object containing request properties to match against.
- `host`: The hostname to match against the HTTP host header. Can be a glob expression.
- `ip`: Matched against the remote IP address of the request. Can be a glob expression.
- `query`: Match against parsed key value pairs from the request querystring.
- `key`: string
- `value`: string. Can be a glob expression.
- `header`: Match against parsed key value pairs from the request headers.
- `key`: string
- `value`: string. Can be a glob expression.
- `cookie`: Match against parsed key value pairs from cookies sent by the request.
- `key`: string
- `value`: string. Can be a glob expression.## 📖 Examples
Here are some example redirects to use:
### Basic
Here is the most basic configuration consisting of a source pathname and a destination pathname to redirect the request to if it matches the source.
*redirects.json*
```json
[
{ "src": "/user", "dest": "/api/user" }
]
```### Path params
You can use params (`:string`) to pass parts of a request pathname to the destination:
*redirects.json*
```json
[
{ "src": "/api/:path", "dest": "https://api.example.com/:path" }
]
```For example `/api/users/names` will be redirected to `https://api.example.com/users/names`.
### Custom status code
By default redirects will be performed with the `301` status code, this can be changed with the `statusCode` option:
*redirects.json*
```json
[
{ "src": "/source", "dest": "https://github.com/betahuhn/express-redirection", "statusCode": 302 },
]
```### Request method
By default it will redirect requests regardless of the HTTP method used. You can specify a specific one instead:
*redirects.json*
```json
[
{ "method": "POST", "src": "/user", "dest": "/api/user" },
]
```### Hostname
You can also limit the redirect to a specific hostname:
*redirects.json*
```json
[
{ "host": "example.com", "src": "/user", "dest": "/api/user" },
]
```The `host` value can also be a glob pattern like `*.example.com`
### Conditional redirect
You can use the `has` option to define propteries that need to exist on the request in order for the redirect to apply:
*redirects.json*
```json
[
{
"src": "/feedback",
"dest": "/feedback/issue",
"has": {
"query": {
"type": "issue"
}
}
}
]
```Here only requests to `/feedback` with the querystring of `?type=issue` would be redirected.
### Advanced
*redirects.json*
```json
[
{
"src": "/:path((?!uk/).*)",
"dest": "/uk/:path*",
"has": {
"header": {
"cf-ipcountry": "GB"
}
},
"statusCode": 307
}
]
```Translation: Request for `/product/features` from GB (based on `cf-ipcountry` header) will be redirected to `/uk/product/features` with a status code of `307`
## 💻 Development
- run `yarn lint` or `npm run lint` to run eslint.
- run `yarn watch` or `npm run watch` to watch for changes.
- run `yarn build` or `npm run build` to produce a compiled version in the `lib` folder.## ❔ About
This project was developed by me ([@betahuhn](https://github.com/BetaHuhn)) in my free time. If you want to support me:
[](https://www.paypal.com/cgi-bin/webscr?cmd=_s-xclick&hosted_button_id=394RTSBEEEFEE)
[](https://ko-fi.com/F1F81S2RK)
### Credits
The project was inspired by Vercel's `vercel.json` [redirects](https://vercel.com/docs/configuration#project/redirects). I wanted something similar to use for any Express app.
## 📄 License
Copyright 2021 Maximilian Schiller
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.