Overview
Understanding Environment and Settings
Managing your project environment and configuration options is essential for tailoring how your application builds and runs. Next.js relies on two main mechanisms for project-wide configuration: environment variables for managing secrets or environment-specific values, and a configuration file located at the root of your project directory to modify advanced behavior, enable experimental features, and control build options.
Note
Environment files and configuration settings are automatically loaded during development, production builds, and test runs.
Configuring Environment Variables
Environment File Loading and Order
Next.js automatically loads environment variables from environment files into your application. Depending on your active environment mode, Next.js evaluates and loads files in a specific order of precedence.
When your project starts, Next.js checks for environment files based on the current mode (development, production, or test).
Supported environment file names:
.env.${mode}.local.env.local(Note: Skipped duringtestmode).env.${mode}.env
Sources: .env.${mode}.local, .env.local, .env.${mode}, .env
Warning
Environment variable keys starting with NODE_, __, or matching NEXT_RUNTIME are strictly restricted under configuration and will throw an error if defined improperly.
Exposing Variables to the Browser
By default, environment variables defined in your environment files are only available on the server. To make an environment variable accessible within browser-side code, prefix its name with NEXT_PUBLIC_.
# Available on server and client
NEXT_PUBLIC_API_URL=https://api.example.com
# Available on server only
DATABASE_SECRET_KEY=super-secret-valueProject-Wide Settings
Overview of Project Settings
Project-wide settings are managed using a configuration file located in the root directory of your project (such as next.config.ts). This file allows you to customize directory structures, build outputs, image handling, and compiler behavior.
Step-by-Step: Setting Up Your Configuration File
- Navigate to the root directory of your project.
- Create or open your configuration file (
next.config.ts). - Define and export your project options using the configuration template:
import type { NextConfig } from "next";
const nextConfig: NextConfig = {
reactStrictMode: true,
// Add other project-wide options here
};
export default nextConfig;Key Configuration Options
The following table highlights commonly used configuration properties available in project settings:
| Configuration Key | Description | Default Value |
|---|---|---|
reactStrictMode | Enables React Strict Mode for highlighting potential application problems. | null (or true in selected templates) |
distDir | Specifies the name of the directory used for build output. | '.next' |
cleanDistDir | Automatically cleans the build directory before starting a new build. | true |
assetPrefix | Sets a custom prefix for all asset URLs (e.g., for CDNs). | '' |
compress | Enables Gzip compression for rendered content and static files. | true |
trailingSlash | Appends a trailing slash to all generated URLs. | false |
Tip
Always verify that your distDir is never set to reserved directories like public, as Next.js restricts output to reserved folders.