Defining redirects for Next.js applications

Requirements
Creating the redirects app
- Creating the redirect content type
- Creating the Redirects Content App
Adding redirects
Fetching data
- Fetching data from the REST delivery endpoint
- Fetching data from the GraphQL API
Parsing the data
Checking for redirects using Next.js Middleware
Updating redirect data using a webhook
Checking your redirects

During a website redesign, modifying the URL path of a page may be necessary.

For example, you may want to relocate the contact page to the “about us” section. This change should result in the page that is currently accessed at the /contact path being accessed at the new /about-us/contact path.

For a change like this, web teams must consider that the original link might still be in use, for example, on social media or other websites. To avoid losing traffic from these sources – and causing frustration for users – we use redirects.

When delivering content using the headless approach, managing redirects at scale can be a challenge.

This blog post will show how to create a Magnolia Content App that enables content authors to easily manage redirects for a headless environment and how to pass the defined redirects to a Next.js application using both REST and GraphQL methods.

Requirements

Magnolia 6.2.25 or higher
Webooks module 1.0.0 or higher
REST Client module 2.0.4 or higher
GraphQL module 1.1.2 or higher
Next.js application

The easiest way to get started with Magnolia and Next.js is the minimal-headless-spa-demos tutorial. You can also explore our nextjs-redirect-demo project, where the Next.js application and Redirects Content App are already set up.

Creating the redirects app

For this tutorial, we assume that Magnolia and Next.js are up and running.

First, we need to define how redirects are created and stored to allow content authors to manage them.

Let's start by creating a new directory for the Magnolia Light Module called nextjs-redirect-lm. Within this directory, we will soon create a Content Type and a Content App for the redirects.

Creating the redirect content type

Magnolia Content Types define and describe the types and structure of content in your project. Let's define a new Content Type called redirect with three properties:

name: This serves as the unique identifier for each redirect.
rootPage: This property represents the current root page that is targeted for redirection. In other words
it is the source page from which users will be redirected.
redirect: This property represents the redirection rules. It is composed of multiple attributes: 1)from: This field represents the initial URL path from where the redirection originates. 2)to: This field represents the destination URL. It could either be an internal link within your site or an external link to a different site. 3) code: This field represents the HTTP status code that will be sent with the redirect.

Create the file /nextjs-redirect-lm/contentTypes/redirect.yaml for the above content model:

  datasource:
  workspace: redirects
  autoCreate: true

model:
  nodeType: lib:redirect
  properties:
    - name: name
    - name: rootPage
    - name: redirect
      type: redirectItem
      multiple: true
  subModels:
    - name: redirectItem
      properties:
        - name: from
        - name: to
          type: toItem
        - name: code
    - name: toItem
      properties:
        - name: field
        - name: internal
        - name: custom

Once we created the Content Type, let's create a Content App.

Creating the Redirects Content App

A Magnolia Content App is an app for managing structured content. It defines the layout of the Content Type’s properties and other properties. Let's define a new Content App called redirects-app.

Create the file /nextjs-redirect-lm/apps/redirects-app.yaml:

  !content-type:redirect
name: redirects-app
label: Redirects App

subApps:
  browser:
    actions:
      activate:
        availability:
          multiple: true
  detail:
    form:
      properties:
        name:
          $type: textField
          required: true
        rootPage:
          $type: pageLinkField
          showOptions: true
          textInputAllowed: true
          converterClass: info.magnolia.ui.editor.converter.JcrNodeToPathConverter
          required: true
        redirect:
          $type: jcrMultiField
          field:
            $type: compositeField
            properties:
              from:
                $type: textField
                required: true
              to:
                $type: switchableField
                field:
                  $type: comboBoxField
                  required: true
                  datasource:
                    $type: optionListDatasource
                    options:
                      - name: internal
                        value: internal
                      - name: custom
                        value: custom
                itemProvider:
                  $type: jcrChildNodeProvider
                forms:
                  - name: internal
                    properties:
                      internal:
                        $type: pageLinkField
                        showOptions: true
                        textInputAllowed: true
                        converterClass: info.magnolia.ui.editor.converter.JcrNodeToPathConverter
                        required: true
                  - name: custom
                    properties:
                      custom:
                        $type: textField
                        required: true
              code:
                $type: textField
                required: true

