Resolving CORS Issues in Next.js Production Environment: Configuring Rewrites and API Proxies

Problem Background and Root Cause Analysis

In modern web development, Cross-Origin Resource Sharing (CORS) presents a common technical challenge. When a Next.js application deployed on Vercel (domain: www.example.com) needs to communicate with a .NET Core Web API hosted on a different server (domain: api.example.com), browsers enforce the same-origin policy for security reasons, blocking cross-origin requests.

From a technical perspective, the core of CORS issues lies in the browser's preflight mechanism for cross-origin requests. When a client initiates a cross-origin request, the browser first sends an OPTIONS request to the target server to check if the server permits the cross-origin request. Only after the preflight passes will the actual GET, POST, or other requests be executed.

The reason it works correctly in the development environment using npm run dev is that the Next.js development server includes built-in proxy functionality that can bypass browser CORS restrictions. However, in the production environment using npm run start, this proxy functionality is no longer active, leading to CORS errors.

Core Solution: Configuring Rewrite Rules

According to Next.js official documentation, the most effective solution is to implement API request proxying through the rewrites functionality in the next.config.js file. This approach leverages Next.js's server-side rendering capabilities to convert client-side cross-origin requests into server-to-server same-origin requests.

The specific implementation steps are as follows: create or modify the next.config.js file in the project root directory and add the following configuration:

module.exports = {
    async rewrites() {
        return [
            {
                source: '/api/:path*',
                destination: 'https://api.example.com/:path*',
            },
        ]
    },
};

This configuration works by automatically forwarding client requests to the /api/ path to https://api.example.com/ through the Next.js server, which sets appropriate CORS headers in the response. Since the requests originate from the server side, they completely bypass browser CORS restrictions.

Code Implementation and Usage Examples

In client-side code, relative paths should be used to initiate API requests instead of directly using the external API's full URL. Here is a practical example using Axios:

import axios from 'axios';

// Correct approach - using relative paths
const fetchData = async () => {
    try {
        const response = await axios.get('/api/users');
        return response.data;
    } catch (error) {
        console.error('API request failed:', error);
        throw error;
    }
};

// Incorrect approach - directly using external URL (will cause CORS error)
const fetchDataWrong = async () => {
    try {
        const response = await axios.get('https://api.example.com/users');
        return response.data;
    } catch (error) {
        // CORS error will be caught here
        console.error('CORS error:', error);
        throw error;
    }
};

Through this method, all API requests first pass through the Next.js server, which handles communication with the external API and returns the results to the client. This process is completely transparent to the client, allowing developers to focus on application logic without worrying about underlying cross-origin issues.

Alternative Solutions Comparison and Analysis

In addition to using rewrites configuration, the community provides several other solutions, each with its own applicable scenarios and trade-offs.

Solution 1: Using the nextjs-cors Library

This is a CORS handling library specifically designed for Next.js, based on Express.js's cors middleware. Usage example:

import NextCors from 'nextjs-cors';

async function handler(req, res) {
    await NextCors(req, res, {
        methods: ['GET', 'HEAD', 'PUT', 'PATCH', 'POST', 'DELETE'],
        origin: '*',
        optionsSuccessStatus: 200,
    });

    // Business logic code
    res.json({ message: 'Hello NextJs Cors!' });
}

The advantage of this approach is fine-grained control over CORS policies, but it requires individual configuration in each API route, resulting in higher maintenance overhead.

Solution 2: API Route Proxy Pattern

By creating proxy APIs in the pages/api directory, external API calls are encapsulated on the server side:

// pages/api/proxy.js
export default async function handler(req, res) {
    try {
        const response = await fetch('https://api.example.com/data', {
            method: req.method,
            headers: req.headers,
            body: req.body
        });
        const data = await response.json();
        res.status(200).json(data);
    } catch (error) {
        res.status(500).json({ error: error.message });
    }
}

This solution offers maximum flexibility, allowing the addition of authentication, caching, data transformation, and other middleware logic, but requires creating corresponding proxy routes for each external API endpoint.

Production Environment Deployment Considerations

When deploying configurations to production environments, several key points require attention:

Environment Variable Configuration: It is recommended to use environment variables to manage API endpoint URLs, avoiding hardcoding in the code:

module.exports = {
    async rewrites() {
        return [
            {
                source: '/api/:path*',
                destination: `${process.env.API_BASE_URL}/:path*`,
            },
        ]
    },
};

Path Matching Optimization: The rewrites configuration supports complex path matching patterns that can be adjusted according to actual requirements:

module.exports = {
    async rewrites() {
        return [
            // Exact match for specific paths
            {
                source: '/api/users',
                destination: 'https://api.example.com/users',
            },
            // Wildcard match for all API paths
            {
                source: '/api/:path*',
                destination: 'https://api.example.com/:path*',
            },
        ]
    },
};

Performance Considerations: Rewrite rules add processing overhead to the server. When configuring, consider caching strategies and request optimization. For high-concurrency scenarios, combining CDN and caching mechanisms is recommended to improve performance.

Security Best Practices

When implementing CORS solutions, security is a crucial factor that cannot be overlooked:

Restrict Allowed Origins: In production environments, avoid using origin: '*' and explicitly specify allowed domains:

// In API routes
const allowedOrigins = ['https://www.example.com', 'https://app.example.com'];
const origin = req.headers.origin;
if (allowedOrigins.includes(origin)) {
    res.setHeader('Access-Control-Allow-Origin', origin);
}

Request Validation: When proxying requests, validate and sanitize request parameters to prevent injection attacks:

// Validate requests in API proxy
const validateRequest = (req) => {
    // Validate request method, parameter formats, etc.
    if (!['GET', 'POST'].includes(req.method)) {
        throw new Error('Unsupported request method');
    }
    // Validate and sanitize request parameters
    return sanitizeParams(req.body);
};

Conclusion and Recommendations

Configuring the rewrites functionality in next.config.js is the optimal solution for resolving CORS issues in Next.js production environments. This method is simple and efficient, requiring no modifications to existing code logic while maintaining good performance and security.

For complex application scenarios, multiple solutions can be combined: use rewrites for most simple API calls and employ API route proxying for interfaces requiring special handling. Regardless of the chosen approach, security best practices should be followed to ensure application stability and security.

In practical development, it is recommended to plan the API architecture early in the project, considering cross-origin communication requirements to avoid dealing with CORS issues late in the development cycle. Through proper architectural design and technology selection, development efficiency and user experience can be significantly improved.