lilredirector v0.5.3
a simple redirector engine for cloudflare workers.
installation
- install the package
$ npm install lilredirector
- create a kv namespace called
REDIRECTS
using wrangler
$ wrangler kv:namespace create REDIRECTS
- add the
kv-namespace
provided by wrangler output towrangler.toml
kv_namespaces = [{ binding = "REDIRECTS", id = "$id", preview_id = "$id" }]
usage
import redirector from 'lilredirector'
addEventListener('fetch', event => event.respondWith(handler(event)))
// note the `event` function argument! many workers scripts will
// pass in `event.request`, lilredirector needs the full `event` object
async function handler(event) {
const { response, error } = await redirector(event)
if (response) return response
// optionally return an error response
if (error) return error
// other workers code
}
configuration
import redirector from 'lilredirector'
addEventListener('fetch', event => event.respondWith(handler(event)))
async function handler(event) {
const { response, error } = await redirector(event, {
// configuration options can be passed as an optional object.
// see the below documentation for examples of each:
//
// baseUrl
// basicAuthentication
// cancelBulkAddOnError
// removeTrailingSlashes
// validateRedirects
})
// ...
}
changing the base url
by default, lilredirector serves the UI and any associated data handlers from /_redirects
. this can be customized by providing baseUrl
in lilredirector's configuration:
async function handler(event) {
const { response, error } = await redirector(event, {
baseUrl: `/mylilredirector`,
})
if (response) return response
}
removing trailing slashes
by default, lilredirector will match and redirect URLs without trailing slashes. for instance, if you have a redirect set up for /about
, visiting /about/
will search for a redirect for /about
in the lilredirector database, and redirect accordingly. this feature can be disabled by passing the removeTrailingSlashes
boolean in the configuration object into the redirector
function:
async function handler(event) {
const { response, error } = await redirector(event, {
removeTrailingSlashes: false,
})
if (response) return response
}
validating redirects
by default, lilredirector will validate a redirect before allowing it to be saved. for instance, if you attempt to save a redirect for /about
that points to /foo
, a page that doesn't exist, lilredirector will error on save and return an error message in the UI. this can be disabled using the config option validateRedirects
async function handler(event) {
const { response, error } = await redirector(event, {
validateRedirects: false,
})
if (response) return response
}
canceling bulk adds on validation errors
as of lilredirector 0.2.0, there is support in the UI for adding multiple redirects using a bulk UI. if the above validateRedirects
option is enabled, lilredirector will validate each redirect inside of the bulk operation before saving.
by default, lilredirector will save valid URLs in a bulk operation even if some are invalid - instead of canceling the operation completely, it will return an error message indicating the individual failed/invalid URLs.
this can be changed using the cancelBulkAddOnError
value in configuration, which will cause the entire bulk operation to cancel if any of the URLs are found to be invalid:
async function handler(event) {
const { response, error } = await redirector(event, {
cancelBulkAddOnError: true,
})
if (response) return response
}
how it works
handlers
lilredirector embeds itself under the /_redirects
path, unless specified otherwise by the baseUrl
configuration param as defined in the previous section. here's a list of the paths you'll be adding to your application:
path | fn |
---|---|
/_redirects | ui |
/_redirects/delete | redirect delete handler |
/_redirects/update | redirect create/update handler |
editor
manage and create new redirects at /_redirects
!
as of version 0.2.0, the lilredirector UI has support for bulk redirect adding. using the "add multiple redirects" dropdown, you can add redirects in a larger textarea
element using CSV format, as seen below:
/firsturl,https://myredirectlocation.com
/second,https://mysecondredirectlocation.com
this feature is beta and may be prone to errors. simple comma-separated value CSVs with no headers/footers are the only tested and supported values for this field at this time.
authentication
you should really, really put this behind authentication!
basic authentication
using the configuration object, you can enable basic auth for lilredirector and any subpaths (creating/deleting redirects):
async function handler(event) {
const { response, error } = await redirector(event, {
basicAuthentication: {
username: USERNAME,
password: PASSWORD,
},
})
if (response) return response
}
it is strongly recommended that you use wrangler secret
to define and store your basic auth credentials, as seen above:
$ wrangler secret put USERNAME
$ wrangler secret put PASSWORD
cloudflare access
you can add complex role-based auth using cloudflare access. see the below screenshot for an example config:
3 years ago
3 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago