---
title: "Environment and Configuration"
description: "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 usi..."
last_updated: "2026-09-23T10:57:21.239757+00:00"
canonical_url: "https://www.doc0.dev/docs/8f4009b0-65bd-4480-9b00-e201f0914bb3/guide/configuration/environment-and-configuration"
---

## Overview

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.

---

## Configuring Runtime Settings

### Overview

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.

### Basic Configuration Structure

Here is how a basic TypeScript configuration file looks:

```typescript
import type { NextConfig } from "next";

const nextConfig: NextConfig = {
  /* config options here */
};

export default nextConfig;
```

You can also write your configuration as a function or an asynchronous function to handle dynamic logic:

```typescript
import type { NextConfig } from 'next'

async function nextConfig(): Promise<NextConfig> {
  return {
    experimental: {
      proxyPrefetch: 'flexible',
    },
  };
}

export default nextConfig
```

---

## Managing Environment Variables

### Overview

Environment variables are loaded automatically based on your current running environment and mode (development, production, or test).

### Priority Order of Environment Files

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}`
- `.env`

> [!WARNING]
> Keys starting with `NODE_` or `__` (such as `NODE_ENV` or `__NEXT_PRIVATE_`) are strictly reserved and not allowed under custom configuration environment blocks.

### Public vs. Private Variables

- **Public Variables:** Any environment variable prefixed with `NEXT_PUBLIC_` is exposed safely to the browser and client-side code.
- **Private Variables:** Variables without the `NEXT_PUBLIC_` prefix remain securely on the server and are hidden from client-side bundles.

## Related

- [Installation and Setup](https://www.doc0.dev/docs/8f4009b0-65bd-4480-9b00-e201f0914bb3/guide/getting-started/installation-and-setup)
- [Deployment and Hosting](https://www.doc0.dev/docs/8f4009b0-65bd-4480-9b00-e201f0914bb3/guide/how-to-guides/deployment-and-hosting)


## Sitemap

See the full [sitemap](https://www.doc0.dev/docs/8f4009b0-65bd-4480-9b00-e201f0914bb3/llms.txt) for all pages in this wiki.