What is next.config.js and what can you configure in it?
next.config.js is the main configuration file for Next.js that allows you to customize build settings, enable features, and configure various aspects of your application's behavior
The next.config.js file (or next.config.ts for TypeScript) is a Node.js module that sits at the root of your Next.js project and controls how the framework builds and runs your application. This file exports a configuration object that Next.js reads during build time and runtime, enabling you to customize everything from image optimization to build output directories, environment variables, and experimental features. Starting with Next.js 15, you can write this configuration file in either JavaScript or TypeScript for better type safety .
- 1
Build and Compilation: Configure how Next.js builds your application. Options include
swcMinify(use Rust-based SWC minifier),compiler(customize SWC transforms), andwebpack(customize webpack configuration). The default compiler is SWC, which is significantly faster than Babel . - 2
Images and Assets: The
imagesconfiguration allows you to define image optimization behavior, including remote patterns (allowed image domains), image sizes for responsive images, and formats like WebP and AVIF. You can also disable image optimization if needed . - 3
Redirects and Rewrites: Configure server-side redirects, rewrites, and headers through functions like
redirects(),rewrites(), andheaders(). These run before the response is sent and can be used for SEO, A/B testing, or proxy patterns . - 4
Environment Variables: Control environment variable exposure with
env(build-time env vars) andpublicRuntimeConfig(client-side available variables). You can also use.envfiles which are automatically loaded . - 5
Internationalization: Configure i18n routing with
i18nobject, specifying locales, default locale, and domain-based locale detection. This enables automatic language detection and prefixed routes .
- 1
Experimental Features: Next.js provides a
experimentalobject to enable cutting-edge features likeinstrumentationHook(for monitoring),typedRoutes(experimental type-safe routes), orserverActions(enabled by default in Next.js 15). These features are subject to change . - 2
Custom Webpack: For advanced use cases, you can extend Next.js's internal webpack configuration using the
webpackfunction. This allows adding custom loaders, plugins, or modifying the build pipeline, but should be used with caution . - 3
Middleware Configuration: Configure middleware behavior with
matcheroptions to specify which paths should run middleware. This is typically done in the middleware.ts file itself, but related config can be placed here . - 4
Output Configuration: Control the build output format with
output: 'standalone'for self-hosted deployments (creates a minimal standalone folder), oroutput: 'export'for static HTML exports . - 5
Server Component Configuration: Configure server component behavior, including the external packages list that should be bundled and runtime options .
If you're using TypeScript, you can use next.config.ts instead of .js for better type checking and autocompletion. Next.js automatically detects this file and applies TypeScript validation. The configuration object is typed with import('next').NextConfig, providing IntelliSense for all available options. This is particularly helpful when working with complex configurations or team projects .
- 1
Development vs Production: You can use
process.env.NODE_ENVin your config file to apply different settings for development, production, or test environments . - 2
Phase-based Configuration: Next.js provides phases like
PHASE_DEVELOPMENT_SERVERandPHASE_PRODUCTION_BUILDthat you can import from 'next/constants' to conditionally apply configuration . - 3
Runtime Configuration: For values that need to be available at runtime (not build time), use
publicRuntimeConfigandserverRuntimeConfigfor client-side and server-side values respectively . - 4
Dynamic Configuration: The config file can export an async function that receives
phaseanddefaultConfigparameters, allowing for programmatic configuration generation .
Scenario Questions
0-2 years experience
- 1You need to enable image optimization for external domains in a new Next.js project. How would you modify next.config.js to achieve that?
- 2If you add a custom webpack alias in next.config.js but the alias isn’t recognized when you run the dev server, what could be wrong?
2-5 years experience
- 1Your team added a new environment variable in next.config.js, but it's not available in the client‑side code. Walk me through how you’d debug this.
- 2We want to use a custom Babel plugin only for production builds. How would you configure next.config.js, and what trade‑offs should you consider?
5-8 years experience
- 1Our application is growing and we need to split the webpack config into multiple files for maintainability. How would you restructure next.config.js, and what impact does it have on build performance?
- 2We’re seeing increased build times after adding several image domains and redirects in next.config.js. How would you investigate and mitigate the slowdown?
8+ years experience
- 1The company is moving from a single Next.js app to a monorepo with multiple apps sharing a base next.config.js. How would you design a shared configuration strategy that balances team autonomy and consistency?
- 2We need to migrate our existing next.config.js (CommonJS) to an ES module while supporting legacy plugins that expect CommonJS. What architectural considerations and migration plan would you propose?
Follow-up Questions
- What happens if you modify next.config.js without restarting the dev server?
- How does Next.js cache the configuration between builds?
- Can you describe any impact on serverless deployment when you add experimental flags?