How it actually works

package.json scripts don’t automatically read .env. They run a command in a shell, and the shell only sees variables from the current process environment (so $PORT is empty unless it was exported).

That’s why this appears to work but doesn’t:

{
  "scripts": {
    "start": "node server.js --port $PORT"
  }
}

Also, env var syntax is shell-specific: $PORT (bash), %PORT% (cmd), $env:PORT (PowerShell).

Options

• dotenv-cli: loads .env for any command.
• cross-env: sets inline env vars; does not load .env.
• Node --env-file: for node only (Node >= 20.6.0; existing env wins).

This covers most cases:

{
  "scripts": {
    "dev": "dotenv -- vite",
    "test": "dotenv -- cross-env NODE_ENV=test vitest"
  }
}

CI and containers

In CI and production, treat .env files as a local dev tool. Use environment variables and secret stores instead.