Definire variabili di ambiente con Next.js: guida completa con esempi pratici

Le variabili di ambiente sono uno degli strumenti più potenti e sottovalutati nello sviluppo moderno, soprattutto quando si lavora con framework avanzati come Next.js. In un contesto in cui le applicazioni web sono sempre più complesse e distribuite su diversi ambienti — sviluppo locale, staging, produzione — diventa fondamentale gestire in modo pulito e sicuro tutti quei valori che non devono essere hardcodati nel codice sorgente: URL delle API, chiavi di accesso, domini, segreti e parametri di configurazione.

Con Next.js, la gestione delle variabili di ambiente è estremamente semplice ma anche molto strutturata, perché il framework integra nativamente il supporto ai file .env, offre un meccanismo chiaro per distinguere tra lato server e lato client, e permette di sfruttare al massimo TypeScript per una configurazione centralizzata e tipizzata.

Questa guida completa ti accompagna passo dopo passo nel processo di definizione, utilizzo e validazione delle variabili di ambiente in Next.js, partendo dalle basi e arrivando a soluzioni professionali come la creazione di un file di configurazione centralizzato. Troverai esempi pratici, best practice e strategie per lavorare in modo sicuro e scalabile, così da migliorare la qualità e la manutenibilità del tuo progetto.

Cosa sono le variabili di ambiente e perché usarle in Next.js

Le variabili di ambiente sono valori esterni al codice sorgente, utili per configurare l’applicazione senza modificarne la logica interna. Ad esempio, URL di API, chiavi segrete, credenziali o feature flag possono essere impostati come variabili di ambiente e utilizzati all’interno dell’app Next.js. Questo approccio ha diversi vantaggi: migliora la sicurezza, evita di esporre dati sensibili nel repository, facilita il deploy su diversi ambienti e permette di cambiare facilmente configurazioni senza toccare il codice.

Come creare le variabili di ambiente in Next.js

Next.js supporta per impostazione predefinita i file .env per gestire le variabili. Questi file vanno creati nella root del progetto e possono essere di diversi tipi:

• .env.local – usato per lo sviluppo locale (non va mai committato su Git)

• .env.development – per configurazioni specifiche dell’ambiente di sviluppo

• .env.production – per la produzione

• .env.test – per i test automatizzati

Esempio di .env.local:

SERVER=http://localhost:3000
ENDPOINT=/api/posts
API_KEY=abcdef12345
DOMAIN=miosito.it
NEXT_PUBLIC_API_URL=https://api.miosito.it

Le variabili così definite sono disponibili all’interno del codice tramite process.env.

Lato client e lato server: differenza fondamentale

Per motivi di sicurezza, Next.js non espone automaticamente tutte le variabili al browser. Quelle definite in .env sono disponibili solo lato server.
Se hai bisogno di utilizzare una variabile anche lato client, devi aggiungere il prefisso NEXT_PUBLIC_ al nome:

NEXT_PUBLIC_API_URL=https://api.miosito.it

Ora puoi usarla direttamente nei componenti React:

export default function Home() {
  return <p>Chiamata API su: {process.env.NEXT_PUBLIC_API_URL}</p>
}

Creare un file di configurazione centralizzato e type-safe

Un approccio professionale nei progetti Next.js è creare un file di configurazione centralizzato che legga, validi ed esporti le variabili di ambiente in modo type-safe. In questo modo hai un unico punto di accesso alla configurazione dell’applicazione e puoi intercettare subito eventuali errori se una variabile è mancante.

Crea ad esempio un file src/config/index.ts:

interface Config {
  server: string;
  endpoint: string;
  apiKey: string;
  domain: string;
  isDevelopment: boolean;
  isProduction: boolean;
}

function validateEnvVar(name: string, value: string | undefined): string {
  if (!value) {
    throw new Error(`Missing required environment variable: ${name}`);
  }
  return value;
}

const config: Config = {
  server: validateEnvVar('SERVER', process.env.SERVER),
  endpoint: validateEnvVar('ENDPOINT', process.env.ENDPOINT),
  apiKey: validateEnvVar('API_KEY', process.env.API_KEY),
  domain: validateEnvVar('DOMAIN', process.env.DOMAIN),
  isDevelopment: process.env.NODE_ENV === 'development',
  isProduction: process.env.NODE_ENV === 'production',
};

export default config;

Ora puoi importare questa configurazione in qualsiasi parte del progetto:

import config from '@/config'

console.log(config.server)
console.log(config.isProduction)

I vantaggi di questo approccio sono evidenti: tutte le variabili richieste vengono validate all’avvio, la configurazione è centralizzata e tipizzata, la manutenzione è più semplice e il rischio di errori diminuisce drasticamente.

Gestione automatica dei diversi ambienti

Next.js carica automaticamente i file .env corretti a seconda dell’ambiente:

• npm run dev → usa .env.local e .env.development

• npm run build / npm start → usa .env.production e .env.local

L’ordine di priorità è il seguente:
.env.local → .env.<environment> → .env

Questo significa che puoi sovrascrivere i valori in base all’ambiente semplicemente creando più file .env.

Esempio completo: API privata lato server e variabile pubblica lato client

API_SECRET_KEY=abcdef12345
NEXT_PUBLIC_BASE_URL=https://api.miosito.it

Lato server (API route):

// pages/api/posts.js
export default async function handler(req, res) {
  const data = await fetch(`${process.env.NEXT_PUBLIC_BASE_URL}/posts`, {
    headers: { Authorization: `Bearer ${process.env.API_SECRET_KEY}` }
  }).then(r => r.json())
  res.status(200).json(data)
}

Lato client:

// pages/index.js
export default function Home() {
  return <div>API Base URL: {process.env.NEXT_PUBLIC_BASE_URL}</div>
}

Best practice per lavorare con le variabili di ambiente

• Non committare mai .env.local su Git.

• Usa NEXT_PUBLIC_ solo per variabili non sensibili.

• Crea un file .env.example con valori placeholder per documentare le variabili richieste.

• Centralizza e valida la configurazione con un file TypeScript come visto sopra.

Conclusione

Gestire correttamente le variabili di ambiente in Next.js è una best practice essenziale per costruire applicazioni sicure, scalabili e facilmente configurabili. Con l’approccio visto in questa guida puoi lavorare in modo professionale, distinguendo ciò che deve restare lato server da ciò che può essere esposto al client e mantenendo tutto ordinato con un file di configurazione centralizzato e tipizzato.