Guide Install npm Packages for a Node.js App on aaPanel - Printable Version +- AdminsForum (https://adminsforum.com) +-- Forum: Free & open-source control panels (https://adminsforum.com/Forum-free-open-source-control-panels) +--- Forum: aaPanel (https://adminsforum.com/Forum-aapanel) +---- Forum: aaPanel Guides & Tutorials (https://adminsforum.com/Forum-aapanel-guides-tutorials) +----- Forum: aaPanel Websites & Web Servers Guides (https://adminsforum.com/Forum-aapanel-websites-web-servers-guides) +----- Thread: Guide Install npm Packages for a Node.js App on aaPanel (/Thread-guide-install-npm-packages-for-a-node-js-app-on-aapanel)

Install npm Packages for a Node.js App on aaPanel - DEV - 10-14-2026 Installing a Node.js runtime is only the first step. An application may also need packages from npm. This guide installs Express in a separate lab folder on an aaPanel server, fixes a writable-cache problem and verifies a clean lockfile-based installation.     npm dependency workflow based on the isolated lab test. Tested: Ubuntu 22.04.5 LTS, aaPanel Free 8.0.7, Node.js 24.21.0, npm 11.19.0 and Express 5.3.0 on 14 October 2026. Commands ran as www in /www/af-npm-lab. This is an SSH workflow, not a demonstration of aaPanel's Module button. The live website was not modified. 1. Confirm the intended Node.js runtime Install Node.js first using the aaPanel runtime guide. Check the Node version supported by your application and dependencies. Use the same intended runtime for package installation and app execution. Our runtime is under /www/server/nodejs/v24.21.0/bin. Replace that path if your installed version differs. A shell's node command can point to a different runtime from the one selected for an aaPanel project. 2. Create a separate practice directory As an administrator over SSH, choose a directory that does not already contain an application: Code:Copy sudo mkdir /www/af-npm-lab sudo chown www:www /www/af-npm-lab sudo runuser -u www -- bash The final command opens a shell as www. The remaining npm commands below belong in that shell. Do not initialise a new package.json over a real application's existing manifest. For an existing project, use its supplied manifest, lockfile and installation instructions. 3. Set the runtime and a writable npm cache Code:Copy export PATH=/www/server/nodejs/v24.21.0/bin:$PATH export npm_config_cache=/www/af-npm-lab/.npm-cache cd /www/af-npm-lab node --version npm --version We verified v24.21.0 and 11.19.0. These exports affect the current shell; they are not a permanent change to aaPanel's project configuration. Our first attempt encountered a shared npm cache at /www/server/nodejs/cache that www could not write to. A separate writable cache fixed the problem without running npm as root or making shared directories writable to everyone. For real deployments, choose a protected cache location outside publicly served files and ensure the intended run user owns it. 4. Initialise only the new sample project Code:Copy npm init -y This creates package.json for the practice folder. Review the result. Its default test script is a placeholder, not a passing application test. 5. Install the example dependency Code:Copy npm install express --ignore-scripts --registry=https://registry.npmjs.org npm ls express The test used the official npm registry. Express installed as version 5.3.0, and npm ls showed it as a dependency of af-npm-lab. The command also produced package-lock.json and populated node_modules. We used --ignore-scripts for this controlled example. Some real packages require installation scripts or build steps; disabling those can leave them unusable. Follow the application's documented requirements rather than applying this flag indiscriminately. 6. Understand the files package.json: Declares the project and its dependency requirements. package-lock.json: Records npm's resolved dependency tree for this project. node_modules: Contains installed packages; its presence alone does not prove a working app. .npm-cache: Our chosen local download cache, not application source. Preserve the manifest and lockfile in your source and recovery process. Do not mix package managers casually: a project built around a Yarn or pnpm lockfile needs its corresponding workflow. 7. Verify a clean installation from the lockfile Only run the following in the isolated practice folder: Code:Copy sha256sum package-lock.json npm ci --ignore-scripts --registry=https://registry.npmjs.org sha256sum package-lock.json npm ls express The two lockfile checksums matched in our test, and Express remained installed. npm ci requires an existing matching lockfile, installs the whole project and replaces an existing node_modules directory. It is therefore not a harmless diagnostic command to run inside a serving production release. If the manifest and lockfile disagree, npm ci reports an error rather than silently updating the lockfile. Resolve that mismatch in a controlled development or build workflow; do not delete the lockfile merely to hide the problem. 8. Check that Node can load the package From the practice directory: Code:Copy node -e 'const express=require("express"); const app=express(); console.log(typeof app.get === "function" ? "EXPRESS_LOAD_PASS" : "FAIL")' Our output was EXPRESS_LOAD_PASS. This confirms that Node can import Express and create an application object. It does not start a web service or prove an entire application, database or domain works. npm's audit output reported zero known vulnerabilities during this test. That result is time-dependent and is not a guarantee that a package or application is secure. The lab also displayed a warning about an unknown global --init.module configuration; it did not prevent these checks from passing. 9. Common installation errors EACCES or cache write failure: Check directory ownership and use a writable cache for the intended user. Avoid permissions 777 or a root install as shortcuts. npm ci needs a lockfile: Check you are in the right directory and have the project's npm lockfile. Module not found: Check the working directory, installed dependency and runtime used to start the app. Unsupported engine: Compare package requirements with the selected Node version. Registry or certificate error: Check connectivity and registry settings; do not bypass TLS validation to force a download. 10. Return to aaPanel deployment Type exit to leave the www practice shell. For a real application, prepare dependencies and any required build in a separate release directory, then configure the correct runtime and start command in aaPanel. Restart the intended project and verify its expected response. See Deploy a Node.js app with a domain and HTTPS. Lab result: Express loaded successfully; npm ci passed; the lockfile checksum stayed unchanged. The isolated practice directory is retained. No public application or production dependency update was performed. References: npm ci documentation and Express installation documentation.