1. Introduction 🚀

Every real application needs a way to change behavior between development, preview, and production without changing code. Next.js handles this through environment variables and the next.config.ts file. This tutorial covers both — how to load secrets safely, and how to shape the framework's build and runtime behavior.

2. What are Environment Variables? 🤔

An environment variable is a named value available to your running code but stored outside of it — in a file or your hosting provider's dashboard — so the same codebase can behave differently across environments.

3. Why Use Environment Variables? 🎯

Beyond convenience, environment variables keep secrets out of source control and let the exact same build artifact be deployed to different environments with different configuration.

4. Environment Files 📁

Next.js automatically loads variables from several .env file variants, each serving a different purpose.

5. Loading Environment Variables 📥

Next.js loads these files automatically — no extra package like dotenv is required. Values become available on process.env as soon as the process starts.

DATABASE_URL="postgresql://user:pass@localhost:5432/mydb"
STRIPE_SECRET_KEY="sk_live_xxx"
NEXT_PUBLIC_ANALYTICS_ID="G-XXXXXXX"

6. Public Environment Variables 🌍

Any variable prefixed with NEXT_PUBLIC_ is inlined into the client-side JavaScript bundle at build time, making it accessible in the browser.

'use client';

export function Analytics() {
  const id = process.env.NEXT_PUBLIC_ANALYTICS_ID;
  return <script data-analytics-id={id} />;
}

7. Server-Only Environment Variables 🔒

Variables without the NEXT_PUBLIC_ prefix are only available in server-side code — Server Components, Route Handlers, Middleware, and Server Actions — and are stripped from the client bundle.

export async function POST(request: Request) {
  const stripeKey = process.env.STRIPE_SECRET_KEY; // safe: server-only
  const client = new Stripe(stripeKey!);
  // ...
}

8. process.env 🧾

process.env is the standard Node.js object through which all environment variables are read, regardless of framework. Next.js replaces references at build time for statically-known keys, enabling dead-code elimination.

export const isProduction = process.env.NODE_ENV === 'production';
export const apiUrl = process.env.API_URL ?? 'http://localhost:3000';

9. Environment Variable Expansion 🔗

Next.js supports referencing one variable's value from another using $VARIABLE_NAME syntax within a .env file.

BASE_URL="https://api.example.com"
USERS_ENDPOINT="$BASE_URL/users"

10. Environment Variable Load Order 📊

When the same variable is defined in multiple files, Next.js resolves it using a fixed precedence order, checking each file in turn until a value is found.

11. Development Configuration 🛠️

Use .env.development (or .env.local) for values specific to local development, like a local database URL or a test-mode payment key.

DATABASE_URL="postgresql://localhost:5432/dev_db"
STRIPE_SECRET_KEY="sk_test_xxx"

12. Production Configuration 🏭

Production secrets are almost always set through your hosting provider's dashboard (Vercel, for example) rather than committed to .env.production, since that file is version-controlled.

13. Preview Configuration 👁️

Many hosting providers support a separate preview environment for pull requests, letting you use a staging database or sandboxed API keys distinct from both development and production.

14. next.config.ts ⚙️

next.config.ts (or .js) is where you configure framework-level behavior — build output, redirects, image domains, experimental flags — as opposed to runtime secrets.

import type { NextConfig } from 'next';

const nextConfig: NextConfig = {
  reactStrictMode: true,
  images: { domains: ['cdn.example.com'] },
};

export default nextConfig;

15. Application Configuration 🧩

Beyond next.config.ts, most apps keep a small, typed configuration module that centralizes reads from process.env, so the rest of the codebase never touches process.env directly.

export const config = {
  databaseUrl: process.env.DATABASE_URL!,
  stripeKey: process.env.STRIPE_SECRET_KEY!,
  siteUrl: process.env.NEXT_PUBLIC_SITE_URL ?? 'http://localhost:3000',
};

16. Runtime Configuration 🔄

Unlike build-time inlined NEXT_PUBLIC_ variables, true runtime configuration is read fresh every time the server process starts, letting the same build be deployed to multiple environments unchanged.

17. Build Configuration 🏗️

Some next.config.ts options directly affect the build process itself — like output mode, TypeScript/ESLint error handling, or compiler options.

const nextConfig: NextConfig = {
  typescript: { ignoreBuildErrors: false },
  eslint: { ignoreDuringBuilds: false },
};

18. Experimental Features 🧪

The experimental key in next.config.ts gates in-progress features that may change or be removed between releases — useful for early adoption but riskier for production stability.

const nextConfig: NextConfig = {
  experimental: {
    ppr: true,
    typedRoutes: true,
  },
};

19. Turbopack Configuration ⚡

Turbopack is Next.js's Rust-based bundler, configurable through the turbopack key for custom loaders, resolve aliases, and module rules.

const nextConfig: NextConfig = {
  turbopack: {
    resolveAlias: {
      '@ui': './src/components/ui',
    },
  },
};

20. Webpack Configuration 📦

For projects not yet on Turbopack, the webpack() function lets you extend or override the underlying webpack configuration directly.

const nextConfig: NextConfig = {
  webpack(config) {
    config.resolve.alias['@ui'] = './src/components/ui';
    return config;
  },
};

21. Redirects Configuration ↪️

The redirects() function lets you define permanent or temporary URL redirects centrally, without writing Middleware or per-page logic.

const nextConfig: NextConfig = {
  async redirects() {
    return [
      { source: '/old-blog/:slug', destination: '/blog/:slug', permanent: true },
    ];
  },
};

22. Rewrites Configuration 🔀

The rewrites() function maps an incoming path to a different destination without changing the URL the visitor sees — useful for proxying an external API.

const nextConfig: NextConfig = {
  async rewrites() {
    return [
      { source: '/api/proxy/:path*', destination: 'https://external-api.com/:path*' },
    ];
  },
};

23. Headers Configuration 🏷️

The headers() function attaches custom response headers to matched paths at the framework level, ideal for global security or caching headers.

const nextConfig: NextConfig = {
  async headers() {
    return [
      {
        source: '/(.*)',
        headers: [{ key: 'X-Frame-Options', value: 'DENY' }],
      },
    ];
  },
};

24. Image Configuration 🖼️

The images key configures which external domains the built-in next/image component is allowed to optimize, along with formats and device sizes.

const nextConfig: NextConfig = {
  images: {
    remotePatterns: [{ protocol: 'https', hostname: 'cdn.example.com' }],
    formats: ['image/avif', 'image/webp'],
  },
};

25. Transpile Packages 📦

The transpilePackages option tells Next.js to compile specific node_modules packages through its own build pipeline — necessary for monorepo packages or libraries shipped as untranspiled ESM/TS.

const nextConfig: NextConfig = {
  transpilePackages: ['ui', '@my-org/shared-components'],
};

26. Output Configuration 📤

The output option changes what next build produces — the default full server build, a minimal standalone bundle for containers, or a fully exported static site.

const nextConfig: NextConfig = {
  output: 'standalone', // ideal for Docker deployments
};

27. Security Best Practices 🔒

28. Common Configuration Mistakes 🚫

29. Frequently Asked Questions ❓

30. Summary 📚