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 updatespackage-lock.jsonif 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:
Run
composer installin/data/wordpress/. Also check whether the theme directory has its owncomposer.jsonfile and runcomposer installthere if needed.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.jsonfile, runnpm installinstead.)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:
Open your crontab for editing:
crontab -e
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 -gfails withEACCES: permission denied: Seravo servers do not allowsudoaccess to system directories. Install the package locally in your project (npm install <package>and run it vianpx) 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 withnpm ci --legacy-peer-deps(ornpm install --legacy-peer-deps).npm run buildcrashes withJavaScript heap out of memory: Large theme builds can exceed Node.js's default memory limit. Try increasing the heap limit during the build withNODE_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
404errors for CSS or JS files: Check the asset paths in your theme'sfunctions.php(wp_enqueue_style/wp_enqueue_script). If you are using Roots Sage, verify thatmanifest.jsonwas generated in thedistorpublicdirectory.Fatal error or missing classes during the build: The theme is often missing its own
vendor/directory. Check whether the theme directory contains acomposer.jsonfile and runcomposer installinside the theme directory before runningnpm 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].
