@quarva/netlify-plugin-contextual-redirects v1.1.0

Contextual Redirects for Netlify

A Netlify build plugin to activate different redirects based on the deploy context.

Usage

Install

npm install @quarva/netlify-plugin-contextual-redirects

or

yarn add @quarva/netlify-plugin-contextual-redirects

Add the plugin to netlify.toml

[[plugins]]
package = "@quarva/netlify-plugin-contextual-redirects"

Note: The [[plugins]] line is required for each plugin, even if you have other plugins in your netlify.toml file already.

Configuration

Contexts

Before the plugin will do anything, you need to configure the deploy contexts in which it should activate. This is done by passing an array to the contexts input.

The array can include any of the standard Netlify deploy contexts - e.g. production or deploy-preview - or a branch name, if you've enabled branch deploys for your site.

[[plugins]]
package = "@quarva/netlify-plugin-contextual-redirects"
	[plugins.inputs]
		"contexts" = ["production","staging"]
		# Here, production is a standard context and staging is a branch.

Modes

This plugin supports both standalone _redirects files and redirect blocks in netlify.toml. You can switch between these two using the mode input.

By default, the plugin operates in standalone mode - this will always write to a _redirects file in your site's publish direrctory. If that file already exists, it will be overwritten.

In append mode, redirects will be appended to the end of your netlify.toml file and existing redirects won't be overwritten. This allows you to combine permanent redirects - which live in the base netlify.toml - with context-specific rules.

[[plugins]]
package = "@quarva/netlify-plugin-contextual-redirects"
	[plugins.inputs]
		"contexts" = ["production","staging"]
		"mode" = "append"
		# Can be "append" or "standalone"

Redirect Sources

When the plugin detects an active context, it looks for a redirects_$context file in your site's publish directory - for example, /dist/redirects_production.

You can tell the plugin to look for source files in a different path using the redirect_path input.

Important: make sure the source files are formatted according to the mode you chose. Source files for append mode must use [[redirects]] blocks, and source files for standalone mode must use the Netlify _redirects syntax.

[[plugins]]
package = "@quarva/netlify-plugin-contextual-redirects"
	[plugins.inputs]
		"redirect_path" = "./config/redirects"

Other Options

[[plugins]]
package = "@quarva/netlify-plugin-contextual-redirects"
	[plugins.inputs]
		"verbose" = ""
		 # If true, the plugin will write each step to the deploy log.

Contextual Redirects for Netlify is a foundry project from Quarva.