Fixing Next.js Error: Only Absolute URLs Are Supported

Understanding the Absolute URL Error in Next.js

When developing with Next.js, you might encounter an error stating ‘Only absolute URLs are supported’. This usually occurs when making requests to external services or APIs. In Next.js, an absolute URL is required because server-side data fetching methods, such as getServerSideProps or getStaticProps, run on the server where there’s no relative path to resolve as would be from a browser. This leads to the Next.js framework expecting a URL that includes the protocol (http or https) and the domain name.

How to Resolve the Error

Fixing the absolute URL error in Next.js involves making sure that all your external requests are made with full URLs. For local development, you might be referring to your localhost with a relative URL and this is typically the source of the error. It’s essential to use environment variables to manage your API endpoints. This approach simplifies switching between development and production environments.

The concept of environment variables in Next.js can be easily implemented using a .env.local file for local development and respective environment files for staging or production. By placing your base URL into these variables, you ensure your application always uses the correct endpoint.

Implement the Solution

To apply this solution, you need to define environment variables and update your data fetching code to use absolute URLs. Here is how you can do this:

1. Create a .env.local file in your project root if it doesn’t exist already.
2. Add your local and production base URLs to the file. For example:

NEXT_PUBLIC_API_BASE_URL=http://localhost:3000/api
NEXT_PUBLIC_API_PROD_URL=https://your-production-api.com/api

Ensure to prefix your variable names with NEXT_PUBLIC_ to expose them to the browser.

Next, update your API request functions to read the environment variable:

const baseUrl = process.env.NODE_ENV === 'production' ? process.env.NEXT_PUBLIC_API_PROD_URL : process.env.NEXT_PUBLIC_API_BASE_URL;

In your data fetching functions, such as getServerSideProps, use this baseUrl:

export async function getServerSideProps(context) {
    const res = await fetch(`${baseUrl}/your-endpoint`);
    const data = await res.json();

    return {
        props: { data },
    };
}

By utilizing template literals and embedding the baseUrl, you can ensure that your requests are using absolute URLs.

It’s important to restart your Next.js server after adding or modifying environment variables for the changes to take effect.

Additional Considerations

It is also good practice to create utility functions or custom hooks for API calls where the absolute URL preparation is abstracted. This not only helps in centralizing your API logic but also makes it easier to handle changes in your API endpoints or logic in a single place.

In cases where you’re making API calls from the client side and the API is hosted on the same domain as your Next.js app, a proxy setup in next.config.js can be helpful to avoid dealing with CORS issues while still using relative URLs for the client-side requests.

Handling errors gracefully in your API calls is also crucial, so make sure to include try-catch blocks or error handling logic as appropriate. This will help prevent your application from crashing due to unhandled exceptions.

Complete Code Example

To see this in action, here’s a complete example of a Next.js page using the correct setup for absolute URLs:

// pages/index.js
import React from 'react';

const baseUrl = process.env.NODE_ENV === 'production' ? process.env.NEXT_PUBLIC_API_PROD_URL : process.env.NEXT_PUBLIC_API_BASE_URL;

const HomePage = ({ data }) => {
    return (
        // Render your data here
    );
};

export async function getServerSideProps(context) {
    const res = await fetch(`${baseUrl}/your-endpoint`);
    const data = await res.json();

    return {
        props: { data },
    };
}

export default HomePage;

This code example demonstrates fetching data on the server side using an absolute URL derived from environment variables. This pattern maintains consistency across your codebase and ensures you do not encounter the absolute URL error.