We have now defined the overall layout of our Content App.

Note that the rootPage property has a pageLinkField type and that a redirect property consists of a from, to, and code field.

Also, notice that the to property if of a switchableField type with two possible options:

internal
custom

You may consider extending the Content App by a description and field validators ensuring that field input is entered in the correct format and length.

At this point, the new app should be visible in Magnolia:

Adding redirects

Now, open the Redirects App and click the "Add item" button. You should see the following form:

Go ahead and create your first redirect using the parameters from the screenshot.

Fetching data

How can we now access the data we just entered in the Content App?

There are two ways to fetch the data from a Content App: using a REST delivery endpoint or a GraphQL API.

Fetching data from the REST delivery endpoint

Return to the Light Module folder and create a new file to create the REST delivery endpoint.

/nextjs-redirect-lm/restEndpoints/delivery/redirects_v1.yaml:

  class: info.magnolia.rest.delivery.jcr.v2.JcrDeliveryEndpointDefinition
workspace: redirects
depth: 3
includeSystemProperties: false
bypassWorkspaceAcls: true
limit: 50
systemProperties:
  - mgnl:lastModified
  - mgnl:created

The endpoint is available immediately after creating its configuration and we can access the data on this URL: http://localhost:8080/magnoliaAuthor/.rest/delivery/redirects/v1/?rootPage%5Blike%5D=%2Fnextjs-redirect-demo%25

Note the ?rootPage[like]=/nextjs-redirect-demo% in the URL? This part allows us to filter the results using request parameters.

If you defined a redirect in the previous step, the response should look like this:

JSON:

  {
    "total": 1,
    "offset": 0,
    "limit": 50,
    "results": [
        {
            "@name": "Contact-Page-Redirect",
            "@path": "/Contact-Page-Redirect",
            "@id": "4c7c577e-71b8-47a6-8fe2-c94fc496f11d",
            "@nodeType": "mgnl:content",
            "rootPage": "/nextjs-redirect-demo",
            "name": "Contact Page Redirect",
            "mgnl:lastModified": "2022-10-31T14:04:11.398+01:00",
            "mgnl:created": "2022-10-31T14:04:11.397+01:00",
            "redirect": {
                "@name": "redirect",
                "@path": "/Contact-Page-Redirect/redirect",
                "@id": "a36b3c4a-904a-4540-841c-da953baf52b6",
                "@nodeType": "mgnl:contentNode",
                "mgnl:lastModified": "2022-10-31T14:04:11.413+01:00",
                "mgnl:created": "2022-10-31T14:04:11.413+01:00",
                "redirect0": {
                    "@name": "redirect0",
                    "@path": "/Contact-Page-Redirect/redirect/redirect0",
                    "@id": "1c59c77f-c6c6-4c4f-8346-22056a1ecf93",
                    "@nodeType": "mgnl:contentNode",
                    "from": "/contacts",
                    "code": "301",
                    "mgnl:lastModified": "2022-10-31T14:04:11.437+01:00",
                    "mgnl:created": "2022-10-31T14:04:11.437+01:00",
                    "to": {
                        "@name": "to",
                        "@path": "/Contact-Page-Redirect/redirect/redirect0/to",
                        "@id": "c5789397-05ba-45b3-b7ff-1d810760c3e1",
                        "@nodeType": "mgnl:contentNode",
                        "internal": "/nextjs-redirect-demo/about-us/contacts",
                        "mgnl:lastModified": "2022-10-31T14:04:11.439+01:00",
                        "field": "internal",
                        "mgnl:created": "2022-10-31T14:04:11.439+01:00",
                        "@nodes": []
                    },
                    "@nodes": ["to"]
                },
                "@nodes": ["redirect0"]
            },
            "@nodes": ["redirect"]
        }
    ]
}

