Node.js environment variables: .env files, cPanel and PM2

Environment variables keep settings such as database passwords, API keys and the port number outside your code. The same code can then run on your laptop, a staging server and production with different values. This guide shows where to set them on cPanel hosting and on a VPS.

Before you start

• A Node.js app on cPanel hosting or a Linux VPS.
• A list of the variables your app expects (often in a .env.example file in the project).

Read environment variables in code

Node.js exposes every variable on process.env:

const port = process.env.PORT || 3000;
const dbUrl = process.env.DATABASE_URL;

Values are always strings. Convert them when you need a number or boolean, for example Number(process.env.PORT).

Use a .env file

1. Create a file named .env in the project root:
   Copy

   NODE_ENV=production
   PORT=3000
   DATABASE_URL=mysql://appuser:CHANGE_ME@localhost:3306/appdb

2. Node.js 20.6 and later can load it without any package:
   Copy

   node --env-file=.env server.js

3. On older versions install dotenv and load it at the very top of your entry file:
   Copy

   npm install dotenv

   Copy

   require('dotenv').config();

4. Add .env to .gitignore so it is never committed.

Set variables in cPanel

1. Log in to cPanel (from the MdmHost dashboard open Services and click the cPanel button).
2. Go to cPanel → Software → Setup Node.js App and click the pencil icon next to your app.
3. Under Environment variables click Add Variable, enter the name and value, and click Done.
4. Click Save, then Restart so the app picks up the change.

Full details of the app screen are in Set up a Node.js app in cPanel.

Set variables with PM2

Put them in the env block of ecosystem.config.js, then reload with the new values:

pm2 restart ecosystem.config.js --update-env

See PM2 process manager for the full ecosystem file.

Set variables in a systemd service

If you run the app as a systemd unit, point it to an environment file:

[Service]
EnvironmentFile=/home/deploy/myapp/.env
ExecStart=/usr/bin/node /home/deploy/myapp/server.js

Run sudo systemctl daemon-reload and restart the service after editing.

Next.js build-time vs runtime variables

In Next.js, variables starting with NEXT_PUBLIC_ are written into the browser JavaScript at build time. Change them and you must rebuild with npm run build. Variables without the prefix are only available on the server and are read at runtime. Never give a secret the NEXT_PUBLIC_ prefix.

Troubleshooting

• Variable is undefined — the app was not restarted, the name has a typo, or dotenv is loaded after the code that reads it.
• Works locally, not on the server — the .env file was not uploaded (it is usually excluded from Git), so create it on the server.

Next steps

• Deploy a Next.js app on a Linux VPS
• Deploy a Next.js app on cPanel hosting
• Fix common Node.js errors