Using Node.js and npm at Seravo | Seravo Knowledge Base

Node.js and its package manager npm (Node Package Manager) help manage JavaScript packages for your site or theme, ensuring consistent installations across different environments. These tools are essential when developing modern WordPress themes and web projects.

Node.js and npm come pre-installed in Seravo’s environment under the /data/wordpress directory.

Getting Started

Like Composer, npm is managed via the command line (SSH). Always verify that you are in the correct directory before running commands. The most common locations are:

/data/wordpress/ (site-wide packages)
/data/wordpress/htdocs/wp-content/themes/your-theme/ (theme-specific packages)

Common Commands

When your project includes a package.json file, install dependencies using:

npm install

This command installs packages and their dependencies into the node_modules directory and updates package-lock.json if needed.

When deploying or migrating an existing project that already contains a package-lock.json file, it is best practice to perform a clean install:

npm ci

This command installs exact package versions defined in the lockfile, ensuring your environment matches development. It also deletes any existing node_modules folder prior to installation.

Installing or removing individual packages:

npm install <package-name> 
npm uninstall <package-name>

Updating packages (within version constraints in package.json):

npm update

Building the Theme (Build)

Installing packages alone isn't enough; production CSS and JS assets must be built and compiled. This is typically handled by running:

npm run build

Modern Themes (e.g., Roots Sage)

Many modern themes rely on npm packages and Composer-based project structures. Building a theme at Seravo usually requires the following steps:

Run composer install in /data/wordpress/. Check if the theme directory has its own separate composer.json file and run composer install there as well if necessary.
Navigate to the theme directory. If a package-lock.json file exists, run npm ci (otherwise, use npm install).
Compile theme assets by running npm run build.

Note: Some themes use Yarn by default. If you see a yarn.lock file in the theme folder, use Yarn commands instead (e.g., yarn install and yarn build).

Running Node.js Applications in the Background

In addition to WordPress, you can run persistent Node.js applications alongside your site, such as lightweight microservices (e.g., custom API endpoints or chatbots).

Process Management (PM2)

Persistent applications need a process manager so they stay active in the background, even through server reboots or maintenance events. PM2 is the recommended tool for this:

npm install -g pm2

Automated Restarts (Crontab)

Seravo environments do not grant root (sudo) access, meaning PM2's native startup scripts cannot be installed. You can automate application restarts upon reboot by adding an entry to your server's crontab:

Open crontab for editing: crontab -e
Add the following line:
@reboot pm2 start /data/wordpress/nodeapps/app/app.config.cjs

Exposing the Application to the Web

When a Node app runs locally in the background (e.g., at http://localhost:3030), it is not publicly accessible over the web. Avoid routing traffic directly to the server's public IP address; instead, configure an Nginx reverse proxy.

Create a custom nginx configuration file in /data/wordpress/nginx/ to proxy incoming traffic to the application's local port. Example app.conf:

location ^~ /api/app {
  proxy_pass http://127.0.0.1:3030/;
  proxy_set_header Host $http_host;
  proxy_set_header X-Forwarded-Host $http_host;
  proxy_set_header X-Real-IP $remote_addr;
  proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
  proxy_set_header X-Forwarded-Proto $scheme;
}

Troubleshooting

Error: ERESOLVE unable to resolve dependency tree

This halts installation due to peer dependency version conflicts. If you are confident the project functions with the current versions, bypass the check with: npm install --legacy-peer-deps (or npm ci --legacy-peer-deps)

Build succeeded, but frontend displays 404 errors

Check functions.php to ensure style and script paths (wp_enqueue_style / wp_enqueue_script) point to the correct output directories. If using Roots Sage, verify that manifest.json was generated inside the dist or public folder.

Fatal Error during build

This is typically caused by missing Composer dependencies inside the theme. Check whether the theme folder has its own composer.json file. If so, run composer install inside the theme directory to generate the required vendor folder before running the build step.