How to install npm packages for my Node.js app

Your app's packages are installed into a virtual environment that belongs to the app on the server. You don't upload them. There are two ways to install them.

Before you start

• Your project must have a package.json in the application root listing your dependencies.
• Don't upload node_modules. On the server, node_modules in your application root is a link into the virtual environment. Uploading your own folder over it breaks the app. If you already uploaded one, delete it before continuing.

Way 1: The Run NPM Install button

Use this for a normal install with no build step.

1. In cPanel, go to Software → Setup Node.js App. On a compatible DirectAdmin server, the same tool is listed as Node.js App.
2. Click the pencil (Edit) icon next to your app.
3. Click Run NPM Install.
4. Wait for the confirmation message.
5. Click Restart.

The button is greyed out when there is no package.json in the application root. Check the folder and the spelling of the file name.

Way 2: npm over SSH

Use this when you need npm run build, want to see errors as they happen, or the button fails.

1. Turn on SSH access

SSH is switched off by default on shared hosting. Open a support ticket to ask for it to be enabled for your account.

2. Connect

From a terminal on your computer (Terminal on macOS, PowerShell or Windows Terminal on Windows):

ssh username@example.co.za

Use your cPanel username and password. If your domain isn't pointing to Webway yet, use the server hostname instead.

3. Enter the app's virtual environment

On the app screen, copy the command shown under Enter to the virtual environment. It looks like this:

source /home/username/nodevenv/myapp/20/bin/activate && cd /home/username/myapp

Paste it into your SSH session and press Enter. Your prompt changes to show the environment is active. From here, node and npm are the version your app uses.

Copy the command from the screen rather than typing it. The path includes your username, the app folder and the Node.js version, and one wrong character sends you to the wrong environment.

4. Install

npm install

For a build step, run it after the install:

npm run build

5. Restart the app

Either click Restart on the app screen, or run touch tmp/restart.txt in the application root.

Installing a single package

Over SSH, inside the virtual environment:

npm install express

This also adds it to package.json, so a later Run NPM Install picks it up.

Updating packages

Over SSH, inside the virtual environment:

npm update

Then restart the app. Test carefully. Updates can change how packages behave.

Heavy installs and builds

Your account has a memory limit (2 GB by default, shared with everything else on the account). Large installs and builds such as next build can run out of memory part-way and fail with a message such as Killed or JavaScript heap out of memory.

If that happens:

1. Run the build on your own computer.
2. Upload the build output (for example the .next or dist folder) with the rest of your code.
3. On the server, run only npm install --omit=dev (or npm install --production on older npm) to install what the app needs at run time.

Common errors

Message	Cause	Fix
The Run NPM Install button is greyed out	No package.json in the application root	Check the folder path on the app screen and that the file is in that folder
npm: command not found over SSH	You haven't entered the virtual environment	Run the source …/activate command from the app screen
Cannot find module 'xyz' when the app starts	Packages not installed, or node_modules was uploaded	Delete any uploaded node_modules, run the install again, restart
Killed or heap out of memory	Memory limit hit during install or build	Build locally and upload the output
EACCES: permission denied	Trying to install outside your home folder, or a global install (-g)	Drop -g. Everything installs into the app's environment

Related guides

• How to set up a Node.js app
• My Node.js or Python app won't start or shows an error