Gatsby Meta Refresh Redirect Plugin

Common errors

• Redirect not working or generating correctly.

  cause The `gatsby-plugin-meta-redirect` plugin is not placed last in the `plugins` array in `gatsby-config.js`, allowing other plugins to override or interfere with its output.
  fix Move `gatsby-plugin-meta-redirect` to the very end of the `plugins` array in your `gatsby-config.js` file.

• Low SEO ranking for pages with redirects, or 'soft 404' warnings in search console.

  cause The plugin uses `<meta http-equiv="refresh">` which is interpreted by search engines as a soft redirect (similar to a 302 'Found' status), not a permanent 301 'Moved Permanently'. This can impact page authority transfer and SEO.
  fix For critical redirects, implement true 301 server-side redirects via your hosting provider's configuration (e.g., `_redirects` file for Netlify/Vercel, NGINX rules for custom servers) instead of relying solely on meta refresh. Update internal links and sitemaps to point to the final URLs.

Warnings

• gotcha The `gatsby-plugin-meta-redirect` plugin *must* be the last entry in the `plugins` array within your `gatsby-config.js` file. Failure to do so can result in redirects not being generated or working incorrectly, as other plugins might interfere with the build output or path generation.
  Fix: Ensure `gatsby-plugin-meta-redirect` is the final plugin listed in `gatsby-config.js`.
• gotcha This plugin generates redirects using client-side `<meta http-equiv="refresh">` tags, not server-side 301 HTTP redirects. While functional for static hosting, meta refresh redirects are generally less favorable for Search Engine Optimization (SEO) as they are treated as temporary (302-like) redirects by search engines and may not pass full link equity. They can also lead to a poorer user experience due to a slight delay.
  Fix: For SEO-critical permanent redirects, prefer hosting-provider-specific 301 redirect solutions (e.g., Netlify `_redirects` file, Vercel redirects in `vercel.json`, or server-side configurations) if your host supports them. Use this plugin when server-side control is not available or for non-SEO-critical temporary redirects.
• deprecated The `gatsby-plugin-meta-redirect` package has not been updated in over seven years (last published in November 2018) and is considered unmaintained. This raises concerns about compatibility with newer Gatsby versions, Node.js environments, and potential security vulnerabilities that will not be addressed.
  Fix: Evaluate alternatives like `gatsby-plugin-client-side-redirect` (though also old) or server-side redirect solutions provided by your hosting provider. For new projects, consider Gatsby versions that have native redirect capabilities or more actively maintained plugins.

Install

• npm install gatsby-plugin-meta-redirect npm
• yarn add gatsby-plugin-meta-redirect yarn
• pnpm add gatsby-plugin-meta-redirect pnpm

Imports

• gatsby-plugin-meta-redirect
  wrong:

  import gatsbyPluginMetaRedirect from 'gatsby-plugin-meta-redirect';

  correct:

  // in gatsby-config.js
  plugins: [
    // other plugins...
    `gatsby-plugin-meta-redirect` // must be last
  ];

  This plugin does not export any JavaScript symbols for direct import. Its functionality is enabled by adding it to the `plugins` array in `gatsby-config.js`. The configuration must be the last entry in the plugins array for proper operation.
• createRedirect
  wrong:

  import { createRedirect } from 'gatsby-plugin-meta-redirect';

  correct:

  // in gatsby-node.js
  exports.createPages = async ({ actions }) => {
    const { createRedirect } = actions;
    createRedirect({
      fromPath: '/old-url/',
      toPath: '/new-url/',
      isPermanent: true,
      redirectInBrowser: true
    });
    // ... other createPage calls
  };

  `createRedirect` is a Gatsby Node API action (provided via `actions` object), not an export of `gatsby-plugin-meta-redirect`. The plugin *consumes* these actions to generate the HTML redirect files.

Quickstart

This quickstart demonstrates how to configure `gatsby-plugin-meta-redirect` in `gatsby-config.js` and how to define redirects using Gatsby's `createRedirect` action within `gatsby-node.js` for both static and data-driven redirect scenarios. It illustrates basic permanent redirects, language-specific redirects, and iterating over markdown frontmatter to generate redirects programmatically.

// gatsby-config.js
module.exports = {
  plugins: [
    // Ensure this plugin is the last one in your array
    `gatsby-plugin-meta-redirect`
  ]
};

// gatsby-node.js
const path = require('path');

exports.createPages = async ({ actions, graphql }) => {
  const { createRedirect, createPage } = actions;

  // Example 1: Basic permanent redirect
  createRedirect({
    fromPath: '/legacy-page/',
    toPath: '/new-destination/',
    isPermanent: true,
    redirectInBrowser: true
  });

  // Example 2: Redirect with a language preference
  createRedirect({
    fromPath: '/global-content/',
    toPath: '/en-US/global-content/',
    Language: 'en'
  });

  // Example 3: Programmatic redirect based on data (e.g., old blog post slugs)
  const result = await graphql(`
    {
      allMarkdownRemark {
        edges {
          node {
            frontmatter {
              slug
              oldPaths
            }
          }
        }
      }
    }
  `);

  if (result.errors) {
    throw result.errors;
  }

  const posts = result.data.allMarkdownRemark.edges;

  posts.forEach(({ node }) => {
    if (node.frontmatter.oldPaths) {
      node.frontmatter.oldPaths.forEach(oldPath => {
        createRedirect({
          fromPath: oldPath,
          toPath: node.frontmatter.slug,
          isPermanent: true,
          redirectInBrowser: true
        });
      });
    }
    createPage({
      path: node.frontmatter.slug,
      component: path.resolve('./src/templates/blog-post.js'),
      context: {
        slug: node.frontmatter.slug,
      },
    });
  });
};