Optimizing image handling in a Next.js application is crucial for performance and user experience. Next.js provides a built-in Image Optimization API that automatically optimizes images on-demand for faster load times. However, the way we specify which external domains are allowed to serve images has changed. The older images.domains configuration has been deprecated in favor of the more flexible images.remotePatterns.
Thank me by sharing on Twitter 
Why the Change?
The images.domains configuration allowed developers to specify a list of domains from which images could be served. While this was straightforward, it lacked flexibility. The new images.remotePatterns configuration provides more control over image sources by allowing you to specify protocols, hostnames, and paths.
Benefits of images.remotePatterns
- Granular Control: Specify not just domains, but also protocols and paths.
- Enhanced Security: Define more specific patterns, reducing unauthorized image sources.
- Future-Proofing: Aligns with Next.js’s ongoing improvements and best practices.
Implementing images.remotePatterns
Step 1: Locate Your Next.js Configuration File
Your Next.js configuration is typically found in next.config.js or next.config.mjs. Open this file in your preferred code editor.
Step 2: Replace images.domains with images.remotePatterns
Here’s how you can do it:
Before (with images.domains)
// next.config.js
module.exports = {
images: {
domains: ['example.com', 'anotherdomain.com'],
},
};After (with images.remotePatterns)
// next.config.js
module.exports = {
images: {
remotePatterns: [
{
protocol: 'https',
hostname: 'example.com',
},
{
protocol: 'https',
hostname: 'anotherdomain.com',
},
],
},
};For a TypeScript configuration file (next.config.mjs), it would look like this:
Co-Intelligence: Living and Working with AI
$17.79 (as of April 4, 2025 14:21 GMT +00:00 - More info)
The Technological Republic: Hard Power, Soft Belief, and the Future of the West
$15.75 (as of April 4, 2025 14:21 GMT +00:00 - More info)
Python Crash Course, 3rd Edition: A Hands-On, Project-Based Introduction to Programming
$28.99 (as of April 4, 2025 14:21 GMT +00:00 - More info)// next.config.mjs
export default {
images: {
remotePatterns: [
{
protocol: 'https',
hostname: 'example.com',
},
{
protocol: 'https',
hostname: 'anotherdomain.com',
},
],
},
};Optional: Add Path Patterns
You can also specify path patterns to refine the sources of your images:
// next.config.js
module.exports = {
images: {
remotePatterns: [
{
protocol: 'https',
hostname: 'example.com',
pathname: '/images/**',
},
{
protocol: 'https',
hostname: 'anotherdomain.com',
pathname: '/media/**',
},
],
},
};Testing and Verifying the Changes
- Restart Your Development Server:
npm run dev - Test Image Loading: Visit pages where external images are used to ensure they load correctly.
- Debugging Tips: If images are not loading, double-check the protocol, hostname, and path patterns in your configuration.
Conclusion
Migrating from images.domains to images.remotePatterns in Next.js is a straightforward process that enhances the security and flexibility of your image handling configuration. By following the steps outlined in this guide, you can ensure your application remains up-to-date with the latest best practices and continues to perform optimally.
Updating your configurations to keep pace with framework changes is part of maintaining a modern web application. With this migration, you’re not only adhering to the latest standards but also improving the robustness of your Next.js project.