Fetching data from the GraphQL API

Earlier, we defined a Content Type using our content model. Using the GraphQL API at http://localhost:8080/magnoliaAuthor/.graphql, you can query specific data by sending a POST request with the query in the body specifying the content properties you want to fetch.

For example, query all redirects where the rootPage property starts with a specific string:

JSON

  {
    redirects (filter: "@rootPage LIKE '/nextjs-redirect-demo%'"){
        redirect {
            from
            to {
                field
                internal
                custom
            }
            code
        }
    }
}

The GraphQL API responds with a JSON object that mirrors the structure of your query, filled with the requested data. You can then use this data directly in your application.

Calling all frontend developers

Use the headless approach for Magnolia. Check out all of our headless documentation.

Learn more

Parsing the data

To use the redirect data in Next.js, we need to parse it.

Parsing data from the REST delivery API

As REST doesn't allow us to choose which properties to fetch, we need to do this manually.

  const nodeName = "/nextjs-redirect-demo"
const REST_API = "http://localhost:8080/magnoliaAuthor/.rest/delivery/redirects/v1"

async function parseRedirectsREST() {
    const redirects = await fetchAPI(`${REST_API}/?rootPage%5Blike%5D=${nodeName}%25`);
    return redirects.results.flatMap(parseRedirectItem);
}

function parseRedirectItem(item) {
    const rootPage = item.rootPage.replace(nodeName, "");
    return item.redirect["@nodes"].map((redirectNode) => ({
        from: rootPage + item.redirect[redirectNode].from,
        to: parseRedirectTo(item.redirect[redirectNode].to),
        code: item.redirect[redirectNode].code,
    }));
}

function parseRedirectTo(to) {
    return {
        field: to.field,
        custom: to.custom,
        internal: replaceNodeName(to.internal),
    };
}

function replaceNodeName(url) {
    return url?.replace(nodeName, "/")?.replace("//", "/");
}

async function fetchAPI(url, options) {
    try {
        const response = await fetch(url, options);
        if (!response.ok) {
            throw new Error(`An error has occurred: ${response.status}`);
        }
        return await response.json();
    } catch (error) {
        console.error(error);
        return [];
    }
}

Parsing data from the GraphQL API

GraphQL allows us to specify the properties we want to fetch, making the parsing process easier.

  const nodeName = "/nextjs-redirect-demo"
const GraphQL_API = "http://localhost:8080/magnoliaAuthor/.graphql"

async function parseRedirectsGRAPHQL() {
    const options = {
        method: "POST",
        headers: {
            'Content-Type': 'application/json',
            'Accept': 'application/json',
        },
        body: JSON.stringify({
            query: `
                {
                    redirects (filter: "@rootPage LIKE '/nextjs-redirect-demo%'"){
                        redirect {
                            from
                            to {
                                field
                                internal
                                custom
                            }
                            code
                        }
                    }
                }
            `
        })
    };

    const response = await fetchAPI(GraphQL_API, options);
    let parsedRed = response?.data?.redirects[0]?.redirect || [];

    return parsedRed.map(item => {
        item.to.internal = replaceNodeName(item.to.internal);
        return item;
    });
}

function replaceNodeName(url) {
    return url?.replace(nodeName, "/")?.replace("//", "/");
}

async function fetchAPI(url, options) {
    try {
        const response = await fetch(url, options);
        if (!response.ok) {
            throw new Error(`An error has occurred: ${response.status}`);
        }
        return await response.json();
    } catch (error) {
        console.error(error);
        return [];
    }
}

Parsing result

Based on the data we’ve entered earlier, both functions parseRedirectsREST and parseRedirectsGRAPHQL generate the following array:

JSON

  [
  { 
    "from": "/contacts", 
    "to": {
      "field": "internal", 
      "internal": "/about-us/contacts", 
      "custom": null
    }, 
    "code": "301" 
  }
]

Checking for redirects using Next.js Middleware

Next.js Middleware has a great feature that allows us to run code before a request is completed. We can use it to check for redirects.

