Skip to main content

Using Node.js and npm in Seravo's Environment

Learn how to use Node.js and npm in Seravo's environment: building modern WordPress themes, running persistent Node applications with PM2, and troubleshooting common issues.

Node.js and its package manager npm (Node Package Manager) help you manage JavaScript dependencies and build modern frontend assets consistently across environments.

Node.js and npm come pre-installed in both Seravo's server environment and the local Docker development container. You can check the active versions from the command line with:

node -v npm -v

Getting Started

Like Composer, npm is operated via the command line (either over SSH on the server or inside your local Docker development container). Before running commands, always make sure you are in the correct project directory:

  • /data/wordpress/ (site-wide packages)

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

Note: Never commit the node_modules/ directory to Git (it is excluded by default in Seravo's .gitignore). Always keep package.json and package-lock.json tracked in version control.

Common npm Commands

  • Install dependencies (package.json):

    npm install

    Installs packages into node_modules/ and updates package-lock.json if needed.

  • Clean install for production or staging (package-lock.json):

    npm ci

    Removes any existing node_modules/ directory and installs the exact package versions specified in the lockfile. This is the recommended command for servers and deployment automation.

  • Install or remove a single package:

    npm install <package-name> npm uninstall <package-name>
  • Update packages (within lockfile constraints):

    npm update

Building a Theme

Installing packages alone is usually not enough—theme SCSS and JavaScript source files must also be compiled into browser-ready assets. This is typically done with:

npm run build

Modern Themes (e.g., Roots Sage)

Many modern WordPress themes combine Composer and npm workflows. Building such a theme on Seravo typically requires the following steps:

  1. Run composer install in /data/wordpress/. Also check whether the theme directory has its own composer.json file and run composer install there if needed.

  2. Navigate to the theme directory and install Node dependencies:

    cd /data/wordpress/htdocs/wp-content/themes/your-theme
    npm ci

    (If the project does not include a package-lock.json file, run npm install instead.)

  3. Compile the production assets:

    npm run build

Tip: You can automate these commands in your server's /data/wordpress/.git/hooks/post-receive script so the theme builds automatically on every git push, or compile the assets locally before committing.

Note: Some themes use Yarn by default. If your theme directory contains a yarn.lock file, use Yarn commands (yarn install and yarn build) instead.

Running Node.js Applications in the Background

Alongside WordPress, you can also run persistent lightweight Node.js applications, such as microservices or API endpoints. Keep in mind that background Node.js processes share the same container memory and CPU resources as WordPress and the database.

Process Management (PM2)

Persistent applications require a process manager such as PM2 to stay running and recover automatically from crashes.

Because Seravo's environment does not grant root (sudo) privileges, install PM2 either locally inside your application's directory (recommended):

cd /data/wordpress/nodeapps/app
npm install pm2
npx pm2 start app.config.cjs

Or configure a user-level global npm prefix in your home directory before installing globally:

mkdir -p ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH="$HOME/.npm-global/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc
npm install -g pm2

Automatic Startup on Reboot (Crontab)

Without sudo privileges, PM2's built-in pm2 startup command is not available. To ensure your application starts automatically after a server reboot (such as during scheduled maintenance), add a @reboot entry to your user crontab:

  1. Open your crontab for editing:

    crontab -e
  2. Add the following line at the end of the file:

    @reboot cd /data/wordpress/nodeapps/app && npx pm2 start app.config.cjs

Exposing the Application Publicly (nginx)

A Node application listening on a local port (for example, [http://127.0.0.1:3030](http://127.0.0.1:3030)) is not directly reachable from the public internet. Route external traffic to the application by creating a custom nginx configuration file in /data/wordpress/nginx/, such as /data/wordpress/nginx/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;
}

Apply the new configuration by restarting nginx:

wp-restart-nginx

Tip: The trailing slash in proxy_pass http://127.0.0.1:3030/; strips the /api/app prefix before forwarding the request to your Node application. If your application expects the full path intact, omit the trailing slash: proxy_pass http://127.0.0.1:3030;.

Common Issues and Troubleshooting

  • npm install -g fails with EACCES: permission denied: Seravo servers do not allow sudo access to system directories. Install the package locally in your project (npm install <package> and run it via npx) or configure a user-writable global prefix (npm config set prefix '~/.npm-global').

  • Error ERESOLVE unable to resolve dependency tree: There is a peer dependency version conflict between packages. If you are confident the project works with the current versions, bypass the check with npm ci --legacy-peer-deps (or npm install --legacy-peer-deps).

  • npm run build crashes with JavaScript heap out of memory: Large theme builds can exceed Node.js's default memory limit. Try increasing the heap limit during the build with NODE_OPTIONS="--max-old-space-size=2048" npm run build, or compile the assets on your local workstation and deploy them via Git.

  • The build succeeded, but the site returns 404 errors for CSS or JS files: Check the asset paths in your theme's functions.php (wp_enqueue_style / wp_enqueue_script). If you are using Roots Sage, verify that manifest.json was generated in the dist or public directory.

  • Fatal error or missing classes during the build: The theme is often missing its own vendor/ directory. Check whether the theme directory contains a composer.json file and run composer install inside the theme directory before running npm run build.

  • The theme requires a newer Node.js version than the server default: Compile the assets in your local development environment (for example, using nvm) and commit the built production files directly to Git.

See Also

With Node.js and npm, you can reliably manage modern theme build pipelines and lightweight background services in Seravo's environment. If you need assistance configuring nginx routing or assessing your site's resource requirements, our support team is happy to help at [email protected].

Did this answer your question?