Getting Started
Core Concepts
Troubleshooting
Managing runtime settings, customizing project options, and handling environment variables are crucial tasks when building applications. This guide covers how to customize your project settings using configuration files and how to securely manage public and private environment variables across different deployment phases.
Note
Environment variables and configuration files let you alter how your application behaves in development, testing, and production without changing your source code.
You can customize your project behavior by creating a configuration file in your project root directory. Configuration files support standard object definitions, asynchronous functions, and CommonJS or ES module syntax.
Here is how a basic TypeScript configuration file looks:
import
You can also write your configuration as a function or an asynchronous function to handle dynamic logic:
import type { NextConfig } from 'next'
async function nextConfig(): Promise<NextConfig> {
return {
experimental: {
proxyPrefetch: 'flexible',
},
};
}
export default nextConfigEnvironment variables are loaded automatically based on your current running environment and mode (development, production, or test).
The system searches for environment files in a specific order of precedence depending on whether you are running in development, production, or test mode.
Supported environment files include:
.env.${mode}.local.env.local (excluded during test mode).env.${mode}.envWarning
Keys starting with NODE_ or __ (such as NODE_ENV or __NEXT_PRIVATE_) are strictly reserved and not allowed under custom configuration environment blocks.
NEXT_PUBLIC_ is exposed safely to the browser and client-side code.NEXT_PUBLIC_ prefix remain securely on the server and are hidden from client-side bundles.