To do so, create a middleware.js file in your Next.js application’s root directory.

The below example works with both REST and GraphQL responses. Please comment out the fetching option you don’t want to use.

  import {NextResponse} from "next/server";
const nodeName = process.env.NODE_NAME
const redirect_REST_API = process.env.MGNL_API_REST_REDIRECTS
const redirect_GRAPHQL_API = process.env.MGNL_API_GRAPHQL_REDIRECTS
let storedRedirects = [];

// Fetches redirects using REST or GraphQL
async function fetchRedirects() {
    // This function fetches redirects and can be configured to use either the REST or the GraphQL endpoint

    //return parseRedirectsREST(redirect_REST_API);
    return parseRedirectsGRAPHQL(redirect_GRAPHQL_API)
}

// Parses redirects fetched from REST API
async function parseRedirectsREST(url) {
    const redirects = await fetchAPI(`${url}/?rootPage%5Blike%5D=${nodeName}%25`);
    return redirects.results.flatMap(parseRedirectItem);
}

// Parses redirects fetched from GraphQL API
async function parseRedirectsGRAPHQL(url) {
    const options = {
        method: "POST",
        headers: {
            'Content-Type': 'application/json',
            'Accept': 'application/json',
        },
        body: JSON.stringify({
            query: `
                {
                    redirects (filter: "@rootPage LIKE '/nextjs-redirect-demo%'"){
                        redirect {
                            from
                            to {
                                field
                                internal
                                custom
                            }
                            code
                        }
                    }
                }
            `
        })
    };

    const response = await fetchAPI(url, options);
    let parsedRed = response?.data?.redirects[0]?.redirect || [];

    return parsedRed.map(item => {
        item.to.internal = replaceNodeName(item.to.internal);
        return item;
    });
}

// Parses a single redirect item
function parseRedirectItem(item) {
    const rootPage = item.rootPage.replace(nodeName, "");
    return item.redirect["@nodes"].map((redirectNode) => ({
        from: rootPage + item.redirect[redirectNode].from,
        to: parseRedirectTo(item.redirect[redirectNode].to),
        code: item.redirect[redirectNode].code,
    }));
}

// Parses 'to' field in a redirect
function parseRedirectTo(to) {
    return {
        field: to.field,
        custom: to.custom,
        internal: replaceNodeName(to.internal),
    };
}

// Replaces nodeName in a url
function replaceNodeName(url) {
    return url?.replace(nodeName, "/")?.replace("//", "/");
}

async function fetchAPI(url, options) {
    try {
        const response = await fetch(url, options);
        if (!response.ok) {
            throw new Error(`An error has occurred: ${response.status}`);
        }
        return await response.json();
    } catch (error) {
        console.error(error);
        return [];
    }
}

export async function middleware(request) {
    if (request.nextUrl.pathname === "/update-redirects" || storedRedirects?.length === 0) {
        storedRedirects = await fetchRedirects();
        return NextResponse.next();
    }

    const redirect = storedRedirects.find(r => r.from === request.nextUrl.pathname);
    if (redirect) {
        const url = redirect.to.field === 'internal'
            ? new URL(redirect.to.internal, request.url)
            : new URL(redirect.to.custom);
        return NextResponse.redirect(url, parseInt(redirect.code));
    }

    return NextResponse.next();
}

Updating redirect data using a webhook

How can we trigger an update of the list of redirects in Next.js every time a redirect is created or changed in Magnolia?

We can use a webhook that gets triggered by a Published and Unpublished event. So, let's go back to the Light Module directory to create the webhook configuration.

/nextjs-redirect-lm/webhooks/webhookConfig_1.yaml

  name: webhook1
url: http://localhost:3000/update-redirects
method: GET
enabled: true

events:
  - name: contentPublished
    eventType: Published
    entity: redirect
  - name: contentUnpublished
    eventType: Unpublished
    entity: redirect

From now on, every time a redirect is published or un-published in the Content App, the webhook http://localhost:3000/update-redirects will be called to update the list of redirects in Next.js.